@actual-app/core 26.3.0

package/src/shared/transactions.test.ts

@@ -0,0 +1,275 @@
+// @ts-strict-ignore
+import { v4 as uuidv4 } from 'uuid';
+
+import type { TransactionEntity } from '../types/models';
+
+import {
+  addSplitTransaction,
+  deleteTransaction,
+  makeAsNonChildTransactions,
+  makeChild,
+  splitTransaction,
+  updateTransaction,
+} from './transactions';
+
+function makeTransaction(data: Partial<TransactionEntity>): TransactionEntity {
+  return {
+    id: uuidv4(),
+    amount: 2422,
+    date: '2020-01-05',
+    account: 'acc-id-1',
+    ...data,
+  };
+}
+
+function makeSplitTransaction(data, children) {
+  const parent = makeTransaction({ ...data, is_parent: true });
+  return [parent, ...children.map(t => makeChild(parent, t))];
+}
+
+function splitError(amount: number) {
+  return { difference: amount, type: 'SplitTransactionError', version: 1 };
+}
+
+describe('Transactions', () => {
+  test('updating a transaction works', () => {
+    const transactions = [
+      makeTransaction({ amount: 5000 }),
+      makeTransaction({ id: 't1', amount: 4000 }),
+      makeTransaction({ amount: 3000 }),
+    ];
+    const { data, diff } = updateTransaction(
+      transactions,
+      makeTransaction({
+        id: 't1',
+        amount: 5000,
+      }),
+    );
+    expect(data.find(d => d.subtransactions)).toBeFalsy();
+    expect(diff).toEqual({
+      added: [],
+      deleted: [],
+      updated: [expect.objectContaining({ id: 't1', amount: 5000 })],
+    });
+    expect(
+      data
+        .map(t => ({ id: t.id, amount: t.amount }))
+        .sort(
+          (a, b) =>
+            b.amount - a.amount || String(a.id).localeCompare(String(b.id)),
+        ),
+    ).toEqual([
+      { id: expect.any(String), amount: 5000 },
+      { id: 't1', amount: 5000 },
+      { id: expect.any(String), amount: 3000 },
+    ]);
+  });
+
+  test('updating does nothing if value not changed', () => {
+    const updatedTransaction = makeTransaction({ id: 't1', amount: 5000 });
+    const transactions = [
+      updatedTransaction,
+      makeTransaction({ amount: 3000 }),
+    ];
+    const { data, diff } = updateTransaction(transactions, updatedTransaction);
+    expect(diff).toEqual({ added: [], deleted: [], updated: [] });
+    expect(
+      data
+        .map(t => ({ id: t.id, amount: t.amount }))
+        .sort(
+          (a, b) =>
+            b.amount - a.amount || String(a.id).localeCompare(String(b.id)),
+        ),
+    ).toEqual([
+      { id: expect.any(String), amount: 5000 },
+      { id: expect.any(String), amount: 3000 },
+    ]);
+  });
+
+  test('deleting a transaction works', () => {
+    const transactions = [
+      makeTransaction({ amount: 5000 }),
+      makeTransaction({ id: 't1', amount: 4000 }),
+      makeTransaction({ amount: 3000 }),
+    ];
+    const { data, diff } = deleteTransaction(transactions, 't1');
+
+    expect(diff).toEqual({
+      added: [],
+      deleted: [{ id: 't1' }],
+      updated: [],
+    });
+    expect(
+      data
+        .map(t => ({ id: t.id, amount: t.amount }))
+        .sort(
+          (a, b) =>
+            b.amount - a.amount || String(a.id).localeCompare(String(b.id)),
+        ),
+    ).toEqual([
+      { id: expect.any(String), amount: 5000 },
+      { id: expect.any(String), amount: 3000 },
+    ]);
+  });
+
+  test('splitting a transaction works', () => {
+    const transactions = [
+      makeTransaction({ id: 't1', amount: 5000 }),
+      makeTransaction({ amount: 3000 }),
+    ];
+    const { data, diff } = splitTransaction(transactions, 't1');
+    expect(data.find(d => d.subtransactions)).toBeFalsy();
+
+    expect(diff).toEqual({
+      added: [expect.objectContaining({ amount: 0, parent_id: 't1' })],
+      deleted: [],
+      updated: [
+        {
+          id: 't1',
+          is_parent: true,
+          error: splitError(5000),
+        },
+      ],
+    });
+    expect(data).toEqual([
+      expect.objectContaining({
+        id: 't1',
+        amount: 5000,
+        error: splitError(5000),
+      }),
+      expect.objectContaining({ parent_id: 't1', amount: 0 }),
+      expect.objectContaining({ amount: 3000 }),
+    ]);
+  });
+
+  test('adding a split transaction works', () => {
+    const transactions = [
+      makeTransaction({ amount: 2001 }),
+      ...makeSplitTransaction({ id: 't1', amount: 2500 }, [
+        { id: 't2', amount: 2000 },
+        { id: 't3', amount: 500 },
+      ]),
+      makeTransaction({ amount: 3002 }),
+    ];
+
+    expect(transactions.filter(t => t.parent_id === 't1').length).toBe(2);
+
+    // Should be able to pass in any id from the split trans
+    const { data, diff } = addSplitTransaction(transactions, 't1');
+    expect(data.find(d => d.subtransactions)).toBeFalsy();
+
+    expect(data.filter(t => t.parent_id === 't1').length).toBe(3);
+    expect(diff).toEqual({
+      added: [
+        expect.objectContaining({
+          id: expect.any(String),
+          amount: 0,
+          parent_id: 't1',
+        }),
+      ],
+      deleted: [],
+      updated: [],
+    });
+    expect(data.length).toBe(6);
+  });
+
+  test('updating a split transaction works', () => {
+    const transactions = [
+      makeTransaction({ amount: 2001 }),
+      ...makeSplitTransaction({ id: 't1', amount: 2500 }, [
+        { id: 't2', amount: 2000 },
+        { id: 't3', amount: 500 },
+      ]),
+      makeTransaction({ amount: 3002 }),
+    ];
+    const { data, diff } = updateTransaction(
+      transactions,
+      makeTransaction({
+        id: 't2',
+        amount: 2200,
+      }),
+    );
+    expect(data.find(d => d.subtransactions)).toBeFalsy();
+    expect(diff).toEqual({
+      added: [],
+      deleted: [],
+      updated: [
+        { id: 't1', error: splitError(-200) },
+        { id: 't2', amount: 2200 },
+      ],
+    });
+    expect(data.length).toBe(5);
+  });
+
+  test('deleting a split transaction works', () => {
+    const transactions = [
+      makeTransaction({ amount: 2001 }),
+      ...makeSplitTransaction({ id: 't1', amount: 2500 }, [
+        { id: 't2', amount: 2000 },
+        { id: 't3', amount: 500 },
+      ]),
+      makeTransaction({ amount: 3002 }),
+    ];
+    const { data, diff } = deleteTransaction(transactions, 't2');
+
+    expect(diff).toEqual({
+      added: [],
+      deleted: [expect.objectContaining({ id: 't2' })],
+      updated: [{ id: 't1', error: splitError(2000) }],
+    });
+    expect(data).toEqual([
+      expect.objectContaining({ amount: 2001 }),
+      expect.objectContaining({
+        amount: 2500,
+        is_parent: true,
+        error: splitError(2000),
+      }),
+      expect.objectContaining({ amount: 500, parent_id: 't1' }),
+      expect.objectContaining({ amount: 3002 }),
+    ]);
+  });
+
+  test('deleting all child split transactions works', () => {
+    const transactions = [
+      makeTransaction({ amount: 2001 }),
+      ...makeSplitTransaction(
+        { id: 't1', amount: 2500, error: splitError(500) },
+        [{ id: 't2', amount: 2000 }],
+      ),
+      makeTransaction({ amount: 3002 }),
+    ];
+    const { data } = deleteTransaction(transactions, 't2');
+
+    expect(data).toEqual([
+      expect.objectContaining({ amount: 2001 }),
+      // Must delete error if no children
+      expect.objectContaining({ amount: 2500, error: null }),
+      expect.objectContaining({ amount: 3002 }),
+    ]);
+  });
+
+  test('unsplitting last remaining child converts parent to regular transaction', () => {
+    const [parent, child] = makeSplitTransaction(
+      { id: 't1', amount: 2000, category: 'cat1' },
+      [{ id: 't2', amount: 0, category: 'cat2' }],
+    );
+
+    const transactions = [parent, child];
+
+    const result = makeAsNonChildTransactions([child], transactions);
+
+    expect(result.updated).toHaveLength(1);
+    expect(result.deleted).toHaveLength(1);
+
+    expect(result.updated[0]).toMatchObject({
+      id: 't1',
+      amount: 2000,
+      is_parent: false,
+      category: 'cat2',
+    });
+
+    expect(result.deleted[0]).toMatchObject({
+      id: 't2',
+    });
+  });
+});

package/src/shared/transactions.ts

@@ -0,0 +1,433 @@
+import { v4 as uuidv4 } from 'uuid';
+
+import { logger } from '../platform/server/log';
+import type { TransactionEntity } from '../types/models';
+
+import { applyChanges, diffItems, last } from './util';
+
+export function isTemporaryId(id: string) {
+  return id.indexOf('temp') !== -1;
+}
+
+export function isPreviewId(id: string) {
+  return id.indexOf('preview/') !== -1;
+}
+
+// The amount might be null when adding a new transaction
+function num(n: number | null | undefined) {
+  return typeof n === 'number' ? n : 0;
+}
+
+function SplitTransactionError(total: number, parent: TransactionEntity) {
+  const difference = num(parent.amount) - total;
+
+  return {
+    type: 'SplitTransactionError' as const,
+    version: 1 as const,
+    difference,
+  };
+}
+
+type GenericTransactionEntity = TransactionEntity;
+
+export function makeChild<T extends GenericTransactionEntity>(
+  parent: T,
+  data: object = {},
+) {
+  const prefix = parent.id === 'temp' ? 'temp' : '';
+
+  return {
+    amount: 0,
+    ...data,
+    category: 'category' in data ? data.category : parent.category,
+    payee: 'payee' in data ? data.payee : parent.payee,
+    id: 'id' in data ? data.id : prefix + uuidv4(),
+    account: parent.account,
+    date: parent.date,
+    cleared: parent.cleared != null ? parent.cleared : null,
+    reconciled: 'reconciled' in data ? data.reconciled : parent.reconciled,
+    starting_balance_flag:
+      parent.starting_balance_flag != null
+        ? parent.starting_balance_flag
+        : null,
+    is_child: true,
+    parent_id: parent.id,
+    error: null,
+  } as unknown as T;
+}
+
+function makeNonChild<T extends GenericTransactionEntity>(
+  parent: T,
+  data: object,
+) {
+  return {
+    amount: 0,
+    ...data,
+    cleared: parent.cleared != null ? parent.cleared : null,
+    reconciled: parent.reconciled != null ? parent.reconciled : null,
+    sort_order: parent.sort_order || null,
+    starting_balance_flag: null,
+    is_child: false,
+    parent_id: null,
+  } as unknown as T;
+}
+
+function makeTransactionWithChildCategory<T extends GenericTransactionEntity>(
+  parent: T,
+  data: Partial<TransactionEntity>,
+) {
+  return {
+    ...parent,
+    is_parent: false,
+    category: data.category || null,
+  } as unknown as T;
+}
+
+export function recalculateSplit(trans: TransactionEntity) {
+  // Calculate the new total of split transactions and make sure
+  // that it equals the parent amount
+  const total = (trans.subtransactions || []).reduce(
+    (acc, t) => acc + num(t.amount),
+    0,
+  );
+
+  const { error: _error, ...rest } = trans;
+  return {
+    ...rest,
+    error:
+      total === num(trans.amount) ? null : SplitTransactionError(total, trans),
+  } satisfies TransactionEntity;
+}
+
+function findParentIndex(
+  transactions: readonly TransactionEntity[],
+  idx: number,
+) {
+  // This relies on transactions being sorted in a way where parents
+  // are always before children, which is enforced in the db layer.
+  // Walk backwards and find the last parent;
+  while (idx >= 0) {
+    const trans = transactions[idx];
+    if (trans.is_parent) {
+      return idx;
+    }
+    idx--;
+  }
+  return null;
+}
+
+function getSplit(
+  transactions: readonly TransactionEntity[],
+  parentIndex: number,
+) {
+  const split = [transactions[parentIndex]];
+  let curr = parentIndex + 1;
+  while (curr < transactions.length && transactions[curr].is_child) {
+    split.push(transactions[curr]);
+    curr++;
+  }
+  return split;
+}
+
+export function ungroupTransactions(transactions: TransactionEntity[]) {
+  return transactions.reduce<TransactionEntity[]>((list, parent) => {
+    const { subtransactions, ...trans } = parent;
+    const _subtransactions = subtransactions || [];
+
+    list.push(trans);
+
+    for (let i = 0; i < _subtransactions.length; i++) {
+      list.push(_subtransactions[i]);
+    }
+    return list;
+  }, []);
+}
+
+export function groupTransaction(
+  split: TransactionEntity[],
+): TransactionEntity {
+  return {
+    ...split[0],
+    subtransactions: split.slice(1),
+  } satisfies TransactionEntity;
+}
+
+export function ungroupTransaction(split: TransactionEntity | null) {
+  if (split == null) {
+    return [];
+  }
+  return ungroupTransactions([split]);
+}
+
+export function applyTransactionDiff(
+  groupedTrans: Parameters<typeof ungroupTransaction>[0],
+  diff: Parameters<typeof applyChanges>[0],
+) {
+  return groupTransaction(
+    applyChanges(
+      diff,
+      ungroupTransaction(groupedTrans) || [],
+    ) as TransactionEntity[],
+  );
+}
+
+function replaceTransactions(
+  transactions: readonly TransactionEntity[],
+  id: string,
+  func: (transaction: TransactionEntity) => TransactionEntity | null,
+): {
+  data: TransactionEntity[];
+  newTransaction: TransactionEntity | null;
+  diff: ReturnType<typeof diffItems<TransactionEntity>>;
+} {
+  const idx = transactions.findIndex(t => t.id === id);
+  const trans = transactions[idx];
+  const transactionsCopy = [...transactions];
+
+  if (idx === -1) {
+    throw new Error('Tried to edit unknown transaction id: ' + id);
+  }
+
+  if (trans.is_parent || trans.is_child) {
+    const parentIndex = findParentIndex(transactions, idx);
+    if (parentIndex == null) {
+      logger.log('Cannot find parent index');
+      return {
+        data: [],
+        diff: { added: [], deleted: [], updated: [] },
+        newTransaction: null,
+      };
+    }
+
+    const split = getSplit(transactions, parentIndex);
+    let grouped = func(groupTransaction(split));
+    const newSplit = ungroupTransaction(grouped);
+
+    let diff: ReturnType<typeof diffItems<TransactionEntity>>;
+    if (newSplit == null) {
+      // If everything was deleted, just delete the parent which will
+      // delete everything
+      diff = { added: [], deleted: [{ id: split[0].id }], updated: [] };
+      grouped = { ...split[0], _deleted: true };
+      transactionsCopy.splice(parentIndex, split.length);
+    } else {
+      diff = diffItems<TransactionEntity>(split, newSplit);
+      transactionsCopy.splice(parentIndex, split.length, ...newSplit);
+    }
+
+    return { data: transactionsCopy, newTransaction: grouped, diff };
+  } else {
+    const grouped = func(trans);
+    const newTrans = ungroupTransaction(grouped) || [];
+    if (grouped) {
+      grouped.subtransactions = grouped.subtransactions || [];
+    }
+    transactionsCopy.splice(idx, 1, ...newTrans);
+
+    return {
+      data: transactionsCopy,
+      newTransaction: grouped || {
+        ...trans,
+        _deleted: true,
+      },
+      diff: diffItems<TransactionEntity>([trans], newTrans),
+    };
+  }
+}
+
+export function addSplitTransaction(
+  transactions: readonly TransactionEntity[],
+  id: string,
+) {
+  return replaceTransactions(transactions, id, trans => {
+    if (!trans.is_parent) {
+      return trans;
+    }
+    const prevSub = last(trans.subtransactions || []);
+    trans.subtransactions?.push(
+      makeChild(trans, {
+        amount: 0,
+        sort_order: num(prevSub && prevSub.sort_order) - 1,
+      }),
+    );
+    return trans;
+  });
+}
+
+export function updateTransaction(
+  transactions: readonly TransactionEntity[],
+  transaction: TransactionEntity,
+) {
+  return replaceTransactions(transactions, transaction.id, trans => {
+    if (trans.is_parent) {
+      const parent = trans.id === transaction.id ? transaction : trans;
+      const originalSubtransactions =
+        parent.subtransactions ?? trans.subtransactions;
+      const sub = originalSubtransactions?.map(t => {
+        // Make sure to update the children to reflect the updated
+        // properties (if the parent updated)
+
+        let child = t;
+        if (trans.id === transaction.id) {
+          const { payee: childPayee, ...rest } = t;
+          const newPayee =
+            childPayee === trans.payee ? transaction.payee : childPayee;
+          child = {
+            ...rest,
+            ...(newPayee != null ? { payee: newPayee } : {}),
+          };
+        } else if (t.id === transaction.id) {
+          child = transaction;
+        }
+
+        return makeChild(parent, child);
+      });
+
+      return recalculateSplit({
+        ...parent,
+        ...(sub && { subtransactions: sub }),
+      });
+    } else {
+      return transaction;
+    }
+  });
+}
+
+export function deleteTransaction(
+  transactions: TransactionEntity[],
+  id: string,
+) {
+  return replaceTransactions(transactions, id, trans => {
+    if (trans.is_parent) {
+      if (trans.id === id) {
+        return null;
+      } else if (trans.subtransactions?.length === 1) {
+        const { subtransactions: _subtransactions, ...rest } = trans;
+        return {
+          ...rest,
+          is_parent: false,
+          error: null,
+        } satisfies TransactionEntity;
+      } else {
+        const sub = trans.subtransactions?.filter(t => t.id !== id);
+        return recalculateSplit({
+          ...trans,
+          ...(sub && { subtransactions: sub }),
+        });
+      }
+    } else {
+      return null;
+    }
+  });
+}
+
+export function splitTransaction(
+  transactions: readonly TransactionEntity[],
+  id: string,
+  createSubtransactions?: (
+    parentTransaction: TransactionEntity,
+  ) => TransactionEntity[],
+) {
+  return replaceTransactions(transactions, id, trans => {
+    if (trans.is_parent || trans.is_child) {
+      return trans;
+    }
+
+    const subtransactions = createSubtransactions?.(trans) || [
+      makeChild(trans),
+    ];
+
+    const { error: _error, ...rest } = trans;
+
+    return {
+      ...rest,
+      is_parent: true,
+      error: num(trans.amount) === 0 ? null : SplitTransactionError(0, trans),
+      subtransactions: subtransactions.map(t => ({
+        ...t,
+        sort_order: t.sort_order || -1,
+      })),
+    } satisfies TransactionEntity;
+  });
+}
+
+export function realizeTempTransactions(
+  transactions: TransactionEntity[],
+): TransactionEntity[] {
+  const parent = {
+    ...transactions.find(t => !t.is_child),
+    id: uuidv4(),
+    sort_order: Date.now(),
+  } as TransactionEntity;
+  const children = transactions.filter(t => t.is_child);
+  return [
+    parent,
+    ...children.map(
+      child =>
+        ({
+          ...child,
+          id: uuidv4(),
+          parent_id: parent.id,
+        }) satisfies TransactionEntity,
+    ),
+  ];
+}
+
+export function makeAsNonChildTransactions(
+  childTransactionsToUpdate: TransactionEntity[],
+  transactions: TransactionEntity[],
+) {
+  const [parentTransaction, ...childTransactions] = transactions;
+  const newNonChildTransactions = childTransactionsToUpdate.map(t =>
+    makeNonChild(parentTransaction, t),
+  );
+
+  const remainingChildTransactions = childTransactions.filter(
+    t =>
+      !newNonChildTransactions.some(updatedTrans => updatedTrans.id === t.id),
+  );
+  if (
+    childTransactions.length === 1 &&
+    childTransactionsToUpdate.length === 1 &&
+    childTransactionsToUpdate[0].id === childTransactions[0].id
+  ) {
+    return {
+      updated: [
+        makeTransactionWithChildCategory(
+          parentTransaction,
+          childTransactionsToUpdate[0],
+        ),
+      ],
+      deleted: [childTransactionsToUpdate[0]],
+    };
+  }
+
+  const nonChildTransactionsToUpdate =
+    remainingChildTransactions.length === 1
+      ? [
+          ...newNonChildTransactions,
+          makeNonChild(parentTransaction, remainingChildTransactions[0]),
+        ]
+      : newNonChildTransactions;
+
+  const deleteParentTransaction = remainingChildTransactions.length <= 1;
+
+  const updatedParentTransaction = {
+    ...parentTransaction,
+    ...(!deleteParentTransaction
+      ? {
+          amount: remainingChildTransactions
+            .map(t => t.amount)
+            .reduce((total, amount) => total + amount, 0),
+        }
+      : {}),
+  };
+
+  return {
+    updated: [
+      ...(!deleteParentTransaction ? [updatedParentTransaction] : []),
+      ...nonChildTransactionsToUpdate,
+    ],
+    deleted: [...(deleteParentTransaction ? [updatedParentTransaction] : [])],
+  };
+}