@actual-app/core 26.3.0

package/src/server/rules/condition.ts

@@ -0,0 +1,436 @@
+// @ts-strict-ignore
+import * as dateFns from 'date-fns';
+
+import { logger } from '../../platform/server/log';
+import {
+  addDays,
+  isAfter,
+  isBefore,
+  monthFromDate,
+  parseDate,
+  subDays,
+  yearFromDate,
+} from '../../shared/months';
+import {
+  FIELD_TYPES,
+  getApproxNumberThreshold,
+  isValidOp,
+  sortNumbers,
+} from '../../shared/rules';
+
+import {
+  assert,
+  parseBetweenAmount,
+  parseDateString,
+  parseRecurDate,
+} from './rule-utils';
+
+export const CONDITION_TYPES = {
+  date: {
+    ops: ['is', 'isapprox', 'gt', 'gte', 'lt', 'lte'],
+    nullable: false,
+    parse(op, value, fieldName) {
+      const parsed =
+        typeof value === 'string'
+          ? parseDateString(value)
+          : value.frequency != null
+            ? parseRecurDate(value)
+            : null;
+      assert(
+        parsed,
+        'date-format',
+        `Invalid date format (field: ${fieldName})`,
+      );
+
+      // Approximate only works with exact & recurring dates
+      if (op === 'isapprox') {
+        assert(
+          parsed.type === 'date' || parsed.type === 'recur',
+          'date-format',
+          `Invalid date value for "isapprox" (field: ${fieldName})`,
+        );
+      }
+      // These only work with exact dates
+      else if (op === 'gt' || op === 'gte' || op === 'lt' || op === 'lte') {
+        assert(
+          parsed.type === 'date',
+          'date-format',
+          `Invalid date value for "${op}" (field: ${fieldName})`,
+        );
+      }
+
+      return parsed;
+    },
+  },
+  id: {
+    ops: [
+      'is',
+      'contains',
+      'matches',
+      'oneOf',
+      'isNot',
+      'doesNotContain',
+      'notOneOf',
+      'and',
+      'onBudget',
+      'offBudget',
+    ],
+    nullable: true,
+    parse(op, value, fieldName) {
+      if (op === 'oneOf' || op === 'notOneOf' || op === 'and') {
+        assert(
+          Array.isArray(value),
+          'no-empty-array',
+          `oneOf must have an array value (field: ${fieldName})`,
+        );
+        return value;
+      }
+      return value;
+    },
+  },
+  string: {
+    ops: [
+      'is',
+      'contains',
+      'matches',
+      'oneOf',
+      'isNot',
+      'doesNotContain',
+      'notOneOf',
+      'hasTags',
+    ],
+    nullable: true,
+    parse(op, value, fieldName) {
+      if (op === 'oneOf' || op === 'notOneOf') {
+        assert(
+          Array.isArray(value),
+          'no-empty-array',
+          `oneOf must have an array value (field: ${fieldName}): ${JSON.stringify(
+            value,
+          )}`,
+        );
+        return value.filter(Boolean).map(val => val.toLowerCase());
+      }
+
+      assert(
+        typeof value === 'string',
+        'not-string',
+        `Invalid string value (field: ${fieldName})`,
+      );
+
+      if (
+        op === 'contains' ||
+        op === 'matches' ||
+        op === 'doesNotContain' ||
+        op === 'hasTags'
+      ) {
+        assert(
+          value.length > 0,
+          'no-empty-string',
+          `${op} must have non-empty string (field: ${fieldName})`,
+        );
+      }
+
+      if (op === 'hasTags') {
+        return value;
+      }
+
+      return value.toLowerCase();
+    },
+  },
+  number: {
+    ops: ['is', 'isapprox', 'isbetween', 'gt', 'gte', 'lt', 'lte'],
+    nullable: false,
+    parse(op, value, fieldName) {
+      const parsed =
+        typeof value === 'number'
+          ? { type: 'literal', value }
+          : parseBetweenAmount(value);
+
+      assert(
+        parsed != null,
+        'not-number',
+        `Value must be a number or between amount: ${JSON.stringify(
+          value,
+        )} (field: ${fieldName})`,
+      );
+
+      if (op === 'isbetween') {
+        assert(
+          parsed.type === 'between',
+          'number-format',
+          `Invalid between value for "${op}" (field: ${fieldName})`,
+        );
+      } else {
+        assert(
+          parsed.type === 'literal',
+          'number-format',
+          `Invalid number value for "${op}" (field: ${fieldName})`,
+        );
+      }
+
+      return parsed;
+    },
+  },
+  boolean: {
+    ops: ['is'],
+    nullable: false,
+    parse(op, value, fieldName) {
+      assert(
+        typeof value === 'boolean',
+        'not-boolean',
+        `Value must be a boolean: ${value} (field: ${fieldName})`,
+      );
+
+      return value;
+    },
+  },
+};
+
+export class Condition {
+  field;
+  op;
+  options;
+  rawValue;
+  type;
+  unparsedValue;
+  value;
+
+  constructor(op, field, value, options) {
+    const typeName = FIELD_TYPES.get(field);
+    assert(typeName, 'internal', 'Invalid condition field: ' + field);
+
+    const type = CONDITION_TYPES[typeName];
+
+    // It's important to validate rules because a faulty rule might mess
+    // up the user's transaction (and be very confusing)
+    assert(
+      type,
+      'internal',
+      `Invalid condition type: ${typeName} (field: ${field})`,
+    );
+    assert(
+      isValidOp(field, op),
+      'internal',
+      `Invalid condition operator: ${op} (type: ${typeName}, field: ${field})`,
+    );
+
+    if (type.nullable !== true) {
+      assert(value != null, 'no-null', `Field cannot be empty: ${field}`);
+    }
+
+    // For strings, an empty string is equal to null
+    if (typeName === 'string' && type.nullable !== true) {
+      assert(value !== '', 'no-null', `Field cannot be empty: ${field}`);
+    }
+
+    this.rawValue = value;
+    this.unparsedValue = value;
+    this.op = op;
+    this.field = field;
+    this.value = type.parse ? type.parse(op, value, field) : value;
+    this.options = options;
+    this.type = typeName;
+  }
+
+  eval(object) {
+    let fieldValue = object[this.field];
+    const type = this.type;
+
+    if (type === 'string') {
+      fieldValue ??= '';
+    }
+
+    if (fieldValue === undefined) {
+      return false;
+    }
+
+    if (typeof fieldValue === 'string') {
+      fieldValue = fieldValue.toLowerCase();
+    }
+
+    if (type === 'number' && this.options) {
+      if (this.options.outflow) {
+        if (fieldValue > 0) {
+          return false;
+        }
+
+        fieldValue = -fieldValue;
+      } else if (this.options.inflow) {
+        if (fieldValue < 0) {
+          return false;
+        }
+      }
+    }
+
+    const extractValue = v => (type === 'number' ? v.value : v);
+
+    switch (this.op) {
+      case 'isapprox':
+      case 'is':
+        if (type === 'date') {
+          if (fieldValue == null) {
+            return false;
+          }
+
+          if (this.value.type === 'recur') {
+            const { schedule } = this.value;
+            if (this.op === 'isapprox') {
+              const fieldDate = parseDate(fieldValue);
+              return schedule.occursBetween(
+                dateFns.subDays(fieldDate, 2),
+                dateFns.addDays(fieldDate, 2),
+              );
+            } else {
+              return schedule.occursOn({ date: parseDate(fieldValue) });
+            }
+          } else {
+            const { date } = this.value;
+
+            if (this.op === 'isapprox') {
+              const fullDate = parseDate(date);
+              const high = addDays(fullDate, 2);
+              const low = subDays(fullDate, 2);
+
+              return fieldValue >= low && fieldValue <= high;
+            } else {
+              switch (this.value.type) {
+                case 'date':
+                  return fieldValue === date;
+                case 'month':
+                  return monthFromDate(fieldValue) === date;
+                case 'year':
+                  return yearFromDate(fieldValue) === date;
+                default:
+              }
+            }
+          }
+        } else if (type === 'number') {
+          const number = this.value.value;
+          if (this.op === 'isapprox') {
+            const threshold = getApproxNumberThreshold(number);
+            return (
+              fieldValue >= number - threshold &&
+              fieldValue <= number + threshold
+            );
+          }
+          return fieldValue === number;
+        }
+        return fieldValue === this.value;
+
+      case 'isNot':
+        return fieldValue !== this.value;
+      case 'isbetween': {
+        // The parsing logic already checks that the value is of the
+        // right type (only numbers with high and low)
+        const [low, high] = sortNumbers(this.value.num1, this.value.num2);
+        return fieldValue >= low && fieldValue <= high;
+      }
+      case 'contains':
+        if (fieldValue === null) {
+          return false;
+        }
+        return String(fieldValue).indexOf(this.value) !== -1;
+      case 'doesNotContain':
+        if (fieldValue === null) {
+          return false;
+        }
+        return String(fieldValue).indexOf(this.value) === -1;
+      case 'oneOf':
+        if (fieldValue === null) {
+          return false;
+        }
+        return this.value.indexOf(fieldValue) !== -1;
+
+      case 'hasTags':
+        if (fieldValue === null) {
+          return false;
+        }
+        return String(fieldValue).indexOf(this.value) !== -1;
+
+      case 'notOneOf':
+        if (fieldValue === null) {
+          return false;
+        }
+        return this.value.indexOf(fieldValue) === -1;
+      case 'gt':
+        if (fieldValue === null) {
+          return false;
+        } else if (type === 'date') {
+          return isAfter(fieldValue, this.value.date);
+        }
+
+        return fieldValue > extractValue(this.value);
+      case 'gte':
+        if (fieldValue === null) {
+          return false;
+        } else if (type === 'date') {
+          return (
+            fieldValue === this.value.date ||
+            isAfter(fieldValue, this.value.date)
+          );
+        }
+
+        return fieldValue >= extractValue(this.value);
+      case 'lt':
+        if (fieldValue === null) {
+          return false;
+        } else if (type === 'date') {
+          return isBefore(fieldValue, this.value.date);
+        }
+        return fieldValue < extractValue(this.value);
+      case 'lte':
+        if (fieldValue === null) {
+          return false;
+        } else if (type === 'date') {
+          return (
+            fieldValue === this.value.date ||
+            isBefore(fieldValue, this.value.date)
+          );
+        }
+        return fieldValue <= extractValue(this.value);
+      case 'matches':
+        if (fieldValue === null) {
+          return false;
+        }
+        try {
+          return new RegExp(this.value).test(fieldValue);
+        } catch (e) {
+          logger.log('invalid regexp in matches condition', e);
+          return false;
+        }
+
+      case 'onBudget':
+        if (!object._account) {
+          return false;
+        }
+
+        return object._account.offbudget === 0;
+
+      case 'offBudget':
+        if (!object._account) {
+          return false;
+        }
+
+        return object._account.offbudget === 1;
+
+      default:
+    }
+
+    return false;
+  }
+
+  getValue() {
+    return this.value;
+  }
+
+  serialize() {
+    return {
+      op: this.op,
+      field: this.field,
+      value: this.unparsedValue,
+      type: this.type,
+      ...(this.options ? { options: this.options } : null),
+    };
+  }
+}

package/src/server/rules/customFunctions.ts

@@ -0,0 +1,61 @@
+import { FunctionArgumentType, FunctionPlugin } from 'hyperformula';
+import type { InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
+import type { ProcedureAst } from 'hyperformula/typings/parser';
+
+import { integerToAmount } from '../../shared/util';
+
+export class CustomFunctionsPlugin extends FunctionPlugin {
+  integerToAmount(ast: ProcedureAst, state: InterpreterState) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('INTEGER_TO_AMOUNT'),
+      (integerAmount: number, decimalPlaces: number = 2) => {
+        return integerToAmount(integerAmount, decimalPlaces);
+      },
+    );
+  }
+
+  fixed(ast: ProcedureAst, state: InterpreterState) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('FIXED'),
+      (number: number, decimals: number = 0) => {
+        return Number(number).toFixed(decimals);
+      },
+    );
+  }
+}
+
+CustomFunctionsPlugin.implementedFunctions = {
+  INTEGER_TO_AMOUNT: {
+    method: 'integerToAmount',
+    parameters: [
+      { argumentType: FunctionArgumentType.NUMBER },
+      {
+        argumentType: FunctionArgumentType.NUMBER,
+        optionalArg: true,
+        defaultValue: 2,
+      },
+    ],
+  },
+  FIXED: {
+    method: 'fixed',
+    parameters: [
+      { argumentType: FunctionArgumentType.NUMBER },
+      {
+        argumentType: FunctionArgumentType.NUMBER,
+        optionalArg: true,
+        defaultValue: 0,
+      },
+    ],
+  },
+};
+
+export const customFunctionsTranslations = {
+  enUS: {
+    INTEGER_TO_AMOUNT: 'INTEGER_TO_AMOUNT',
+    FIXED: 'FIXED',
+  },
+};

package/src/server/rules/formula-action.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+
+import type { TransactionForRules } from '../transactions/transaction-rules';
+
+import { Action } from './action';
+
+describe('Formula-based rule actions', () => {
+  it('should execute a simple math formula', () => {
+    const action = new Action('set', 'amount', null, {});
+    const transaction: Partial<TransactionForRules> = { amount: 500 };
+    const result = action.executeFormulaSync('=100 + 200', transaction);
+
+    expect(result).toBe(30000);
+  });
+
+  it('should use transaction field variables', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = { amount: 5000 };
+    const result = action.executeFormulaSync('=amount / 100', transaction);
+
+    expect(result).toBe(5000);
+  });
+
+  it('should support IF function with transaction fields', () => {
+    const action = new Action('set', 'notes', null, {});
+
+    const transaction1 = { amount: 1000 };
+    const result1 = action.executeFormulaSync(
+      '=IF(amount > 0, "Income", "Expense")',
+      transaction1,
+    );
+    expect(result1).toBe('Income');
+
+    const transaction2 = { amount: -1000 };
+    const result2 = action.executeFormulaSync(
+      '=IF(amount > 0, "Income", "Expense")',
+      transaction2,
+    );
+    expect(result2).toBe('Expense');
+  });
+
+  it('should support UPPER string function', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = { notes: 'hello world' };
+    const result = action.executeFormulaSync('=UPPER(notes)', transaction);
+
+    expect(result).toBe('HELLO WORLD');
+  });
+
+  it('should support CONCATENATE function', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = {
+      imported_payee: 'Store Name',
+      notes: 'Purchase',
+    };
+    const result = action.executeFormulaSync(
+      '=CONCATENATE(imported_payee, " - ", notes)',
+      transaction,
+    );
+
+    expect(result).toBe('Store Name - Purchase');
+  });
+
+  it('should support LEFT function', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = { imported_payee: 'Store Name' };
+    const result = action.executeFormulaSync(
+      '=LEFT(imported_payee, 5)',
+      transaction,
+    );
+
+    expect(result).toBe('Store');
+  });
+
+  it('should provide today variable', () => {
+    const action = new Action('set', 'date', null, {});
+    const transaction = { date: '2024-01-01' };
+    const result = action.executeFormulaSync('=today', transaction);
+
+    // Should be a date string in YYYY-MM-DD format
+    expect(typeof result).toBe('string');
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  it('should throw error for invalid formula', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = { amount: 100 };
+
+    expect(() => {
+      action.executeFormulaSync('=INVALID_FUNCTION()', transaction);
+    }).toThrow();
+  });
+
+  it('should throw error for formula without = prefix', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction = { amount: 100 };
+
+    expect(() => {
+      action.executeFormulaSync('amount + 100', transaction);
+    }).toThrow('Formula must start with =');
+  });
+
+  it('should support balance field variable', () => {
+    const action = new Action('set', 'notes', null, {});
+    const transaction: Partial<TransactionForRules> = {
+      balance: 1500,
+      notes: 'original',
+    };
+    const result = action.executeFormulaSync('=balance * 2', transaction);
+
+    expect(result).toBe(300000);
+  });
+
+  it('should execute formula and convert to number type', () => {
+    const action = new Action('set', 'amount', null, {
+      formula: '=500 + 250',
+    });
+
+    const transaction = { amount: 100 };
+    action.exec(transaction);
+
+    expect(transaction.amount).toBe(75000);
+  });
+
+  it('should execute formula and convert to string type', () => {
+    const action = new Action('set', 'notes', null, {
+      formula: '=UPPER("hello")',
+    });
+
+    const transaction = { notes: 'original' };
+    action.exec(transaction);
+
+    expect(transaction.notes).toBe('HELLO');
+  });
+
+  it('should handle formula errors gracefully', () => {
+    const action = new Action('set', 'notes', null, {
+      formula: '=1/0', // Division by zero
+    });
+
+    const transaction = { notes: 'original' };
+
+    // Should not throw, but keep original value on error
+    expect(() => {
+      action.exec(transaction);
+    }).not.toThrow();
+
+    // Original value should be preserved
+    expect(transaction.notes).toBe('original');
+  });
+
+  it('should validate numeric field output', () => {
+    const action = new Action('set', 'amount', null, {
+      formula: '=UPPER("test")', // Returns string for numeric field
+    });
+
+    const transaction = { amount: 100 };
+    action.exec(transaction);
+
+    // Should keep original value when formula produces non-numeric result
+    expect(transaction.amount).toBe(100);
+  });
+
+  it('should convert non-string results to string for text fields', () => {
+    const action = new Action('set', 'notes', null, {
+      formula: '=500 + 250', // Returns number
+    });
+
+    const transaction = { notes: 'original' };
+    action.exec(transaction);
+
+    // Should convert number to string
+    expect(transaction.notes).toBe('75000');
+  });
+});