A local-first personal finance app
// @ts-strict-ignore
import { formatDistanceToNow } from 'date-fns';
import type { Locale } from 'date-fns';
import { getDecimalPlaces } from './currencies';
export function last<T>(arr: Array<T>) {
return arr[arr.length - 1];
}
export function getChangedValues<T extends { id?: string }>(obj1: T, obj2: T) {
const diff: Partial<T> = {};
const keys = Object.keys(obj2);
let hasChanged = false;
// Keep the id field because this is mostly used to diff database
// objects
if (obj1.id) {
diff.id = obj1.id;
}
for (let i = 0; i < keys.length; i++) {
const key = keys[i];
if (obj1[key] !== obj2[key]) {
diff[key] = obj2[key];
hasChanged = true;
}
}
return hasChanged ? diff : null;
}
export function hasFieldsChanged<T extends object>(
obj1: T,
obj2: T,
fields: Array<keyof T>,
) {
let changed = false;
for (let i = 0; i < fields.length; i++) {
const field = fields[i];
if (obj1[field] !== obj2[field]) {
changed = true;
break;
}
}
return changed;
}
export type Diff<T extends { id: string }> = {
added: T[];
updated: Partial<T>[];
deleted: Pick<T, 'id'>[];
};
export function applyChanges<T extends { id: string }>(
changes: Diff<T>,
items: T[],
) {
items = [...items];
if (changes.added) {
changes.added.forEach(add => {
items.push(add);
});
}
if (changes.updated) {
changes.updated.forEach(({ id, ...fields }) => {
const idx = items.findIndex(t => t.id === id);
items[idx] = {
...items[idx],
...fields,
};
});
}
if (changes.deleted) {
changes.deleted.forEach(t => {
const idx = items.findIndex(t2 => t.id === t2.id);
if (idx !== -1) {
items.splice(idx, 1);
}
});
}
return items;
}
export function partitionByField<T, K extends keyof T>(data: T[], field: K) {
const res = new Map();
for (let i = 0; i < data.length; i++) {
const item = data[i];
const key = item[field];
const items = res.get(key) || [];
items.push(item);
res.set(key, items);
}
return res;
}
export function groupBy<T, K extends keyof T>(data: T[], field: K) {
const res = new Map<T[K], T[]>();
for (let i = 0; i < data.length; i++) {
const item = data[i];
const key = item[field];
const existing = res.get(key) || [];
res.set(key, existing.concat([item]));
}
return res;
}
// This should replace the existing `groupById` function, since a
// `Map` is better, but we can't swap it out because `Map` has a
// different API and we need to go through and update everywhere that
// uses it.
function _groupById<T extends { id: string }>(data: T[]) {
const res = new Map<string, T>();
for (let i = 0; i < data.length; i++) {
const item = data[i];
res.set(item.id, item);
}
return res;
}
export function diffItems<T extends { id: string }>(
items: T[],
newItems: T[],
): Diff<T> {
const grouped = _groupById(items);
const newGrouped = _groupById(newItems);
const added: T[] = [];
const updated: Partial<T>[] = [];
const deleted: Pick<T, 'id'>[] = items
.filter(item => !newGrouped.has(item.id))
.map(item => ({ id: item.id }));
newItems.forEach(newItem => {
const item = grouped.get(newItem.id);
if (!item) {
added.push(newItem);
} else {
const changes = getChangedValues(item, newItem);
if (changes) {
updated.push(changes);
}
}
});
return { added, updated, deleted };
}
export function groupById<T extends { id: string }>(
data: T[] | null | undefined,
): Record<string, T> {
if (!data) {
return {};
}
const res: { [key: string]: T } = {};
for (let i = 0; i < data.length; i++) {
const item = data[i];
res[item.id] = item;
}
return res;
}
export function setIn(
map: Map<string, unknown>,
keys: string[],
item: unknown,
): void {
for (let i = 0; i < keys.length; i++) {
const key = keys[i];
if (i === keys.length - 1) {
map.set(key, item);
} else {
if (!map.has(key)) {
map.set(key, new Map<string, unknown>());
}
map = map.get(key) as Map<string, unknown>;
}
}
}
export function getIn(map, keys) {
let item = map;
for (let i = 0; i < keys.length; i++) {
item = item.get(keys[i]);
if (item == null) {
return item;
}
}
return item;
}
export function fastSetMerge<T>(set1: Set<T>, set2: Set<T>) {
const finalSet = new Set(set1);
const iter = set2.values();
let value = iter.next();
while (!value.done) {
finalSet.add(value.value);
value = iter.next();
}
return finalSet;
}
export function titleFirst(str: string | null | undefined) {
if (!str || str.length <= 1) {
return str?.toUpperCase() ?? '';
}
return str[0].toUpperCase() + str.slice(1);
}
export function reapplyThousandSeparators(amountText: string) {
if (!amountText || typeof amountText !== 'string') {
return amountText;
}
const { decimalSeparator, thousandsSeparator, value } = getNumberFormat();
const [integerPartRaw, decimalPart = ''] = amountText.split(decimalSeparator);
// Apostrophe-dot: accept both U+2019 and keyboard U+0027 on input (see getNumberFormat formatter)
const stripThousands =
value === 'apostrophe-dot'
? (s: string) => s.replaceAll(/[\u2019\u0027]/g, '')
: (s: string) => s.replaceAll(thousandsSeparator, '');
const numericValue = Number(stripThousands(integerPartRaw));
if (isNaN(numericValue)) {
return amountText; // Return original if parsing fails
}
const integerPart = numericValue
.toLocaleString('en-US')
.replaceAll(',', thousandsSeparator);
return decimalPart
? integerPart + decimalSeparator + decimalPart
: integerPart;
}
export function appendDecimals(
amountText: string,
hideDecimals = false,
): string {
const { decimalSeparator: separator } = getNumberFormat();
let result = amountText;
if (result.slice(-1) === separator) {
result = result.slice(0, -1);
}
if (!hideDecimals) {
result = result.replaceAll(/[,.]/g, '');
result = result.replace(/^0+(?!$)/, '');
result = result.padStart(3, '0');
result = result.slice(0, -2) + separator + result.slice(-2);
}
return amountToCurrency(currencyToAmount(result));
}
const NUMBER_FORMATS = [
'comma-dot',
'dot-comma',
'space-comma',
'apostrophe-dot',
'comma-dot',
'comma-dot-in',
] as const;
export type NumberFormats = (typeof NUMBER_FORMATS)[number];
function isNumberFormat(input: string = ''): input is NumberFormats {
return (NUMBER_FORMATS as readonly string[]).includes(input);
}
export const numberFormats: Array<{
value: NumberFormats;
label: string;
labelNoFraction: string;
}> = [
{ value: 'comma-dot', label: '1,000.33', labelNoFraction: '1,000' },
{ value: 'dot-comma', label: '1.000,33', labelNoFraction: '1.000' },
{
value: 'space-comma',
label: '1\u202F000,33',
labelNoFraction: '1\u202F000',
},
{ value: 'apostrophe-dot', label: "1'000.33", labelNoFraction: "1'000" },
{ value: 'comma-dot-in', label: '1,00,000.33', labelNoFraction: '1,00,000' },
];
let numberFormatConfig: {
format: NumberFormats;
hideFraction: boolean;
} = {
format: 'comma-dot',
hideFraction: false,
};
export function parseNumberFormat({
format,
hideFraction,
}: {
format?: string;
hideFraction?: string | boolean;
}) {
return {
format: isNumberFormat(format) ? format : 'comma-dot',
hideFraction: String(hideFraction) === 'true',
};
}
export function setNumberFormat(config: typeof numberFormatConfig) {
numberFormatConfig = config;
}
export function getNumberFormat({
format = numberFormatConfig.format,
hideFraction = numberFormatConfig.hideFraction,
decimalPlaces,
}: {
format?: NumberFormats;
hideFraction?: boolean;
decimalPlaces?: number;
} = numberFormatConfig) {
let locale, thousandsSeparator, decimalSeparator;
const currentFormat = format || numberFormatConfig.format;
const currentHideFraction =
typeof hideFraction === 'boolean'
? hideFraction
: numberFormatConfig.hideFraction;
switch (format) {
case 'space-comma':
locale = 'fr-FR';
thousandsSeparator = '\u202F';
decimalSeparator = ',';
break;
case 'dot-comma':
locale = 'de-DE';
thousandsSeparator = '.';
decimalSeparator = ',';
break;
case 'apostrophe-dot':
locale = 'de-CH';
thousandsSeparator = '\u2019'; // Intl may return U+0027 (Node <24.13.1/ICU 77)
decimalSeparator = '.';
break;
case 'comma-dot-in':
locale = 'en-IN';
thousandsSeparator = ',';
decimalSeparator = '.';
break;
case 'comma-dot':
default:
locale = 'en-US';
thousandsSeparator = ',';
decimalSeparator = '.';
}
const fractionDigitsOptions: {
minimumFractionDigits: number;
maximumFractionDigits: number;
} =
typeof decimalPlaces === 'number'
? {
minimumFractionDigits: decimalPlaces,
maximumFractionDigits: decimalPlaces,
}
: {
minimumFractionDigits: currentHideFraction ? 0 : 2,
maximumFractionDigits: currentHideFraction ? 0 : 2,
};
const intlFormatter = new Intl.NumberFormat(locale, fractionDigitsOptions);
// Wrapper to handle -0 edge case
// Normalize apostrophe-dot to U+2019 for consistency across
// Node/ICU versions (https://github.com/nodejs/node/issues/61861)
const formatter = {
format: (value: number) => {
let formatted = intlFormatter.format(value);
if (currentFormat === 'apostrophe-dot') {
formatted = formatted.replace(/'/g, '\u2019');
}
return formatted === '-0' ? '0' : formatted;
},
};
return {
value: currentFormat,
thousandsSeparator,
decimalSeparator,
formatter,
};
}
// Number utilities
/**
* The exact amount.
*/
export type Amount = number;
/**
* The exact amount that is formatted based on the configured number format.
* For example, 123.45 would be '123.45' or '123,45'.
*/
export type CurrencyAmount = string;
/**
* The amount with the decimal point removed.
* For example, 123.45 would be 12345.
* Always two implied decimals, whatever the currency: ¥1,500 is 150000.
*/
export type IntegerAmount = number;
// We dont use `Number.MAX_SAFE_NUMBER` and such here because those
// numbers are so large that it's not safe to convert them to floats
// (i.e. N / 100). For example, `9007199254740987 / 100 ===
// 90071992547409.88`. While the internal arithemetic would be correct
// because we always do that on numbers, the app would potentially
// display wrong numbers. Instead of `2**53` we use `2**51` which
// gives division more room to be correct
export const MAX_SAFE_NUMBER = 2 ** 51 - 1;
const MIN_SAFE_NUMBER = -MAX_SAFE_NUMBER;
export function safeNumber(value: number) {
if (!Number.isInteger(value)) {
throw new Error(
'safeNumber: number is not an integer: ' + JSON.stringify(value),
);
}
if (value > MAX_SAFE_NUMBER || value < MIN_SAFE_NUMBER) {
throw new Error(
"safeNumber: can't safely perform arithmetic with number: " + value,
);
}
return value;
}
export function toRelaxedNumber(currencyAmount: CurrencyAmount): Amount {
return integerToAmount(currencyToInteger(currencyAmount) || 0);
}
export function integerToCurrency(
integerAmount: IntegerAmount,
formatter = getNumberFormat().formatter,
) {
return formatter.format(integerToAmount(safeNumber(integerAmount)));
}
export function integerToCurrencyWithDecimal(
integerAmount: IntegerAmount,
currencyCode?: string,
) {
if (currencyCode !== undefined) {
const dp = getDecimalPlaces(currencyCode);
return integerToCurrency(
integerAmount,
getNumberFormat({ ...numberFormatConfig, decimalPlaces: dp }).formatter,
);
}
// If decimal digits exist, keep them. Otherwise format them as usual.
if (integerAmount % 100 !== 0) {
return integerToCurrency(
integerAmount,
getNumberFormat({
...numberFormatConfig,
hideFraction: false,
}).formatter,
);
}
return integerToCurrency(integerAmount);
}
export function amountToCurrency(amount: Amount): CurrencyAmount {
return getNumberFormat().formatter.format(amount);
}
export function amountToCurrencyNoDecimal(amount: Amount): CurrencyAmount {
return getNumberFormat({
...numberFormatConfig,
hideFraction: true,
}).formatter.format(amount);
}
export function currencyToAmount(currencyAmount: string): Amount | null {
currencyAmount = currencyAmount.replace(/\u2212/g, '-');
let integer, fraction;
// match the last dot or comma in the string
const match = currencyAmount.match(/[,.](?=[^.,]*$)/);
if (
!match ||
(match[0] === getNumberFormat().thousandsSeparator &&
match.index + 4 <= currencyAmount.length)
) {
fraction = null;
integer = currencyAmount.replace(/[^\d-]/g, '');
} else {
integer = currencyAmount.slice(0, match.index).replace(/[^\d-]/g, '');
fraction = currencyAmount.slice(match.index + 1);
}
const amount = parseFloat(integer + '.' + fraction);
return isNaN(amount) ? null : amount;
}
export function currencyToInteger(
currencyAmount: CurrencyAmount,
): IntegerAmount | null {
const amount = currencyToAmount(currencyAmount);
return amount == null ? null : amountToInteger(amount);
}
export function stringToInteger(str: string): number | null {
const amount = parseInt(
str.replace(/\u2212/g, '-').replace(/[^-0-9.,]/g, ''),
);
if (!isNaN(amount)) {
return amount;
}
return null;
}
export function amountToInteger(
amount: Amount,
decimalPlaces: number = 2,
): IntegerAmount {
const multiplier = Math.pow(10, decimalPlaces);
return Math.round(amount * multiplier);
}
export function integerToAmount(
integerAmount: IntegerAmount,
decimalPlaces: number = 2,
): Amount {
const divisor = Math.pow(10, decimalPlaces);
return integerAmount / divisor;
}
// This is used when the input format could be anything (from
// financial files and we don't want to parse based on the user's
// number format, because the user could be importing from many
// currencies. We extract out the numbers and just ignore separators.
export function looselyParseAmount(amount: string) {
function safeNumber(v: number): null | number {
if (isNaN(v)) {
return null;
}
const value = v * 100;
if (value > MAX_SAFE_NUMBER || value < MIN_SAFE_NUMBER) {
return null;
}
return v;
}
function extractNumbers(v: string): string {
return v.replace(/[^0-9-]/g, '');
}
amount = amount.trim();
if (amount.startsWith('(') && amount.endsWith(')')) {
// Remove Unicode minus inside parentheses before converting to ASCII minus
amount = amount.replace(/\u2212/g, '');
amount = amount.replace('(', '-').replace(')', '');
} else {
// Replace Unicode minus with ASCII minus for non-parenthesized amounts
amount = amount.replace(/\u2212/g, '-');
}
// Look for a decimal marker, then look for either 1-2 or 4-9 decimal places.
// This avoids matching against 3 places which may not actually be decimal.
// Only digits count as places, so a currency symbol or code after the
// number does not change how many there are.
const m = amount.match(/[.,](\d{4,9}|\d{1,2})[^\d.,]*$/);
if (!m || m.index === undefined) {
return safeNumber(parseFloat(extractNumbers(amount)));
}
const left = extractNumbers(amount.slice(0, m.index));
const right = extractNumbers(amount.slice(m.index + 1));
return safeNumber(parseFloat(left + '.' + right));
}
export function sortByKey<T>(arr: T[], key: keyof T): T[] {
return [...arr].sort((item1, item2) => {
if (item1[key] < item2[key]) {
return -1;
} else if (item1[key] > item2[key]) {
return 1;
}
return 0;
});
}
// Date utilities
export function tsToRelativeTime(
ts: string | null,
locale: Locale,
options: {
capitalize: boolean;
} = { capitalize: false },
): string {
if (!ts) return 'Unknown';
const parsed = new Date(parseInt(ts, 10));
let distance = formatDistanceToNow(parsed, { addSuffix: true, locale });
if (options.capitalize) {
distance = distance.charAt(0).toUpperCase() + distance.slice(1);
}
return distance;
}
export function applyFindReplace(
text: string | null | undefined,
find: string,
replace: string,
useRegex: boolean,
): string {
if (find === '') return text ?? '';
if (!text) return '';
try {
const pattern = useRegex ? new RegExp(find, 'g') : find;
return text.replaceAll(pattern, replace);
} catch {
return text;
}
}