@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/function-catalog.js

@@ -0,0 +1,94 @@
+/**
+ * What Insert Function shows for each function: its group, the argument
+ * list, and one line on what it does. The engine's table (`FUNCTIONS`) is
+ * the source of truth for which names exist; a name missing here is listed
+ * with a bare `NAME(...)` and no description rather than left out, so a
+ * custom function registered through `withCustomFunctions` appears too.
+ */
+import { FUNCTIONS } from './functions.js';
+import { SIGNATURES } from './autocomplete.js';
+const CATALOG = {
+    SUM: { group: 'Math', description: 'Adds all the numbers in a range of cells.', signature: 'SUM(number1, [number2], ...)' },
+    ABS: { group: 'Math', description: 'Returns the absolute value of a number, a number without its sign.', signature: 'ABS(number)' },
+    INT: { group: 'Math', description: 'Rounds a number down to the nearest integer.', signature: 'INT(number)' },
+    MOD: { group: 'Math', description: 'Returns the remainder after a number is divided by a divisor.', signature: 'MOD(number, divisor)' },
+    POWER: { group: 'Math', description: 'Returns the result of a number raised to a power.', signature: 'POWER(number, power)' },
+    SQRT: { group: 'Math', description: 'Returns the square root of a number.', signature: 'SQRT(number)' },
+    ROUND: { group: 'Math', description: 'Rounds a number to a specified number of digits.' },
+    ROUNDUP: { group: 'Math', description: 'Rounds a number up, away from zero.', signature: 'ROUNDUP(number, digits)' },
+    ROUNDDOWN: { group: 'Math', description: 'Rounds a number down, toward zero.', signature: 'ROUNDDOWN(number, digits)' },
+    SUMIF: { group: 'Math', description: 'Adds the cells specified by a given condition or criteria.' },
+    SUMIFS: { group: 'Math', description: 'Adds the cells specified by a given set of conditions or criteria.' },
+    AVERAGE: { group: 'Statistical', description: 'Returns the average (arithmetic mean) of its arguments.', signature: 'AVERAGE(number1, [number2], ...)' },
+    AVG: { group: 'Statistical', description: 'The same as AVERAGE.', signature: 'AVG(number1, [number2], ...)' },
+    MIN: { group: 'Statistical', description: 'Returns the smallest number in a set of values.', signature: 'MIN(number1, [number2], ...)' },
+    MAX: { group: 'Statistical', description: 'Returns the largest value in a set of values.', signature: 'MAX(number1, [number2], ...)' },
+    COUNT: { group: 'Statistical', description: 'Counts the number of cells in a range that contain numbers.', signature: 'COUNT(value1, [value2], ...)' },
+    COUNTA: { group: 'Statistical', description: 'Counts the number of cells in a range that are not empty.', signature: 'COUNTA(value1, [value2], ...)' },
+    COUNTBLANK: { group: 'Statistical', description: 'Counts the number of empty cells in a range.', signature: 'COUNTBLANK(range)' },
+    MEDIAN: { group: 'Statistical', description: 'Returns the median, the number in the middle of a set of numbers.', signature: 'MEDIAN(number1, [number2], ...)' },
+    STDEV: { group: 'Statistical', description: 'Estimates standard deviation based on a sample.', signature: 'STDEV(number1, [number2], ...)' },
+    RANK: { group: 'Statistical', description: 'Returns the rank of a number in a list of numbers.', signature: 'RANK(number, ref, [order])' },
+    COUNTIF: { group: 'Statistical', description: 'Counts the number of cells within a range that meet the given condition.' },
+    COUNTIFS: { group: 'Statistical', description: 'Counts the number of cells specified by a given set of conditions.' },
+    AVERAGEIF: { group: 'Statistical', description: 'Finds the average of the cells specified by a given condition.' },
+    IF: { group: 'Logical', description: 'Checks whether a condition is met, and returns one value if TRUE and another if FALSE.' },
+    IFS: { group: 'Logical', description: 'Checks whether one or more conditions are met and returns a value corresponding to the first TRUE condition.' },
+    IFERROR: { group: 'Logical', description: 'Returns a value you specify if a formula evaluates to an error; otherwise, returns the result of the formula.' },
+    IFNA: { group: 'Logical', description: 'Returns the value you specify if the expression resolves to #N/A, otherwise returns the result of the expression.', signature: 'IFNA(value, fallback)' },
+    SWITCH: { group: 'Logical', description: 'Evaluates an expression against a list of values and returns the result corresponding to the first matching value.' },
+    AND: { group: 'Logical', description: 'Checks whether all arguments are TRUE, and returns TRUE if all arguments are TRUE.', signature: 'AND(logical1, [logical2], ...)' },
+    OR: { group: 'Logical', description: 'Checks whether any of the arguments are TRUE, and returns TRUE or FALSE.', signature: 'OR(logical1, [logical2], ...)' },
+    NOT: { group: 'Logical', description: 'Changes FALSE to TRUE, or TRUE to FALSE.', signature: 'NOT(logical)' },
+    XOR: { group: 'Logical', description: 'Returns a logical exclusive OR of all arguments.', signature: 'XOR(logical1, [logical2], ...)' },
+    ISNUMBER: { group: 'Information', description: 'Checks whether a value is a number, and returns TRUE or FALSE.', signature: 'ISNUMBER(value)' },
+    ISTEXT: { group: 'Information', description: 'Checks whether a value is text, and returns TRUE or FALSE.', signature: 'ISTEXT(value)' },
+    ISLOGICAL: { group: 'Information', description: 'Checks whether a value is a logical value (TRUE or FALSE), and returns TRUE or FALSE.', signature: 'ISLOGICAL(value)' },
+    ISBLANK: { group: 'Information', description: 'Checks whether a reference is to an empty cell, and returns TRUE or FALSE.', signature: 'ISBLANK(value)' },
+    LEN: { group: 'Text', description: 'Returns the number of characters in a text string.', signature: 'LEN(text)' },
+    LEFT: { group: 'Text', description: 'Returns the specified number of characters from the start of a text string.', signature: 'LEFT(text, [count])' },
+    RIGHT: { group: 'Text', description: 'Returns the specified number of characters from the end of a text string.', signature: 'RIGHT(text, [count])' },
+    MID: { group: 'Text', description: 'Returns the characters from the middle of a text string, given a starting position and length.' },
+    UPPER: { group: 'Text', description: 'Converts a text string to all uppercase letters.', signature: 'UPPER(text)' },
+    LOWER: { group: 'Text', description: 'Converts all letters in a text string to lowercase.', signature: 'LOWER(text)' },
+    TRIM: { group: 'Text', description: 'Removes all spaces from a text string except for single spaces between words.', signature: 'TRIM(text)' },
+    CONCAT: { group: 'Text', description: 'Concatenates a list or range of text strings.', signature: 'CONCAT(text1, [text2], ...)' },
+    CONCATENATE: { group: 'Text', description: 'Joins several text strings into one text string.', signature: 'CONCATENATE(text1, [text2], ...)' },
+    TEXTJOIN: { group: 'Text', description: 'Concatenates a list or range of text strings using a delimiter.' },
+    SUBSTITUTE: { group: 'Text', description: 'Replaces existing text with new text in a text string.' },
+    FIND: { group: 'Text', description: 'Returns the starting position of one text string within another; case-sensitive.', signature: 'FIND(find, within, [start])' },
+    SEARCH: { group: 'Text', description: 'Returns the position of one text string within another; not case-sensitive.', signature: 'SEARCH(find, within, [start])' },
+    TEXT: { group: 'Text', description: 'Converts a value to text in a specific number format.' },
+    TODAY: { group: 'Date & Time', description: "Returns the current date formatted as a date.", signature: 'TODAY()' },
+    NOW: { group: 'Date & Time', description: 'Returns the current date and time formatted as a date and time.', signature: 'NOW()' },
+    YEAR: { group: 'Date & Time', description: 'Returns the year of a date, an integer in the range 1900 - 9999.', signature: 'YEAR(date)' },
+    MONTH: { group: 'Date & Time', description: 'Returns the month, a number from 1 (January) to 12 (December).', signature: 'MONTH(date)' },
+    DAY: { group: 'Date & Time', description: 'Returns the day of the month, a number from 1 to 31.', signature: 'DAY(date)' },
+    DATE: { group: 'Date & Time', description: 'Returns the date for a given year, month and day.' },
+    EOMONTH: { group: 'Date & Time', description: 'Returns the last day of the month before or after a specified number of months.' },
+    DAYS: { group: 'Date & Time', description: 'Returns the number of days between two dates.', signature: 'DAYS(end_date, start_date)' },
+    DATEDIF: { group: 'Date & Time', description: 'Calculates the number of days, months or years between two dates.', signature: 'DATEDIF(start_date, end_date, unit)' },
+    VLOOKUP: { group: 'Lookup & Reference', description: 'Looks for a value in the leftmost column of a table, and returns a value in the same row from a column you specify.' },
+    HLOOKUP: { group: 'Lookup & Reference', description: 'Looks for a value in the top row of a table, and returns a value in the same column from a row you specify.' },
+    XLOOKUP: { group: 'Lookup & Reference', description: 'Searches a range for a match and returns the corresponding item from a second range.' },
+    INDEX: { group: 'Lookup & Reference', description: 'Returns a value from a range at the intersection of a given row and column.' },
+    MATCH: { group: 'Lookup & Reference', description: 'Returns the relative position of an item in a range that matches a specified value.' },
+};
+/** The IF family is dispatched by the evaluator, not the function table. */
+const EVALUATOR_FUNCTIONS = ['IF', 'IFS', 'IFERROR', 'IFNA', 'SWITCH'];
+export const FUNCTION_GROUPS = [
+    'Math', 'Statistical', 'Logical', 'Information', 'Text', 'Date & Time', 'Lookup & Reference', 'Other',
+];
+/** Every function the engine knows, described, alphabetical. */
+export function functionCatalog() {
+    const names = new Set([...Object.keys(FUNCTIONS), ...EVALUATOR_FUNCTIONS]);
+    return [...names].sort().map((name) => {
+        const entry = CATALOG[name];
+        return {
+            name,
+            group: entry?.group ?? 'Other',
+            signature: entry?.signature ?? SIGNATURES[name] ?? `${name}(...)`,
+            description: entry?.description ?? '',
+        };
+    });
+}

package/dist/sheet/functions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The function table.
+ *
+ * Each entry receives its arguments already evaluated, in two shapes:
+ *   - `flat`  every argument flattened into one list, ranges expanded. What
+ *             SUM and COUNT want.
+ *   - `args`  one list per argument, so a function can tell `SUM(A1:A3, 5)`
+ *             from `SUM(A1:A3)` and `SUMIF` can line a range up against a
+ *             parallel one.
+ *   - `grids` the 2-D shape of any range argument, kept for VLOOKUP / INDEX /
+ *             MATCH, which lose meaning once flattened.
+ *
+ * Functions that must NOT evaluate every argument (IF, IFERROR, AND, OR with
+ * short-circuit semantics) are handled in the evaluator instead, because by the
+ * time a table entry runs, evaluation has already happened.
+ */
+import { isError, type CellValue } from './ast.js';
+export type FnArgs = {
+    flat: ReadonlyArray<CellValue>;
+    args: ReadonlyArray<ReadonlyArray<CellValue>>;
+    grids: ReadonlyArray<ReadonlyArray<ReadonlyArray<CellValue>> | null>;
+};
+export type SheetFunction = (a: FnArgs) => CellValue;
+export declare const FUNCTIONS: Record<string, SheetFunction>;
+/** Merge caller-supplied functions over the built-ins. Keys are uppercased so
+ *  a consumer can register `myFn` and write `=MYFN()`. */
+export declare function withCustomFunctions(custom: Record<string, SheetFunction> | undefined): Record<string, SheetFunction>;
+export { isError };

package/dist/sheet/functions.js

@@ -0,0 +1,362 @@
+/**
+ * The function table.
+ *
+ * Each entry receives its arguments already evaluated, in two shapes:
+ *   - `flat`  every argument flattened into one list, ranges expanded. What
+ *             SUM and COUNT want.
+ *   - `args`  one list per argument, so a function can tell `SUM(A1:A3, 5)`
+ *             from `SUM(A1:A3)` and `SUMIF` can line a range up against a
+ *             parallel one.
+ *   - `grids` the 2-D shape of any range argument, kept for VLOOKUP / INDEX /
+ *             MATCH, which lose meaning once flattened.
+ *
+ * Functions that must NOT evaluate every argument (IF, IFERROR, AND, OR with
+ * short-circuit semantics) are handled in the evaluator instead, because by the
+ * time a table entry runs, evaluation has already happened.
+ */
+import { FormulaError, isError, err } from './ast.js';
+import { toNumber, toBool, toText, looseEquals, compare, numericOnly, isBlank, matchesCriterion, } from './coerce.js';
+const first = (a) => a.flat[0] ?? '';
+const nth = (a, i) => a.args[i]?.[0] ?? '';
+function sum(values) {
+    return numericOnly(values).reduce((x, y) => x + y, 0);
+}
+function average(values) {
+    const ns = numericOnly(values);
+    if (ns.length === 0)
+        return err('#DIV/0!');
+    return ns.reduce((x, y) => x + y, 0) / ns.length;
+}
+function roundTo(value, digits) {
+    const f = Math.pow(10, digits);
+    // Scale, round, unscale. The epsilon nudge keeps 1.005 -> 1.01 rather than
+    // 1.00, which is the binary-float surprise users report as a bug.
+    return Math.round((value * f) * (1 + Number.EPSILON)) / f;
+}
+function toDate(v) {
+    if (typeof v === 'number') {
+        // Excel serial: day 1 is 1900-01-01, with the famous phantom leap day.
+        return new Date(Date.UTC(1899, 11, 30) + v * 86400000);
+    }
+    const d = new Date(toText(v));
+    if (Number.isNaN(d.getTime()))
+        throw new FormulaError('#VALUE!');
+    return d;
+}
+const iso = (d) => d.toISOString().slice(0, 10);
+/** Sum / count / average over a criterion range, optionally summing a parallel
+ *  range. The three IF functions differ only in what they do with the hits. */
+function criteriaHits(range, criterion) {
+    const out = [];
+    for (let i = 0; i < range.length; i += 1) {
+        if (matchesCriterion(range[i], criterion))
+            out.push(i);
+    }
+    return out;
+}
+/** SUMIFS / COUNTIFS: every (range, criterion) pair must match at an index. */
+function multiCriteriaHits(pairs) {
+    const firstPair = pairs[0];
+    if (!firstPair)
+        return [];
+    const out = [];
+    for (let i = 0; i < firstPair[0].length; i += 1) {
+        if (pairs.every(([range, crit]) => matchesCriterion(range[i] ?? '', crit)))
+            out.push(i);
+    }
+    return out;
+}
+export const FUNCTIONS = {
+    // ---- Math and aggregation -------------------------------------------
+    SUM: (a) => sum(a.flat),
+    AVERAGE: (a) => average(a.flat),
+    AVG: (a) => average(a.flat),
+    MIN: (a) => { const n = numericOnly(a.flat); return n.length ? Math.min(...n) : 0; },
+    MAX: (a) => { const n = numericOnly(a.flat); return n.length ? Math.max(...n) : 0; },
+    COUNT: (a) => a.flat.filter((v) => typeof v === 'number').length,
+    COUNTA: (a) => a.flat.filter((v) => !isBlank(v)).length,
+    COUNTBLANK: (a) => a.flat.filter((v) => isBlank(v)).length,
+    ABS: (a) => Math.abs(toNumber(first(a))),
+    INT: (a) => Math.floor(toNumber(first(a))),
+    MOD: (a) => {
+        const d = toNumber(nth(a, 1));
+        if (d === 0)
+            return err('#DIV/0!');
+        // Excel's MOD follows the sign of the divisor, unlike JavaScript's %.
+        const n = toNumber(nth(a, 0));
+        return n - d * Math.floor(n / d);
+    },
+    POWER: (a) => Math.pow(toNumber(nth(a, 0)), toNumber(nth(a, 1))),
+    SQRT: (a) => {
+        const n = toNumber(first(a));
+        return n < 0 ? err('#NUM!') : Math.sqrt(n);
+    },
+    ROUND: (a) => roundTo(toNumber(nth(a, 0)), Math.round(toNumber(nth(a, 1) || 0))),
+    ROUNDUP: (a) => {
+        const d = Math.round(toNumber(nth(a, 1) || 0));
+        const f = Math.pow(10, d);
+        const v = toNumber(nth(a, 0));
+        return (v < 0 ? -Math.ceil(-v * f) : Math.ceil(v * f)) / f;
+    },
+    ROUNDDOWN: (a) => {
+        const d = Math.round(toNumber(nth(a, 1) || 0));
+        const f = Math.pow(10, d);
+        const v = toNumber(nth(a, 0));
+        return (v < 0 ? -Math.floor(-v * f) : Math.floor(v * f)) / f;
+    },
+    MEDIAN: (a) => {
+        const n = numericOnly(a.flat).sort((x, y) => x - y);
+        if (!n.length)
+            return err('#NUM!');
+        const mid = Math.floor(n.length / 2);
+        return n.length % 2 ? n[mid] : (n[mid - 1] + n[mid]) / 2;
+    },
+    STDEV: (a) => {
+        const n = numericOnly(a.flat);
+        if (n.length < 2)
+            return err('#DIV/0!');
+        const mean = n.reduce((x, y) => x + y, 0) / n.length;
+        const variance = n.reduce((acc, v) => acc + (v - mean) ** 2, 0) / (n.length - 1);
+        return Math.sqrt(variance);
+    },
+    RANK: (a) => {
+        const value = toNumber(nth(a, 0));
+        const pool = numericOnly(a.args[1] ?? []);
+        const ascending = a.args[2] !== undefined && toBool(nth(a, 2));
+        const sorted = pool.slice().sort((x, y) => (ascending ? x - y : y - x));
+        const at = sorted.indexOf(value);
+        return at < 0 ? err('#N/A') : at + 1;
+    },
+    // ---- Conditional aggregation ----------------------------------------
+    SUMIF: (a) => {
+        const range = a.args[0] ?? [];
+        const hits = criteriaHits(range, nth(a, 1));
+        // The optional third argument is the range actually summed.
+        const target = a.args[2] ?? range;
+        return sum(hits.map((i) => target[i] ?? ''));
+    },
+    COUNTIF: (a) => criteriaHits(a.args[0] ?? [], nth(a, 1)).length,
+    AVERAGEIF: (a) => {
+        const range = a.args[0] ?? [];
+        const hits = criteriaHits(range, nth(a, 1));
+        const target = a.args[2] ?? range;
+        return average(hits.map((i) => target[i] ?? ''));
+    },
+    SUMIFS: (a) => {
+        const target = a.args[0] ?? [];
+        const pairs = [];
+        for (let i = 1; i + 1 < a.args.length + 1; i += 2) {
+            const range = a.args[i];
+            if (!range)
+                break;
+            pairs.push([range, a.args[i + 1]?.[0] ?? '']);
+        }
+        return sum(multiCriteriaHits(pairs).map((i) => target[i] ?? ''));
+    },
+    COUNTIFS: (a) => {
+        const pairs = [];
+        for (let i = 0; i < a.args.length; i += 2) {
+            const range = a.args[i];
+            if (!range)
+                break;
+            pairs.push([range, a.args[i + 1]?.[0] ?? '']);
+        }
+        return multiCriteriaHits(pairs).length;
+    },
+    // ---- Logical ---------------------------------------------------------
+    NOT: (a) => !toBool(first(a)),
+    AND: (a) => a.flat.every((v) => toBool(v)),
+    OR: (a) => a.flat.some((v) => toBool(v)),
+    XOR: (a) => a.flat.filter((v) => toBool(v)).length % 2 === 1,
+    // ---- Information -----------------------------------------------------
+    // What a value IS, not what it can be coerced to: "12" typed as text is
+    // text here, the way Excel answers, and a blank is neither.
+    ISNUMBER: (a) => typeof first(a) === 'number',
+    ISTEXT: (a) => typeof first(a) === 'string' && first(a) !== '',
+    ISLOGICAL: (a) => typeof first(a) === 'boolean',
+    ISBLANK: (a) => first(a) === '',
+    // ---- Text ------------------------------------------------------------
+    LEN: (a) => toText(first(a)).length,
+    LEFT: (a) => toText(nth(a, 0)).slice(0, Math.max(0, Math.round(toNumber(a.args[1] ? nth(a, 1) : 1)))),
+    RIGHT: (a) => {
+        const s = toText(nth(a, 0));
+        const n = Math.max(0, Math.round(toNumber(a.args[1] ? nth(a, 1) : 1)));
+        return n >= s.length ? s : s.slice(s.length - n);
+    },
+    MID: (a) => {
+        const s = toText(nth(a, 0));
+        const start = Math.round(toNumber(nth(a, 1)));
+        if (start < 1)
+            return err('#VALUE!');
+        return s.slice(start - 1, start - 1 + Math.max(0, Math.round(toNumber(nth(a, 2)))));
+    },
+    UPPER: (a) => toText(first(a)).toUpperCase(),
+    LOWER: (a) => toText(first(a)).toLowerCase(),
+    TRIM: (a) => toText(first(a)).trim().replace(/\s+/g, ' '),
+    CONCAT: (a) => a.flat.map((v) => toText(v)).join(''),
+    CONCATENATE: (a) => a.flat.map((v) => toText(v)).join(''),
+    TEXTJOIN: (a) => {
+        const sep = toText(nth(a, 0));
+        const skipEmpty = toBool(nth(a, 1));
+        const rest = a.args.slice(2).flat();
+        return rest.filter((v) => !skipEmpty || !isBlank(v)).map((v) => toText(v)).join(sep);
+    },
+    SUBSTITUTE: (a) => {
+        const s = toText(nth(a, 0));
+        const find = toText(nth(a, 1));
+        const replace = toText(nth(a, 2));
+        if (find === '')
+            return s;
+        return s.split(find).join(replace);
+    },
+    FIND: (a) => {
+        // Case sensitive, 1-based, #VALUE! when absent. SEARCH is its
+        // case-insensitive twin.
+        const at = toText(nth(a, 1)).indexOf(toText(nth(a, 0)));
+        return at < 0 ? err('#VALUE!') : at + 1;
+    },
+    SEARCH: (a) => {
+        const at = toText(nth(a, 1)).toLowerCase().indexOf(toText(nth(a, 0)).toLowerCase());
+        return at < 0 ? err('#VALUE!') : at + 1;
+    },
+    TEXT: (a) => {
+        // Minimal: the full Excel format grammar arrives with per-cell number
+        // formats. Until then this covers the common fixed-decimal case.
+        const v = toNumber(nth(a, 0));
+        const pattern = toText(nth(a, 1));
+        const decimals = /\.(0+)/.exec(pattern)?.[1]?.length ?? 0;
+        const body = v.toFixed(decimals);
+        if (pattern.includes(',')) {
+            const [int = '', frac] = body.split('.');
+            const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+            return frac ? `${grouped}.${frac}` : grouped;
+        }
+        return body;
+    },
+    // ---- Date ------------------------------------------------------------
+    TODAY: () => iso(new Date()),
+    NOW: () => new Date().toISOString().slice(0, 19).replace('T', ' '),
+    YEAR: (a) => toDate(first(a)).getUTCFullYear(),
+    MONTH: (a) => toDate(first(a)).getUTCMonth() + 1,
+    DAY: (a) => toDate(first(a)).getUTCDate(),
+    DATE: (a) => iso(new Date(Date.UTC(Math.round(toNumber(nth(a, 0))), Math.round(toNumber(nth(a, 1))) - 1, Math.round(toNumber(nth(a, 2)))))),
+    EOMONTH: (a) => {
+        const d = toDate(nth(a, 0));
+        const months = Math.round(toNumber(nth(a, 1)));
+        // Day 0 of the following month is the last day of the target month.
+        return iso(new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months + 1, 0)));
+    },
+    // DAYS(end, start): whole days, negative when the end comes first.
+    DAYS: (a) => Math.round((toDate(nth(a, 0)).getTime() - toDate(nth(a, 1)).getTime()) / 86400000),
+    // DATEDIF(start, end, unit): Excel's "d", "m" and "y", completed units
+    // only, and #NUM! when the start comes after the end, as Excel gives.
+    DATEDIF: (a) => {
+        const start = toDate(nth(a, 0));
+        const end = toDate(nth(a, 1));
+        if (end.getTime() < start.getTime())
+            return err('#NUM!');
+        const unit = toText(nth(a, 2)).toUpperCase();
+        if (unit === 'D')
+            return Math.floor((end.getTime() - start.getTime()) / 86400000);
+        let months = (end.getUTCFullYear() - start.getUTCFullYear()) * 12 + (end.getUTCMonth() - start.getUTCMonth());
+        if (end.getUTCDate() < start.getUTCDate())
+            months -= 1;
+        if (unit === 'M')
+            return months;
+        if (unit === 'Y')
+            return Math.floor(months / 12);
+        return err('#NUM!');
+    },
+    // ---- Lookup ----------------------------------------------------------
+    VLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const grid = a.grids[1];
+        if (!grid)
+            return err('#REF!');
+        const col = Math.round(toNumber(nth(a, 2)));
+        if (col < 1)
+            return err('#VALUE!');
+        for (const row of grid) {
+            if (row[0] !== undefined && looseEquals(row[0], needle)) {
+                const cell = row[col - 1];
+                return cell === undefined ? err('#REF!') : cell;
+            }
+        }
+        return err('#N/A');
+    },
+    HLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const grid = a.grids[1];
+        if (!grid)
+            return err('#REF!');
+        const rowIndex = Math.round(toNumber(nth(a, 2)));
+        if (rowIndex < 1)
+            return err('#VALUE!');
+        const header = grid[0] ?? [];
+        for (let c = 0; c < header.length; c += 1) {
+            if (looseEquals(header[c], needle)) {
+                const cell = grid[rowIndex - 1]?.[c];
+                return cell === undefined ? err('#REF!') : cell;
+            }
+        }
+        return err('#N/A');
+    },
+    MATCH: (a) => {
+        const needle = nth(a, 0);
+        const pool = a.args[1] ?? [];
+        const mode = a.args[2] ? Math.round(toNumber(nth(a, 2))) : 1;
+        if (mode === 0) {
+            const at = pool.findIndex((v) => looseEquals(v, needle));
+            return at < 0 ? err('#N/A') : at + 1;
+        }
+        // Ordered search: the last value not past the needle.
+        let best = -1;
+        for (let i = 0; i < pool.length; i += 1) {
+            const cmp = compare(pool[i], needle);
+            if (mode === 1 ? cmp <= 0 : cmp >= 0)
+                best = i;
+        }
+        return best < 0 ? err('#N/A') : best + 1;
+    },
+    INDEX: (a) => {
+        const grid = a.grids[0];
+        if (!grid) {
+            const at = Math.round(toNumber(nth(a, 1)));
+            const v = (a.args[0] ?? [])[at - 1];
+            return v === undefined ? err('#REF!') : v;
+        }
+        const given = Math.round(toNumber(nth(a, 1)));
+        // With one number, a one-column range indexes by row and a one-row range
+        // by column, as Excel does: =INDEX(B4:D4, 2) is the second scenario
+        // heading, not #REF!.
+        const oneRow = grid.length === 1 && !a.args[2];
+        const rowIndex = oneRow ? 1 : given;
+        const colIndex = oneRow ? given : a.args[2] ? Math.round(toNumber(nth(a, 2))) : 1;
+        const row = grid[rowIndex - 1];
+        if (!row)
+            return err('#REF!');
+        const cell = row[colIndex - 1];
+        return cell === undefined ? err('#REF!') : cell;
+    },
+    XLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const haystack = a.args[1] ?? [];
+        const results = a.args[2] ?? [];
+        const at = haystack.findIndex((v) => looseEquals(v, needle));
+        if (at < 0)
+            return a.args[3] ? nth(a, 3) : err('#N/A');
+        const cell = results[at];
+        return cell === undefined ? err('#REF!') : cell;
+    },
+};
+/** Merge caller-supplied functions over the built-ins. Keys are uppercased so
+ *  a consumer can register `myFn` and write `=MYFN()`. */
+export function withCustomFunctions(custom) {
+    if (!custom)
+        return FUNCTIONS;
+    const out = { ...FUNCTIONS };
+    for (const [name, fn] of Object.entries(custom))
+        out[name.toUpperCase()] = fn;
+    return out;
+}
+export { isError };

package/dist/sheet/goal-seek.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Goal Seek: find the input value that makes a formula cell hit a target.
+ *
+ * "What interest rate makes the monthly payment 1500?" You know the answer
+ * you want and one cell you are willing to change; the solver finds it.
+ *
+ * The method is secant with a bisection fallback, not Newton. Newton needs a
+ * derivative, and the function here is "recalculate a spreadsheet", which has
+ * no analytic one. Secant approximates the slope from two evaluations, which
+ * is the same information a numerical derivative would cost anyway.
+ *
+ * Bisection is the fallback because secant is fast but not safe: it can step
+ * to infinity on a flat stretch or oscillate on a kink. When a bracket is
+ * known - two inputs whose results straddle the target - bisection cannot
+ * fail, only be slow. Trying secant first and falling back keeps the common
+ * case quick and the awkward case terminating.
+ */
+export type GoalSeekOptions = {
+    /** Stop once the result is this close to the target. */
+    tolerance?: number;
+    /** Give up after this many recalculations. */
+    maxIterations?: number;
+    /** Where to start looking. Defaults to the input cell's current value. */
+    initialGuess?: number;
+    /** Keep the answer inside these bounds. A rate solver wants [0, 1]. */
+    min?: number;
+    max?: number;
+};
+export type GoalSeekResult = {
+    /** Whether the target was reached within tolerance. */
+    converged: boolean;
+    /** The input value found. Present even when it did not converge, so a
+     *  caller can show the closest attempt rather than nothing. */
+    value: number;
+    /** What the formula produced at that input. */
+    result: number;
+    iterations: number;
+    /** Why it stopped, when it did not converge. */
+    reason?: 'maxIterations' | 'notNumeric' | 'flat' | 'outOfBounds';
+};
+/**
+ * Solve `evaluate(input) = target` for `input`.
+ *
+ * `evaluate` sets the input cell, recalculates, and returns the formula
+ * cell's value. It is called many times, so it should be the workbook's own
+ * recalculation rather than anything that touches the DOM.
+ *
+ * The caller owns the input cell: this never writes. It reports the value it
+ * found and lets the caller decide whether to keep it, which is what makes
+ * Excel's "Goal Seek found a solution / OK or Cancel" dialog possible.
+ */
+export declare function goalSeek(evaluate: (input: number) => unknown, target: number, start: number, options?: GoalSeekOptions): GoalSeekResult;
+/** What `goalSeekCell` needs of a workbook. */
+export type GoalSeekSheet = {
+    getRaw(sheet: string, row: number, col: number): string;
+    setRaw(sheet: string, row: number, col: number, text: string): void;
+    getValue(sheet: string, row: number, col: number): unknown;
+};
+export type CellAddress = {
+    sheet: string;
+    row: number;
+    col: number;
+};
+/**
+ * Goal Seek over a workbook: change `input` until `formula` reads `target`.
+ *
+ * The input cell is RESTORED before returning, whatever the outcome. The
+ * solver writes to it dozens of times while searching, and leaving the last
+ * probe behind would be worse than not running: Excel shows you the answer
+ * and asks before keeping it, which it cannot do if the sheet has already
+ * moved. Apply `result.value` yourself once the user says yes.
+ */
+export declare function goalSeekCell(book: GoalSeekSheet, formula: CellAddress, input: CellAddress, target: number, options?: GoalSeekOptions): GoalSeekResult;