@guiexpert/table 1.1.97 → 1.1.99

package/lib/table/sheet/sheet-engine.d.ts

@@ -0,0 +1,207 @@
+import { CellRange } from '../data/common/cell-range.js';
+import { SheetStructureEditIf } from './shift-formula.js';
+import { CellFormulaOptionsIf } from './cell-formula-options.if.js';
+
+/**
+ * The data a {@link SheetEngine} computes on: inputs by **physical** row and column (0-based) – values or formula texts
+ * (`"=B2*C2"`). The table has adapters for its models; `SheetEngine.fromArrays` uses a 2-D array.
+ *
+ * @example
+ * const source: SheetDataSourceIf = {
+ *   getRowCount: () => data.length,
+ *   getColumnCount: () => 4,
+ *   getInput: (row, col) => data[row][col],
+ * };
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface SheetDataSourceIf {
+    getRowCount(): number;
+    getColumnCount(): number;
+    /** The input of a cell: a value or a formula text with `=`. */
+    getInput(row: number, col: number): unknown;
+    /** False for a column whose `=…` texts are plain text (`ColumnDef.cellFormulas: false`). Default: true. */
+    isFormulaColumn?(col: number): boolean;
+    /** The column of a data field for `[field]` in a cell formula, -1 if it is none. */
+    getFieldColumn?(field: string): number;
+    /**
+     * Optional, for sparse data (a sheet with a million empty rows): calls `fn` for every cell that may hold an input –
+     * `rebuild()` then reads only these instead of rows × columns.
+     */
+    forEachInput?(fn: (row: number, col: number, input: unknown) => void): void;
+}
+/**
+ * What a (re)calculation did.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface SheetRecalcResultIf {
+    /** Formula cells whose result changed (row, column). */
+    readonly changedCells: ReadonlyArray<readonly [number, number]>;
+    /** Formula cells evaluated. */
+    readonly evaluated: number;
+}
+/**
+ * True for a formula input: text starting with `=` (more than `=`). `'=…` is text.
+ *
+ * @param {unknown} input - a cell input
+ * @returns {boolean} true for a formula text
+ *
+ * @example
+ * isFormulaText("=B2*C2");   // true
+ * isFormulaText("'=1+1");    // false – text "=1+1"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function isFormulaText(input: unknown): input is string;
+/**
+ * The spreadsheet engine of cell formulas (DOM-free): compiles the formula texts of the data (`"=SUM(D2:D4)"`), keeps a
+ * dependency graph (single cells and range nodes) and recalculates **only the dependent cells** after a change – in
+ * topological order (Kahn), cycles (Tarjan) become `#CIRC!`. No `eval`, no `new Function`. Volatile functions (`TODAY`,
+ * `NOW`, `RAND`, `RANDBETWEEN`) are recomputed on every recalculation.
+ *
+ * @example
+ * const engine = SheetEngine.fromArrays([
+ *   ["Laptop", 1299, 2, "=B1*C1"],
+ *   ["Mouse", 25, 10, "=B2*C2"],
+ *   [null, null, null, "=SUM(D1:D2)"],
+ * ]);
+ * engine.getValue(2, 3);   // 2848
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class SheetEngine {
+    private readonly source;
+    readonly options: CellFormulaOptionsIf;
+    private readonly formulas;
+    private readonly singleDependents;
+    private readonly rangeNodes;
+    private readonly rangesByColumn;
+    private readonly wideRanges;
+    private readonly volatileCells;
+    /** Formula cells per column – a read in a column without formulas skips the map lookup. */
+    private readonly formulaColumns;
+    private readonly env;
+    private readonly fieldColumns;
+    /**
+     * @param {SheetDataSourceIf} source - the data
+     * @param {Partial<CellFormulaOptionsIf> & { now?: () => Date, random?: () => number }} [options] - own functions
+     *        and limits; `now`/`random` for tests
+     */
+    constructor(source: SheetDataSourceIf, options?: Partial<CellFormulaOptionsIf> & {
+        now?: () => Date;
+        random?: () => number;
+    });
+    /**
+     * An engine over a 2-D array (rows of cells) – without a table.
+     *
+     * @param {unknown[][]} data - the cells; formula texts start with `=`
+     * @param {Partial<CellFormulaOptionsIf>} [options] - own functions and limits
+     * @returns {SheetEngine} the engine, already calculated
+     *
+     * @example
+     * SheetEngine.fromArrays([[1, 2, "=A1+B1"]]).getValue(0, 2);   // 3
+     */
+    static fromArrays(data: unknown[][], options?: Partial<CellFormulaOptionsIf>): SheetEngine;
+    /**
+     * Reads all inputs again and calculates every formula (start, `setRows`, other columns).
+     *
+     * @returns {SheetRecalcResultIf} what was calculated
+     */
+    rebuild(): SheetRecalcResultIf;
+    /**
+     * The inputs of cells changed (written by the table): formulas are compiled again, the dependent cells recalculated.
+     *
+     * @param {ReadonlyArray<readonly [number, number]>} cells - physical row and column of each changed cell
+     * @returns {SheetRecalcResultIf} what was recalculated
+     */
+    inputsChanged(cells: ReadonlyArray<readonly [number, number]>): SheetRecalcResultIf;
+    /**
+     * Recalculates the volatile formulas (`TODAY`, `NOW`, `RAND`) and their dependents.
+     *
+     * @returns {SheetRecalcResultIf} what was recalculated
+     */
+    recalculate(): SheetRecalcResultIf;
+    /**
+     * The value of a cell: the result of its formula or its data value (`Date` for dates, a {@link FormulaError} for an
+     * error, `'=…` without the quote).
+     *
+     * @param {number} row - physical row (0-based)
+     * @param {number} col - column (0-based)
+     * @returns {unknown} the value
+     */
+    getValue(row: number, col: number): unknown;
+    /**
+     * True if the cell holds a formula.
+     *
+     * @param {number} row - physical row
+     * @param {number} col - column
+     * @returns {boolean} true for a formula cell
+     */
+    isFormula(row: number, col: number): boolean;
+    /** @returns {number} the number of formula cells */
+    getFormulaCount(): number;
+    /**
+     * Evaluates a formula once (not stored), e.g. for a formula bar preview.
+     *
+     * @param {string} source - the formula (`"=SUM(D2:D4)"`, the `=` is optional)
+     * @param {[number, number]} [at] - the cell it is evaluated in (for `[field]`)
+     * @returns {unknown} the result
+     *
+     * @example
+     * engine.evaluate("=SUM(D2:D4)");   // 3895
+     */
+    evaluate(source: string, at?: readonly [number, number]): unknown;
+    /**
+     * The cells and ranges a formula reads.
+     *
+     * @param {number} row - physical row
+     * @param {number} col - column
+     * @returns {CellRange[]} its precedents (empty for a value cell)
+     */
+    getPrecedents(row: number, col: number): CellRange[];
+    /**
+     * The formula cells that read a cell directly.
+     *
+     * @param {number} row - physical row
+     * @param {number} col - column
+     * @returns {Array<[number, number]>} row and column of each dependent
+     */
+    getDependents(row: number, col: number): Array<[number, number]>;
+    /**
+     * The new formula texts after rows or columns were inserted or deleted (or cells moved) – the caller writes them
+     * (the engine only reads the data). Cells are given at their position **after** the edit.
+     *
+     * @param {SheetStructureEditIf} edit - what changed
+     * @returns {Array<{ row: number, col: number, input: string }>} changed formula texts
+     */
+    adjustForStructureChange(edit: SheetStructureEditIf): Array<{
+        row: number;
+        col: number;
+        input: string;
+    }>;
+    private read;
+    /** A value cell: `""` is blank (a cleared cell), `'=…` is the text `=…`. */
+    private dataValue;
+    private fieldColumn;
+    private add;
+    private remove;
+    /** Calls `fn` for every formula that reads the cell (single references and ranges; a formula may come twice). */
+    private forEachDependent;
+    private dependentsOfKey;
+    /**
+     * Recalculates the formulas reachable from the seeds: BFS over the dependents → Kahn (topological) → the rest are
+     * cycles (Tarjan → #CIRC!) and cells behind them (a second Kahn pass, they inherit the error). Iterative – a chain
+     * of 100 000 cells does not overflow the stack. The dependents of a cell are looked up once per recalculation.
+     *
+     * Cost: the graph part is linear in the dependents; the evaluation reads every cell of every range again – a
+     * running sum `=SUM($B$2:B2)` copied down n rows is O(n²) per change (as in Excel; `=C1+B2` is linear).
+     */
+    private recalc;
+    /** The cells of `nodes` that lie on a cycle (strongly connected components > 1 or a self reference) – iterative Tarjan. */
+    private cycles;
+}

package/lib/table/sheet/sheet-function-info.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A built-in function of cell formulas: name, signature and a short English description – for function suggestions
+ * and help texts.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface FormulaFunctionInfoIf {
+    readonly name: string;
+    /** e.g. `"SUM(number1, [number2], …)"` */
+    readonly signature: string;
+    readonly description: string;
+    readonly group: "Math" | "Conditional" | "Logic" | "Lookup" | "Text" | "Date" | "Info";
+}
+/**
+ * The built-in functions of cell formulas (Excel signatures and semantics), sorted by name.
+ *
+ * @example
+ * FORMULA_FUNCTION_INFO.filter(i => i.name.startsWith("SU")).map(i => i.signature);
+ * // ["SUBSTITUTE(text, old_text, new_text, [instance])", "SUM(number1, [number2], …)", …]
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare const FORMULA_FUNCTION_INFO: readonly FormulaFunctionInfoIf[];

package/lib/table/sheet/sheet-functions.d.ts

@@ -0,0 +1,27 @@
+import { numberToText, SheetValue, ValueOptions } from './sheet-values.js';
+
+/** What a function of a cell formula may use besides its arguments. */
+export interface SheetFnContext extends ValueOptions {
+    /** The serial number of now (TODAY, NOW). */
+    now(): number;
+    /** A random number 0 … 1 (RAND). */
+    random(): number;
+}
+/** A built-in function of cell formulas. */
+export interface SheetFunctionSpec {
+    readonly min: number;
+    readonly max: number;
+    /** Recomputed on every recalculation (TODAY, NOW, RAND). */
+    readonly volatile?: boolean;
+    /** Gets error arguments (ISERROR …) instead of returning the first one. */
+    readonly acceptsErrors?: boolean;
+    /** Arguments evaluated on demand (IF, IFERROR …). */
+    readonly lazy?: (args: Array<() => SheetValue>, ctx: SheetFnContext) => SheetValue;
+    readonly fn?: (args: SheetValue[], ctx: SheetFnContext) => SheetValue;
+}
+/** A criterion of SUMIF/COUNTIF: `5`, `">5"`, `"<>x"`, `"M*"`, `""` (blank). */
+export declare function makeCriterion(criterion: SheetValue, o: ValueOptions): (v: SheetValue) => boolean;
+/** The built-in functions of cell formulas (Excel signatures and semantics). */
+export declare const SHEET_FUNCTIONS: Record<string, SheetFunctionSpec>;
+/** The text of a number for messages and TEXT. */
+export { numberToText };

package/lib/table/sheet/sheet-values.d.ts

@@ -0,0 +1,154 @@
+import { FormulaError } from '../formula/formula-error.js';
+
+/**
+ * A date in a cell formula: the Excel serial number (1900 date system: 1 = 1900-01-01, with Excel's 1900-02-29;
+ * the fraction is the time of day). It counts as a number (arithmetic, `ISNUMBER`) and stays a date through `=A2`,
+ * `IF`, lookups and date ± number; `MIN`/`MAX` and other arithmetic give a number (like Excel's values). The table
+ * shows it as `Date`.
+ *
+ * @example
+ * dateToSerial(new Date(2026, 9, 16));   // 46311
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class SheetDate {
+    readonly serial: number;
+    /** Marker (works across copies of the core). */
+    readonly type = "SheetDate";
+    /** @param {number} serial - the Excel serial number */
+    constructor(serial: number);
+    /** @returns {Date} the date (local time) */
+    toDate(): Date;
+}
+/**
+ * True for a {@link SheetDate}.
+ *
+ * @param {unknown} v - any value
+ * @returns {boolean} true for a sheet date
+ *
+ * @example
+ * isSheetDate(new SheetDate(1));   // true
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function isSheetDate(v: unknown): v is SheetDate;
+/**
+ * The Excel serial number of a date (local calendar date and time, no time zone shift – like Excel).
+ *
+ * @param {Date} date - a date
+ * @returns {number} the serial number (`NaN` for an invalid date)
+ *
+ * @example
+ * dateToSerial(new Date(1900, 0, 1));   // 1
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function dateToSerial(date: Date): number;
+/**
+ * The date of an Excel serial number (local time); serial 60 (Excel's 1900-02-29) becomes 1900-03-01.
+ *
+ * @param {number} serial - the serial number
+ * @returns {Date} the date
+ *
+ * @example
+ * serialToDate(46311);   // 2026-10-16 00:00 local
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function serialToDate(serial: number): Date;
+/** The serial of a calendar date like Excel's DATE (months and days may overflow). */
+export declare function serialOf(year: number, month: number, day: number): number;
+/** Year, month (1–12), day of a serial number. */
+export declare function partsOfSerial(serial: number): {
+    y: number;
+    m: number;
+    d: number;
+};
+/**
+ * A rectangle of cells passed to a function (`SUM(A1:B5)`): read lazily, row by row.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class FormulaRange {
+    readonly row: number;
+    readonly col: number;
+    readonly rows: number;
+    readonly cols: number;
+    private readonly read;
+    /** Marker (works across copies of the core). */
+    readonly type = "FormulaRange";
+    /**
+     * @param {number} row - first row (0-based)
+     * @param {number} col - first column
+     * @param {number} rows - number of rows (cut at the rows of the data)
+     * @param {number} cols - number of columns
+     * @param {(row: number, col: number) => SheetValue} read - reads a cell (sheet coordinates)
+     */
+    constructor(row: number, col: number, rows: number, cols: number, read: (row: number, col: number) => SheetValue);
+    /**
+     * The value at a position inside the range.
+     *
+     * @param {number} r - row inside the range (0-based)
+     * @param {number} c - column inside the range
+     * @returns {SheetValue} the value (blank = `null`)
+     */
+    get(r: number, c: number): SheetValue;
+    /** @returns {SheetValue[]} all values, row by row */
+    values(): SheetValue[];
+}
+/**
+ * True for a {@link FormulaRange}.
+ *
+ * @param {unknown} v - any value
+ * @returns {boolean} true for a range
+ *
+ * @example
+ * if (isFormulaRange(arg)) console.log(arg.rows, arg.cols);
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function isFormulaRange(v: unknown): v is FormulaRange;
+/**
+ * A value inside a cell formula: number, text, boolean, blank (`null`), error, date or – only as argument – a range.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export type SheetValue = number | string | boolean | null | FormulaError | SheetDate | FormulaRange;
+/** Rounds to 15 significant digits like Excel (`0.1 + 0.2` = `0.3`); -0 → 0. */
+export declare function round15(n: number): number;
+/** A number result: not finite → #NUM!, rounded to 15 digits. */
+export declare function num(n: number): number | FormulaError;
+/** The serial number of ISO text (`2026-10-16`, with time), `undefined` if it is none. */
+export declare function isoTextToSerial(text: string): number | undefined;
+/** Options the conversions need. */
+export interface ValueOptions {
+    isoDatesAsDates: boolean;
+}
+/** A value of the data as sheet value: `Date` → {@link SheetDate}, objects → #VALUE!, `NaN` → blank. */
+export declare function fromCellData(v: unknown): SheetValue;
+/** A scalar (a range → #VALUE! – no implicit intersection). */
+export declare function scalar(v: SheetValue): Exclude<SheetValue, FormulaRange>;
+/** A value as number for arithmetic: blank 0, TRUE 1, numeric text, ISO date text (option), date serial. */
+export declare function toNum(v: SheetValue, o: ValueOptions): number | FormulaError;
+/** A number as text like Excel's general format: 15 significant digits, exponent from 1E+21 on. */
+export declare function numberToText(n: number): string;
+/** A value as text: numbers in general format, TRUE/FALSE, a date as its serial number (like Excel). */
+export declare function toStr(v: SheetValue): string | FormulaError;
+/** A value as boolean: numbers ≠ 0, "TRUE"/"FALSE", blank FALSE. */
+export declare function toBool(v: SheetValue): boolean | FormulaError;
+/**
+ * Compares like Excel: numbers (and dates) numerically (15 digits), texts case-insensitively, different types by type
+ * (number < text < boolean, `"3" = 3` is FALSE); blank is 0, `""` or FALSE – whatever the other side is.
+ */
+export declare function compareSheet(a: SheetValue, b: SheetValue): number | FormulaError;
+/** True for blank and `""`. */
+export declare function isEmpty(v: SheetValue): boolean;
+/** A sheet value for the table: SheetDate → Date, ranges → #VALUE!. */
+export declare function toExternal(v: SheetValue): unknown;

package/lib/table/sheet/shift-formula.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A change of the sheet's structure that formulas must follow ({@link adjustFormula}): rows or columns inserted or
+ * deleted at `at` (0-based, `count` of them), or cells moved (cut + paste).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export type SheetStructureEditIf = {
+    kind: "insertRows" | "deleteRows" | "insertColumns" | "deleteColumns";
+    at: number;
+    count: number;
+} | {
+    kind: "moveCells";
+    from: {
+        r1: number;
+        c1: number;
+        r2: number;
+        c2: number;
+    };
+    to: readonly [number, number];
+};
+/**
+ * A formula copied by `dRow` rows and `dCol` columns (fill handle, copy and paste): relative references move, `$`
+ * parts stay; a reference that leaves the sheet becomes `#REF!`. Formula text without `=`.
+ *
+ * @param {string} source - the formula (without `=`)
+ * @param {number} dRow - rows moved
+ * @param {number} dCol - columns moved
+ * @returns {string} the moved formula (canonical text)
+ *
+ * @example
+ * shiftFormula("B2*C2+$F$1", 1, 0);   // "B3*C3+$F$1"
+ * shiftFormula("A1", -1, 0);          // "#REF!"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function shiftFormula(source: string, dRow: number, dCol: number): string;
+/**
+ * All references moved, also absolute ones – e.g. for an export whose cells start elsewhere (a header row above).
+ *
+ * @param {string} source - the formula (without `=`)
+ * @param {number} dRow - rows
+ * @param {number} dCol - columns
+ * @returns {string} the formula
+ *
+ * @example
+ * offsetReferences("$F$1*B2", 1, 0);   // "$F$2*B3"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function offsetReferences(source: string, dRow: number, dCol: number): string;
+/**
+ * A formula after rows or columns were inserted or deleted, or cells moved (Excel's rules): references behind the
+ * edit move, a range grows when rows are inserted inside it and shrinks when some of its rows are deleted; a deleted
+ * reference (or a fully deleted range) becomes `#REF!`, as does one pushed off the sheet (a range ending at the last
+ * row stays there). `moveCells`: references and ranges completely inside the moved cells follow them. Formula text
+ * without `=`; unparsable text and formulas without a changed reference are returned unchanged (same spelling).
+ *
+ * @param {string} source - the formula (without `=`)
+ * @param {SheetStructureEditIf} edit - the change
+ * @returns {string} the adjusted formula
+ *
+ * @example
+ * adjustFormula("SUM(D2:D4)+B3", { kind: "deleteRows", at: 2, count: 1 });   // "SUM(D2:D3)+#REF!"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function adjustFormula(source: string, edit: SheetStructureEditIf): string;