A local-first personal finance app
[AI] Add loan functions to formulas (#8705)
youngcwbf5bcf54fcbc
diff --git a/packages/desktop-client/src/components/formula/formulaCatalog.ts b/packages/desktop-client/src/components/formula/formulaCatalog.tsindex c36ab5f691..8680076f11 100644--- a/packages/desktop-client/src/components/formula/formulaCatalog.ts+++ b/packages/desktop-client/src/components/formula/formulaCatalog.ts@@ -982,6 +982,135 @@ export function getFormulaFunctionCatalog(): Record<{ name: 'pv', description: t('Present value') },],},+ IPMT: {+ name: 'IPMT',+ category: 'math',+ modes: ['query', 'transaction'],+ description: t(+ 'Calculates the interest portion of a loan payment for a given period.',+ ),+ parameters: [+ { name: 'rate', description: t('Interest rate') },+ { name: 'period', description: t('Period to calculate (1-based)') },+ { name: 'nper', description: t('Number of periods') },+ { name: 'pv', description: t('Present value') },+ ],+ },+ PPMT: {+ name: 'PPMT',+ category: 'math',+ modes: ['query', 'transaction'],+ description: t(+ 'Calculates the principal portion of a loan payment for a given period.',+ ),+ parameters: [+ { name: 'rate', description: t('Interest rate') },+ { name: 'period', description: t('Period to calculate (1-based)') },+ { name: 'nper', description: t('Number of periods') },+ { name: 'pv', description: t('Present value') },+ ],+ },+ NPER: {+ name: 'NPER',+ category: 'math',+ modes: ['query', 'transaction'],+ description: t(+ 'Calculates the number of payment periods for a loan or investment.',+ ),+ parameters: [+ { name: 'rate', description: t('Interest rate') },+ { name: 'pmt', description: t('Payment amount') },+ { name: 'pv', description: t('Present value') },+ ],+ },+ CUMIPMT: {+ name: 'CUMIPMT',+ category: 'math',+ modes: ['query', 'transaction'],+ description: t(+ 'Calculates cumulative interest paid between two periods.',+ ),+ parameters: [+ { name: 'rate', description: t('Interest rate') },+ { name: 'nper', description: t('Number of periods') },+ { name: 'pv', description: t('Present value') },+ { name: 'start_period', description: t('First period (1-based)') },+ { name: 'end_period', description: t('Last period (1-based)') },+ {+ name: 'type',+ description: t('0 = end of period, 1 = start of period'),+ },+ ],+ },+ CUMPRINC: {+ name: 'CUMPRINC',+ category: 'math',+ modes: ['query', 'transaction'],+ description: t(+ 'Calculates cumulative principal paid between two periods.',+ ),+ parameters: [+ { name: 'rate', description: t('Interest rate') },+ { name: 'nper', description: t('Number of periods') },+ { name: 'pv', description: t('Present value') },+ { name: 'start_period', description: t('First period (1-based)') },+ { name: 'end_period', description: t('Last period (1-based)') },+ {+ name: 'type',+ description: t('0 = end of period, 1 = start of period'),+ },+ ],+ },+ MIRR: {+ name: 'MIRR',+ category: 'math',+ modes: ['query'],+ description: t(+ 'Calculates the modified internal rate of return for a series of cash flows.',+ ),+ parameters: [+ { name: 'values', description: t('Range of cash flow values') },+ {+ name: 'finance_rate',+ description: t('Interest rate paid on financing'),+ },+ {+ name: 'reinvest_rate',+ description: t('Interest rate earned on reinvested cash flows'),+ },+ ],+ },+ XNPV: {+ name: 'XNPV',+ category: 'math',+ modes: ['query'],+ description: t(+ 'Calculates net present value for cash flows on irregular (dated) intervals.',+ ),+ parameters: [+ { name: 'rate', description: t('Discount rate') },+ { name: 'values', description: t('Range of cash flow values') },+ {+ name: 'dates',+ description: t('Range of dates matching each cash flow'),+ },+ ],+ },+ FVSCHEDULE: {+ name: 'FVSCHEDULE',+ category: 'math',+ modes: ['query'],+ description: t(+ 'Calculates future value of a principal using a schedule of varying interest rates.',+ ),+ parameters: [+ { name: 'principal', description: t('Starting principal amount') },+ {+ name: 'schedule',+ description: t('Range of interest rates to apply successively'),+ },+ ],+ },QUERY: {name: 'QUERY',category: 'query',diff --git a/packages/docs/docs/experimental/formulas.md b/packages/docs/docs/experimental/formulas.mdindex a7f3fbfd78..a6315e2d65 100644--- a/packages/docs/docs/experimental/formulas.md+++ b/packages/docs/docs/experimental/formulas.md@@ -67,6 +67,8 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `COUNTBLANK` | Query | Counts empty cells. | `=COUNTBLANK(A1:A10)` | — || `COUNTIF` | Query | Counts cells that meet a criteria. | `=COUNTIF(A1:A10, ">0")` | — || `COUNTIFS` | Query | Counts cells that meet multiple criteria. | `=COUNTIFS(A1:A10, ">0", B1:B10, "<=5")` | Repeat `(range, criteria)` pairs |+| `CUMIPMT` | Query, Rules | Calculates cumulative interest paid between two periods. | `=CUMIPMT(0.05/12, 60, 20000, 1, 12, 0)` | — |+| `CUMPRINC` | Query, Rules | Calculates cumulative principal paid between two periods. | `=CUMPRINC(0.05/12, 60, 20000, 1, 12, 0)` | — || `DATE` | Query, Rules | Returns date as number of days since null date. | `=DATE(2025, 12, 16)` | — || `DATEDIF` | Query, Rules | Calculates distance between dates. | `=DATEDIF("2025-01-01", "2025-12-31", "D")` | — || `DATEVALUE` | Rules | Parses a date string and returns it as a number. | `=DATEVALUE("2025-12-16")` | — |@@ -78,10 +80,12 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `EXP` | Query | Returns e raised to the power of number. | `=EXP(1)` | — || `FALSE` | Query, Rules | Returns the logical value FALSE. | `=FALSE()` | — || `FIND` | Query, Rules | Finds text within text (case-sensitive). | `=FIND("foo", notes)` | — |+| `FIXED` | Query, Rules | Formats a number to a fixed amount of decimal places. | `=FIXED(1234.5, 2)` | — || `FLOOR` | Query, Rules | Rounds down to nearest multiple of significance. | `=FLOOR(10.8, 1)` | — || `FORMATCURRENCY` | Query, Rules | Formats a number as currency using your app currency, number format, symbol position, and spacing settings by default. | `=FORMATCURRENCY(1234.5)` | `symbol`, `decimals`, `thousandsSeparator`, `decimalSeparator`, `symbolPosition`, `spaceBetweenAmountAndSymbol` || `FORMATNUMBER` | Query, Rules | Formats a number using your app number format settings by default. | `=FORMATNUMBER(1234.5, 2)` | `decimals`, `thousandsSeparator`, `decimalSeparator` || `FV` | Query | Calculates future value of investment. | `=FV(0.05/12, 12, -100)` | — |+| `FVSCHEDULE` | Query | Calculates future value of a principal using a schedule of varying interest rates. | `=FVSCHEDULE(1000, {0.05;0.06;0.07})` | — || `HLOOKUP` | Query | Searches horizontally in first row and returns value. | `=HLOOKUP("key", A1:D10, 2, TRUE)` | — || `IF` | Query, Rules | Returns one value if condition is TRUE, another if FALSE. | `=IF(amount<0, "Expense", "Income")` | — || `IFERROR` | Query, Rules | Returns value if no error, otherwise returns alternative. | `=IFERROR(1/0, 0)` | — |@@ -90,6 +94,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `INDEX` | Query | Returns value at specified row and column. | `=INDEX(A1:C10, 2, 3)` | — || `INTEGER_TO_AMOUNT` | Query, Rules | Converts integer amount to decimal amount (e.g., 1234 -> 12.34). | `=INTEGER_TO_AMOUNT(amount, 2)` | `decimal_places` (default: 2) || `INT` | Rules | Rounds down to nearest integer. | `=INT(10.9)` | — |+| `IPMT` | Query, Rules | Calculates the interest portion of a loan payment for a given period. | `=IPMT(0.05/12, 1, 60, 20000)` | — || `IRR` | Query | Calculates internal rate of return. | `=IRR(A1:A12)` | — || `ISEVEN` | Rules | Returns TRUE if number is even. | `=ISEVEN(10)` | — || `ISODD` | Rules | Returns TRUE if number is odd. | `=ISODD(11)` | — |@@ -115,6 +120,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `MID` | Query, Rules | Returns substring from specified position. | `=MID(notes, 1, 10)` | — || `MIN` | Query | Returns the minimum value. | `=MIN(1, 2, 3)` | Accepts more than 2 values || `MINA` | Query | Returns the minimum value, including text and logical values. | `=MINA(1, TRUE, "2")` | Accepts more than 2 values |+| `MIRR` | Query | Calculates the modified internal rate of return for a series of cash flows. | `=MIRR(A1:A12, 0.1, 0.12)` | — || `MOD` | Query, Rules | Returns the remainder of division. | `=MOD(10, 3)` | — || `MODE` | Query | Returns the most frequently occurring value. | `=MODE(1, 1, 2)` | Accepts more than 2 values || `MONTH` | Query, Rules | Returns the month from a date. | `=MONTH(date)` | — |@@ -122,12 +128,14 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `NETWORKDAYS` | Query | Returns number of working days between dates. | `=NETWORKDAYS("2025-12-01", "2025-12-31")` | — || `NOT` | Query, Rules | Reverses the logical value. | `=NOT(amount<0)` | — || `NOW` | Query, Rules | Returns current date and time. | `=NOW()` | — |+| `NPER` | Query, Rules | Calculates the number of payment periods for a loan or investment. | `=NPER(0.05/12, -200, 10000)` | — || `NPV` | Query | Calculates net present value. | `=NPV(0.1, -1000, 200, 300)` | Accepts more than 2 values || `OR` | Query, Rules | Returns TRUE if any argument is TRUE. | `=OR(amount<0, amount>0)` | Accepts more than 2 conditions || `PERCENTILE` | Query | Returns the k-th percentile. | `=PERCENTILE(A1:A100, 0.9)` | — || `PI` | Query | Returns the value of PI. | `=PI()` | — || `PMT` | Query | Calculates payment for a loan. | `=PMT(0.05/12, 60, 10000)` | — || `POWER` | Query, Rules | Returns base raised to the power of exponent. | `=POWER(2, 8)` | — |+| `PPMT` | Query, Rules | Calculates the principal portion of a loan payment for a given period. | `=PPMT(0.05/12, 1, 60, 20000)` | — || `PROPER` | Query, Rules | Capitalizes first letter of each word. | `=PROPER(notes)` | — || `PRODUCT` | Query | Returns the product of all numbers. | `=PRODUCT(2, 3, 4)` | Accepts more than 2 values || `PV` | Query | Calculates present value of investment. | `=PV(0.05/12, 12, -100)` | — |@@ -173,6 +181,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula| `VLOOKUP` | Query | Searches vertically in first column and returns value. | `=VLOOKUP("key", A1:D10, 2, TRUE)` | — || `WEEKDAY` | Query, Rules | Returns day of week (1-7). | `=WEEKDAY(date, 1)` | — || `WEEKNUM` | Query, Rules | Returns week number of year. | `=WEEKNUM(date, 1)` | — |+| `XNPV` | Query | Calculates net present value for cash flows on irregular (dated) intervals. | `=XNPV(0.1, A1:A5, B1:B5)` | — || `XOR` | Query, Rules | Returns TRUE if odd number of arguments are TRUE. | `=XOR(TRUE(), FALSE())` | Accepts more than 2 conditions || `YEAR` | Query, Rules | Returns the year from a date. | `=YEAR(date)` | — |@@ -339,7 +348,13 @@ Rule formulas evaluate with named variables from the transaction context, includ- `cleared` — Whether transaction is cleared (`TRUE` or `FALSE`)- `reconciled` — Whether transaction is reconciled (`TRUE` or `FALSE`)-Tip: if you want “dollars” from `amount`, use `=amount / 100`.+:::caution Cents in, dollars out+Numbers going **into** a formula and numbers coming **out** of one use different units.++The `amount` and `balance` variables hand you integer cents, but a number your formula produces is read as **dollars** and converted to cents when Actual stores it. So a formula of `=500 + 250` sets the amount to $750.00, not $7.50.++When you calculate with `amount` or `balance`, divide by 100 first so both sides are in dollars. For example, `=amount / 100 * 1.05` adds 5% to the transaction amount, while `=amount * 1.05` gives a result 100 times too large.+:::### Available functions@@ -357,6 +372,18 @@ Tip: if you want “dollars” from `amount`, use `=amount / 100`.- Returns an integer in cents. For the amount in dollars, divide by 100 or `=INTEGER_TO_AMOUNT(BALANCE_OF("Checking"))`.- `BALANCE_OF` is also available in Formula cards, where it returns the account's current balance instead — see [Account balances with `BALANCE_OF("name")`](#account-balances-with-balance_ofname) above.+**Loan payment functions (`IPMT`, `PPMT`, `NPER`, `CUMIPMT`, `CUMPRINC`):**++If you record a loan (mortgage, auto loan, etc.) payment as a single transaction, these functions let a rule split it into interest/principal or show progress, based on the transaction's own `date`. They need a **period number**, which you can derive from the loan's start date with `DATEDIF`:++```text+=IPMT(0.05/12, DATEDIF("2024-01-01", date, "M") + 1, 360, -300000)+```++This computes the interest portion of the payment for the month of the current transaction, for a 30-year (360-month) loan that started 2024-01-01 at 5% annual interest on a $300,000 principal. Swap `IPMT` for `PPMT` to get the principal portion instead, or use `CUMIPMT`/`CUMPRINC` with a `start_period` of `1` and that same period as `end_period` to get interest/principal paid to date.++Write the principal in dollars (`-300000`), not cents. These functions return their result in the same unit you pass in, and Actual expects a numeric formula result in dollars — see [Cents in, dollars out](#available-variables) above.+### Result typesWhen a rule runs, Actual converts the formula result to the field type:@@ -365,3 +392,5 @@ When a rule runs, Actual converts the formula result to the field type:- **date fields**: must produce a valid date- **boolean fields**: `TRUE`/`FALSE` (or a string that equals `"true"`/`"false"`)- **string fields**: converted with `String(...)`++Number fields receive the result in dollars and store it in cents — see [Cents in, dollars out](#available-variables) above.diff --git a/upcoming-release-notes/add-loan-formula-autocomplete.md b/upcoming-release-notes/add-loan-formula-autocomplete.mdnew file mode 100644index 0000000000..b0b2e1e180--- /dev/null+++ b/upcoming-release-notes/add-loan-formula-autocomplete.md@@ -0,0 +1,6 @@+---+category: Enhancements+authors: [youngcw]+---++Add autocomplete and help text for loan and investment formula functions like IPMT, PPMT, NPER, and XNPV