@columenlabs/lumen-ui-types 0.1.34 → 0.1.35

package/dist/formula-functions.d.ts

@@ -0,0 +1,14 @@
+export interface FormulaFunction {
+    name: string;
+    /** How it is called, e.g. `left(text, n)`. */
+    call: string;
+    /** What it gives, in a few words. */
+    detail: string;
+    group: 'Date' | 'Text' | 'Number';
+    /** It gives text (a column of it shows as Text). */
+    text?: boolean;
+    fn: (...args: unknown[]) => unknown;
+}
+export declare const FORMULA_FUNCTIONS: FormulaFunction[];
+/** The functions as one line each, for an assistant's instructions. */
+export declare const formulaFunctionsText: () => string;

package/dist/formula-functions.js

@@ -0,0 +1,269 @@
+// The functions a view formula can call beyond group_sum and total_sum: dates, text and numbers,
+// e.g. `year(transactions.date)`, `left(symbol.name, 3)`, `round(holdings.weight, 1)`. Dates are
+// `YYYY-MM-DD` or ISO text (or epoch milliseconds), read in UTC so the browser and the server agree;
+// date math is date-fns. A function given what it cannot use gives no value (a blank cell).
+import { UTCDate, utc } from '@date-fns/utc';
+import { differenceInCalendarDays, format, getDate, getISODay, getMonth, getQuarter, getYear, isValid, parseISO, startOfISOWeek, startOfMonth, startOfQuarter, startOfYear, } from 'date-fns';
+const asDate = (v) => {
+    const d = typeof v === 'number'
+        ? new UTCDate(v)
+        : typeof v === 'string' && v
+            ? parseISO(v, { in: utc })
+            : null;
+    return d && isValid(d) ? d : null;
+};
+const asText = (v) => typeof v === 'string' ? v : typeof v === 'number' && Number.isFinite(v) ? String(v) : null;
+const asNum = (v) => {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() ? Number(v) : Number.NaN;
+    return Number.isFinite(n) ? n : null;
+};
+const day = (d) => format(d, 'yyyy-MM-dd');
+/** A date part: the function reads one date and gives a number. */
+const part = (get) => (v) => {
+    const d = asDate(v);
+    return d ? get(d) : undefined;
+};
+/** A text function: the first argument is the text, the rest numbers (or text, `rest`). */
+const onText = (f) => (v, ...rest) => {
+    const s = asText(v);
+    return s === null ? undefined : (f(s, ...rest) ?? undefined);
+};
+const STARTS = {
+    week: startOfISOWeek,
+    month: startOfMonth,
+    quarter: startOfQuarter,
+    year: startOfYear,
+};
+export const FORMULA_FUNCTIONS = [
+    {
+        name: 'year',
+        call: 'year(date)',
+        detail: 'the year, 2026',
+        group: 'Date',
+        fn: part(getYear),
+    },
+    {
+        name: 'month',
+        call: 'month(date)',
+        detail: 'the month, 1 to 12',
+        group: 'Date',
+        fn: part((d) => getMonth(d) + 1),
+    },
+    {
+        name: 'day',
+        call: 'day(date)',
+        detail: 'the day of the month',
+        group: 'Date',
+        fn: part(getDate),
+    },
+    {
+        name: 'quarter',
+        call: 'quarter(date)',
+        detail: 'the quarter, 1 to 4',
+        group: 'Date',
+        fn: part(getQuarter),
+    },
+    {
+        name: 'weekday',
+        call: 'weekday(date)',
+        detail: 'the day of the week, 1 Monday to 7 Sunday',
+        group: 'Date',
+        fn: part(getISODay),
+    },
+    {
+        name: 'days_between',
+        call: 'days_between(from, to)',
+        detail: 'days from one date to another',
+        group: 'Date',
+        fn: (a, b) => {
+            const from = asDate(a);
+            const to = asDate(b);
+            return from && to ? differenceInCalendarDays(to, from) : undefined;
+        },
+    },
+    {
+        name: 'start_of',
+        call: "start_of(date, 'month')",
+        detail: "the first day of its 'week', 'month', 'quarter' or 'year'",
+        group: 'Date',
+        text: true,
+        fn: (v, unit) => {
+            const d = asDate(v);
+            const start = typeof unit === 'string' ? STARTS[unit] : undefined;
+            return d && start ? day(start(d)) : undefined;
+        },
+    },
+    {
+        name: 'today',
+        call: 'today()',
+        detail: "today's date (UTC)",
+        group: 'Date',
+        text: true,
+        fn: () => day(new UTCDate()),
+    },
+    {
+        name: 'left',
+        call: 'left(text, n)',
+        detail: 'the first n characters',
+        group: 'Text',
+        text: true,
+        fn: onText((s, n) => {
+            const k = asNum(n);
+            return k === null ? null : s.slice(0, Math.max(0, k));
+        }),
+    },
+    {
+        name: 'right',
+        call: 'right(text, n)',
+        detail: 'the last n characters',
+        group: 'Text',
+        text: true,
+        fn: onText((s, n) => {
+            const k = asNum(n);
+            return k === null ? null : k <= 0 ? '' : s.slice(-k);
+        }),
+    },
+    {
+        name: 'mid',
+        call: 'mid(text, start, length)',
+        detail: 'length characters from position start (the first is 1)',
+        group: 'Text',
+        text: true,
+        fn: onText((s, start, length) => {
+            const a = asNum(start);
+            const n = asNum(length);
+            return a === null || n === null ? null : s.slice(Math.max(0, a - 1), Math.max(0, a - 1 + n));
+        }),
+    },
+    {
+        name: 'slice',
+        call: 'slice(text, from, to)',
+        detail: 'characters from index from up to to, the first is 0 (to left out: to the end)',
+        group: 'Text',
+        text: true,
+        fn: onText((s, from, to) => {
+            const a = asNum(from);
+            if (a === null)
+                return null;
+            return to === undefined ? s.slice(a) : s.slice(a, asNum(to) ?? undefined);
+        }),
+    },
+    {
+        name: 'upper',
+        call: 'upper(text)',
+        detail: 'in capitals',
+        group: 'Text',
+        text: true,
+        fn: onText((s) => s.toUpperCase()),
+    },
+    {
+        name: 'lower',
+        call: 'lower(text)',
+        detail: 'in small letters',
+        group: 'Text',
+        text: true,
+        fn: onText((s) => s.toLowerCase()),
+    },
+    {
+        name: 'trim',
+        call: 'trim(text)',
+        detail: 'without spaces at either end',
+        group: 'Text',
+        text: true,
+        fn: onText((s) => s.trim()),
+    },
+    {
+        name: 'len',
+        call: 'len(text)',
+        detail: 'how many characters',
+        group: 'Text',
+        fn: onText((s) => s.length),
+    },
+    {
+        name: 'concat',
+        call: 'concat(a, b, ...)',
+        detail: 'the values joined into one text (blanks left out)',
+        group: 'Text',
+        text: true,
+        fn: (...args) => args
+            .map(asText)
+            .filter((s) => s !== null)
+            .join(''),
+    },
+    {
+        name: 'contains',
+        call: 'contains(text, part)',
+        detail: 'whether the text holds part (any case)',
+        group: 'Text',
+        fn: onText((s, p) => {
+            const q = asText(p);
+            return q === null ? null : s.toLowerCase().includes(q.toLowerCase());
+        }),
+    },
+    {
+        name: 'replace',
+        call: 'replace(text, find, with)',
+        detail: 'every find swapped for with',
+        group: 'Text',
+        text: true,
+        fn: onText((s, find, to) => {
+            const f = asText(find);
+            return f ? s.replaceAll(f, asText(to) ?? '') : null;
+        }),
+    },
+    {
+        name: 'split_part',
+        call: "split_part(text, ',', n)",
+        detail: 'the nth piece between separators (the first is 1)',
+        group: 'Text',
+        text: true,
+        fn: onText((s, sep, n) => {
+            const by = asText(sep);
+            const k = asNum(n);
+            return by && k !== null && k >= 1 ? (s.split(by)[k - 1] ?? null) : null;
+        }),
+    },
+    {
+        name: 'round',
+        call: 'round(x, digits)',
+        detail: 'rounded, to digits places (0 when left out)',
+        group: 'Number',
+        fn: (v, digits) => {
+            const x = asNum(v);
+            const p = 10 ** (asNum(digits) ?? 0);
+            return x === null ? undefined : Math.round(x * p) / p;
+        },
+    },
+    {
+        name: 'abs',
+        call: 'abs(x)',
+        detail: 'without its sign',
+        group: 'Number',
+        fn: (v) => {
+            const x = asNum(v);
+            return x === null ? undefined : Math.abs(x);
+        },
+    },
+    {
+        name: 'min',
+        call: 'min(a, b, ...)',
+        detail: 'the smallest (blanks left out)',
+        group: 'Number',
+        fn: (...args) => {
+            const xs = args.map(asNum).filter((x) => x !== null);
+            return xs.length ? Math.min(...xs) : undefined;
+        },
+    },
+    {
+        name: 'max',
+        call: 'max(a, b, ...)',
+        detail: 'the largest (blanks left out)',
+        group: 'Number',
+        fn: (...args) => {
+            const xs = args.map(asNum).filter((x) => x !== null);
+            return xs.length ? Math.max(...xs) : undefined;
+        },
+    },
+];
+/** The functions as one line each, for an assistant's instructions. */
+export const formulaFunctionsText = () => FORMULA_FUNCTIONS.map((f) => `${f.call}: ${f.detail}`).join('; ');

package/dist/view-formula.d.ts

@@ -5,7 +5,7 @@ export interface ViewFormulaScope {
     groupSum: (key: string) => number;
     totalSum: (key: string) => number;
 }
-export declare const viewFormulaFunctions: readonly ['group_sum', 'total_sum'];
+export declare const viewFormulaFunctions: readonly ["group_sum", "total_sum", ...string[]];
 /** Compiles a formula (throws on a syntax error) into a row evaluator; a failed row is null. */
 export declare function compileViewFormula(expr: string): (scope: ViewFormulaScope) => number | string | null;
 /**

package/dist/view-formula.js

@@ -9,14 +9,25 @@
 // `account.cash`) or a linked domain (`tax_lots.unrealized`); `frame.<frame>.<column>` for an
 // assistant frame; and another formula by its bare key (`value_nonretire`), at any depth, never in a
 // loop. Rows keep their flat field keys; each surface maps a name to its key (`FormulaNames`).
+// Beyond the two sums it calls the date, text and number functions in `FORMULA_FUNCTIONS`
+// (`year(transactions.date)`); any other function is refused by the check.
 import jexl from 'jexl';
-export const viewFormulaFunctions = ['group_sum', 'total_sum'];
+import { FORMULA_FUNCTIONS } from './formula-functions.js';
+export const viewFormulaFunctions = [
+    'group_sum',
+    'total_sum',
+    ...FORMULA_FUNCTIONS.map((f) => f.name),
+];
+const knownFunctions = new Set(viewFormulaFunctions);
+const textFunctions = new Set(FORMULA_FUNCTIONS.filter((f) => f.text).map((f) => f.name));
 // Functions get only their arguments, so the row being evaluated is set around each evalSync
 // (evaluation is synchronous, so one at a time).
 let current = null;
 const engine = new jexl.Jexl();
 engine.addFunction('group_sum', (key) => typeof key === 'string' && current ? current.groupSum(key) : Number.NaN);
 engine.addFunction('total_sum', (key) => typeof key === 'string' && current ? current.totalSum(key) : Number.NaN);
+for (const f of FORMULA_FUNCTIONS)
+    engine.addFunction(f.name, f.fn);
 /**
  * Folds each dotted name (`symbol.price`, Jexl's member access) into one identifier whose value is
  * the whole name, so the scope reads `symbol.price` in one call, as it reads a bare formula key.
@@ -122,6 +133,8 @@ const endsInText = (a) => {
         return false;
     if (a.type === 'Literal')
         return typeof a.value === 'string';
+    if (a.type === 'FunctionCall')
+        return textFunctions.has(String(a.name));
     if (a.type === 'ConditionalExpression')
         return endsInText(a.consequent) && endsInText(a.alternate);
     if (a.type === 'BinaryExpression' && a.operator === '+')
@@ -141,40 +154,71 @@ export function viewFormulaIsText(expr) {
         return false;
     }
 }
+/** The functions a tree calls that the formula language lacks (a `|transform` is one too). */
+function unknownFunctions(n, out) {
+    if (!n || typeof n !== 'object')
+        return out;
+    if (Array.isArray(n)) {
+        for (const x of n)
+            unknownFunctions(x, out);
+        return out;
+    }
+    const node = n;
+    if (node.type === 'FunctionCall' &&
+        (node.pool !== 'functions' || !knownFunctions.has(String(node.name))))
+        out.add(String(node.name));
+    for (const v of Object.values(node))
+        unknownFunctions(v, out);
+    return out;
+}
+/**
+ * The names a tree reads, found in the tree rather than by running it, so a name on a branch that
+ * did not run, or inside a function given nothing, still counts: each name (dotted names folded)
+ * and each quoted group_sum or total_sum argument.
+ */
+function namesIn(n, out) {
+    if (!n || typeof n !== 'object')
+        return out;
+    if (Array.isArray(n)) {
+        for (const x of n)
+            namesIn(x, out);
+        return out;
+    }
+    const node = n;
+    if (node.type === 'Identifier' && !node.from && !node.relative)
+        out.add(String(node.value));
+    if (node.type === 'FunctionCall' &&
+        (node.name === 'group_sum' || node.name === 'total_sum') &&
+        node.args?.[0]?.type === 'Literal' &&
+        typeof node.args[0].value === 'string')
+        out.add(node.args[0].value);
+    for (const v of Object.values(node))
+        namesIn(v, out);
+    return out;
+}
 /** Why a formula can't run on fields `keys` (null: any field), or null when it can. */
 export function checkViewFormula(expr, keys) {
-    let run;
+    let ast;
     try {
-        run = compileViewFormula(expr);
+        ast = compileNamed(expr)._getAst();
     }
     catch (e) {
         return `syntax: ${e instanceof Error ? e.message : String(e)}`;
     }
-    const unknown = new Set();
-    const known = (k) => {
-        if (keys && !keys.includes(k))
-            unknown.add(k);
-        return 1;
-    };
-    run({ value: known, groupSum: known, totalSum: known });
-    return unknown.size ? `unknown field ${[...unknown].join(', ')}` : null;
+    const missing = [...unknownFunctions(ast, new Set())];
+    if (missing.length)
+        return `unknown function ${missing.join(', ')} (functions: ${viewFormulaFunctions.join(', ')})`;
+    const unknown = keys ? [...namesIn(ast, new Set())].filter((k) => !keys.includes(k)) : [];
+    return unknown.length ? `unknown field ${unknown.join(', ')}` : null;
 }
 /** The names a formula reads (fields and formulas, `group_sum` arguments included); [] when it does not parse. */
 export function formulaReads(expr) {
-    let run;
     try {
-        run = compileViewFormula(expr);
+        return [...namesIn(compileNamed(expr)._getAst(), new Set())];
     }
     catch {
         return [];
     }
-    const read = new Set();
-    const note = (k) => {
-        read.add(k);
-        return 1;
-    };
-    run({ value: note, groupSum: note, totalSum: note });
-    return [...read];
 }
 /** A frame's part of a name: `Earnings next week` is `frame.earnings_next_week`. */
 export function frameSpace(name) {

package/dist/views.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { type JoinKey } from './domains.js';
 import { type FormulaNames } from './view-formula.js';
 export { checkViewFormula, compileViewFormula, type FormulaNames, formulaLoops, formulaReads, frameSpace, renameFormula, viewFormulaFunctions, type ViewFormulaScope, viewFormulaIsText, whyBlank, } from './view-formula.js';
+export { FORMULA_FUNCTIONS, type FormulaFunction, formulaFunctionsText, } from './formula-functions.js';
 /** How a view shows its rows; the sidebar icon follows it. */
 export declare const viewShapes: readonly ['table', 'group', 'pivot'];
 export type ViewShape = (typeof viewShapes)[number];

package/dist/views.js

@@ -7,6 +7,7 @@ import { DOMAIN_KEYS, JOINS, joinFields, joinKeys } from './domains.js';
 import { MARKET_KEY_RE, marketWindows } from './market.js';
 import { checkViewFormula, formulaLoops, frameSpace, renameFormula, } from './view-formula.js';
 export { checkViewFormula, compileViewFormula, formulaLoops, formulaReads, frameSpace, renameFormula, viewFormulaFunctions, viewFormulaIsText, whyBlank, } from './view-formula.js';
+export { FORMULA_FUNCTIONS, formulaFunctionsText, } from './formula-functions.js';
 const viewKey = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/, 'key: lowercase letters, digits and _');
 const MAX_VALUES = 40;
 /** How a view shows its rows; the sidebar icon follows it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui-types",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "Lumen's view model: views, formulas, domains and joins, frames.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,10 @@
       "types": "./dist/view-formula.d.ts",
       "default": "./dist/view-formula.js"
     },
+    "./formula-functions": {
+      "types": "./dist/formula-functions.d.ts",
+      "default": "./dist/formula-functions.js"
+    },
     "./domains": {
       "types": "./dist/domains.d.ts",
       "default": "./dist/domains.js"
@@ -72,6 +76,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@date-fns/utc": "2.1.0",
+    "date-fns": "4.1.0",
     "jexl": "2.3.0",
     "zod": "^4.3.6"
   }