Add BALANCE_OF() function to fetch balance of an arbitrary account

Author: StephenBrown2

packages/desktop-client/src/components/formula/transactionModeFunctions.ts

@@ -58,6 +58,18 @@ export const transactionModeFunctions: Record<string, FunctionDef> = {
       },
     ],
   },
+  BALANCE_OF: {
+    name: 'BALANCE_OF',
+    description: t(
+      'Running balance for another account (cents) at this transaction, same cutoff as balance. Use a quoted account id for a deterministic match, or a quoted account name. Use the balance variable instead for the current account.',
+    ),
+    parameters: [
+      {
+        name: 'account_id_or_name',
+        description: t('Quoted account id or exact account name'),
+      },
+    ],
+  },
   MID: {
     name: 'MID',
     description: t('Returns substring from specified position.'),

packages/docs/docs/experimental/formulas.md

@@ -290,6 +290,13 @@ Rule formulas evaluate with named variables from the transaction context, includ
   - Represents the running balance at this transaction
   - To convert to dollars: `=balance / 100`
 
+**`BALANCE_OF` function (other accounts):**
+
+- `BALANCE_OF("…")` — Running balance for another account, in **cents**, using the same cutoff as `balance` (same `date`, `sort_order`, and `id` ordering as the current transaction).
+- Pass a **quoted account id** (matches an account id in your budget) for a deterministic result, or a **quoted account name** for an exact name match. If the account name is ambiguous (duplicates), the first match is used.
+- If the account is not found, the value is **0**.
+- For the **current** transaction’s account, use the `balance` variable instead of `BALANCE_OF`.
+
 **Text variables:**
 
 - `notes` — Transaction notes/memo field (string, may be empty)

packages/loot-core/src/server/budget/schedule-template.test.ts

@@ -20,6 +20,7 @@ vi.mock('../schedules/app', async () => {
 describe('runSchedule', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    vi.mocked(db.getAccounts).mockResolvedValue([]);
   });
 
   it('should return correct budget when recurring schedule set', async () => {

packages/loot-core/src/server/budget/schedule-template.ts

@@ -8,10 +8,12 @@ import {
   getDateWithSkippedWeekend,
   getNextDate,
 } from '../../shared/schedules';
-import type { CategoryEntity } from '../../types/models';
+import type { CategoryEntity, TransactionEntity } from '../../types/models';
 import type { ScheduleTemplate, Template } from '../../types/models/templates';
 import * as db from '../db';
+import { collectFormulasFromActions } from '../rules/balanceOfFormula';
 import { getRuleForSchedule } from '../schedules/app';
+import { prefetchBalanceOfForTransaction } from '../transactions/transaction-rules';
 
 import { getSheetValue, isReflectBudget } from './actions';
 
@@ -74,10 +76,31 @@ async function createScheduleList(
 
     scheduleAmount = Math.round(scheduleAmount);
 
-    const { amount: postRuleAmount, subtransactions } = rule.execActions({
+    const next_date_string = getNextDate(
+      dateConditions,
+      monthUtils._parse(current_month),
+    );
+
+    const accounts = (await db.getAccounts()) ?? [];
+    const accountsMap = new Map(accounts.map(a => [a.id, a]));
+    const scheduleRuleContext: TransactionEntity = {
       amount: scheduleAmount,
       category: category.id,
       subtransactions: [],
+      ...(next_date_string ? { date: next_date_string } : {}),
+      id: null,
+      sort_order: null,
+    } as TransactionEntity;
+    const formulaStrings = collectFormulasFromActions(rule.actions);
+    const balanceOfPrefetched = await prefetchBalanceOfForTransaction(
+      scheduleRuleContext,
+      accountsMap,
+      formulaStrings,
+    );
+
+    const { amount: postRuleAmount, subtransactions } = rule.execActions({
+      ...scheduleRuleContext,
+      _balanceOfPrefetched: balanceOfPrefetched,
     });
     const categorySubtransactions = subtransactions?.filter(
       t => t.category === category.id,
@@ -91,10 +114,6 @@ async function createScheduleList(
         ? categorySubtransactions.reduce((acc, t) => acc + t.amount, 0)
         : (postRuleAmount ?? scheduleAmount));
 
-    const next_date_string = getNextDate(
-      dateConditions,
-      monthUtils._parse(current_month),
-    );
     const target_interval = dateConditions.value.interval
       ? dateConditions.value.interval
       : 1;

packages/loot-core/src/server/rules/action.ts

@@ -10,6 +10,7 @@ import { currentDay, format, parseDate } from '../../shared/months';
 import { FIELD_TYPES } from '../../shared/rules';
 import type { TransactionForRules } from '../transactions/transaction-rules';
 
+import { substituteBalanceOfLiterals } from './balanceOfFormula';
 import {
   CustomFunctionsPlugin,
   customFunctionsTranslations,
@@ -324,6 +325,9 @@ export class Action {
       };
 
       for (const key of Object.keys(fieldValues)) {
+        if (key === '_balanceOfPrefetched') {
+          continue;
+        }
         let cellValue: string | number | boolean;
         if (
           fieldValues[key] === undefined ||
@@ -337,8 +341,13 @@ export class Action {
         hfInstance.addNamedExpression(key, cellValue);
       }
 
+      const evaluatedFormula = substituteBalanceOfLiterals(
+        formula,
+        transaction._balanceOfPrefetched,
+      );
+
       hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [
-        [formula],
+        [evaluatedFormula],
       ]);
 
       const cellAddress = { sheet: sheetId, col: 0, row: 0 };

packages/loot-core/src/server/rules/balanceOfFormula.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import type * as db from '../db';
+
+import {
+  decodeBalanceOfQuotedLiteral,
+  extractBalanceOfLiterals,
+  resolveAccountIdForBalanceOf,
+  substituteBalanceOfLiterals,
+} from './balanceOfFormula';
+
+describe('balanceOfFormula', () => {
+  it('extractBalanceOfLiterals returns distinct decoded literals', () => {
+    expect(
+      extractBalanceOfLiterals(
+        '=BALANCE_OF("Checking") + BALANCE_OF("Checking")',
+      ),
+    ).toEqual(['Checking']);
+    expect(extractBalanceOfLiterals('=balance_of("Savings")')).toEqual([
+      'Savings',
+    ]);
+  });
+
+  it('decodeBalanceOfQuotedLiteral unescapes quotes and backslashes', () => {
+    expect(decodeBalanceOfQuotedLiteral(String.raw`\"x\"`)).toBe('"x"');
+  });
+
+  it('substituteBalanceOfLiterals replaces calls with cent literals', () => {
+    const map = new Map([
+      ['Checking', 42],
+      ['id-1', 99],
+    ]);
+    expect(substituteBalanceOfLiterals('=BALANCE_OF("Checking")+1', map)).toBe(
+      '=42+1',
+    );
+    expect(substituteBalanceOfLiterals('=BALANCE_OF("Missing")', map)).toBe(
+      '=0',
+    );
+  });
+
+  it('resolveAccountIdForBalanceOf prefers map key then name', () => {
+    const id = 'acc-1';
+    const a1: db.DbAccount = {
+      id,
+      name: 'Dup',
+      offbudget: 0,
+    } as db.DbAccount;
+    const a2: db.DbAccount = {
+      id: 'acc-2',
+      name: 'Other',
+      offbudget: 0,
+    } as db.DbAccount;
+    const map = new Map<string, db.DbAccount>([
+      [id, a1],
+      ['acc-2', a2],
+    ]);
+    expect(resolveAccountIdForBalanceOf(id, map)).toBe(id);
+    expect(resolveAccountIdForBalanceOf('Other', map)).toBe('acc-2');
+    expect(resolveAccountIdForBalanceOf('Nope', map)).toBe(null);
+  });
+});

packages/loot-core/src/server/rules/balanceOfFormula.ts

@@ -0,0 +1,74 @@
+import type * as db from '../db';
+
+/** Collect formula strings from serialized or live rule actions. */
+export function collectFormulasFromActions(
+  actions: Array<{ options?: { formula?: string } }>,
+): string[] {
+  const out: string[] = [];
+  for (const action of actions) {
+    const f = action.options?.formula;
+    if (typeof f === 'string') {
+      out.push(f);
+    }
+  }
+  return out;
+}
+
+/** Decode escape sequences inside a double-quoted formula string literal. */
+export function decodeBalanceOfQuotedLiteral(inner: string): string {
+  return inner.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+/**
+ * Distinct decoded string literals from BALANCE_OF("…") calls in a formula.
+ */
+export function extractBalanceOfLiterals(formula: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const re = /BALANCE_OF\s*\(\s*"((?:[^"\\]|\\.)*)"\s*\)/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(formula)) !== null) {
+    const decoded = decodeBalanceOfQuotedLiteral(m[1]);
+    if (!seen.has(decoded)) {
+      seen.add(decoded);
+      out.push(decoded);
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve account id: map key (id) first, else first exact name match.
+ */
+export function resolveAccountIdForBalanceOf(
+  literal: string,
+  accountsMap: Map<string, db.DbAccount>,
+): string | null {
+  if (accountsMap.has(literal)) {
+    return literal;
+  }
+  for (const acc of accountsMap.values()) {
+    if (acc.name === literal) {
+      return acc.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Replace each BALANCE_OF("…") with a cent literal so HyperFormula never needs
+ * runtime DB (prefetch map is keyed by decoded string literals).
+ */
+export function substituteBalanceOfLiterals(
+  formula: string,
+  map: Map<string, number> | null | undefined,
+): string {
+  return formula.replace(
+    /BALANCE_OF\s*\(\s*"((?:[^"\\]|\\.)*)"\s*\)/gi,
+    (_match, inner: string) => {
+      const key = decodeBalanceOfQuotedLiteral(inner);
+      const cents = map?.get(key) ?? 0;
+      return String(cents);
+    },
+  );
+}

packages/loot-core/src/server/rules/formula-action.test.ts

@@ -111,6 +111,41 @@ describe('Formula-based rule actions', () => {
     expect(result).toBe(300000);
   });
 
+  it('should support BALANCE_OF with prefetched map', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction: Partial<TransactionForRules> = {
+      notes: 'original',
+      _balanceOfPrefetched: new Map([
+        ['Savings', 50000],
+        ['550e8400-e29b-41d4-a716-446655440000', 1200],
+      ]),
+    };
+    const byName = action.executeFormulaSync(
+      '=BALANCE_OF("Savings") + 100',
+      transaction,
+    );
+    expect(byName).toBe(5010000);
+
+    const byId = action.executeFormulaSync(
+      '=BALANCE_OF("550e8400-e29b-41d4-a716-446655440000")',
+      transaction,
+    );
+    expect(byId).toBe(120000);
+  });
+
+  it('should return 0 for BALANCE_OF when literal missing from prefetch map', () => {
+    const action = new Action('set', 'amount', null, {});
+    const transaction: Partial<TransactionForRules> = {
+      amount: 100,
+      _balanceOfPrefetched: new Map(),
+    };
+    const result = action.executeFormulaSync(
+      '=BALANCE_OF("Unknown")',
+      transaction,
+    );
+    expect(result).toBe(0);
+  });
+
   it('should execute formula and convert to number type', () => {
     const action = new Action('set', 'amount', null, {
       formula: '=500 + 250',

packages/loot-core/src/server/rules/rule.ts

@@ -45,6 +45,10 @@ function execSplitActions(actions: Action[], transaction) {
     }
     newTransactions[splitTransactionIndex].parent_amount = transaction.amount;
     newTransactions[splitTransactionIndex].balance = transaction.balance;
+    if (transaction._balanceOfPrefetched) {
+      newTransactions[splitTransactionIndex]._balanceOfPrefetched =
+        transaction._balanceOfPrefetched;
+    }
     action.exec(newTransactions[splitTransactionIndex]);
   });