@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/calculation/formula/LazyValue.d.ts

@@ -0,0 +1,96 @@
+import { ILazy } from '@sheetxl/primitives';
+import { ASTNode } from '../compiler/ASTTypes';
+import { IFormulaBlock } from './IFormulaBlock';
+/**
+ * The handle a `Lazy` parameter receives — one argument's subtree, anchored at the calling cell,
+ * that the engine has either not evaluated yet or has evaluated already.
+ *
+ * @remarks
+ * CALCULATION-PRIVATE as a class; the INTERFACE (`ILazy`) is public, because a function author
+ * declares the slot and may read it. The sibling of `LambdaValue`, and the same idea: "evaluate
+ * this piece of the formula later, anchored at this cell". The difference is only what it closes
+ * over — an argument's subtree rather than a lambda's body — and that this one takes no
+ * parameters, so forcing it is a call with an empty argument list.
+ *
+ * A body does one of two things with it, and the engine answers for both:
+ *
+ * - **returns it unread** — the engine sees its own handle come back as the call's result and
+ *   evaluates the subtree then, on its normal path, so an ASYNC subtree is fine there.
+ * - **forces it** with {@link getValue} — which happens mid-body, where the engine has no way to
+ *   wait, so a subtree that answers a promise is `#VALUE!` rather than a wrong answer.
+ *
+ * A DEFERRED handle carries the block, the node and the registers to evaluate against; a
+ * PRE-FILLED one carries the value alone ({@link LazyValue.of}) and is what the engine hands over
+ * whenever it declines to defer — an empty or literal argument, or a call that is about to lift.
+ * The author cannot tell them apart, which is the point: laziness is the engine's to grant.
+ *
+ * ### Lifetime, and why the deferred handles are pooled
+ *
+ * A handle lives exactly as long as the call it was built for, and that life is SYNCHRONOUS: the
+ * body either forces it in place or returns it unread, and the executor forces a returned one
+ * before it moves on. Nothing retains a handle past that point — every value-layer boundary
+ * (coercion, the operators, a range's typed read, a cell's final value) recognizes and refuses
+ * one. So a deferred handle is not allocated per call; it is taken from a pool indexed by call
+ * DEPTH and argument position ({@link deferred}) and re-pointed at the next call's subtree. Depth,
+ * not node: the same `IF` node re-enters at a deeper level under recursion, and a nested call
+ * inside a body (a forced arm that itself calls `IF`) must not re-point the handles the enclosing
+ * body is still holding. The executor brackets each lazy call with {@link enter} / {@link leave},
+ * which is what makes the nested call land one level deeper.
+ *
+ * The async case is safe under this: {@link _force} stores the promise as the value, and the
+ * executor's chain holds the promise, not the handle.
+ */
+export declare class LazyValue implements ILazy {
+    /** @inheritdoc ILazy.isLazy */
+    readonly isLazy: true;
+    /** The forced value, once {@link _force} has run. */
+    private _value;
+    private _forced;
+    /** The block whose formula the subtree belongs to, or `null` when pre-filled. */
+    private _owner;
+    /** The argument's subtree root. */
+    private _node;
+    /** The register file to evaluate against — the block's own, or a lambda activation's. */
+    private _regs;
+    /** The lambda-parameter frame in scope, when the call sits inside a lambda body. */
+    private _frame;
+    /** The anchor the owner is being evaluated at. */
+    private _row;
+    private _col;
+    private constructor();
+    /**
+     * One row of handles per call depth, one handle per argument position — see the class remarks.
+     * Grows to the deepest nesting and widest lazy call seen, and is never trimmed.
+     */
+    private static readonly _pool;
+    private static _depth;
+    /**
+     * Opens the handle row for a lazy call about to be filled. Answers the depth to pass to
+     * {@link deferred} and back to {@link leave}, in a `finally`.
+     */
+    static enter(): number;
+    /** Closes the row {@link enter} opened. Restores rather than decrements, so a throw cannot skew it. */
+    static leave(depth: number): void;
+    /**
+     * A handle over a subtree the engine has NOT evaluated — the pooled handle at `(depth, slot)`,
+     * re-pointed. Valid until {@link leave} closes the depth; the caller must not keep it past that.
+     */
+    static deferred(depth: number, slot: number, owner: IFormulaBlock, node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LazyValue;
+    /** A handle over a value the engine has ALREADY computed — the decline path. */
+    static of(value: any): LazyValue;
+    /**
+     * Re-points a filled handle at another value. The lift's per-element reset: one handle per lazy
+     * slot for the whole spill, pointed at each sampled member in turn, instead of {@link of} per
+     * element. Only for a handle that was never deferred.
+     */
+    _fill(value: any): void;
+    /**
+     * Evaluates the subtree, at most once. The ENGINE's entry point: a promise here is an async
+     * subtree returned unread, which the caller chains like any other async node result.
+     */
+    _force(): any;
+    /** @inheritdoc ILazy.getValue */
+    getValue(): any;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=LazyValue.d.ts.map

package/types/src/calculation/formula/TokenUtils.d.ts

@@ -1,7 +1,14 @@
 import { FormulaError, IRange } from '@sheetxl/primitives';
 import { ISymbolRegistry } from '../symbol';
 import { ICalculation } from '../ICalculation';
+import { ReferenceCoords } from '../Types';
 import { CompilerLocale } from '../compiler/CompilerLocale';
+/**
+ * A block's references made absolute at a cell: what `IFormulaBlockView.getReferencesAt` answers.
+ * Cells and ranges (a resolved table reference among them) are placed at the cell; a name and a
+ * hole pass through.
+ */
+export declare function absoluteReferences(references: readonly ReferenceCoords[], row: number, column: number): ReferenceCoords[];
 /**
  * Resolves all stable IDs in a token array to their display names.
  *
@@ -14,7 +21,24 @@ import { CompilerLocale } from '../compiler/CompilerLocale';
  * When `symbols` is absent (no registry was used at compile time) the tokens
  * already hold display names and are returned as-is.
  */
-export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean): ICalculation.FormulaToken[];
+export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean, 
+/**
+ * Re-image for a READER rather than for storage. Only an external book reads differently: stored
+ * it is `[n]Sheet1` (a position), displayed it is the book's own spelling, and the book half is
+ * split into its own {@link TokenType.ExternalReference} token so an editor can color or elide it
+ * (DESIGN-EXTERNAL-LINKS §4B).
+ */
+display?: boolean, 
+/**
+ * The formula's cell (`scope` is its sheet's name or id), for display only. A single-column
+ * reference to the table holding it (`Table1[Qty]`, `Table1[@Qty]`) drops the table name, as Excel
+ * shows it; every other structured reference keeps it.
+ */
+home?: {
+    scope: string | null;
+    rowIndex: number;
+    colIndex: number;
+} | null): ICalculation.FormulaToken[];
 /**
  * Token Utils used by FormulaBlock
  */

package/types/src/calculation/formula/index.d.ts

@@ -1,4 +1,5 @@
 export * from './Formula';
 export * from './IFormulaBlock';
+export * from './FormulaRecordView';
 export * from './FormulaBlock';
 //# sourceMappingURL=index.d.ts.map

package/types/src/calculation/functions/FunctionDeclarations.d.ts

@@ -0,0 +1,35 @@
+import { IFunction } from '@sheetxl/primitives';
+/**
+ * The built-in functions' declarations, as data: what each function's slots and return are, with
+ * no calculation running and no implementation loaded.
+ *
+ * @remarks
+ * A file format decides how to spell a formula from what a function's slots accept — whether a
+ * range in a slot is taken whole or intersected, for one. That question has an answer before any
+ * engine starts, and the same answer wherever it is asked, so it is read here rather than from a
+ * calculation's live function registry. The data is the declaration the compiler compiles from.
+ *
+ * The table loads with the formula parser: await `FormulaText.load()` first. Until then every
+ * name is unknown.
+ */
+export declare namespace FunctionDeclarations {
+    /** A declared function. */
+    interface Declared {
+        /** The canonical name. */
+        getName(): string;
+        /** The declaration: parameters and return. */
+        getDeclaration(): IFunction.IDeclaration;
+        /** Whether the function is a built-in. Always `true` here; the shape matches a live function. */
+        isBuiltIn(): boolean;
+    }
+    /**
+     * Returns a built-in function's declaration, or `null` when no built-in has that name or the
+     * table is not loaded.
+     *
+     * @param name The canonical (English) name. Not case sensitive.
+     */
+    function get(name: string): Declared | null;
+    /** Whether a built-in function has this canonical name. Not case sensitive. */
+    function has(name: string): boolean;
+}
+//# sourceMappingURL=FunctionDeclarations.d.ts.map

package/types/src/calculation/functions/Operators.d.ts

@@ -18,6 +18,14 @@ export declare const Infix: {
     '>=': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
     '<=': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
 };
+/**
+ * `+` and `-` as the root of a formula body, where a cancelling result snaps to 0 (see the top of
+ * this file). Elementwise over an array, against each element's own left operand.
+ */
+export declare const RootInfix: {
+    '+': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    '-': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+};
 export declare const Prefix: {
     '-': (context: IFormulaContext, value: any) => any;
     '+': (context: IFormulaContext, value: any) => any;

package/types/src/calculation/functions/expandDeclaration.d.ts

@@ -0,0 +1,15 @@
+import { IFunction } from '@sheetxl/primitives';
+import { MinifiedDeclaration } from '@sheetxl/scripting';
+/**
+ * Expands one minified built-in declaration into its JSON, with the ids of the enums its
+ * parameters use.
+ *
+ * @remarks
+ * Pure: what a declaration says about its slots, with no implementation attached. The function
+ * registry binds the result to an implementation; `FunctionDeclarations` reads it as data.
+ */
+export declare function expandDeclaration(builtInName: string, builtIn: MinifiedDeclaration, expandEnum: (id: string) => IFunction.EnumJSON | undefined): {
+    decl: IFunction.DeclarationJSON;
+    enumIds: string[];
+};
+//# sourceMappingURL=expandDeclaration.d.ts.map

package/types/src/calculation/functions/initializeFunctions.d.ts

@@ -1,5 +1,5 @@
 import { IFunction, IFormulaContext } from '@sheetxl/primitives';
-import { Implementations, MinifiedDeclaration, DynamicDescriptors, FunctionProvider } from '@sheetxl/scripting';
+import { Implementations, MinifiedDeclaration, DynamicDescriptors, FunctionProvider, MinifiedEnums } from '@sheetxl/scripting';
 /**
  * Builds the function map for a calculation: core (open-source) functions, then enterprise
  * (default-on), then any caller-supplied {@link FunctionProvider}s. Later binders override earlier
@@ -15,8 +15,9 @@ export declare function initializeFunctions(getContext: () => IFormulaContext, p
  * @param declarations the built-in declarations
  * @param getDynamicDescriptors an optional function to get the dynamic descriptor module
  * @param defaultCategory the default category to use if not specified in the declaration
+ * @param enums the module's enums, which its parameters reference by id
  */
 export declare const bindDeclarations: (mapFunctions: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, // TODO make this dynamic
 declarations: MinifiedDeclaration, // TODO make this dynamic
-getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string) => void;
+getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string, enums?: MinifiedEnums) => void;
 //# sourceMappingURL=initializeFunctions.d.ts.map