[PR #7335] [MERGED] [AI] Add BALANCE_OF() function to fetch balance of an arbitrary account #48912

Closed
opened 2026-04-26 10:47:16 -05:00 by GiteaMirror · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/actualbudget/actual/pull/7335
Author: @StephenBrown2
Created: 3/30/2026
Status: Merged
Merged: 4/14/2026
Merged by: @youngcw

Base: masterHead: push-mmnmmrvoszkr


📝 Commits (10+)

  • e808724 Add BALANCE_OF() function to fetch balance of an arbitrary account
  • bf6d57a Update VRT screenshots
  • e2eb1b6 Adjust docs
  • 864cc0d [autofix.ci] apply automated fixes
  • 3e1e59e Update tests to verify sidebar balances
  • 9eacc8a Add comments to schedule-template.ts
  • 6b0e867 Update index.ts to recompute sidebar balances
  • 11eae61 [autofix.ci] apply automated fixes
  • cd03a6c Update VRT screenshots
  • 379d701 Address CodeRabbit comments

📊 Changes

19 files changed (+437 additions, -56 deletions)

View changed files

📝 packages/desktop-client/e2e/page-models/account-page.ts (+13 -0)
📝 packages/desktop-client/e2e/transactions.test.ts (+14 -0)
📝 packages/desktop-client/src/components/formula/transactionModeFunctions.ts (+12 -0)
📝 packages/desktop-client/src/components/sidebar/Account.tsx (+11 -1)
📝 packages/desktop-client/src/components/sidebar/Accounts.tsx (+3 -0)
📝 packages/desktop-client/src/hooks/useFormulaExecution.ts (+1 -1)
📝 packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts (+26 -4)
📝 packages/docs/docs/experimental/formulas.md (+16 -0)
📝 packages/loot-core/src/server/budget/schedule-template.test.ts (+1 -0)
📝 packages/loot-core/src/server/budget/schedule-template.ts (+34 -6)
📝 packages/loot-core/src/server/rules/action.ts (+6 -0)
packages/loot-core/src/server/rules/balanceOfFormula.test.ts (+47 -0)
packages/loot-core/src/server/rules/balanceOfFormula.ts (+56 -0)
📝 packages/loot-core/src/server/rules/customFunctions.ts (+26 -7)
📝 packages/loot-core/src/server/rules/formula-action.test.ts (+35 -0)
📝 packages/loot-core/src/server/rules/rule.ts (+2 -0)
📝 packages/loot-core/src/server/sync/index.ts (+22 -1)
📝 packages/loot-core/src/server/transactions/transaction-rules.ts (+106 -36)
upcoming-release-notes/7335.md (+6 -0)

📄 Description

Description

This PR adds BALANCE_OF("…") for rule formulas (the ƒ formula mode on Set actions and split-amount formulas).

  • What it does: You can reference the running balance of another account (in cents, same semantics as the existing balance variable) at the same transaction cutoff as the current row (date, sort_order, id ordering).
  • How the argument is resolved: The quoted string is matched first as an account id (if it exists as a key in the accounts map), then as an exact account name. Unknown accounts resolve to 0; duplicate names use the first match (documented).
  • Current account: For the transaction’s own account, users should keep using the balance variable; BALANCE_OF is for other accounts.
  • Implementation notes: Balances are prefetched in existing async paths (runRules, applyActions, schedule template) into _balanceOfPrefetched on the transaction object. Before HyperFormula runs, substituteBalanceOfLiterals replaces each BALANCE_OF("…") with a numeric cent literal so formula execution stays synchronous and we avoid a HyperFormula plugin that needs DB access. getRunningBalanceBeforeTransaction is shared with prepareTransactionForRules for the existing balance field. Split rule actions receive the same prefetch map as the parent row; finalizeTransactionForRules strips internal fields.

https://discord.com/channels/937901803608096828/1488212143923921088

Testing

Automated

  • packages/loot-core: balanceOfFormula.test.ts (literal extraction, substitution, id vs name resolution).
  • packages/loot-core: formula-action.test.ts (prefetched map + missing literal → 0).

Manual

  • Create or edit a rule with a formula that uses =BALANCE_OF("Your Account Name") or =BALANCE_OF("<account-id>") and confirm the Set field result matches expectations vs the register for that account.
  • Smoke-test schedule flows that run rule actions if you use rules with formulas there.

Checklist

  • Release notes added (see link above)
  • No obvious regressions in affected areas
  • Self-review has been performed - I understand what each change in the code does and why it is needed

Bundle Stats

Bundle Files count Total bundle size % Changed
desktop-client 28 12.91 MB → 12.91 MB (+1.21 kB) +0.01%
loot-core 1 4.84 MB → 4.84 MB (+3.72 kB) +0.08%
api 1 3.88 MB → 3.88 MB (+4.05 kB) +0.10%
cli 1 7.89 MB 0%
View detailed bundle stats

desktop-client

Total

Files count Total bundle size % Changed
28 12.91 MB → 12.91 MB (+1.21 kB) +0.01%
Changeset
File Δ Size
home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts 📈 +327 B (+30.45%) 1.05 kB → 1.37 kB
src/components/formula/transactionModeFunctions.ts 📈 +404 B (+2.89%) 13.64 kB → 14.04 kB
src/components/sidebar/Account.tsx 📈 +358 B (+2.84%) 12.32 kB → 12.67 kB
src/components/sidebar/Accounts.tsx 📈 +145 B (+1.64%) 8.63 kB → 8.77 kB
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger

Asset File Size % Changed
static/js/index.js 3.32 MB → 3.32 MB (+503 B) +0.01%
static/js/FormulaEditor.js 852.77 kB → 853.16 kB (+404 B) +0.05%
static/js/Value.js 4.33 MB → 4.33 MB (+327 B) +0.01%

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
static/js/BackgroundImage.js 121.09 kB 0%
static/js/ReportRouter.js 1.18 MB 0%
static/js/TransactionList.js 82.49 kB 0%
static/js/ca.js 191.98 kB 0%
static/js/da.js 104.66 kB 0%
static/js/de.js 174.38 kB 0%
static/js/en-GB.js 8.2 kB 0%
static/js/en.js 175.89 kB 0%
static/js/es.js 181.8 kB 0%
static/js/extends.js 485.17 kB 0%
static/js/fr.js 177.08 kB 0%
static/js/indexeddb-main-thread-worker-e59fee74.js 13.46 kB 0%
static/js/it.js 165.95 kB 0%
static/js/narrow.js 363.02 kB 0%
static/js/nb-NO.js 151.85 kB 0%
static/js/nl.js 108.93 kB 0%
static/js/pl.js 88.34 kB 0%
static/js/pt-BR.js 177.44 kB 0%
static/js/resize-observer.js 18.06 kB 0%
static/js/th.js 179.3 kB 0%
static/js/theme.js 30.79 kB 0%
static/js/uk.js 212.6 kB 0%
static/js/wide.js 295 B 0%
static/js/workbox-window.prod.es5.js 7.33 kB 0%
static/js/zh-Hans.js 110.19 kB 0%

loot-core

Total

Files count Total bundle size % Changed
1 4.84 MB → 4.84 MB (+3.72 kB) +0.08%
Changeset
File Δ Size
home/runner/work/actual/actual/packages/loot-core/src/server/rules/balanceOfFormula.ts 🆕 +965 B 0 B → 965 B
home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts 📈 +337 B (+30.69%) 1.07 kB → 1.4 kB
home/runner/work/actual/actual/packages/loot-core/src/server/transactions/transaction-rules.ts 📈 +1.36 kB (+6.98%) 19.56 kB → 20.92 kB
home/runner/work/actual/actual/packages/loot-core/src/server/budget/schedule-template.ts 📈 +507 B (+6.95%) 7.13 kB → 7.62 kB
home/runner/work/actual/actual/packages/loot-core/src/server/sync/index.ts 📈 +350 B (+2.48%) 13.77 kB → 14.12 kB
home/runner/work/actual/actual/packages/loot-core/src/server/rules/rule.ts 📈 +99 B (+2.22%) 4.36 kB → 4.46 kB
home/runner/work/actual/actual/packages/loot-core/src/server/rules/action.ts 📈 +154 B (+1.92%) 7.84 kB → 7.99 kB
View detailed bundle breakdown

Added

Asset File Size % Changed
kcab.worker.B_XN_qvd.js 0 B → 4.84 MB (+4.84 MB) -

Removed

Asset File Size % Changed
kcab.worker.DZcmk4OR.js 4.84 MB → 0 B (-4.84 MB) -100%

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged
No assets were unchanged


api

Total

Files count Total bundle size % Changed
1 3.88 MB → 3.88 MB (+4.05 kB) +0.10%
Changeset
File Δ Size
home/runner/work/actual/actual/packages/loot-core/src/server/rules/balanceOfFormula.ts 🆕 +1.23 kB 0 B → 1.23 kB
home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts 📈 +327 B (+30.39%) 1.05 kB → 1.37 kB
home/runner/work/actual/actual/packages/loot-core/src/server/transactions/transaction-rules.ts 📈 +1.44 kB (+7.56%) 19.08 kB → 20.52 kB
home/runner/work/actual/actual/packages/loot-core/src/server/budget/schedule-template.ts 📈 +496 B (+6.93%) 6.99 kB → 7.47 kB
home/runner/work/actual/actual/packages/loot-core/src/server/sync/index.ts 📈 +338 B (+2.47%) 13.35 kB → 13.68 kB
home/runner/work/actual/actual/packages/loot-core/src/server/rules/rule.ts 📈 +98 B (+2.33%) 4.11 kB → 4.2 kB
home/runner/work/actual/actual/packages/loot-core/src/server/rules/action.ts 📈 +152 B (+2.01%) 7.39 kB → 7.54 kB
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger

Asset File Size % Changed
index.js 3.88 MB → 3.88 MB (+4.05 kB) +0.10%

Smaller
No assets were smaller

Unchanged
No assets were unchanged


cli

Total

Files count Total bundle size % Changed
1 7.89 MB 0%
View detailed bundle breakdown

Added
No assets were added

Removed
No assets were removed

Bigger
No assets were bigger

Smaller
No assets were smaller

Unchanged

Asset File Size % Changed
cli.js 7.89 MB 0%

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/actualbudget/actual/pull/7335 **Author:** [@StephenBrown2](https://github.com/StephenBrown2) **Created:** 3/30/2026 **Status:** ✅ Merged **Merged:** 4/14/2026 **Merged by:** [@youngcw](https://github.com/youngcw) **Base:** `master` ← **Head:** `push-mmnmmrvoszkr` --- ### 📝 Commits (10+) - [`e808724`](https://github.com/actualbudget/actual/commit/e808724de792353fcd6ea5a7ddb3e70de3e663a0) Add BALANCE_OF() function to fetch balance of an arbitrary account - [`bf6d57a`](https://github.com/actualbudget/actual/commit/bf6d57a3ecd139e62a27ed21a382d00f3b00657b) Update VRT screenshots - [`e2eb1b6`](https://github.com/actualbudget/actual/commit/e2eb1b656a1f6515723bf331110e90bb39964a90) Adjust docs - [`864cc0d`](https://github.com/actualbudget/actual/commit/864cc0deccc291dc9ce9817c8282add6c988eacc) [autofix.ci] apply automated fixes - [`3e1e59e`](https://github.com/actualbudget/actual/commit/3e1e59e27f713af32eeda1fc316ba7b9cb484d68) Update tests to verify sidebar balances - [`9eacc8a`](https://github.com/actualbudget/actual/commit/9eacc8abc40efa4c78a7a836ef58aadda3f81bfb) Add comments to schedule-template.ts - [`6b0e867`](https://github.com/actualbudget/actual/commit/6b0e867d32c0dcc99b32315e4b1cbc7208352f67) Update index.ts to recompute sidebar balances - [`11eae61`](https://github.com/actualbudget/actual/commit/11eae61bd33b74f3a96a2bb1ae9bd23804ac04d7) [autofix.ci] apply automated fixes - [`cd03a6c`](https://github.com/actualbudget/actual/commit/cd03a6cb90fdb0cca6df152e90b422bc7c6cdfa9) Update VRT screenshots - [`379d701`](https://github.com/actualbudget/actual/commit/379d7011a1ae1e24ffef0c7ca95ffcfdc0fd1aad) Address CodeRabbit comments ### 📊 Changes **19 files changed** (+437 additions, -56 deletions) <details> <summary>View changed files</summary> 📝 `packages/desktop-client/e2e/page-models/account-page.ts` (+13 -0) 📝 `packages/desktop-client/e2e/transactions.test.ts` (+14 -0) 📝 `packages/desktop-client/src/components/formula/transactionModeFunctions.ts` (+12 -0) 📝 `packages/desktop-client/src/components/sidebar/Account.tsx` (+11 -1) 📝 `packages/desktop-client/src/components/sidebar/Accounts.tsx` (+3 -0) 📝 `packages/desktop-client/src/hooks/useFormulaExecution.ts` (+1 -1) 📝 `packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts` (+26 -4) 📝 `packages/docs/docs/experimental/formulas.md` (+16 -0) 📝 `packages/loot-core/src/server/budget/schedule-template.test.ts` (+1 -0) 📝 `packages/loot-core/src/server/budget/schedule-template.ts` (+34 -6) 📝 `packages/loot-core/src/server/rules/action.ts` (+6 -0) ➕ `packages/loot-core/src/server/rules/balanceOfFormula.test.ts` (+47 -0) ➕ `packages/loot-core/src/server/rules/balanceOfFormula.ts` (+56 -0) 📝 `packages/loot-core/src/server/rules/customFunctions.ts` (+26 -7) 📝 `packages/loot-core/src/server/rules/formula-action.test.ts` (+35 -0) 📝 `packages/loot-core/src/server/rules/rule.ts` (+2 -0) 📝 `packages/loot-core/src/server/sync/index.ts` (+22 -1) 📝 `packages/loot-core/src/server/transactions/transaction-rules.ts` (+106 -36) ➕ `upcoming-release-notes/7335.md` (+6 -0) </details> ### 📄 Description <!-- Thank you for submitting a pull request! Make sure to follow the instructions to write release notes for your PR — it should only take a minute or two: https://github.com/actualbudget/docs#writing-good-release-notes. Try running yarn generate:release-notes *before* pushing your PR for an interactive experience. --> ## Description This PR adds **`BALANCE_OF("…")`** for **rule formulas** (the ƒ formula mode on Set actions and split-amount formulas). - **What it does:** You can reference the **running balance of another account** (in **cents**, same semantics as the existing `balance` variable) at the **same transaction cutoff** as the current row (`date`, `sort_order`, `id` ordering). - **How the argument is resolved:** The quoted string is matched first as an **account id** (if it exists as a key in the accounts map), then as an **exact account name**. Unknown accounts resolve to **0**; duplicate names use the first match (documented). - **Current account:** For the transaction’s own account, users should keep using the **`balance`** variable; `BALANCE_OF` is for *other* accounts. - **Implementation notes:** Balances are **prefetched** in existing async paths (`runRules`, `applyActions`, schedule template) into `_balanceOfPrefetched` on the transaction object. Before HyperFormula runs, **`substituteBalanceOfLiterals`** replaces each `BALANCE_OF("…")` with a numeric cent literal so formula execution stays synchronous and we avoid a HyperFormula plugin that needs DB access. `getRunningBalanceBeforeTransaction` is shared with `prepareTransactionForRules` for the existing `balance` field. Split rule actions receive the same prefetch map as the parent row; `finalizeTransactionForRules` strips internal fields. ## Related issue(s) https://discord.com/channels/937901803608096828/1488212143923921088 ## Testing **Automated** - `packages/loot-core`: `balanceOfFormula.test.ts` (literal extraction, substitution, id vs name resolution). - `packages/loot-core`: `formula-action.test.ts` (prefetched map + missing literal → 0). **Manual** - Create or edit a rule with a formula that uses `=BALANCE_OF("Your Account Name")` or `=BALANCE_OF("<account-id>")` and confirm the Set field result matches expectations vs the register for that account. - Smoke-test **schedule** flows that run rule actions if you use rules with formulas there. ## Checklist - [x] Release notes added (see link above) - [x] No obvious regressions in affected areas - [x] Self-review has been performed - I understand what each change in the code does and why it is needed <!--- actual-bot-sections ---> <!--- bundlestats-action-comment key:combined start ---> ### Bundle Stats Bundle | Files count | Total bundle size | % Changed ------ | ----------- | ----------------- | --------- desktop-client | 28 | 12.91 MB → 12.91 MB (+1.21 kB) | +0.01% loot-core | 1 | 4.84 MB → 4.84 MB (+3.72 kB) | +0.08% api | 1 | 3.88 MB → 3.88 MB (+4.05 kB) | +0.10% cli | 1 | 7.89 MB | 0% <details> <summary>View detailed bundle stats</summary> #### desktop-client **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 28 | 12.91 MB → 12.91 MB (+1.21 kB) | +0.01% <details> <summary>Changeset</summary> File | Δ | Size ---- | - | ---- `home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts` | 📈 +327 B (+30.45%) | 1.05 kB → 1.37 kB `src/components/formula/transactionModeFunctions.ts` | 📈 +404 B (+2.89%) | 13.64 kB → 14.04 kB `src/components/sidebar/Account.tsx` | 📈 +358 B (+2.84%) | 12.32 kB → 12.67 kB `src/components/sidebar/Accounts.tsx` | 📈 +145 B (+1.64%) | 8.63 kB → 8.77 kB </details> <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** Asset | File Size | % Changed ----- | --------- | --------- static/js/index.js | 3.32 MB → 3.32 MB (+503 B) | +0.01% static/js/FormulaEditor.js | 852.77 kB → 853.16 kB (+404 B) | +0.05% static/js/Value.js | 4.33 MB → 4.33 MB (+327 B) | +0.01% **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- static/js/BackgroundImage.js | 121.09 kB | 0% static/js/ReportRouter.js | 1.18 MB | 0% static/js/TransactionList.js | 82.49 kB | 0% static/js/ca.js | 191.98 kB | 0% static/js/da.js | 104.66 kB | 0% static/js/de.js | 174.38 kB | 0% static/js/en-GB.js | 8.2 kB | 0% static/js/en.js | 175.89 kB | 0% static/js/es.js | 181.8 kB | 0% static/js/extends.js | 485.17 kB | 0% static/js/fr.js | 177.08 kB | 0% static/js/indexeddb-main-thread-worker-e59fee74.js | 13.46 kB | 0% static/js/it.js | 165.95 kB | 0% static/js/narrow.js | 363.02 kB | 0% static/js/nb-NO.js | 151.85 kB | 0% static/js/nl.js | 108.93 kB | 0% static/js/pl.js | 88.34 kB | 0% static/js/pt-BR.js | 177.44 kB | 0% static/js/resize-observer.js | 18.06 kB | 0% static/js/th.js | 179.3 kB | 0% static/js/theme.js | 30.79 kB | 0% static/js/uk.js | 212.6 kB | 0% static/js/wide.js | 295 B | 0% static/js/workbox-window.prod.es5.js | 7.33 kB | 0% static/js/zh-Hans.js | 110.19 kB | 0% </div> </details> --- #### loot-core **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 4.84 MB → 4.84 MB (+3.72 kB) | +0.08% <details> <summary>Changeset</summary> File | Δ | Size ---- | - | ---- `home/runner/work/actual/actual/packages/loot-core/src/server/rules/balanceOfFormula.ts` | 🆕 +965 B | 0 B → 965 B `home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts` | 📈 +337 B (+30.69%) | 1.07 kB → 1.4 kB `home/runner/work/actual/actual/packages/loot-core/src/server/transactions/transaction-rules.ts` | 📈 +1.36 kB (+6.98%) | 19.56 kB → 20.92 kB `home/runner/work/actual/actual/packages/loot-core/src/server/budget/schedule-template.ts` | 📈 +507 B (+6.95%) | 7.13 kB → 7.62 kB `home/runner/work/actual/actual/packages/loot-core/src/server/sync/index.ts` | 📈 +350 B (+2.48%) | 13.77 kB → 14.12 kB `home/runner/work/actual/actual/packages/loot-core/src/server/rules/rule.ts` | 📈 +99 B (+2.22%) | 4.36 kB → 4.46 kB `home/runner/work/actual/actual/packages/loot-core/src/server/rules/action.ts` | 📈 +154 B (+1.92%) | 7.84 kB → 7.99 kB </details> <details> <summary>View detailed bundle breakdown</summary> <div> **Added** Asset | File Size | % Changed ----- | --------- | --------- kcab.worker.B_XN_qvd.js | 0 B → 4.84 MB (+4.84 MB) | - **Removed** Asset | File Size | % Changed ----- | --------- | --------- kcab.worker.DZcmk4OR.js | 4.84 MB → 0 B (-4.84 MB) | -100% **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** No assets were unchanged </div> </details> --- #### api **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 3.88 MB → 3.88 MB (+4.05 kB) | +0.10% <details> <summary>Changeset</summary> File | Δ | Size ---- | - | ---- `home/runner/work/actual/actual/packages/loot-core/src/server/rules/balanceOfFormula.ts` | 🆕 +1.23 kB | 0 B → 1.23 kB `home/runner/work/actual/actual/packages/loot-core/src/server/rules/customFunctions.ts` | 📈 +327 B (+30.39%) | 1.05 kB → 1.37 kB `home/runner/work/actual/actual/packages/loot-core/src/server/transactions/transaction-rules.ts` | 📈 +1.44 kB (+7.56%) | 19.08 kB → 20.52 kB `home/runner/work/actual/actual/packages/loot-core/src/server/budget/schedule-template.ts` | 📈 +496 B (+6.93%) | 6.99 kB → 7.47 kB `home/runner/work/actual/actual/packages/loot-core/src/server/sync/index.ts` | 📈 +338 B (+2.47%) | 13.35 kB → 13.68 kB `home/runner/work/actual/actual/packages/loot-core/src/server/rules/rule.ts` | 📈 +98 B (+2.33%) | 4.11 kB → 4.2 kB `home/runner/work/actual/actual/packages/loot-core/src/server/rules/action.ts` | 📈 +152 B (+2.01%) | 7.39 kB → 7.54 kB </details> <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** Asset | File Size | % Changed ----- | --------- | --------- index.js | 3.88 MB → 3.88 MB (+4.05 kB) | +0.10% **Smaller** No assets were smaller **Unchanged** No assets were unchanged </div> </details> --- #### cli **Total** Files count | Total bundle size | % Changed ----------- | ----------------- | --------- 1 | 7.89 MB | 0% <details> <summary>View detailed bundle breakdown</summary> <div> **Added** No assets were added **Removed** No assets were removed **Bigger** No assets were bigger **Smaller** No assets were smaller **Unchanged** Asset | File Size | % Changed ----- | --------- | --------- cli.js | 7.89 MB | 0% </div> </details> </details> <!--- bundlestats-action-comment key:combined end ---> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-26 10:47:16 -05:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/actual#48912