Skip to content

A local-first personal finance app

[Enhancements] Removed regex from excel formula execution (#7990)

lelemm0db391db40f6
diff --git a/packages/desktop-client/src/hooks/useFormulaExecution.ts b/packages/desktop-client/src/hooks/useFormulaExecution.ts
index 7f0ed7747a..1ed87f34c0 100644
--- a/packages/desktop-client/src/hooks/useFormulaExecution.ts
+++ b/packages/desktop-client/src/hooks/useFormulaExecution.ts
@@ -1,6 +1,12 @@
import { useEffect, useState } from 'react';
import { send } from '@actual-app/core/platform/client/connection';
+import {
+ createBudgetQueryPrefetchKey,
+ CustomFunctionsPlugin,
+ customFunctionsTranslations,
+} from '@actual-app/core/server/rules/customFunctions';
+import type { FormulaQueryContext } from '@actual-app/core/server/rules/customFunctions';
import * as monthUtils from '@actual-app/core/shared/months';
import { q } from '@actual-app/core/shared/query';
import type { Query } from '@actual-app/core/shared/query';
@@ -11,6 +17,7 @@ import type {
TimeFrame,
} from '@actual-app/core/types/models';
import { HyperFormula } from 'hyperformula';
+import enUS from 'hyperformula/i18n/languages/enUS';
import { getLiveRange } from '#components/reports/getLiveRange';
import { calculateTimeRange } from '#components/reports/reportRanges';
@@ -25,60 +32,104 @@ type QueryConfig = {
type QueriesMap = Record<string, QueryConfig>;
-function escapeRegExp(s: string) {
- return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+if (!HyperFormula.getRegisteredLanguagesCodes().includes('enUS')) {
+ HyperFormula.registerLanguage('enUS', enUS);
}
-// Parse a BUDGET_QUERY parameter - can be extraction function, array literal, or string
-function parseBudgetParam(
- param: string,
-): { type: 'extraction' | 'literal'; data: unknown } | null {
- param = param.trim();
+HyperFormula.registerFunctionPlugin(
+ CustomFunctionsPlugin,
+ customFunctionsTranslations,
+);
+
+type FormulaCellValue = number | string | boolean | null;
+
+function createFormulaQueryContext(): Required<FormulaQueryContext> {
+ return {
+ queryNames: new Set(),
+ queryCountNames: new Set(),
+ queryExtractCategoryNames: new Set(),
+ queryExtractTimeframeStartNames: new Set(),
+ queryExtractTimeframeEndNames: new Set(),
+ budgetQueryRequests: new Map(),
+ querySumPrefetch: new Map(),
+ queryCountPrefetch: new Map(),
+ queryExtractCategoriesPrefetch: new Map(),
+ queryExtractTimeframeStartPrefetch: new Map(),
+ queryExtractTimeframeEndPrefetch: new Map(),
+ budgetQueryPrefetch: new Map(),
+ budgetQueryErrors: new Map(),
+ };
+}
- // Try extraction function: QUERY_EXTRACT_*("queryName")
- const extractMatch = param.match(
- /^(QUERY_EXTRACT_\w+)\s*\(\s*["']([^"']+)["']\s*\)$/,
+function isHyperFormulaError(
+ cellValue: unknown,
+): cellValue is { type: string; message?: string } {
+ return Boolean(
+ cellValue && typeof cellValue === 'object' && 'type' in cellValue,
);
- if (extractMatch) {
- return {
- type: 'extraction',
- data: { funcName: extractMatch[1], queryName: extractMatch[2] },
- };
- }
+}
- // Try array literal: {"id1";"id2";...}
- const arrayMatch = param.match(/^\{([^}]*)\}$/);
- if (arrayMatch) {
- const items = arrayMatch[1]
- .split(';')
- .map(item => item.replace(/^["']|["']$/g, '').trim())
- .filter(item => item.length > 0);
- return { type: 'literal', data: items };
- }
+function evaluateFormulaWithContext({
+ formula,
+ formulaQueryContext,
+ locale,
+ namedExpressions,
+ throwOnCellError = true,
+}: {
+ formula: string;
+ formulaQueryContext: FormulaQueryContext;
+ locale: unknown;
+ namedExpressions?: Record<string, number | string>;
+ throwOnCellError?: boolean;
+}): FormulaCellValue {
+ let hfInstance: ReturnType<typeof HyperFormula.buildEmpty> | null = null;
- // Try string literal: "value"
- const stringMatch = param.match(/^["']([^"']*)["']$/);
- if (stringMatch) {
- return { type: 'literal', data: stringMatch[1] };
- }
+ try {
+ hfInstance = HyperFormula.buildEmpty({
+ licenseKey: 'gpl-v3',
+ language: 'enUS',
+ localeLang: typeof locale === 'string' ? locale : 'en-US',
+ dateFormats: ['DD/MM/YYYY', 'YYYY-MM-DD', 'YYYY/MM/DD'],
+ context: {
+ formulaQuery: formulaQueryContext,
+ },
+ });
- return null;
-}
+ const sheetName = hfInstance.addSheet('Sheet1');
+ const sheetId = hfInstance.getSheetId(sheetName);
-// Resolve a parsed BUDGET_QUERY parameter to its actual value
-function resolveBudgetParam(
- parsed: ReturnType<typeof parseBudgetParam>,
- extractionResults: Record<string, Record<string, unknown>>,
-): unknown {
- if (!parsed || parsed.type === 'literal') {
- return parsed?.data;
- }
+ if (sheetId === undefined) {
+ throw new Error('Failed to create sheet');
+ }
- const { funcName, queryName } = parsed.data as {
- funcName: string;
- queryName: string;
- };
- return extractionResults[funcName]?.[`${funcName}(${queryName})`];
+ if (namedExpressions) {
+ for (const [name, value] of Object.entries(namedExpressions)) {
+ hfInstance.addNamedExpression(
+ name,
+ typeof value === 'number' ? value : String(value),
+ );
+ }
+ }
+
+ hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [[formula]]);
+
+ const cellValue = hfInstance.getCellValue({
+ sheet: sheetId,
+ col: 0,
+ row: 0,
+ });
+
+ if (isHyperFormulaError(cellValue)) {
+ if (throwOnCellError) {
+ throw new Error(`Formula error: ${cellValue.type}`);
+ }
+ return null;
+ }
+
+ return cellValue as FormulaCellValue;
+ } finally {
+ hfInstance?.destroy();
+ }
}
export function useFormulaExecution(
@@ -96,8 +147,6 @@ export function useFormulaExecution(
let cancelled = false;
async function executeFormula() {
- let hfInstance: ReturnType<typeof HyperFormula.buildEmpty> | null = null;
-
if (!formula || !formula.startsWith('=')) {
setResult(null);
setError('Formula must start with =');
@@ -108,269 +157,40 @@ export function useFormulaExecution(
setError(null);
try {
- // Extract QUERY() and QUERY_COUNT() function calls
- const queryMatches = Array.from(
- formula.matchAll(/QUERY\s*\(\s*["']([^"']+)["']\s*\)/gi),
- );
- const queryCountMatches = Array.from(
- formula.matchAll(/QUERY_COUNT\s*\(\s*["']([^"']+)["']\s*\)/gi),
- );
-
- // Fetch data for each query
- const queryData: Record<string, number> = {};
- const queryCountData: Record<string, number> = {};
-
- // Deduplicate names (a query can appear multiple times in the same formula)
- const queryNames = Array.from(new Set(queryMatches.map(m => m[1])));
- const queryCountNames = Array.from(
- new Set(queryCountMatches.map(m => m[1])),
- );
-
- // Extract QUERY_EXTRACT_* calls for evaluation
- // These extraction functions are used as parameters to BUDGET_QUERY
- const extractionFunctions = {
- QUERY_EXTRACT_CATEGORIES:
- /QUERY_EXTRACT_CATEGORIES\s*\(\s*["']([^"']+)["']\s*\)/gi,
- QUERY_EXTRACT_TIMEFRAME_START:
- /QUERY_EXTRACT_TIMEFRAME_START\s*\(\s*["']([^"']+)["']\s*\)/gi,
- QUERY_EXTRACT_TIMEFRAME_END:
- /QUERY_EXTRACT_TIMEFRAME_END\s*\(\s*["']([^"']+)["']\s*\)/gi,
- };
-
- // Store extraction results
- const extractionResults: Record<string, Record<string, unknown>> = {
- QUERY_EXTRACT_CATEGORIES: {},
- QUERY_EXTRACT_TIMEFRAME_START: {},
- QUERY_EXTRACT_TIMEFRAME_END: {},
- };
-
- // Evaluate extraction functions first
- for (const [funcName, regex] of Object.entries(extractionFunctions)) {
- const matches = Array.from(formula.matchAll(regex));
- for (const match of matches) {
- const queryName = match[1];
- const key = `${funcName}(${queryName})`;
-
- if (!extractionResults[funcName][key]) {
- try {
- if (funcName === 'QUERY_EXTRACT_CATEGORIES') {
- extractionResults[funcName][key] =
- await extractQueryCategories(queryName, queries);
- } else if (funcName === 'QUERY_EXTRACT_TIMEFRAME_START') {
- extractionResults[funcName][key] =
- await extractQueryTimeframeStart(queryName, queries);
- } else if (funcName === 'QUERY_EXTRACT_TIMEFRAME_END') {
- extractionResults[funcName][key] =
- await extractQueryTimeframeEnd(queryName, queries);
- }
- } catch (err) {
- console.error(
- `Error evaluating ${funcName}(${queryName})`,
- err,
- );
- extractionResults[funcName][key] = null;
- }
- }
- }
- }
-
- // Match BUDGET_QUERY(dimension, param1, param2, param3) where each param can be:
- // extraction function, array literal {...}, or string "..."
- const paramPattern = String.raw`(?:QUERY_EXTRACT_\w+\s*\([^)]*\)|\{[^}]*\}|["'][^"']*["'])`;
- const budgetMatches = Array.from(
- formula.matchAll(
- new RegExp(
- `BUDGET_QUERY\\s*\\(\\s*["']([^"']+)["']\\s*,\\s*(${paramPattern})\\s*,\\s*(${paramPattern})\\s*,\\s*(${paramPattern})\\s*\\)`,
- 'gi',
- ),
- ),
- );
-
- for (const queryName of queryNames) {
- const queryConfig = queries[queryName];
-
- if (!queryConfig) {
- console.warn(`Query "${queryName}" not found in queries config`);
- queryData[queryName] = 0;
- continue;
- }
-
- const data = await fetchQuerySum(queryConfig);
- queryData[queryName] = integerToAmount(data, 2);
- }
-
- for (const queryName of queryCountNames) {
- const queryConfig = queries[queryName];
-
- if (!queryConfig) {
- console.warn(`Query "${queryName}" not found in queries config`);
- queryCountData[queryName] = 0;
- continue;
- }
-
- const count = await fetchQueryCount(queryConfig);
- queryCountData[queryName] = count;
- }
-
- // Replace QUERY() and QUERY_COUNT() calls with actual values in the formula
- let processedFormula = formula;
- for (const [queryName, value] of Object.entries(queryData)) {
- const regex = new RegExp(
- `QUERY\\s*\\(\\s*["']${escapeRegExp(queryName)}["']\\s*\\)`,
- 'gi',
- );
- processedFormula = processedFormula.replace(regex, String(value));
- }
- for (const [queryName, value] of Object.entries(queryCountData)) {
- const regex = new RegExp(
- `QUERY_COUNT\\s*\\(\\s*["']${escapeRegExp(queryName)}["']\\s*\\)`,
- 'gi',
- );
- processedFormula = processedFormula.replace(regex, String(value));
- }
-
- // Process BUDGET_QUERY BEFORE replacing extraction functions
- // This ensures we match BUDGET_QUERY with extraction functions still intact
- if (budgetMatches.length > 0) {
- for (const match of budgetMatches) {
- const dimension = match[1];
- const param1Str = match[2].trim();
- const param2Str = match[3].trim();
- const param3Str = match[4].trim();
-
- try {
- // Parse and resolve parameters
- const param1 = resolveBudgetParam(
- parseBudgetParam(param1Str),
- extractionResults,
- );
- const param2 = resolveBudgetParam(
- parseBudgetParam(param2Str),
- extractionResults,
- );
- const param3 = resolveBudgetParam(
- parseBudgetParam(param3Str),
- extractionResults,
- );
-
- // Validate resolved parameters
- if (
- !Array.isArray(param1) ||
- typeof param2 !== 'string' ||
- typeof param3 !== 'string'
- ) {
- console.error(
- 'Failed to resolve BUDGET_QUERY parameters:',
- param1Str,
- param2Str,
- param3Str,
- );
- continue;
- }
-
- // Evaluate BUDGET_QUERY
- const val = await fetchBudgetDimensionValueDirect(
- dimension,
- param1 as string[],
- param2 as string,
- param3 as string,
- );
-
- processedFormula = processedFormula.replace(
- match[0],
- String(val),
- );
- } catch (err) {
- console.error('Error evaluating BUDGET_QUERY', err);
- }
- }
- }
-
- // NOW replace remaining QUERY_EXTRACT_* functions with their evaluated values
- // (any that weren't consumed by BUDGET_QUERY)
- for (const [funcName, regex] of Object.entries(extractionFunctions)) {
- const matches = Array.from(processedFormula.matchAll(regex));
- for (const match of matches) {
- const queryName = match[1];
- const key = `${funcName}(${queryName})`;
- const value = extractionResults[funcName][key];
-
- if (value !== null && value !== undefined) {
- const escapedQueryName = escapeRegExp(queryName);
- const replacementRegex = new RegExp(
- `${funcName}\\s*\\(\\s*["']${escapedQueryName}["']\\s*\\)`,
- 'gi',
- );
-
- // Format the replacement value based on type
- let replacement: string;
- if (Array.isArray(value)) {
- // For arrays, convert to HyperFormula array literal
- replacement = `{${value.map(v => `"${v}"`).join(';')}}`;
- } else if (typeof value === 'string') {
- // For strings, wrap in quotes
- replacement = `"${value}"`;
- } else {
- // For numbers
- replacement = String(value);
- }
-
- processedFormula = processedFormula.replace(
- replacementRegex,
- replacement,
- );
- }
- }
- }
-
- // Create HyperFormula instance
- hfInstance = HyperFormula.buildEmpty({
- licenseKey: 'gpl-v3',
- language: 'enUS',
- localeLang: typeof locale === 'string' ? locale : 'en-US',
- dateFormats: ['DD/MM/YYYY', 'YYYY-MM-DD', 'YYYY/MM/DD'],
+ const formulaQueryContext = createFormulaQueryContext();
+
+ evaluateFormulaWithContext({
+ formula,
+ formulaQueryContext,
+ locale,
+ namedExpressions,
+ throwOnCellError: false,
});
- // Add a sheet and set the formula in cell A1
- const sheetName = hfInstance.addSheet('Sheet1');
- const sheetId = hfInstance.getSheetId(sheetName);
+ await prefetchFormulaQueries(formulaQueryContext, queries);
- if (sheetId === undefined) {
- throw new Error('Failed to create sheet');
- }
-
- // Add named expressions if provided
- if (namedExpressions) {
- for (const [name, value] of Object.entries(namedExpressions)) {
- hfInstance.addNamedExpression(
- name,
- typeof value === 'number' ? value : String(value),
- );
- }
- }
+ formulaQueryContext.budgetQueryRequests.clear();
+ evaluateFormulaWithContext({
+ formula,
+ formulaQueryContext,
+ locale,
+ namedExpressions,
+ throwOnCellError: false,
+ });
- // Set the formula
- hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [
- [processedFormula],
- ]);
+ await prefetchBudgetQueries(formulaQueryContext);
- // Get the result
- const cellValue = hfInstance.getCellValue({
- sheet: sheetId,
- col: 0,
- row: 0,
+ const cellValue = evaluateFormulaWithContext({
+ formula,
+ formulaQueryContext,
+ locale,
+ namedExpressions,
});
if (cancelled) return;
- // Check if there's an error
- if (cellValue && typeof cellValue === 'object' && 'type' in cellValue) {
- setError(`Formula error: ${cellValue.type}`);
- setResult(null);
- } else {
- setResult(cellValue as number | string);
- setError(null);
- }
+ setResult(cellValue as number | string);
+ setError(null);
} catch (err) {
if (cancelled) return;
console.error('Formula execution error:', err);
@@ -380,14 +200,6 @@ export function useFormulaExecution(
if (!cancelled) {
setIsLoading(false);
}
-
- try {
- hfInstance?.destroy();
- } catch (err) {
- console.error('Error destroying HyperFormula instance:', err);
- setError('Error destroying HyperFormula instance');
- setResult(null);
- }
}
}
@@ -401,6 +213,91 @@ export function useFormulaExecution(
return { result, isLoading, error };
}
+async function prefetchFormulaQueries(
+ formulaQueryContext: Required<FormulaQueryContext>,
+ queries: QueriesMap,
+) {
+ for (const queryName of formulaQueryContext.queryNames) {
+ const queryConfig = queries[queryName];
+
+ if (!queryConfig) {
+ console.warn(`Query "${queryName}" not found in queries config`);
+ formulaQueryContext.querySumPrefetch.set(queryName, 0);
+ continue;
+ }
+
+ const data = await fetchQuerySum(queryConfig);
+ formulaQueryContext.querySumPrefetch.set(
+ queryName,
+ integerToAmount(data, 2),
+ );
+ }
+
+ for (const queryName of formulaQueryContext.queryCountNames) {
+ const queryConfig = queries[queryName];
+
+ if (!queryConfig) {
+ console.warn(`Query "${queryName}" not found in queries config`);
+ formulaQueryContext.queryCountPrefetch.set(queryName, 0);
+ continue;
+ }
+
+ formulaQueryContext.queryCountPrefetch.set(
+ queryName,
+ await fetchQueryCount(queryConfig),
+ );
+ }
+
+ for (const queryName of formulaQueryContext.queryExtractCategoryNames) {
+ formulaQueryContext.queryExtractCategoriesPrefetch.set(
+ queryName,
+ await extractQueryCategories(queryName, queries),
+ );
+ }
+
+ for (const queryName of formulaQueryContext.queryExtractTimeframeStartNames) {
+ formulaQueryContext.queryExtractTimeframeStartPrefetch.set(
+ queryName,
+ await extractQueryTimeframeStart(queryName, queries),
+ );
+ }
+
+ for (const queryName of formulaQueryContext.queryExtractTimeframeEndNames) {
+ formulaQueryContext.queryExtractTimeframeEndPrefetch.set(
+ queryName,
+ await extractQueryTimeframeEnd(queryName, queries),
+ );
+ }
+}
+
+async function prefetchBudgetQueries(
+ formulaQueryContext: Required<FormulaQueryContext>,
+) {
+ for (const request of formulaQueryContext.budgetQueryRequests.values()) {
+ const key = createBudgetQueryPrefetchKey(request);
+
+ try {
+ formulaQueryContext.budgetQueryPrefetch.set(
+ key,
+ await fetchBudgetDimensionValueDirect(
+ request.dimension,
+ request.categoryIds,
+ request.startMonth,
+ request.endMonth,
+ ),
+ );
+ formulaQueryContext.budgetQueryErrors.delete(key);
+ } catch (err) {
+ console.error('Error evaluating BUDGET_QUERY', err);
+ formulaQueryContext.budgetQueryPrefetch.delete(key);
+ formulaQueryContext.budgetQueryErrors.set(
+ key,
+ err instanceof Error ? err.message : String(err),
+ );
+ }
+ }
+}
+
// Helper function to convert timeFrame mode to condition string for getLiveRange
function timeFrameModeToCondition(mode: TimeFrame['mode']): string | null {
// Map timeFrame modes to ReportOptions condition strings
diff --git a/packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts b/packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts
index 60ca06b310..1667738d73 100644
--- a/packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts
+++ b/packages/desktop-client/src/hooks/useTransactionFormulaExecution.ts
@@ -9,7 +9,9 @@ import enUS from 'hyperformula/i18n/languages/enUS';
import { useLocale } from './useLocale';
-HyperFormula.registerLanguage('enUS', enUS);
+if (!HyperFormula.getRegisteredLanguagesCodes().includes('enUS')) {
+ HyperFormula.registerLanguage('enUS', enUS);
+}
HyperFormula.registerFunctionPlugin(
CustomFunctionsPlugin,
customFunctionsTranslations,
diff --git a/packages/loot-core/src/server/rules/action.ts b/packages/loot-core/src/server/rules/action.ts
index 435c175b55..bd960afaec 100644
--- a/packages/loot-core/src/server/rules/action.ts
+++ b/packages/loot-core/src/server/rules/action.ts
@@ -16,7 +16,9 @@ import {
} from './customFunctions';
import { assert } from './rule-utils';
-HyperFormula.registerLanguage('enUS', enUS);
+if (!HyperFormula.getRegisteredLanguagesCodes().includes('enUS')) {
+ HyperFormula.registerLanguage('enUS', enUS);
+}
HyperFormula.registerFunctionPlugin(
CustomFunctionsPlugin,
customFunctionsTranslations,
diff --git a/packages/loot-core/src/server/rules/customFunctions.test.ts b/packages/loot-core/src/server/rules/customFunctions.test.ts
new file mode 100644
index 0000000000..4c7875b10b
--- /dev/null
+++ b/packages/loot-core/src/server/rules/customFunctions.test.ts
@@ -0,0 +1,208 @@
+import { HyperFormula } from 'hyperformula';
+import enUS from 'hyperformula/i18n/languages/enUS';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import {
+ createBudgetQueryPrefetchKey,
+ CustomFunctionsPlugin,
+ customFunctionsTranslations,
+} from './customFunctions';
+import type { FormulaQueryContext } from './customFunctions';
+
+function createFormulaQueryContext(): Required<FormulaQueryContext> {
+ return {
+ queryNames: new Set(),
+ queryCountNames: new Set(),
+ queryExtractCategoryNames: new Set(),
+ queryExtractTimeframeStartNames: new Set(),
+ queryExtractTimeframeEndNames: new Set(),
+ budgetQueryRequests: new Map(),
+ querySumPrefetch: new Map(),
+ queryCountPrefetch: new Map(),
+ queryExtractCategoriesPrefetch: new Map(),
+ queryExtractTimeframeStartPrefetch: new Map(),
+ queryExtractTimeframeEndPrefetch: new Map(),
+ budgetQueryPrefetch: new Map(),
+ budgetQueryErrors: new Map(),
+ };
+}
+
+function evaluateFormula(
+ formula: string,
+ formulaQueryContext: FormulaQueryContext,
+) {
+ const { cellValue } = evaluateFormulaSheet(formula, formulaQueryContext);
+ return cellValue;
+}
+
+function evaluateFormulaSheet(
+ formula: string,
+ formulaQueryContext: FormulaQueryContext,
+) {
+ const hf = HyperFormula.buildEmpty({
+ licenseKey: 'gpl-v3',
+ language: 'enUS',
+ context: {
+ formulaQuery: formulaQueryContext,
+ },
+ });
+
+ try {
+ const sheetName = hf.addSheet('Sheet1');
+ const sheetId = hf.getSheetId(sheetName);
+
+ if (sheetId === undefined) {
+ throw new Error('Failed to create sheet');
+ }
+
+ hf.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [[formula]]);
+
+ return {
+ cellValue: hf.getCellValue({ sheet: sheetId, col: 0, row: 0 }),
+ sheetValues: hf.getSheetValues(sheetId),
+ };
+ } finally {
+ hf.destroy();
+ }
+}
+
+describe('CustomFunctionsPlugin formula query functions', () => {
+ beforeAll(() => {
+ if (!HyperFormula.getRegisteredLanguagesCodes().includes('enUS')) {
+ HyperFormula.registerLanguage('enUS', enUS);
+ }
+
+ HyperFormula.registerFunctionPlugin(
+ CustomFunctionsPlugin,
+ customFunctionsTranslations,
+ );
+ });
+
+ it('records QUERY and QUERY_COUNT requests and returns prefetched values', () => {
+ const context = createFormulaQueryContext();
+ context.querySumPrefetch.set('income', 123.45);
+ context.queryCountPrefetch.set('income', 3);
+
+ const result = evaluateFormula(
+ '=QUERY("income") + QUERY_COUNT("income")',
+ context,
+ );
+
+ expect(result).toBeCloseTo(126.45);
+ expect(context.queryNames).toEqual(new Set(['income']));
+ expect(context.queryCountNames).toEqual(new Set(['income']));
+ });
+
+ it('defaults missing query prefetch values to zero while collecting names', () => {
+ const context = createFormulaQueryContext();
+
+ const result = evaluateFormula(
+ '=QUERY("missing") + QUERY_COUNT("missing")',
+ context,
+ );
+
+ expect(result).toBe(0);
+ expect(context.queryNames).toEqual(new Set(['missing']));
+ expect(context.queryCountNames).toEqual(new Set(['missing']));
+ });
+
+ it('resolves BUDGET_QUERY from prefetched nested query extraction values', () => {
+ const context = createFormulaQueryContext();
+ const request = {
+ dimension: 'spent',
+ categoryIds: ['cat-a', 'cat-b'],
+ startMonth: '2026-01',
+ endMonth: '2026-03',
+ };
+ const budgetKey = createBudgetQueryPrefetchKey(request);
+
+ context.queryExtractCategoriesPrefetch.set('expenses', request.categoryIds);
+ context.queryExtractTimeframeStartPrefetch.set(
+ 'expenses',
+ request.startMonth,
+ );
+ context.queryExtractTimeframeEndPrefetch.set('expenses', request.endMonth);
+ context.budgetQueryPrefetch.set(budgetKey, 42.5);
+
+ const result = evaluateFormula(
+ '=BUDGET_QUERY("spent", QUERY_EXTRACT_CATEGORIES("expenses"), QUERY_EXTRACT_TIMEFRAME_START("expenses"), QUERY_EXTRACT_TIMEFRAME_END("expenses"))',
+ context,
+ );
+
+ expect(result).toBe(42.5);
+ expect(context.queryExtractCategoryNames).toEqual(new Set(['expenses']));
+ expect(context.queryExtractTimeframeStartNames).toEqual(
+ new Set(['expenses']),
+ );
+ expect(context.queryExtractTimeframeEndNames).toEqual(
+ new Set(['expenses']),
+ );
+ expect(context.budgetQueryRequests.get(budgetKey)).toEqual(request);
+ });
+
+ it('spills QUERY_EXTRACT_CATEGORIES as a standalone array result', () => {
+ const context = createFormulaQueryContext();
+ context.queryExtractCategoriesPrefetch.set('expenses', ['cat-a', 'cat-b']);
+
+ const result = evaluateFormulaSheet(
+ '=QUERY_EXTRACT_CATEGORIES("expenses")',
+ context,
+ );
+
+ expect(result.sheetValues).toEqual([['cat-a'], ['cat-b']]);
+ expect(context.queryExtractCategoryNames).toEqual(new Set(['expenses']));
+ });
+
+ it('surfaces BUDGET_QUERY prefetch failures as formula errors', () => {
+ const context = createFormulaQueryContext();
+ const request = {
+ dimension: 'spnt',
+ categoryIds: ['cat-a'],
+ startMonth: '2026-01',
+ endMonth: '2026-03',
+ };
+ const budgetKey = createBudgetQueryPrefetchKey(request);
+
+ context.queryExtractCategoriesPrefetch.set('expenses', request.categoryIds);
+ context.queryExtractTimeframeStartPrefetch.set(
+ 'expenses',
+ request.startMonth,
+ );
+ context.queryExtractTimeframeEndPrefetch.set('expenses', request.endMonth);
+ context.budgetQueryErrors.set(
+ budgetKey,
+ 'Invalid BUDGET_QUERY dimension: spnt',
+ );
+
+ const result = evaluateFormula(
+ '=BUDGET_QUERY("spnt", QUERY_EXTRACT_CATEGORIES("expenses"), QUERY_EXTRACT_TIMEFRAME_START("expenses"), QUERY_EXTRACT_TIMEFRAME_END("expenses"))',
+ context,
+ );
+
+ expect(result).toMatchObject({
+ type: 'VALUE',
+ message: 'Invalid BUDGET_QUERY dimension: spnt',
+ });
+ });
+
+ it('ignores empty and non-id values in direct BUDGET_QUERY category ranges', () => {
+ const context = createFormulaQueryContext();
+ const request = {
+ dimension: 'spent',
+ categoryIds: ['cat-a', '123'],
+ startMonth: '2026-01',
+ endMonth: '2026-03',
+ };
+ const budgetKey = createBudgetQueryPrefetchKey(request);
+
+ context.budgetQueryPrefetch.set(budgetKey, 10);
+
+ const result = evaluateFormula(
+ '=BUDGET_QUERY("spent", {"cat-a"; ""; TRUE(); 123}, "2026-01", "2026-03")',
+ context,
+ );
+
+ expect(result).toBe(10);
+ expect(context.budgetQueryRequests.get(budgetKey)).toEqual(request);
+ });
+});
diff --git a/packages/loot-core/src/server/rules/customFunctions.ts b/packages/loot-core/src/server/rules/customFunctions.ts
index d2791aafc4..2fc22491f7 100644
--- a/packages/loot-core/src/server/rules/customFunctions.ts
+++ b/packages/loot-core/src/server/rules/customFunctions.ts
@@ -1,10 +1,89 @@
-import { FunctionArgumentType, FunctionPlugin } from 'hyperformula';
+import {
+ ArraySize,
+ CellError,
+ EmptyValue,
+ ErrorType,
+ FunctionArgumentType,
+ FunctionPlugin,
+ SimpleRangeValue,
+} from 'hyperformula';
import type { InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
import type { ProcedureAst } from 'hyperformula/typings/parser';
import { integerToAmount } from '#shared/util';
+export type BudgetQueryRequest = {
+ dimension: string;
+ categoryIds: string[];
+ startMonth: string;
+ endMonth: string;
+};
+
+export type FormulaQueryContext = {
+ queryNames?: Set<string>;
+ queryCountNames?: Set<string>;
+ queryExtractCategoryNames?: Set<string>;
+ queryExtractTimeframeStartNames?: Set<string>;
+ queryExtractTimeframeEndNames?: Set<string>;
+ budgetQueryRequests?: Map<string, BudgetQueryRequest>;
+ querySumPrefetch?: Map<string, number>;
+ queryCountPrefetch?: Map<string, number>;
+ queryExtractCategoriesPrefetch?: Map<string, string[]>;
+ queryExtractTimeframeStartPrefetch?: Map<string, string>;
+ queryExtractTimeframeEndPrefetch?: Map<string, string>;
+ budgetQueryPrefetch?: Map<string, number>;
+ budgetQueryErrors?: Map<string, string>;
+};
+
+type CustomFunctionsContext = {
+ balanceOfPrefetch?: Map<string, number>;
+ formulaQuery?: FormulaQueryContext;
+};
+
+export function createBudgetQueryPrefetchKey({
+ dimension,
+ categoryIds,
+ startMonth,
+ endMonth,
+}: BudgetQueryRequest): string {
+ return JSON.stringify({
+ dimension: dimension.toLowerCase(),
+ categoryIds,
+ startMonth,
+ endMonth,
+ });
+}
+
+function categoryRangeToIds(categories: SimpleRangeValue): string[] {
+ return categories
+ .valuesFromTopLeftCorner()
+ .filter(
+ value =>
+ value !== EmptyValue &&
+ !(value instanceof CellError) &&
+ (typeof value === 'string' || typeof value === 'number'),
+ )
+ .map(value => String(value).trim())
+ .filter(value => value.length > 0);
+}
+
+function categoryIdsToRange(categoryIds: string[]): SimpleRangeValue {
+ return SimpleRangeValue.onlyValues(
+ categoryIds.length > 0
+ ? categoryIds.map(categoryId => [categoryId])
+ : [['']],
+ );
+}
+
export class CustomFunctionsPlugin extends FunctionPlugin {
+ private getCustomFunctionsContext(): CustomFunctionsContext | undefined {
+ return this.config.context as CustomFunctionsContext | undefined;
+ }
+
+ private getFormulaQueryContext(): FormulaQueryContext | undefined {
+ return this.getCustomFunctionsContext()?.formulaQuery;
+ }
+
integerToAmount(ast: ProcedureAst, state: InterpreterState) {
return this.runFunction(
ast.args,
@@ -33,13 +112,124 @@ export class CustomFunctionsPlugin extends FunctionPlugin {
state,
this.metadata('BALANCE_OF'),
(accountKey: string) => {
- const ctx = this.config.context as
- | { balanceOfPrefetch?: Map<string, number> }
- | undefined;
+ const ctx = this.getCustomFunctionsContext();
return ctx?.balanceOfPrefetch?.get(accountKey) ?? 0;
},
);
}
+
+ query(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('QUERY'),
+ (queryName: string) => {
+ const ctx = this.getFormulaQueryContext();
+ ctx?.queryNames?.add(queryName);
+ return ctx?.querySumPrefetch?.get(queryName) ?? 0;
+ },
+ );
+ }
+
+ queryCount(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('QUERY_COUNT'),
+ (queryName: string) => {
+ const ctx = this.getFormulaQueryContext();
+ ctx?.queryCountNames?.add(queryName);
+ return ctx?.queryCountPrefetch?.get(queryName) ?? 0;
+ },
+ );
+ }
+
+ queryExtractCategories(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('QUERY_EXTRACT_CATEGORIES'),
+ (queryName: string) => {
+ const ctx = this.getFormulaQueryContext();
+ ctx?.queryExtractCategoryNames?.add(queryName);
+ return categoryIdsToRange(
+ ctx?.queryExtractCategoriesPrefetch?.get(queryName) ?? [],
+ );
+ },
+ );
+ }
+
+ queryExtractCategoriesSize(ast: ProcedureAst): ArraySize {
+ if (ast.args.length !== 1) {
+ return ArraySize.error();
+ }
+
+ const [queryNameAst] = ast.args;
+ const queryName =
+ queryNameAst.type === 'STRING' ? queryNameAst.value : undefined;
+ const categoryCount = queryName
+ ? this.getFormulaQueryContext()?.queryExtractCategoriesPrefetch?.get(
+ queryName,
+ )?.length
+ : undefined;
+
+ return new ArraySize(1, Math.max(categoryCount ?? 1, 1));
+ }
+
+ queryExtractTimeframeStart(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('QUERY_EXTRACT_TIMEFRAME_START'),
+ (queryName: string) => {
+ const ctx = this.getFormulaQueryContext();
+ ctx?.queryExtractTimeframeStartNames?.add(queryName);
+ return ctx?.queryExtractTimeframeStartPrefetch?.get(queryName) ?? '';
+ },
+ );
+ }
+
+ queryExtractTimeframeEnd(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('QUERY_EXTRACT_TIMEFRAME_END'),
+ (queryName: string) => {
+ const ctx = this.getFormulaQueryContext();
+ ctx?.queryExtractTimeframeEndNames?.add(queryName);
+ return ctx?.queryExtractTimeframeEndPrefetch?.get(queryName) ?? '';
+ },
+ );
+ }
+
+ budgetQuery(ast: ProcedureAst, state: InterpreterState) {
+ return this.runFunction(
+ ast.args,
+ state,
+ this.metadata('BUDGET_QUERY'),
+ (
+ dimension: string,
+ categories: SimpleRangeValue,
+ startMonth: string,
+ endMonth: string,
+ ) => {
+ const ctx = this.getFormulaQueryContext();
+ const request: BudgetQueryRequest = {
+ dimension: dimension.toLowerCase(),
+ categoryIds: categoryRangeToIds(categories),
+ startMonth,
+ endMonth,
+ };
+ const key = createBudgetQueryPrefetchKey(request);
+ ctx?.budgetQueryRequests?.set(key, request);
+ const error = ctx?.budgetQueryErrors?.get(key);
+ if (error) {
+ return new CellError(ErrorType.VALUE, error);
+ }
+ return ctx?.budgetQueryPrefetch?.get(key) ?? 0;
+ },
+ );
+ }
}
CustomFunctionsPlugin.implementedFunctions = {
@@ -58,6 +248,15 @@ CustomFunctionsPlugin.implementedFunctions = {
},
],
},
+ BUDGET_QUERY: {
+ method: 'budgetQuery',
+ parameters: [
+ { argumentType: FunctionArgumentType.STRING },
+ { argumentType: FunctionArgumentType.RANGE },
+ { argumentType: FunctionArgumentType.STRING },
+ { argumentType: FunctionArgumentType.STRING },
+ ],
+ },
INTEGER_TO_AMOUNT: {
method: 'integerToAmount',
parameters: [
@@ -69,12 +268,39 @@ CustomFunctionsPlugin.implementedFunctions = {
},
],
},
+ QUERY: {
+ method: 'query',
+ parameters: [{ argumentType: FunctionArgumentType.STRING }],
+ },
+ QUERY_COUNT: {
+ method: 'queryCount',
+ parameters: [{ argumentType: FunctionArgumentType.STRING }],
+ },
+ QUERY_EXTRACT_CATEGORIES: {
+ method: 'queryExtractCategories',
+ sizeOfResultArrayMethod: 'queryExtractCategoriesSize',
+ parameters: [{ argumentType: FunctionArgumentType.STRING }],
+ },
+ QUERY_EXTRACT_TIMEFRAME_END: {
+ method: 'queryExtractTimeframeEnd',
+ parameters: [{ argumentType: FunctionArgumentType.STRING }],
+ },
+ QUERY_EXTRACT_TIMEFRAME_START: {
+ method: 'queryExtractTimeframeStart',
+ parameters: [{ argumentType: FunctionArgumentType.STRING }],
+ },
};
export const customFunctionsTranslations = {
enUS: {
BALANCE_OF: 'BALANCE_OF',
+ BUDGET_QUERY: 'BUDGET_QUERY',
FIXED: 'FIXED',
INTEGER_TO_AMOUNT: 'INTEGER_TO_AMOUNT',
+ QUERY: 'QUERY',
+ QUERY_COUNT: 'QUERY_COUNT',
+ QUERY_EXTRACT_CATEGORIES: 'QUERY_EXTRACT_CATEGORIES',
+ QUERY_EXTRACT_TIMEFRAME_END: 'QUERY_EXTRACT_TIMEFRAME_END',
+ QUERY_EXTRACT_TIMEFRAME_START: 'QUERY_EXTRACT_TIMEFRAME_START',
},
};
diff --git a/upcoming-release-notes/7990.md b/upcoming-release-notes/7990.md
new file mode 100644
index 0000000000..f0fd60421d
--- /dev/null
+++ b/upcoming-release-notes/7990.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [lelemm]
+---
+
+Remove regex dependency from Excel formula execution for improved performance and reliability.