@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

package/types/src/calculation/ICalculation.d.ts

@@ -0,0 +1,1016 @@
+import { FormulaError, IRange, Scalar, IRuntime } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { IModel } from '../model';
+import { IFunctionCollection } from '../scripting';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { INamed } from '../named';
+import { INamedFormulasCollection } from './INamedFormulasCollection';
+/**
+ * Calculation is the process of computing formulas and then displaying the results
+ * as values in the cells that contain the formulas.
+ */
+export interface ICalculation extends IModel {
+    /**
+     * Execute a calculate on the Graph.
+     *
+     * @param options The options or a boolean. If `true' a full calculation will be done.
+     * @returns A promise that will be resolved when the calculation is completed.
+     *
+     * @remarks
+     * For async functions this will return before they are completed.
+     */
+    calculate(options?: boolean | ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * Starts the ICalculation engine.
+     *
+     * @remarks
+     * * This is required to be called before any calculations can be performed.
+     * * This will initialize the calculation engine and prepare it for use.
+     * * Will fire events and return a promise when the calculation is started. (or errors);
+     */
+    start: () => Promise<void>;
+    /**
+     * Stops the ICalculation engine.
+     */
+    stop: () => Promise<void>;
+    /**
+     * Returns when all calculations are complete and there are no pending calculations.
+     *
+     * @remarks
+     * * This is useful when needing to ensure that the values in the calculation cycle are up-to-date.
+     * * For streaming functions still will return the current value.
+     */
+    ready(): Promise<ICalculation.Status>;
+    /**
+     * Returns the current status of the calculation engine.
+     */
+    getStatus(): ICalculation.Status;
+    /**
+     * Returns the functions available for the calculation engine.
+     */
+    getFunctions(): IFunctionCollection;
+    /**
+     * Returns the named formulas available in the calculation engine.
+     */
+    getNamedFormulas(): INamedFormulasCollection;
+    /** @inheritdoc IFormulaContext.getRuntime */
+    getRuntime(): IRuntime;
+    /**
+     * Parses a formula expression and returns a *transient* formula object.
+     *
+     * @remarks
+     * - This does **not** register the formula in the workbook or dependency graph.
+     * - Use it for:
+     *   - interactive editing (tooltips, watches, function help)
+     *   - condition / validation expressions
+     *   - ad-hoc “what-if” evaluations
+     */
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    /**
+     * Evaluates a expression in the context of the sheet and returns the resulting value.
+     *
+     * @param expression The expression to evaluate.
+     * @param options Optional evaluation options.
+     *
+     * @remarks
+     * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
+     */
+    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICalculation.IListeners, options?: IListener.Options): IListener.Remove;
+}
+/**
+ * {@inheritDoc ICalculation}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICalculation}
+ */
+export declare namespace ICalculation {
+    /**
+     * The most characters a formula expression can hold, matching Excel's limit on formula
+     * contents.
+     *
+     * @remarks
+     * The leading `=` is not part of the expression and does not count against this.
+     *
+     * Longer text is refused at compile rather than parsed: the formula carries a parse error and
+     * {@link IFormula.getTokens} answers a single unparsed token. Nothing downstream — the
+     * tokenizer, the AST, a formula input — is ever handed an expression of unbounded size.
+     */
+    const MAX_EXPRESSION_LENGTH = 8192;
+    /**
+     * Represents a formula that can be evaluated.
+     */
+    interface IFormula {
+        /**
+         * Return the value for a formula.
+         *
+         * @see ICalculation.FormulaToken.evalIndex
+         */
+        evaluate(options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
+        /**
+         * Returns the status.
+         */
+        getCalculationStatus(): ICalculation.ResultStatus;
+        /**
+         * Return the formula's expression — the text WITHOUT a leading `=`.
+         *
+         * @param options Options for converting the formula to text.
+         *
+         * @remarks
+         * One shape for every kind of formula, a cell's and a defined name's alike. It is the STORED
+         * shape, which is what OOXML `<f>` and `<definedName>` hold and what {@link setExpression}
+         * takes back, so read/modify/write needs no adjusting in between.
+         *
+         * Displaying a formula means prefixing `'=' +` — Excel's own API answers that prefixed form
+         * (`Range.Formula`, `Name.RefersTo`) because ITS setters treat the `=` as the formula-ness
+         * marker: assigning `Range.Formula = "SUM(1,2)"` stores text. Ours do not — every entry point
+         * accepts the expression with or without it — so the prefix is presentation, and belongs at
+         * the point of display rather than in a second accessor.
+         */
+        getExpression(options?: ICalculation.FormulaTextOptions): string;
+        /**
+         * The cell this formula is anchored at — the cell its relative references are written from.
+         *
+         * @remarks
+         * `A1` in a formula anchored at `B1` means "the cell to my left"; the same text anchored at
+         * `B6` means "five rows up and one left". The anchor is what makes that text unambiguous, and
+         * a caller re-siting a formula ({@link shift}) needs it to know where it is starting from.
+         *
+         * `null` for a formula with no cell of its own — a temporary formula created without coords,
+         * which evaluates in a virtual space.
+         */
+        getAnchor(): IRange.CellCoords | null;
+        /**
+         * This formula as it would read at `target`: a DETACHED copy, filled.
+         *
+         * @param target The cell the copy is anchored at.
+         *
+         * @returns The filled copy, or `null` when this formula has no compiler behind it to mint one.
+         *
+         * @remarks
+         * Excel's **fill/copy**, not its move: relative references follow the formula to its new home
+         * and absolute (`$`) ones stay put, so the copy means at `target` what this one means at its
+         * own {@link getAnchor | anchor}. `A1*2` anchored at `B1`, shifted to `B6`, is `A6*2`.
+         *
+         * The distinction matters and is easy to invert. Re-compiling {@link getExpression}'s text at
+         * another cell keeps the TEXT and changes the meaning — that is a move, and a formula that
+         * meant "myself" starts meaning "some cells up". This keeps the meaning and changes the text.
+         *
+         * Nothing is committed; the copy is anchored at `target` whether or not anything lives there.
+         */
+        shift(target: IRange.CellCoords): IFormula | null;
+        /**
+         * Returns an ordered list of ranges referenced in this formula.
+         *
+         * @remarks
+         * * Returns `null` if there are no references.
+         * * These are the resolved ranges from `setReferenceAt()`
+         */
+        getReferences(): ICellRanges | null;
+        /**
+         * Whether any reference in this formula is unresolvable — `#REF!`.
+         *
+         * @remarks
+         * Asks the compiled references, not the text: a `"#REF!"` STRING literal in the formula is
+         * not a reference error. A reference degrades to one when its target is deleted, or when a
+         * {@link shift} pushes a relative reference above or left of the sheet.
+         */
+        hasRefError(): boolean;
+        /**
+         * Replaces a specific reference in the formula with a new one.
+         *
+         * @param index The zero-based index of the reference to be updated (from `getReferences()`).
+         * @param reference The new address or range to occupy that position.
+         * @param options Optional transaction or operation options.
+         * @throws Error is `index` is out of bounds relative to `getReferences()`.
+         *
+         * @remarks
+         * This is the primary way to "refactor" a formula—for example, if a user
+         * drags a highlighted range in the UI to a new location.
+         */
+        setReferenceAt(index: number, reference: ICellRange.Address, options?: string | ITransaction.OperationOptions): this;
+        /**
+         * Cycles the absolute/relative (`$`) style of the reference at the specified index.
+         *
+         * @param index The zero-based index of the reference to be cycled (from `getReferences()`).
+         * @param side Which part of the reference to cycle (relative to a range operator `:`):
+         *   - `'self'` (default) — the reference has no range operator (a single cell); cycles the whole
+         *     reference as a unit, keeping it a single cell.
+         *   - `'left'` — the left operand of a range (the "start" corner).
+         *   - `'right'` — the right operand of a range (the "end" corner).
+         *   A single-cell **range** (e.g. `A1:A1`) is still a range — it has a `'left'` and a `'right'`, so
+         *   it is NOT `'self'`. That distinction only survives in the tokens (see {@link FormulaToken.refSide}).
+         * @param mode Optional target mode. If omitted, cycles to the next mode in the sequence.
+         * @param options Optional transaction or operation options.
+         *
+         * @remarks
+         * The modes are:
+         * - `0`: Absolute (e.g., $A$1)
+         * - `1`: Absolute row, relative column (e.g., A$1)
+         * - `2`: Absolute column, relative row (e.g., $A1)
+         * - `3`: Relative (e.g., A1)
+         *
+         * * This is the `F4 Cycle` behavior commonly found in spreadsheet editors.
+         */
+        setReferenceModeAt(index: number, side?: ICalculation.ReferenceSide, mode?: number, options?: string | ITransaction.OperationOptions): this;
+        /**
+         * Returns true if the formula consists entirely of cell or range references and
+         * range operators (`:`, ` `, `#`, etc.) with no function calls or computed expressions.
+         *
+         * @remarks
+         * A pure-reference formula always resolves to a range, making it suitable for use as a navigation
+         * target. Named formulas that return true can meaningfully implement `getRanges()`.
+         */
+        isReferenceOnly(): boolean;
+        /**
+         * Returns true if this formula contains one or more volatile functions
+         * (e.g. `NOW`, `RAND`, `OFFSET`, `INDIRECT`).
+         *
+         * @remarks
+         * - Volatile formulas are re-evaluated on every calculation cycle regardless
+         *   of whether their inputs have changed.
+         * - This is a runtime property tracked by the calculation engine — it cannot
+         *   be derived from static AST analysis alone.
+         * - Named formulas where `isVolatile()` is true should not be used as
+         *   navigation targets even if `isReferenceOnly()` returns true, since their
+         *   resolved range may differ by context.
+         */
+        isVolatile(): boolean;
+        /**
+         * Return the formula as an array of tokenized values.
+         *
+         * @param evalIndex Allows for a partial evaluation based on a token index.
+         *
+         * @remarks
+         * These can be used by advanced editors.
+         *
+         * @see ICalculation.FormulaToken.evalIndex
+         */
+        getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
+        /**
+         * Whether the formula text **parsed** without error. `false` for an in-progress / malformed formula
+         * (`=SUM(`, `=A1:`, `=1+`) — the parser recovered a best-effort token stream but the input isn't a
+         * complete expression. This is a PARSE concern only: a well-formed formula that evaluates to an error
+         * (`=1/0`) is still valid. Lets an editor flag "more input expected" without re-parsing.
+         */
+        isValid(): boolean;
+        /**
+         * Attempt Excel-style **Formula AutoCorrect** on an invalid formula.
+         *
+         * @returns A corrected, DETACHED formula (not committed anywhere — the same shape
+         * {@link ICalculation.createFormula} returns, anchored at this formula's cell), or
+         * `null` when this formula is already {@link isValid | valid} or no safe correction exists.
+         *
+         * @remarks
+         * Currently ONE deliberately narrow rule: append the missing trailing closers (`)`, `}`) —
+         * `=SUM(A1:A2` → `=SUM(A1:A2)` — and only when the repaired text parses clean. A repair that
+         * would still be invalid (`=SUM(` → `=SUM()` fails arity) is never returned, nor is anything
+         * attempted for over-closed / interleaved brackets or an unterminated string. Never mutates
+         * this formula. Interactive hosts call this at commit; programmatic writes (`setValue`, file
+         * load) never auto-correct.
+         */
+        autoCorrect(): IFormula | null;
+        /**
+         * For runtime type checking.
+         */
+        readonly isIFormula: true;
+    }
+    /**
+     * A named formula — a persistent, user-facing formula bound to a name.
+     *
+     * @remarks
+     * Combines the full {@link IFormula} contract (evaluate, tokenize, inspect) with
+     * {@link INamed.INamedValue} (stable id, user-visible name, optional range coords).
+     * `getCoords()` returns non-null only when `isReferenceOnly()` is `true`.
+     */
+    /**
+     * A defined name owned by the calculation engine.
+     *
+     * @remarks
+     * Extends {@link INamed} so calc's items can flow through the aggregating `INamedCollection`
+     * without an adapter — an adapter would carry a second copy of each name's state, which is the
+     * duplication defined-name ownership exists to remove.
+     *
+     * It is both: a name (`getName`, `getScope`, `isHidden`) and the formula that name is bound to
+     * (`getText`, `getReferences`, `evaluate`). `INamed.getRanges` arrives from `INamed` and is
+     * meaningful exactly when {@link IFormula.isReferenceOnly} holds.
+     */
+    interface INamedFormula extends IFormula, INamed<string> {
+        /**
+         * The sheet name this formula is scoped to, or `null` for global scope.
+         */
+        getScope(): string | null;
+        /**
+         * Renames this defined name.
+         *
+         * @remarks
+         * A rename, not a redefinition: the stable symbol id is unchanged, so formulas that reference
+         * this name keep resolving and re-render with the new text.
+         */
+        setName(name: string): this;
+        /**
+         * Redefines the expression this name is bound to.
+         *
+         * @remarks
+         * A redefinition, not a replacement: the stable symbol id is unchanged, so formulas referencing
+         * this name pick up the new expression rather than going `#NAME?`. A leading `=` is optional —
+         * a bare range address is simply a reference expression.
+         */
+        setExpression(expression: string, options?: ITransaction.OperationOptions): this;
+        /**
+         * The comment, or `null` if none has been set.
+         */
+        getComment(): string | null;
+        /**
+         * If `true` the name is not shown in the UI. This does not affect resolution in formulas.
+         */
+        isHidden(): boolean;
+        /**
+         * {@link isHidden}
+         *
+         * @remarks
+         * Required here — every named formula supports hiding, unlike the broader {@link INamed}.
+         */
+        setHidden(hidden: boolean, options?: ITransaction.OperationOptions): this;
+        /**
+         * The ranges this name designates, or `null` when it holds an expression.
+         *
+         * @remarks
+         * Required here — every named formula answers (with `null` unless
+         * {@link IFormula.isReferenceOnly} holds), unlike the broader {@link INamed}.
+         */
+        getRanges(): ICellRanges | null;
+        /**
+         * {@link INamed.toJSON}
+         *
+         * @remarks
+         * Required here — every named formula serializes, unlike the broader {@link INamed}.
+         */
+        toJSON(): INamed.JSON | null;
+        /**
+         * What this name's body reads — cells and names, one hop, one answer; `null` when it reads
+         * nothing.
+         *
+         * @remarks
+         * The precedent half of the same four graph methods {@link ICell} exposes, resolved at the
+         * DEFINING anchor (the cell the body was authored from) — the same answer the Name Manager
+         * gives, since a name with relative references has no one answer until applied somewhere.
+         *
+         * A name the body reads rides in the collection as an `INamedRange` node, exactly as in
+         * {@link getDirectDependents} — `Doubled = Base*2` reports the `Base` node plus whatever
+         * cells the body reads directly. Contrast {@link IFormula.getReferences}: that is the ordered,
+         * index-aligned reference list (the `setReferenceAt` currency, `#REF!` slots included); this
+         * is the graph answer.
+         */
+        getDirectPrecedents(): ICellRanges | null;
+        /**
+         * Everything upstream of this name — {@link getDirectPrecedents} walked to exhaustion.
+         *
+         * @remarks
+         * The walk unions the body's cell-graph precedents with every name the body reaches through
+         * the symbol graph, each contributing its own body's walk; a cycle terminates and reports the
+         * names on it. One hop it deliberately does not flatten: a name referenced by an UPSTREAM
+         * CELL (`X = A1*2`, `A1 = SomeName`) is that cell's precedent, not this answer's — a tree
+         * walk crosses it through the cell's own {@link ICell.getDirectPrecedents}.
+         */
+        getPrecedents(): ICellRanges | null;
+        /**
+         * What references this SYMBOL — cells and names, one answer; `null` when nothing does.
+         *
+         * @remarks
+         * **Symbol-level, not target-level.** `=SUM(Revenue)` is a dependent of `Revenue`;
+         * `=SUM(Sales!$B$2:$B$100)` is not, even where that is exactly what `Revenue` designates. So
+         * `named.getRanges()?.getDirectDependents()` is not a substitute — it answers the address
+         * question, and for a name holding an expression (`TaxRate = 0.21`) there are no ranges to ask
+         * at all.
+         *
+         * **A dependent NAME rides in the same collection** as an `INamedRange` node: with
+         * `Doubled = Base*2`, `Doubled` is a dependent of `Base` as surely as any cell that names it —
+         * delete `Base` and every cell reading `Doubled` goes `#NAME?` too, without ever having
+         * mentioned `Base`. Such a member carries the `isINamedRange` brand; its coords are the name's
+         * ANCHOR (its defining cell), never a target, so lead with `getName()` when displaying one.
+         *
+         * This is the "is it safe to redefine or delete this name?" primitive: these are precisely the
+         * dependents that go `#NAME?` if the name is removed — an answer with no members at all
+         * (`null`) is the only genuinely-unused reading. The engine already tracks both edges — a name
+         * compiles into its own grid, and every formula that mentions one carries its id — so this is
+         * a door onto existing bookkeeping.
+         *
+         * Cells are reduced to regions rather than listed per cell, exactly as
+         * {@link ICell.getDirectDependents} does: a column of 400 formulas reading the name comes back
+         * as one range. Name nodes lead, cells follow.
+         */
+        getDirectDependents(): ICellRanges | null;
+        /**
+         * The transitive downstream of this name — everything that would recalculate if its expression
+         * changed, cells and names both.
+         *
+         * @remarks
+         * {@link getDirectDependents} walked to exhaustion across BOTH graphs (the symbol edges names
+         * ride on, and the ordinary cell graph between them), and the same distinction the cell family
+         * draws ({@link ICell.getDependents}). Direct is the blast radius of DELETING the name (those
+         * dependents go `#NAME?`); this is the blast radius of REDEFINING it.
+         *
+         * With `Outer = Mid*3` and `Mid = Base*2`, `Base` reports `Mid` and `Outer` as name nodes plus
+         * every cell downstream of either. A cycle terminates and reports the names on it, this one
+         * included.
+         */
+        getDependents(): ICellRanges | null;
+        /**
+         * Removes this named formula from its collection.
+         */
+        delete(): void;
+    }
+    /**
+     * What a {@link FormulaTokenContext} names — the two constructs that open an argument
+     * list, and the two registries that can resolve {@link FormulaTokenContext.name}.
+     */
+    type FormulaTokenContextType = 'function' | 'table';
+    /**
+     * What a token sits INSIDE — the enclosing call and, for a token that is one, which argument.
+     *
+     * @remarks
+     * Stamped on every token within an argument list, including the delimiters that opened and closed
+     * it (they carry `argIndex: -1`). It is what turns a flat token list into a tree: `B2` at argument
+     * 0 of `SUM`, rather than just `B2`.
+     */
+    interface FormulaTokenContext {
+        /**
+         * The display name of the enclosing function (`SUM`) or table (`Sales`).
+         *
+         * @remarks
+         * Always a DISPLAY name, never the stable id the AST carries — resolved alongside the token's
+         * own `value`/`text`, and localized the same way (see {@link FormulaToken.value}). An unknown
+         * function keeps the name as typed.
+         */
+        name: string;
+        /**
+         * Which argument of {@link name} this token belongs to, zero-based.
+         *
+         * @remarks
+         * `-1` when the token is not in an argument at all — the delimiters themselves (`(`, `)`, `[`,
+         * `]`). A separator belongs to the argument BEFORE it.
+         */
+        argIndex: number;
+        /**
+         * Whether {@link name} is a function (`SUM(`) or a table (`Sales[`).
+         */
+        type: FormulaTokenContextType;
+    }
+    /**
+     * Which part of a reference a cell token is, relative to a range operator `:` — the signal
+     * {@link IFormula.setReferenceModeAt} needs to cycle the correct corner.
+     * - `'self'` — a standalone cell reference (no `:`).
+     * - `'left'` / `'right'` — the operands of a range. A single-cell range `A1:A1` is still a range, so
+     *   its two cell tokens are `'left'` and `'right'` — NOT `'self'` (coords alone can't tell them apart).
+     */
+    type ReferenceSide = 'left' | 'right' | 'self';
+    /**
+     * The {@link FormulaToken.value} of a `named` token — a reference to a named formula, split into
+     * its name and its optional sheet qualifier.
+     *
+     * @remarks
+     * The counterpart of {@link IRange.FixableCellCoords} for a `cell` token: the qualifier lives
+     * beside the name rather than smeared into it, so a serializer can re-emit `Sheet1!MyName`
+     * without re-parsing the text.
+     */
+    interface NamedRef {
+        /**
+         * The name as it should be displayed or typed, e.g. `MyName`.
+         *
+         * @remarks
+         * Always the CURRENT display name — a rename is already reflected here, and the name a consumer
+         * reads is the one they can hand back to the API.
+         */
+        readonly name: string;
+        /**
+         * The sheet name for a sheet-scoped name (`Sheet1!MyName`).
+         *
+         * @remarks
+         * Absent (or `null`) for a workbook-scoped name — the common case. Bare, so it still needs
+         * quoting when it contains spaces.
+         */
+        readonly scope?: string | null;
+        /**
+         * `true` on an OPTIONAL `LAMBDA` parameter DECLARATION — the `[b]` in `LAMBDA(a,[b],a+1)`.
+         *
+         * @remarks
+         * The brackets are declaration syntax, not part of the name (`name` stays `b`), so they are
+         * carried as this flag and re-imaged by the serializer — the same split as a sheet qualifier.
+         * Never set on a USE of the parameter, nor outside a `LAMBDA` declaration list.
+         */
+        readonly optional?: boolean;
+    }
+    /**
+     * The {@link FormulaToken.value} of an error-REFERENCE token — `#REF!` or `#NAME?`, a reference
+     * whose target is gone — split into the error it resolves to and its optional sheet qualifier.
+     *
+     * @remarks
+     * `Data!#REF!` is what a row delete leaves behind, and the qualifier is the only remaining record
+     * of WHICH sheet's cells died — so it is carried beside the error rather than smeared into the
+     * text, exactly as {@link NamedRef} carries a name's. OOXML models the same distinction natively
+     * (`PtgRefErr` vs `PtgRefErr3d`).
+     *
+     * Only error tokens that are REFERENCES take this shape. An error LITERAL (`#DIV/0!`, `#N/A`) is a
+     * value, never scoped, and its `value` stays a plain {@link FormulaError}. Both arrive as
+     * `type: 'error'`, so a consumer that wants the error either way reads `value.error ?? value`.
+     *
+     * Reference-layer only: EVALUATION of a `#REF!` still produces the plain {@link FormulaError}, so
+     * a cell value never holds one of these.
+     */
+    interface ErrorRef {
+        /**
+         * The error the dead reference resolves to — `#REF!` (deleted cells) or `#NAME?` (a stored
+         * unresolvable name).
+         */
+        readonly error: FormulaError.Known;
+        /**
+         * The sheet name for a qualified error reference (`Data!#REF!`).
+         *
+         * @remarks
+         * Absent (or `null`) when the break was local to the formula's own sheet — the bare form Excel
+         * writes for a same-sheet delete, and the only form it writes when the SHEET itself is deleted.
+         * Bare, so it still needs quoting when it contains spaces.
+         */
+        readonly scope?: string | null;
+    }
+    /**
+     * Represents a portion of a formula for rendering typical in an editor.
+     */
+    interface FormulaToken {
+        /**
+         * The type of token.
+         */
+        type: string;
+        /**
+         * The resolved/normalized form of the token; the shape depends on {@link type}.
+         *
+         * @remarks
+         * Reference tokens are structured — a `cell` token carries {@link IRange.FixableCellCoords},
+         * a `named` token a {@link NamedRef}, and an error REFERENCE token (`#REF!`, `#NAME?`) an
+         * {@link ErrorRef}, each holding its own sheet qualifier (`coords.scope` / `ref.scope`) so
+         * serializers can re-emit `Sheet1!…`. Most other tokens (operators, function names, separators)
+         * carry a string; literals carry their parsed value (number, boolean, error).
+         */
+        value: string | IRange.FixableCellCoords | NamedRef | ErrorRef | any;
+        /**
+         * The raw source text this token occupied — exactly the characters that produced it (a whitespace
+         * token holds the literal spaces). Concatenating `text` across the whole array reproduces the
+         * original expression, so a consumer can derive each token's character offset as the running sum
+         * of `text.length` — no separate start/end is needed.
+         *
+         * @remarks
+         * Pairs with {@link value}: `text` is what was typed, `value` is the resolved/normalized form. The
+         * two diverge exactly where normalization is lossy — a number (`3.0` → `3`, `1**2` → `100`) or a
+         * cell (raw `b2` vs the resolved coords). `undefined` only for a token with no captured source
+         * image (e.g. a reference the engine rewrote programmatically rather than one the user typed).
+         */
+        text?: string;
+        /**
+         * Allows for partial formula evaluation for tooltips or formula writing.
+         * Only available for tokens types that can be evaluated.
+         *
+         * @remarks
+         * To determine the 'token span' for the evaluation you can can tokens left and right
+         * until you reach a token that has a larger evalIndex or there are no more tokens.
+         */
+        evalIndex?: number;
+        /**
+         * `true` when this token is part of a reference *literal* — a cell (`A1`), a range operator that
+         * binds one (`:`, ` `, `#`, `@`), a named reference, or a structured-reference part. Lets an editor
+         * color the whole reference span (operators included) without enumerating token types.
+         *
+         * @remarks
+         * Distinct from merely having a {@link referenceIndex}: a function that *returns* a reference (e.g.
+         * `INDEX`, `OFFSET`) carries a `referenceIndex` but is **not** a reference literal, so `isReference`
+         * is absent on its `function` token. Color by `referenceIndex` only when `isReference` is `true`.
+         */
+        isReference?: boolean;
+        /**
+         * `true` when this token is a **name-completion candidate** — an identifier that could be resolved
+         * against the function / named-reference / table registries: a function name, a named reference, a
+         * table reference, or a partial identifier still being typed (a trailing run in an `unparsed` tail).
+         * The sibling of {@link isReference}: it lets an editor decide, from the caret's token alone, that an
+         * autocomplete list belongs here — without re-scanning the raw text. Use the token's `text` as the
+         * prefix to filter. Absent on non-candidate tokens (numbers, strings, cells, operators, punctuation).
+         */
+        isLookup?: boolean;
+        /**
+         * Indicates that the token is part of a reference.
+         *
+         * @remarks
+         * * Multiple tokens can be part of the same reference.
+         * * The referenceIndex will be the offset of the range in the {@link ICalculation.IFormula.getReferences} array.
+         */
+        referenceIndex?: number;
+        /**
+         * For a reference **cell** token, which part of the reference it is — `'self'` for a standalone cell,
+         * or `'left'`/`'right'` for the operands of a range `:` (see {@link ReferenceSide}). Lets an editor
+         * pick the range corner for {@link IFormula.setReferenceModeAt} (F4) without re-parsing. Absent on
+         * non-reference tokens.
+         */
+        refSide?: ICalculation.ReferenceSide;
+        /**
+         * If the token is part of a a function this will be set. This will be the 'closest' function if nested.
+         */
+        context?: ICalculation.FormulaTokenContext;
+    }
+    /**
+     * A read-only "lite" view of one node of a formula's AST, as presented to a
+     * {@link FormulaTransform}.
+     *
+     * @remarks
+     * Values are DISPLAY-resolved — a `named` node presents its display text ({@link NamedRef}),
+     * a `function` node its canonical (English) name, a `tableReference`/`tableColumn` its display
+     * name, and a `cell` node its coordinates with a sheet display-name qualifier. Stable internal
+     * ids never appear. Internal compilation details (trivia/whitespace, evaluation indices,
+     * caches) are not exposed; whitespace and typed images are carried across a transform by the
+     * engine invisibly.
+     *
+     * `type` uses the same vocabulary as {@link FormulaToken.type} (`'function'`, `'infix'`,
+     * `'prefix'`, `'postfix'`, `'named'`, `'cell'`, `'tableReference'`, `'tableSpecifier'`,
+     * `'tableColumn'`, `'number'`, `'string'`, `'boolean'`, `'error'`, …).
+     *
+     * A transform returns nodes as PLAIN OBJECTS in this shape — either a shallow spread-copy of a
+     * node it received (`{ ...node, value }` to rename, `{ ...node, inputs }` to re-child; identity
+     * and whitespace trivia are preserved through a spread) or a fresh literal
+     * (`{ type: 'function', value: name, inputs }`). The engine derives the internals (reference
+     * flags, images) from `type` + `value`; there is no node class to construct.
+     */
+    interface FormulaNode {
+        /**
+         * The node type — same vocabulary as {@link FormulaToken.type}.
+         */
+        readonly type: string;
+        /**
+         * The display-resolved value; the shape depends on {@link type} (see {@link FormulaToken.value}).
+         */
+        readonly value?: any;
+        /**
+         * Child nodes, or `null`/absent for a leaf.
+         */
+        readonly inputs?: readonly FormulaNode[] | null;
+        /**
+         * `true` when the node is part of a reference expression (a cell, a range operator, a named
+         * reference, a structured-reference part).
+         */
+        readonly isReference?: boolean;
+    }
+    /**
+     * A structural transform over a formula's AST — a visitor applied where formulas serialize
+     * ({@link ISheet.ToJSONOptions.formulaTransform | toJSON}) or parse.
+     *
+     * @remarks
+     * Called once for every node, children before parents (depth-first). Return a replacement
+     * {@link FormulaNode} to substitute the node, or `undefined`/`void` to leave it alone.
+     * Replacement is copy-on-write — untouched subtrees are shared. The ROOT is visited last with
+     * `parent === undefined`, so a whole-tree (multi-pass) rewrite is simply a visitor that acts
+     * only there and returns the new root.
+     *
+     * `parent` is the enclosing node — needed by parent-sensitive rules (e.g. `@` directly under
+     * a `tableReference` is a this-row marker, elsewhere an implicit intersection).
+     *
+     * The transform runs ONCE per formula block on the compiled AST (per-cell re-anchoring and
+     * re-imaging stay untouched); a transform that replaces nothing costs no recompile. It must be
+     * side-effect free and no-op-safe on a partially parsed (errored) tree.
+     */
+    type FormulaTransform = (node: FormulaNode, parent: FormulaNode | undefined) => FormulaNode | void;
+    /**
+     * Options for evaluating a formula.
+     */
+    interface EvaluateOptions {
+        /**
+         * If specified, evaluates only the token span associated with this index.
+         *
+         * @defaultValue `-1` (full evaluation)
+         *
+         * @remarks
+         * Use {@link ICalculation.FormulaToken.evalIndex} to discover valid indices.
+         */
+        evalIndex?: number;
+        /**
+         * Temporary range of values to use for this evaluation.
+         *
+         * @remarks
+         * - **Not implemented yet** — evaluation currently ignores this option.
+         * - Does **not** mutate the workbook.
+         * - Acts as a pure overlay for one or more precedents used by this formula.
+         * - Typically a literal or computed `IRange` created via `ctx.getRange(...)`
+         *   in predicates or editors.
+         */
+        values?: IRange;
+        /**
+         * Evaluate the formula once per cell of the given coordinates.
+         *
+         * @remarks
+         * - The formula must be anchored at the top-left of `block` (the `coords` passed to
+         *   {@link ICalculation.createFormula}); relative and structured references
+         *   are adjusted per-cell, exactly as a formula filled across the shape.
+         * - The result is an `IRange` of the block's shape, read with local coordinates
+         *   (`getValueAt(0, 0)` is the block's top-left). A 1×1 block still unboxes to a
+         *   scalar unless {@link alwaysReturnRange} is set.
+         * - A cell whose evaluation errors carries the error as that cell's value; other
+         *   cells are unaffected.
+         * - Cells evaluate sequentially — an async cell (a formula hitting an async function)
+         *   settles before the next cell starts.
+         * - Honored by temporary formulas ({@link ICalculation.evaluate} /
+         *   {@link ICalculation.createFormula}); a committed cell formula ignores it.
+         * - Often used for "preview this formula over this region" or batched
+         *   validation of an expression over a condition range.
+         */
+        block?: IRange.Coords;
+        /**
+         * If specified, the result will always be returned as an `IRange`,
+         * even when the logical result is a single scalar value.
+         *
+         * @remarks
+         * By default, formulas that evaluate to a single cell return a scalar
+         * value. Setting this to `true` disables that scalar unboxing and
+         * keeps the result in range form (1×1), which can be useful for
+         * batch-oriented or shape-sensitive consumers.
+         */
+        alwaysReturnRange?: boolean;
+    }
+    /**
+     * Options for converting a formula to text.
+     */
+    interface FormulaTextOptions {
+        /**
+         * If `true`, the formula will be returned in R1C1 notation.
+         *
+         * @defaultValue `false`
+         */
+        r1c1?: boolean;
+        /**
+         * The cell coordinates for which the formula text is being requested.
+         */
+        cell?: IRange.CellCoords;
+        /**
+         * If specified, the formula text will only be generate for a given eval index.
+         */
+        evalIndex?: number;
+        /**
+         * If `true`, function names are returned in CANONICAL (English) form — the
+         * persistence/interchange representation (files, clipboard interchange, APIs).
+         * Default `false` = display form, localized via the active language pack
+         * (I18N-DESIGN.md Plane 3).
+         *
+         * @defaultValue `false`
+         */
+        canonical?: boolean;
+        /**
+         * A structural transform applied to the compiled AST before imaging — how a format
+         * exporter (e.g. xlsx) applies its version-compatibility spellings.
+         *
+         * @see {@link FormulaTransform}
+         */
+        formulaTransform?: FormulaTransform;
+    }
+    interface Events extends IModel.Events {
+        /**
+         * Called when the calculation has been updated and
+         * a calculation has not been started.
+         */
+        onStale?(source: ICalculation): void;
+        /**
+         * Called when a calculation is starting.
+         */
+        onStarting?(source: ICalculation): void;
+        /**
+         * Called when a calculation is stopping.
+         */
+        onStopping?(source: ICalculation): void;
+        /**
+         * Called when the calculation status has changed.
+         */
+        onStatusChange?(source: ICalculation): void;
+        /**
+         * Called when a calculation is completed.
+         */
+        onComplete?(source: ICalculation): void;
+        /**
+         * Called when the calculation engine is unable to calc.
+         *
+         * @remarks
+         * This is not when a specific function fails, but when the calculation engine is unable to complete the calculation.
+         */
+        onError?(source: ICalculation): void;
+        /**
+         * Called when the ICalculation has been loaded and is ready to calc.
+         */
+        onReady?(source: ICalculation): void;
+        /**
+         * Called when the ICalculation has been loaded and is ready to calc.
+         */
+        onStop?(source: ICalculation): void;
+    }
+    /**
+     * Represents the calculation engine's overall status.
+     */
+    const Status: {
+        /**
+         * The calculation engine is in manual mode and will only update cell values when a calculation is explicitly triggered.
+         */
+        readonly Ready: "ready";
+        /**
+         * The calculation engine has encountered an error and is unable to perform calculations.
+         * This status represents engine-level errors, separate from cell-level errors (which are represented as Scalar.Error values).
+         */
+        readonly Error: "error";
+        /**
+         * The calculation engine is starting up and initializing its internal state.
+         */
+        readonly Starting: "starting";
+        /**
+         * The calculation engine is stopping and cleaning up its internal state.
+         */
+        readonly Stopping: "stopping";
+        /**
+         * The calculation engine is disabled.
+         */
+        readonly Off: "off";
+    };
+    type Status = typeof Status[keyof typeof Status];
+    /**
+     * Represents the calculation mode of the engine, which determines when and how formulas are recalculated.
+     */
+    const CalculationMode: {
+        /**
+         * In automatic calculation mode, the calculation engine automatically recalculates all dependent formulas
+         * whenever a change is made to the workbook that affects their inputs. This is the default mode and ensures
+         * that all formula results are always up to date.
+         */
+        readonly Automatic: "auto";
+        /**
+         * In manual calculation mode, the calculation engine does not automatically recalculate formulas when changes
+         * are made. Instead, formulas are only recalculated when the user explicitly triggers a calculation
+         * (e.g., by pressing F9 or calling `calculate()`).
+         * This mode can improve performance in large workbooks where automatic recalculation would be too slow, but it
+         * requires users to remember to manually recalculate to see updated results.
+         */
+        readonly Manual: "manual";
+        /**
+         * Calculates new formula results every time the relevant data is changed, unless the formula is in a data table.
+         */
+        readonly AutomaticExceptTables: "automaticExceptTables";
+    };
+    type CalculationMode = typeof CalculationMode[keyof typeof CalculationMode];
+    /**
+     * Represents the status of a calculation result
+     */
+    const ResultStatus: {
+        /**
+         * The value is up-to-date and reflects the latest calculation.
+         */
+        readonly Ready: "ready";
+        /**
+         * The value may not reflect the latest calculation, typically due to the calculation engine being in manual mode.
+         */
+        readonly Stale: "stale";
+        /**
+         * The value is being calculated asynchronously, typically because the function used returned a Promise.
+         * All dependent values will also be in the Pending state. If the promise returns an error or times out, the value will be an error value.
+         */
+        readonly Pending: "pending";
+        /**
+         * The value is up-to-date, but the underlying data source is streaming live updates.
+         */
+        readonly Streaming: "streaming";
+    };
+    type ResultStatus = typeof ResultStatus[keyof typeof ResultStatus];
+    /**
+     * Options for when calculating.
+     */
+    interface CalculateOptions {
+        /**
+         * If `true` a full calc will be done not just invalid values.
+         *
+         * @defaultValue `false`
+         */
+        full?: boolean;
+        /**
+         * If specified, only the formulas intersecting with this range will be calculated.
+         *
+         * @remarks
+         * If `full` is `true`, this option is ignored and a full calculation is performed.
+         */
+        range?: ICellRange.Address;
+        /**
+         * If specified, only the named sheet SEEDS the pass — Excel's "Calculate Sheet" (Shift+F9).
+         *
+         * @remarks
+         * Unlike {@link range}, which collects every formula it covers whether or not it is out of date,
+         * this still respects dirtiness: it narrows WHICH sheet's pending work is picked up, not whether
+         * up-to-date formulas are recalculated. Combine with `full` to force one sheet.
+         *
+         * Only the seed is scoped. Dependents on other sheets are still evaluated (they are reached by
+         * the dependency walk), and volatiles are still collected workbook-wide — they are drained and
+         * re-registered by evaluation, so skipping them would deregister the other sheets' volatiles.
+         * Excel leaves both stale; being more current is the safe direction.
+         *
+         * This is deliberately NOT the internal per-grid entry point (`ICalcGrid.calculate`), which is
+         * how ordinary edits schedule their pass and must stay workbook-wide — a formula's precedents
+         * live in other sheets, and a named formula's body lives in a virtual grid of its own.
+         */
+        scope?: string;
+    }
+    interface JSON {
+        /**
+         * Indicates whether the workbook has completed its last calculation cycle.
+         *
+         * @remarks
+         * If `true`, the workbook is up to date with calculations.
+         */
+        calcCompleted?: boolean;
+        /**
+         * Defines the calculation mode for the workbook.
+         */
+        calcMode?: ICalculation.CalculationMode;
+        /**
+         * Specifies whether calculations should be performed when the workbook is saved.
+         *
+         * @remarks
+         * If `true`, the workbook recalculates all formulas before saving.
+         */
+        calcOnSave?: boolean;
+        /**
+         * Specifies whether calculations should be performed concurrently across multiple threads.
+         *
+         * @remarks
+         * If `true`, the workbook uses multi-threading for calculations.
+         */
+        concurrentCalc?: boolean;
+        /**
+         * Specifies whether concurrent calculations are allowed in manual calculation mode.
+         *
+         * @remarks
+         * If `true`, manual calculations can utilize multiple threads.
+         */
+        concurrentManualCount?: boolean;
+        /**
+         * Specifies whether the workbook forces a full recalculation of all formulas.
+         *
+         * @remarks
+         * If `true`, all formulas will be recalculated from scratch regardless of dependencies.
+         */
+        forceFullCalc?: boolean;
+        /**
+         * Specifies whether a full recalculation should be performed when the workbook is loaded.
+         *
+         * @remarks
+         * If `true`, the workbook recalculates all formulas upon loading.
+         */
+        fullCalcOnLoad?: boolean;
+        /**
+         * Indicates whether calculations should be performed using full precision.
+         *
+         * @remarks
+         * If `true`, all calculations are performed with the maximum precision available.
+         */
+        fullPrecision?: boolean;
+        /**
+         * Specifies whether the workbook should iterate calculations when circular references are present.
+         *
+         * @remarks
+         * If `true`, the workbook allows iterative calculations to resolve circular references.
+         */
+        iterate?: boolean;
+        /**
+         * Defines the maximum number of iterations allowed when performing iterative calculations.
+         *
+         * @defaultValue `100`
+         *
+         * @remarks
+         * This value is only used if `iterate` is set to `true`.
+         */
+        maxIterations?: number;
+        /**
+         * Defines the maximum change between iterations that must be reached before the iterative calculation stops.
+         *
+         * @defaultValue `0.001`
+         *
+         * @remarks
+         * A smaller delta will make the iterative calculation more precise but may take longer to complete.
+         *
+         */
+        maxIterateChange?: number;
+        /**
+         * Specifies the reference mode for calculations.
+         *
+         * @remarks
+         * Possible values could include 'A1' or 'R1C1', representing different reference styles.
+         */
+        refMode?: string;
+    }
+    interface IListeners extends IListener.Callbacks<ICalculation, ICalculation.Events> {
+    }
+}
+//# sourceMappingURL=ICalculation.d.ts.map