@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

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

@@ -0,0 +1,117 @@
+/**
+ * Valid FormulaToken types.
+ */
+export declare const TokenType: {
+    /**
+     * The formula could not be tokenized at all. `value` holds the raw expression text. Signals to the
+     * UI that no token stream is available; distinct from `Error` which is a recognized Excel error value.
+     */
+    readonly Unparsed: "unparsed";
+    /**
+     * A parenthesized sub-expression, e.g. `(A1+B1)`.
+     */
+    readonly Paren: "paren";
+    /**
+     * A binary operator between two operands,
+     * e.g. `+`, `*`, `:`, `&`.
+     */
+    readonly Infix: "infix";
+    /**
+     * A unary operator before its operand,
+     * e.g. `-` (negation) or `@` (implicit intersection).
+     */
+    readonly Prefix: "prefix";
+    /**
+     * A unary operator after its operand,
+     * e.g. `%` (percent) or `#` (spill-range anchor).
+     */
+    readonly Postfix: "postfix";
+    /**
+     * A function call, e.g. `SUM(...)`. `value` is the function name.
+     */
+    readonly Function: "function";
+    /**
+     * Function application where the callee is an EXPRESSION rather than a name — an immediately
+     * invoked lambda, `LAMBDA(a,b,a+b)(1,2)`.
+     *
+     * `inputs[0]` is the callee; `inputs[1..]` are the arguments. `value` is `null` — unlike
+     * {@link Function} there is no name to carry.
+     *
+     * A `(` binds as a call ONLY when it touches the callee's last token: `LAMBDA(x,x+1) (3)` with a
+     * space is an implicit intersection, and Excel refuses it. See DESIGN-FORMULA-APPLICATION.md.
+     */
+    readonly Call: "call";
+    /**
+     * An error literal, e.g. `#DIV/0!` or `#REF!`.
+     */
+    readonly Error: "error";
+    /**
+     * A number literal, e.g. `3.14` or `2e10`.
+     */
+    readonly Number: "number";
+    /**
+     * The boolean literals `TRUE` and `FALSE`.
+     */
+    readonly Boolean: "boolean";
+    /**
+     * A double-quoted Excel string literal, e.g. `"hello"`.
+     */
+    readonly String: "string";
+    /**
+     * Separator token used between function arguments or array columns.
+     */
+    readonly Separator: "separator";
+    /**
+     * Root-level comma-separated list (e.g. named formula 'A1,A2')
+     */
+    readonly List: "list";
+    /**
+     * The `{` or `}` delimiter of a literal array.
+     */
+    readonly Type: "type";
+    /**
+     * A literal array constant, e.g. `{1,2;3,4}`.
+     */
+    readonly Array: "array";
+    /**
+     * One row inside a literal array, e.g. `{1,2;3,4}` has two rows.
+     */
+    readonly Row: "row";
+    /**
+     * A cell or range reference, e.g. `A1`, `$B$2`, `A1:B3`,
+     * or a cross-sheet reference.
+     */
+    readonly Cell: "cell";
+    /**
+     * A named formula reference, e.g. `TotalRevenue`.
+     */
+    readonly Named: "named";
+    /**
+     * Tokens related to structured reference parsing. (e.g. Table[])
+     *
+     */
+    readonly TableReference: "tableReference";
+    /**
+     * Tokens related to Table Specifiers. (e.g. #All, #Data, #Headers, #Totals, #This Row)
+     */
+    readonly TableSpecifier: "tableSpecifier";
+    /**
+     * Tokens related to column specifiers in structured references. (e.g. [Column1], Column1)
+     */
+    readonly TableColumn: "tableColumn";
+    /**
+     * External references. For example: [Book.xlsx]Sheet1!A1
+     */
+    readonly ExternalReference: "externalReference";
+    /**
+     * An omitted function argument, e.g. the middle argument of `=IF(A1,,0)`.
+     * Evaluates to `undefined`.
+     */
+    readonly Empty: "empty";
+    /**
+     * Whitespace.
+     */
+    readonly Whitespace: "whitespace";
+};
+export type TokenType = typeof TokenType[keyof typeof TokenType];
+//# sourceMappingURL=TokenType.d.ts.map

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

@@ -0,0 +1,110 @@
+import { IRange, FormulaError } from '@sheetxl/primitives';
+/**
+ * A named formula reference — the `value` of a Named AST node. INTERNAL: stable ids are a
+ * calculation-private notion, so this type stays inside the package.
+ *
+ * @remarks
+ * `nameId` is the stable UUID after `linkSymbols` resolves the display name (or the display name
+ * itself when no registry is available, e.g. unit tests). `scope` is the sheet stableId of an
+ * explicit qualifier (`Sheet2!Total`) after linking — it stays the raw sheet NAME only when the
+ * sheet is unknown or no registry was used, so a rename re-images the qualifier rather than leaving
+ * dead text. Serializers must emit it (`sheetNameToString(scope) + '!'`) or the qualifier is
+ * silently stripped on re-imaging (the erroring `=Sheet1!1+1` that once round-tripped into a clean
+ * `=1+1`).
+ *
+ * The public counterpart is {@link ICalculation.NamedRef}, the `value` of a `named`
+ * {@link ICalculation.FormulaToken} — same split (name + sheet scope), but `name` is a display name,
+ * not an id. `generateFormulaTokens` projects this onto that, and `resolveTokenSymbols` swaps the id
+ * for the display name before any token reaches a consumer.
+ */
+export interface NamedReference {
+    /** Stable ID of the named formula, or display name before symbol linking. */
+    readonly nameId: string;
+    /** Sheet stableId of an explicit qualifier (a raw sheet name when unlinked/unknown). */
+    readonly scope?: string | null;
+    /**
+     * An optional LAMBDA parameter declaration arriving through a transform (`_xlop.b` on xlsx
+     * read) — a PRE-BIND marker only: `bindScopes` claims it into `binding.optional` at a LAMBDA
+     * declaration position, and it means nothing anywhere else. The typed spelling (`[b]`) never
+     * carries it — that parses as a bracketed shape the binder recognizes directly.
+     */
+    readonly optional?: boolean;
+}
+/**
+ * Pre-computed structured reference (table) query.
+ *
+ * @remarks
+ * All column/table identifiers are stable IDs produced by `linkSymbols`, so the query
+ * is valid even after formula rewriting.
+ */
+export interface StructuredReference {
+    /**
+     * Stable ID of the referenced table.
+     *
+     * @remarks
+     * Empty string for implicit self-references such as `[@Col]` or `[#All]`
+     * (no table name prefix in the formula).
+     */
+    tableId: string;
+    /**
+     * Section specifier for the table reference.
+     *
+     * | Value | Meaning |
+     * |-------|---------|
+     * | 0 | Data rows (default when no specifier) |
+     * | 1 | All rows (`#All`) |
+     * | 2 | Header row only (`#Headers`) |
+     * | 3 | Totals row only (`#Totals`) |
+     * | 4 | Headers + Data (`#Headers, #Data`) |
+     * | 5 | Totals + Data (`#Totals, #Data`) |
+     */
+    spec: number;
+    /**
+     * Stable ID of the first (or only) referenced column.
+     * `null` when the whole table section is referenced (no column selector).
+     */
+    columnFromId: string | null;
+    /**
+     * Stable ID of the last column in a column-range reference (e.g. `[Col1]:[Col3]`).
+     * `null` when not a column range.
+     */
+    columnToId: string | null;
+    /**
+     * `true` when the `@` (this-row / implicit intersection) qualifier was present, e.g. `[@Col]`.
+     */
+    isThisRow: boolean;
+    /** The scope id. */
+    scopeId?: string;
+}
+/**
+ * Union of all ReferenceCoord types.
+ *
+ * - `IRange.FixableCoords` — a range reference (or a degenerate 1×1 range: `colStart===colEnd`, which
+ *   PRESERVES the existing shape — a single-cell *range* `A1:A1` stays a range).
+ * - `IRange.FixableCellCoords` — a single *cell* reference (`colIndex`/`rowIndex`). Passing this REPLACES
+ *   the reference's shape: an existing range collapses to a lone cell (`A1:B2` → `A1`). This is how a
+ *   caller says "I mean a cell" without a side-channel flag — the type carries the intent.
+ * - `NamedReference` — a named formula reference (distinguish via `'nameId' in ref`)
+ * - `FormulaError.Ref` — a broken reference (`#REF!`)
+ * - `null` — no reference at this slot
+ */
+export type ReferenceCoords = IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref | null;
+/**
+ * Options for `IFormulaBlock.setReferenceAt`.
+ */
+export interface SetReferenceOptions {
+    /**
+     * The reference's own SHEET is what died, not just the cells it named — so the `#REF!` left
+     * behind is written BARE rather than qualified.
+     *
+     * @remarks
+     * Measured in Excel: a row/area delete leaves the qualified form (`Data!#REF!`), which is the
+     * breadcrumb naming whose cells went; deleting the sheet itself leaves a bare `#REF!`, since
+     * there is no longer a sheet to name. Only the caller knows which of the two it is performing —
+     * `CalcGrid.delete` is walking the precedents OF the grid it is about to drop, while every
+     * shift path is deleting rows within a sheet that survives. It cannot be inferred here: the
+     * sheet is still registered when this rewrite runs, so resolving the qualifier still succeeds.
+     */
+    scopeDeleted?: boolean;
+}
+//# sourceMappingURL=Types.d.ts.map

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

@@ -0,0 +1,3 @@
+export declare const ERROR_NOT_STARTED = "The calculation engine is not started. Call start() first.";
+export declare const ERROR_INITIALIZING = "The calculation engine is initializing. Please wait until it is ready.";
+//# sourceMappingURL=_CalculationMessages.d.ts.map

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

@@ -0,0 +1,2 @@
+export declare function getBuiltInFunctionNames(): Promise<readonly string[]>;
+//# sourceMappingURL=builtInNames.d.ts.map

package/types/src/calculation/compiler/ASTTypes.d.ts

@@ -0,0 +1,180 @@
+import { IRange, IFunction } from '@sheetxl/primitives';
+import { NamedReference } from '../Types';
+import { TokenType } from '../TokenType';
+/**
+ * Represents a node in the Abstract Syntax Tree (AST) of a formula.
+ */
+export interface ASTNode<T extends TokenType = TokenType, V = any> {
+    /**
+     * The type of AST node.
+     */
+    type: T;
+    /**
+     * Identifies the value at the AST node.
+     * (e.g. range, function name, operator, literal value, etc.)
+     */
+    value?: V;
+    /**
+     * A list of inputs (or child nodes) that contribute to the expression.
+     *
+     * @remarks
+     * Leaf nodes are built with an explicit `null` (serialization-stable); `undefined` also occurs.
+     */
+    inputs?: ASTNode[] | null;
+    /**
+     * The pre-resolve function
+     */
+    fn?: Function;
+    /**
+     * Any white space before the node.
+     */
+    wsBefore?: string;
+    /**
+     * Any white space after the node.
+     *
+     * @remarks
+     * This will only be populated for the root node.
+     */
+    wsAfter?: string;
+    /**
+     * Indicates the ids for evaluating this node.
+     * This is used incremental execution (tooltip)
+     *
+     * @see {@link ICalculation.FormulaToken.evalIndex}
+     */
+    evalIndex?: number;
+    /**
+     * For live editing. We may need to add original start/end offsets to align?
+     *
+     * @remarks
+     * If an image does not exist then should be created from the value. For example a cell reference that
+     * has been updated will not have an image.
+     */
+    image?: string;
+    /**
+     * If the node is a reference.
+     */
+    isReference?: boolean;
+    /**
+     * Indicates the index of the references from getReferences()
+     *
+     * @remarks
+     * * Multiple nodes may have the same reference index as these.
+     * * Used to color code references in the editor.
+     */
+    referenceIndex?: number;
+    /**
+     * If the node is a literal.
+     */
+    isLiteral?: boolean;
+    /**
+     * Set by the binder pass on a `named` node that participates in a `LET`/`LAMBDA` scope — the
+     * declaration itself, or a use its scope covers.
+     *
+     * @remarks
+     * A bound node is NOT a name: it mints no symbol, contributes no named-formula edge, is not a
+     * reference, and reads its value from its binding's register slot rather than from the name
+     * resolver. See `CompilerUtils.bindScopes`.
+     */
+    binding?: BindingRef;
+    /**
+     * Set by the binder pass on the `LET`/`LAMBDA` function node that OPENS a scope.
+     *
+     * @remarks
+     * Its presence is what makes the call an engine form rather than a call to the declaration
+     * carriers exported from `formulas` — see `FormulaBlock.evaluateAt`.
+     */
+    binder?: BinderScope;
+    /**
+     * Set by the binder pass on a BOUND use that is the direct argument of `ISOMITTED` — the one
+     * read site allowed to see the OMITTED sentinel raw (design §3.5). Every other frame read
+     * converts the sentinel to blank.
+     */
+    rawFrameRead?: boolean;
+    /**
+     * Set by the compiler on a `named` node INSIDE a `LAMBDA` body: resolved at apply time, not in
+     * the eager reference pass.
+     *
+     * @remarks
+     * Deferral is what permits recursion — a self-recursive named lambda's inner self-reference,
+     * resolved eagerly, would trip the `activeNames` cycle guard while the outer resolution is
+     * still on the stack. The node keeps its precedent slot (over-approximated precedents are the
+     * accepted cost — design §3.4); only the eager VALUE resolution is skipped.
+     */
+    deferredResolve?: boolean;
+    /**
+     * If ast had an error.
+     *
+     * @remarks
+     * This is different than a valid parsed error.
+     */
+    error?: boolean;
+}
+/**
+ * The binder-pass annotation on a `named` node inside a `LET`/`LAMBDA` scope.
+ */
+export interface BindingRef {
+    /**
+     * The binding's slot — an index into `CompiledFormula.bindings`, unique within one formula.
+     */
+    slot: number;
+    /**
+     * `true` on the DECLARATION position (`x` in `LET(x,1,x+1)`), absent on a use.
+     *
+     * @remarks
+     * A declaration is a binding position, not an expression: it evaluates to nothing and is never
+     * executed.
+     */
+    declaration?: boolean;
+    /**
+     * `true` on an OPTIONAL declaration — `[b]` in `LAMBDA(a,[b],a+1)` (application §2.6).
+     *
+     * @remarks
+     * Declarations only, LAMBDA only (optionals are trailing-only and LET refuses the brackets —
+     * {@link CompilerUtils.findBinderViolation | findBinderViolation} enforces both). Apply reads it
+     * through `LambdaParam.optional`: an absent or explicitly-skipped argument binds the OMITTED
+     * sentinel instead of being `#VALUE!`.
+     */
+    optional?: boolean;
+}
+/**
+ * The binder-pass annotation on a `LET`/`LAMBDA` function node.
+ */
+export interface BinderScope {
+    /** Which form opened the scope. */
+    kind: 'let' | 'lambda';
+    /** The slots this call declares, in declaration order. */
+    slots: readonly number[];
+}
+/**
+ * AST callback
+ */
+export interface ASTVisitor {
+    /**
+     * Called once for every node (depth-first).
+     *
+     * @remarks
+     * If a non-void value is returned the node will be replaced with it.
+     * Returning `undefined` leaves the node intact.
+     */
+    (node: ASTNode, parent: ASTNode | undefined, path: ASTNode[]): ASTNode | void;
+}
+export type CellNode = ASTNode<typeof TokenType.Cell, IRange.FixableCellCoords>;
+export interface NamedNode extends ASTNode<typeof TokenType.Named, NamedReference> {
+}
+export interface FunctionNode extends ASTNode<typeof TokenType.Function, any> {
+    /**
+     * Re use this as a cache for built-in static functions.
+     *
+     */
+    cacheFn?: IFunction;
+}
+export type ParenNode = ASTNode<typeof TokenType.Paren>;
+/**
+ * The result of parsing a formula. Contains the root of the AST and any parse errors.
+ */
+export interface ParseResult {
+    root: ASTNode;
+    errors: any[];
+}
+//# sourceMappingURL=ASTTypes.d.ts.map

package/types/src/calculation/compiler/CompilerLocale.d.ts

@@ -0,0 +1,69 @@
+import { FormulaError } from '@sheetxl/primitives';
+import { LanguageTag } from '@sheetxl/utils';
+import { SRSpecifiers } from '../../i18n/LanguagePack';
+import { FormulaSeparators, CANONICAL_SEPARATORS } from './FormulaSeparators';
+export { type FormulaSeparators, CANONICAL_SEPARATORS };
+export { type SRSpecifiers };
+/**
+ * The single locale contract shared by every stage of the formula compiler — the lexer (which builds
+ * its token regexes from the raw word-lists), the parser actions (which map typed text → canonical
+ * AST values), and the emit path (which re-images canonical AST → display text).
+ *
+ * It supersedes the three ad-hoc shapes that said the same thing differently: the lexer's old
+ * `FormulaLexerOptions` string fields, the parser's loose `_booleanTrue`/`_separatorDecimal` plus its
+ * `parseErrorLocal` module global, and `TokenUtils.EmitLocale`. One object is now threaded everywhere.
+ *
+ * Two faces, deliberately:
+ *   • **raw data** (`separators`, `booleanTrue`/`booleanFalse`, `errorLiterals`/`errorRefs`,
+ *     `specifiers`) — consumed by the LEXER, which needs literal strings to compile regex alternates
+ *     (a callback can't build a regex); and
+ *   • **callbacks** (`parseBoolean`/`parseError`/…, `localizeBoolean`/`localizeError`/…) — consumed by
+ *     the PARSER (text → canonical) and the EMIT path (canonical → text).
+ *
+ * Storage stays canonical: every `parse*` ALWAYS accepts the canonical English spelling in addition to
+ * the localized one, and `localize*` for {@link CANONICAL_LOCALE} is the identity (English) form.
+ */
+export interface CompilerLocale {
+    /** The four formula separators (function/column/row/decimal). */
+    separators: FormulaSeparators;
+    /** The `TRUE` literal in this locale (canonical `TRUE` is always lexed too). */
+    booleanTrue: string;
+    /** The `FALSE` literal in this locale (canonical `FALSE` is always lexed too). */
+    booleanFalse: string;
+    /** Localized LITERAL error labels (`#WERT!`, …) to ADD alongside the always-lexed canonical set. */
+    errorLiterals: string[];
+    /** Localized REFERENCE error labels (`#BEZUG!`) — parse where a reference is expected. */
+    errorRefs: string[];
+    /** Localized SR specifier words; absent for a locale that does not translate them. */
+    specifiers?: SRSpecifiers;
+    /** `WAHR`/`TRUE` → `true`, `FALSCH`/`FALSE` → `false`, anything else → `undefined`. */
+    parseBoolean(image: string): boolean | undefined;
+    /** A typed error label (canonical or localized) → its canonical {@link FormulaError}, else `undefined`. */
+    parseError(image: string): FormulaError.Known | undefined;
+    /** A typed SR specifier (`[#Alle]`/`#Alle`/`All`) → its canonical key (`All`), else `undefined`. */
+    parseSpecifier?(image: string): string | undefined;
+    /** `true`/`false` → the locale's `WAHR`/`FALSCH`. */
+    localizeBoolean(value: boolean): string;
+    /** A canonical error → its localized label (`#WERT!`); canonical returns the English label. */
+    localizeError(error: FormulaError.Known): string;
+    /** A canonical SR specifier key (`All`) → its localized word (`Alle`); canonical returns English. */
+    localizeSpecifier?(canonical: string): string;
+}
+/**
+ * The canonical (storage / identity) locale: canonical separators, English `TRUE`/`FALSE`, no localized
+ * error or specifier alternates, and every `parse*`/`localize*` is the English identity. This is the
+ * default for the calc path and for any storage/API text, which is always canonical.
+ */
+export declare const CANONICAL_LOCALE: CompilerLocale;
+/**
+ * Build the {@link CompilerLocale} for a set of `separators` (Plane 1, from the workbook locale) and
+ * the active-or-`tag` spreadsheet-language pack (Plane 3). The pack is read ONCE here; the raw fields
+ * feed the lexer and the callbacks delegate to the tag-bound {@link LanguagePack} helpers, so this is
+ * the one place that knows how a pack maps onto the compiler. Both the editing compiler (parse) and
+ * the display emit path call it.
+ *
+ * @param separators The resolved formula separators. Defaults to canonical.
+ * @param tag The language tag, or `undefined` for the active language.
+ */
+export declare function createCompilerLocale(separators?: FormulaSeparators, tag?: LanguageTag): CompilerLocale;
+//# sourceMappingURL=CompilerLocale.d.ts.map