@guiexpert/table 1.1.98 → 1.1.100

package/lib/table/sheet/cell-address.d.ts

@@ -0,0 +1,100 @@
+/** Rows of a sheet (like Excel): 1 … 1 048 576. */
+export declare const SHEET_MAX_ROWS = 1048576;
+/** Columns of a sheet (like Excel): A … XFD = 16 384. */
+export declare const SHEET_MAX_COLUMNS = 16384;
+/**
+ * The letters of a column (0-based): 0 → `"A"`, 25 → `"Z"`, 26 → `"AA"`, 16 383 → `"XFD"`.
+ *
+ * @param {number} columnIndex - 0-based column
+ * @returns {string} the letters (`""` for an index outside 0 … 16 383)
+ *
+ * @example
+ * columnLetter(27);   // "AB"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function columnLetter(columnIndex: number): string;
+/**
+ * The 0-based column of letters: `"A"` → 0, `"ab"` → 27 (case does not matter).
+ *
+ * @param {string} letters - column letters
+ * @returns {number} the column, `-1` if invalid or beyond `XFD`
+ *
+ * @example
+ * columnIndexOfLetter("XFD");   // 16383
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function columnIndexOfLetter(letters: string): number;
+/**
+ * A parsed cell address: 0-based row and column, `$` = absolute.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface CellAddressIf {
+    row: number;
+    col: number;
+    absRow: boolean;
+    absCol: boolean;
+}
+/**
+ * The address of a cell: `toCellAddress(2, 1)` → `"B3"`, with `$` for absolute parts.
+ *
+ * @param {number} row - 0-based row
+ * @param {number} col - 0-based column
+ * @param {{ absRow?: boolean, absCol?: boolean }} [abs] - `$` before the row / column
+ * @returns {string} the address, `"#REF!"` outside the sheet
+ *
+ * @example
+ * toCellAddress(0, 5, { absRow: true, absCol: true });   // "$F$1"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function toCellAddress(row: number, col: number, abs?: {
+    absRow?: boolean;
+    absCol?: boolean;
+}): string;
+/**
+ * Parses a cell address like `"B3"`, `"$B$3"`, `"b$3"`.
+ *
+ * @param {string} address - the address
+ * @returns {CellAddressIf | undefined} row, column (0-based) and the absolute parts; `undefined` if invalid
+ *
+ * @example
+ * parseCellAddress("$B3");   // { row: 2, col: 1, absRow: false, absCol: true }
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function parseCellAddress(address: string): CellAddressIf | undefined;
+/**
+ * A parsed range: first and last cell (0-based, inclusive). A whole column (`"A:A"`) has the rows 0 … 1 048 575 and
+ * `wholeColumns: true`, a whole row (`"3:3"`) the columns 0 … 16 383 and `wholeRows: true`.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface RangeAddressIf {
+    from: CellAddressIf;
+    to: CellAddressIf;
+    wholeColumns?: boolean;
+    wholeRows?: boolean;
+}
+/**
+ * Parses a range like `"A1:B5"`, `"$A$1:B5"`, `"A:A"`, `"B:D"`, `"3:3"` or a single cell `"C7"`. The corners are
+ * sorted (`"B5:A1"` = `"A1:B5"`).
+ *
+ * @param {string} address - the range
+ * @returns {RangeAddressIf | undefined} the range; `undefined` if invalid
+ *
+ * @example
+ * parseRangeAddress("A:A")?.to.row;   // 1048575
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function parseRangeAddress(address: string): RangeAddressIf | undefined;

package/lib/table/sheet/cell-formula-options.d.ts

@@ -0,0 +1,27 @@
+import { FormulaFunction } from '../formula/formula-options.if.js';
+import { CellFormulaOptionsIf } from './cell-formula-options.if.js';
+
+/**
+ * The defaults of {@link CellFormulaOptionsIf} (cell formulas).
+ *
+ * @example
+ * CellFormulaOptions.create(true)?.maxRangeCells;   // 10000000
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class CellFormulaOptions implements CellFormulaOptionsIf {
+    functions: Record<string, FormulaFunction>;
+    isoDatesAsDates: boolean;
+    maxRangeCells: number;
+    rejectInvalidFormulas: boolean;
+    columns?: string[];
+    /**
+     * The options of {@link TableOptionsIf.cellFormulas}: `undefined`/`false` = off, `true` = the defaults, an object =
+     * the defaults overridden by its values (`undefined` keeps the default).
+     *
+     * @param {boolean | Partial<CellFormulaOptionsIf>} [option] - the option
+     * @returns {CellFormulaOptionsIf | undefined} complete options, `undefined` if off
+     */
+    static create(option?: boolean | Partial<CellFormulaOptionsIf>): CellFormulaOptionsIf | undefined;
+}

package/lib/table/sheet/cell-formula-options.if.d.ts

@@ -0,0 +1,27 @@
+import { FormulaFunction } from '../formula/formula-options.if.js';
+
+/**
+ * Cell formulas like in Excel ({@link TableOptionsIf.cellFormulas}, {@link SheetEngine}): `=B2*C2`, `=SUM(D2:D100)`.
+ * `cellFormulas: true` uses the defaults of {@link CellFormulaOptions}; an object overrides single values.
+ *
+ * @example
+ * const engine = SheetEngine.fromArrays(data, { functions: { VAT: (net) => Number(net) * 0.19 } });
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface CellFormulaOptionsIf {
+    /**
+     * Own functions by name (case-insensitive); they may replace built-in ones. A range argument (`A1:B5`) arrives as
+     * {@link FormulaRange}, a date as its serial number.
+     */
+    functions: Record<string, FormulaFunction>;
+    /** ISO text (`"2026-10-16"`) counts as date in arithmetic (`=A2+1`) and date functions. Default `true`. */
+    isoDatesAsDates: boolean;
+    /** Larger ranges are `#ERROR!` (`A1:XFD1048576`). Default `10_000_000`. */
+    maxRangeCells: number;
+    /** The table refuses formulas with a syntax error instead of storing them (`#ERROR!`). Default `false`. */
+    rejectInvalidFormulas: boolean;
+    /** Only these properties hold formulas (the other columns keep `=…` as text). Default: every data column. */
+    columns?: string[];
+}

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

@@ -0,0 +1,20 @@
+/** Where the data of the sheet lie in the file: rows above, columns in front, and their number. */
+export interface ExcelSheetPlacementIf {
+    dRow: number;
+    dCol: number;
+    rows: number;
+    cols: number;
+}
+/**
+ * The formula of a cell formula for an Excel file: all references moved by the offset of the sheet (header rows,
+ * leading columns – also absolute parts), whole columns/rows bounded to the data (the file holds headers and totals
+ * around them), newer functions with `_xlfn.`. `undefined` for a formula Excel cannot read: a syntax error or a field
+ * (`[price]`). Text without `=`.
+ *
+ * @param {string} input - the cell formula (with `=`)
+ * @param {ExcelSheetPlacementIf} at - where the data are in the file
+ * @returns {string | undefined} the Excel formula
+ *
+ * @internal
+ */
+export declare function toExcelFormula(input: string, at: ExcelSheetPlacementIf): string | undefined;

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

@@ -0,0 +1,19 @@
+import { FormulaNode, FormulaRefNode } from '../formula/formula-ast.if.js';
+
+/** A reference as text: `B3`, `$B$3`; whole columns/rows in ranges. */
+export declare function formatRef(ref: FormulaRefNode): string;
+/**
+ * The canonical text of a formula AST (without `=`): functions and references in capitals, `,` between arguments,
+ * texts with `""` for a quotation mark, parentheses only where needed. Used for moving formulas and the Excel export.
+ *
+ * @param {FormulaNode} ast - the syntax tree
+ * @returns {string} the formula text
+ *
+ * @example
+ * formatFormula({ kind: "binary", op: "*", left: { kind: "ref", row: 1, col: 1, absRow: false, absCol: false },
+ *   right: { kind: "literal", value: 2 } });   // "B2*2"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function formatFormula(ast: FormulaNode): string;

package/lib/table/sheet/sheet-cells.if.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The link between the body model and the cell formulas of a table ({@link TableOptionsIf.cellFormulas}): the model
+ * asks it for the value of every text input – an `=…` cell of a formula column gives its result. Set by the table.
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export interface SheetCellsIf {
+    /** The value of a cell of an array row (`AreaModelArrayOfArrays`): the result for a formula, otherwise `input`. */
+    valueAt(row: unknown, columnIndex: number, input: string): unknown;
+    /** The value of a property of a row object: the result for a formula, otherwise `input`. */
+    valueOfProperty(row: unknown, property: string, input: string): unknown;
+    /** True if the column of this property may hold formulas. */
+    isFormulaProperty(property: string): boolean;
+    /** True if the column may hold formulas. */
+    isFormulaColumnIndex(columnIndex: number): boolean;
+}

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

@@ -0,0 +1,47 @@
+import { FormulaFunction } from '../formula/formula-options.if.js';
+import { FormulaError } from '../formula/formula-error.js';
+import { SheetFnContext } from './sheet-functions.js';
+import { SheetValue } from './sheet-values.js';
+
+/** A range a formula reads (0-based, inclusive, already cut to the sheet). */
+export interface RangeRef {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}
+/** What the compiled formula of a cell needs from the engine. */
+export interface SheetCompileEnv {
+    /** The value of a cell (formula result or data). */
+    read(row: number, col: number): SheetValue;
+    /** Rows of the data (ranges are cut there). */
+    rowCount(): number;
+    /** The column of a data field (`[price]`), -1 if it is none. */
+    fieldColumn(name: string): number;
+    /** Own functions (upper case names). */
+    functions: Map<string, FormulaFunction>;
+    /** Largest range (cells) – larger ones are #ERROR!. */
+    maxRangeCells: number;
+    fn: SheetFnContext;
+}
+/** A compiled cell formula: evaluation and the cells it reads. */
+export interface CompiledCellFormula {
+    evaluate(): SheetValue;
+    /** Single cells read (`row * 16384 + col`). */
+    readonly singles: number[];
+    readonly ranges: RangeRef[];
+    readonly volatile: boolean;
+    /** Syntax error or unknown function – the evaluation returns it. */
+    readonly error?: FormulaError;
+}
+/** The key of a cell in maps. */
+export declare function cellKey(row: number, col: number): number;
+/**
+ * Compiles the formula of a cell (`=B2*C2`) into closures over the engine – no `eval`, no `new Function`.
+ *
+ * @param {string} source - the formula with `=`
+ * @param {number} row - the row of the cell (for `[field]`)
+ * @param {SheetCompileEnv} env - the engine
+ * @returns {CompiledCellFormula} the compiled formula
+ */
+export declare function compileCellFormula(source: string, row: number, env: SheetCompileEnv): CompiledCellFormula;

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;