@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/calculation/state/IContextContainer.d.ts

@@ -0,0 +1,320 @@
+import { Scalar, IRange, IRuntime, IFormulaContext } from '@sheetxl/primitives';
+import { ISparseGrid, ISpatialMap, ISpatialMap3D, ISpatialQuery } from '../../collections';
+import { ISymbolRegistry } from '../symbol';
+import { IFormulaBlock } from '../formula';
+import { PrecedentSpatialValue, PrecedentKind, FormulaSpatialValue } from '../spatial';
+import { ICalcGrid } from '../grid';
+import { ICalculation } from '../ICalculation';
+import { CalcNode } from './CalcNode';
+import { CalcScope } from './CalcScope';
+/**
+ * Interface to allow grids to interact with calculation container.
+ */
+export interface IContextContainer {
+    /**
+     * The Formula compiler for parsing formulas.
+     *
+     * @remarks
+     * This is passed in so that the Calculation engine can lazy load
+     *
+     * @param editing If `true` the block is compiled with the `'editing'` compiler profile — the
+     * expression is preserved exactly as typed and a parse failure gets maximum recovery (see
+     * `FormulaCompilerProfile`). Used by `createFormula` (the formula editor); the default
+     * (`'calc'`) profile normalizes and spends nothing on recovery.
+     * @param formulaTransform A structural transform applied to the parsed tree (pre-link) — the
+     * READ half of the dialect hook, supplied only by format loads (see `ICalcGrid.fromJSON`).
+     */
+    createFormulaBlock(gridId: string, context: IFormulaContext, expression: string, rowIndex: number, colIndex: number, editing?: boolean, formulaTransform?: ICalculation.FormulaTransform): IFormulaBlock;
+    /**
+     * Returns the symbol registry for name → stableId resolution.
+     */
+    getSymbols(): ISymbolRegistry;
+    /**
+     * Resolves a scope id to its sheet display name.
+     *
+     * @param scope The scope to resolve.
+     * @returns The sheet name, or `undefined` if the scope is unknown.
+     */
+    resolveScope(scope: string): string | undefined;
+    getSheetIndex?: (sheetName?: string) => number;
+    getSheetCount?: () => number;
+    getScope(): CalcScope;
+    getRuntime(): IRuntime;
+    /**
+     * Returns the current datetime in milliseconds.
+     */
+    getNow(): number;
+    /**
+     * Returns a map of volatile calcs.
+     *
+     * @remarks
+     * Returns `null` if the container does not track volatiles.
+     */
+    getVolatiles(): Set<CalcNode> | null;
+    /**
+     * Returns a 3D formulas.
+     */
+    getFormulas(): ISpatialMap3D<FormulaSpatialValue>;
+    /**
+     * Set the formula spatial.
+     *
+     * @remarks
+     * This is used by Grid for shifting
+     */
+    setFormulas(spatial: ISpatialMap3D<FormulaSpatialValue>): void;
+    /**
+     * Returns a 3D precedents.
+     */
+    getPrecedents(): ISpatialMap3D<PrecedentSpatialValue>;
+    /**
+     * Update the precedent spatial.
+     *
+     * @remarks
+     * This is used by Grid for shifting
+     */
+    setPrecedents(spatial: ISpatialMap3D<PrecedentSpatialValue>): void;
+    /**
+     * Returns the current block-level dynamic precedent map, keyed by FormulaSpatialValue.
+     *
+     * @remarks
+     * At most one entry per (block, {@link PrecedentKind}) — so at most two, because one block can be
+     * BOTH kinds at once: `=INDIRECT("A1:A3")` reads a range it discovers at runtime AND spills over
+     * one it writes. Those two rectangles have nothing to do with each other, and the single slot this
+     * map used to hold forced them into a bounding box that described neither.
+     *
+     * Every path that replaces a block evicts through this map, so it must list ALL of the block's
+     * entries: one left behind points at a dead block, whose CalcNodes the dirty walk then collects
+     * alongside the live replacement's, pushing one cell twice in the value builder
+     * (`OutOfOrderError`).
+     */
+    getDynamics(): Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
+    /**
+     * Replaces the dynamic precedent map (copy-on-write commit).
+     */
+    setDynamics(map: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>): void;
+    /**
+     * Returns the grid for a given gridId. This is used to get other grids when calculating.
+     */
+    getGrid(gridId: string): ICalcGrid | null;
+    /**
+     * Upserts a grid into the container's registry (create or replace), keyed by its `gridId`.
+     *
+     * @remarks
+     * Called in two situations:
+     * 1. **Construction** — a newly created `CalcGrid` self-registers so it is reachable via
+     *    {@link getGrid} / {@link getGridValues}.
+     * 2. **Clone** — the cloned grid re-registers under the same `gridId`, atomically replacing
+     *    the previous iteration in the registry and enabling swap-in-place semantics.
+     *
+     * @param calcGrid The grid instance to register.
+     */
+    registerGrid(calcGrid: ICalcGrid): void;
+    /**
+     * Removes the grid with the given `gridId` from the container's registry.
+     *
+     * @remarks
+     * Called by {@link ICalcGrid.delete} during sheet teardown to release the grid and allow
+     * it to be garbage-collected. Any pending listeners attached to the grid should be cleaned
+     * up before removal.
+     *
+     * @param gridId The stable ID of the grid to remove.
+     */
+    unregisterGrid(gridId: string): void;
+    /**
+     * Marks a grid as dirty for calculation.
+     *
+     * @param dirtyRegions The regions that are dirty. If not provided the entire grid is considered dirty.
+     *
+     * @remarks
+     * For performance these are mutable.
+     */
+    markDirty(dirtyRegions: ISpatialMap.Entry[]): void;
+    /**
+     * Returns the dirty spatial query for a given gridId.
+     */
+    getDirtyGrid(gridId: string): ISpatialQuery;
+    /**
+     * When calcing from a grid context.
+     *
+     * @param gridId The grid id
+     * @param options Optional calculation options.
+     */
+    calculateGrid(gridId: string, options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * Returns the monotonically incrementing generation counter for the calculation engine.
+     *
+     * The counter is incremented by 1 before each calculation pass. It is used to:
+     * - Distinguish spill entries produced in the current cycle from stale ones (prior cycles),
+     *   so spill notifications are only emitted for the current pass.
+     * - Stamp `Results.cycleId` when inputs are set during a shift or grid update.
+     * - Finalize incremental commits via `update.done(cycleId, …)`.
+     *
+     * @remarks
+     * Deliberately NOT transactional state, and never serialized (a load restarts at 0). It stamps
+     * `CalcNode`s and `SpillEntry`s — plain mutable graph objects that undo/redo does not rewind —
+     * so the counter must not rewind either. A rewindable copy would re-issue an id that live nodes
+     * still carry, and the "already visited this cycle" guards would skip their re-evaluation.
+     */
+    getCycleId(): number;
+    /**
+     * Returns the committed or in-progress scalar values for the given grid.
+     *
+     * During an active calculation pass, returns the in-progress values from the current
+     * {@link ICalcGrid.IncrementalUpdates} (reflecting cells already calculated this cycle).
+     * Outside a calculation pass, returns the last committed values from the grid.
+     *
+     * Use this for read-only value lookups (e.g. cross-sheet ref resolution). Prefer
+     * {@link getIncrementalUpdates} when you need to write values or access the full update state.
+     *
+     * @param gridId The stable ID of the grid to read.
+     * @returns The sparse grid of scalar values, or `null` if the grid does not exist.
+     */
+    getGridValues(gridId: string): ISparseGrid<Scalar>;
+    /**
+     * Returns the in-progress {@link ICalcGrid.IncrementalUpdates} record for the given grid
+     * during an active calculation pass.
+     *
+     * If the grid has not yet been initialized for the current pass, lazily calls
+     * {@link ICalcGrid.beginUpdates} and registers the record. This is the primary write surface
+     * during calculation: use it to write values, record spills, accumulate formats, and drive
+     * commit notifications.
+     *
+     * Returns `null` outside of an active calculation pass.
+     *
+     * @param gridId The stable ID of the grid.
+     * @returns The incremental update record for this pass, or `null` if no pass is active.
+     */
+    getIncrementalUpdates(gridId: string): ICalcGrid.IncrementalUpdates | null;
+    /**
+     * Registers a dynamic (runtime-discovered) precedent for the given node during an active
+     * calc cycle. Called by CalcExecutor after spill detection ({@link PrecedentKind.Spill}) and by
+     * CalculationContext for INDIRECT/OFFSET-style refs ({@link PrecedentKind.Reference}).
+     * Dispatches to the per-cycle `addDynamic` closure; no-op outside of `_calculate`.
+     *
+     * @remarks
+     * Used during calculation and contains transient precedents.
+     *
+     * `kind` is what tells the two callers apart afterwards. They pass geometrically opposite ranges —
+     * a spill's own output versus a range read on some other grid — and nothing downstream can
+     * recover which is which from the coords.
+     */
+    addDynamicPrecedent(calcNode: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+    /**
+     * Queues an action to run at the engine's next safe point, and schedules that point.
+     *
+     * @remarks
+     * Safe means two things, and they are why this exists rather than calling inline: the engine can
+     * actually do the work (the compiler is loaded, grids are populated), and the synchronous work
+     * that queued the action has finished — a `setInputs` run re-entrantly during an active commit is
+     * what produced the intermittent `OutOfOrderError` in the value builder.
+     *
+     * No guard is required. Queuing schedules its own drain, so an action queued here always runs:
+     * while `Starting` it is held for `start()`'s drain, inside a drain it joins the pass already
+     * running, and on a settled engine a microtask drain is posted for it.
+     *
+     * It did require one, and was called `whenStarting` for that reason — the queue was pumped only
+     * as a side effect of `start`/`ready`/`calculate`, so an action queued on a settled engine waited
+     * for a calculation that might never come and was dropped rather than delayed. Callers written
+     * against that rule (guarding on {@link isLoading} or a `Starting` status) remain correct; the
+     * guard is now redundant, not wrong.
+     *
+     * What a caller does owe: the action must be safe to run at an arbitrary microtask boundary, not
+     * only from inside a calculation.
+     *
+     * Used by surfaces (e.g. `CalcGrid`) to defer writes that arrive while the engine is still
+     * populating. That drain happens inline at the tail of `Calculation.start()`, so `await start()`
+     * still resolves only after queued work completes.
+     */
+    whenSafe(action: () => Promise<unknown>): void;
+    /**
+     * `true` while the engine is either `Starting` or inside a pending-action drain — at any drain
+     * site, not only the load drain in `Calculation.start()`.
+     *
+     * @remarks
+     * A grid must NOT trigger a calc while this is `true`: a formula could evaluate against a sibling
+     * sheet whose values have not been drained yet (e.g. a volatile/cross-sheet formula reading an
+     * empty cell). Defer such calcs via {@link whenSafe} so they run after the full drain.
+     *
+     * This used to be set by the load drain alone, so during a drain ahead of a calculation it read
+     * `false` and a grid populating there took the inline branch — a calc re-entered from inside a
+     * drain, the exact shape the deferral exists to avoid.
+     */
+    isLoading(): boolean;
+    /**
+     * Recompiles every formula that references `nameId`, directly or through another name.
+     *
+     * @remarks
+     * Brute-force all3D scan over `formulaSpatial`, matched via `IFormulaBlock.getNamedIds` against
+     * `nameId` and {@link getNamedDependentNames}. Called after a named formula is wired or deleted
+     * so dependents pick up the change. A recompile, not a dirty-mark, on purpose: a definition
+     * change requires dependents to re-derive their precedents (`setInputs`), which `markDirty` does
+     * not do. Where a re-evaluation suffices, use {@link invalidateNamed} instead.
+     */
+    recompileNamed(nameId: string): void;
+    /**
+     * Marks every formula that references `nameId` — directly or through another name — dirty, so it
+     * re-evaluates against the name's current definition.
+     *
+     * @remarks
+     * The dirty-mark half of {@link recompileNamed}, and the right one whenever nothing about the
+     * dependents themselves changed — only what the name yields. Names are applied at EVAL, never
+     * inlined at compile, so a re-evaluation is all a dependent needs; that includes healing one
+     * sitting at `#NAME?` from a since-undone delete.
+     *
+     * Preferred over {@link recompileNamed} where it suffices: recompiling re-images each dependent's
+     * text and re-parses it, which re-resolves its symbols — work that can fail on a formula that was
+     * evaluating perfectly well off an id-bound edge.
+     *
+     * Its caller is a revert. Reverting restores the name's body (it is versioned state) but marks
+     * nothing dirty — derived values are a cache the store does not carry.
+     */
+    invalidateNamed(nameId: string): void;
+    /**
+     * The formula BLOCKS that directly reference `nameId`, in calc currency (`scope` = the block's
+     * grid id).
+     *
+     * @remarks
+     * The read half of the `getNamedIds` bookkeeping {@link recompileNamed} already writes against,
+     * and the reason it is here rather than a scan at each call site: a name's dependents are not in
+     * `precedentSpatial`. A name is applied at EVAL, never inlined at compile, so a reference to one
+     * registers no precedent range — the edge exists only as the nameId list each compiled block
+     * carries. Answering per name therefore means an `all3D` sweep of every formula in the book, and
+     * a roster asking it of thirty names would sweep thirty times.
+     *
+     * So the sweep is done ONCE and bucketed by nameId, memoized against the identity of the formula
+     * spatial that produced it. That map is copy-on-write — every insert, remove, shift and recompile
+     * clones it before mutating — so identity IS the version, and a stale bucket set is not
+     * expressible. Names number in the tens and only formulas that mention one are held, so the index
+     * is small; the first query after any formula edit pays for it, and the rest are map lookups.
+     *
+     * The whole block, not a windowed part of it: a name means the same symbol in every cell of a
+     * block, so there is no sub-window to narrow to (unlike a cell precedent, where a relative
+     * reference makes only part of the block depend on the queried cell).
+     *
+     * Blocks on VIRTUAL grids come back too — a name referencing this one. Callers that want cells
+     * resolve the scope and drop what is not a sheet.
+     */
+    getNamedDependents(nameId: string): readonly IRange.Coords[];
+    /**
+     * The ids of every NAME that references `nameId`, transitively. Excludes `nameId` itself unless
+     * a cycle genuinely leads back to it.
+     *
+     * @remarks
+     * The symbol graph's transitive closure, and the one thing the cell graph cannot supply. A name
+     * applies at EVAL and is never inlined, so `=Doubled` registers no precedent range on `Doubled`
+     * and none on `Base` behind it: with `Doubled = Base*2`, the only edge from `Base` to the cells
+     * reading `Doubled` runs `Base → Doubled → those cells`, and its first leg exists solely as the
+     * nameId lists {@link getNamedDependents} indexes.
+     *
+     * So a change to a name reaches `{nameId} ∪ getNamedDependentNames(nameId)` before the ordinary
+     * dependency graph takes over — one hop reaches only `=Base` cells and leaves `=Doubled` cells
+     * holding a stale value with no precedent edge to correct them.
+     *
+     * Walks {@link getNamedDependents}, taking the hop again on every block that lands on a virtual
+     * grid (that grid IS the id of the name whose body it is), and expands each id once so a cycle
+     * (`A = B+1`, `B = A+1`) terminates. Built off the same memoized index, so this costs map
+     * lookups, not a sweep per name.
+     */
+    getNamedDependentNames(nameId: string): ReadonlySet<string>;
+}
+//# sourceMappingURL=IContextContainer.d.ts.map

package/types/src/calculation/state/IContextContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContextContainer.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/state/IContextContainer.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,6 @@
+export * from './CalcNode';
+export * from './CalcScope';
+export * from './CalcState';
+export * from './IContextContainer';
+export * from './CalculationContext';
+//# sourceMappingURL=index.d.ts.map

package/types/src/calculation/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/state/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/types/src/calculation/symbol/FunctionSymbolProvider.d.ts

@@ -0,0 +1,44 @@
+import { IFunctionCollection } from '../../scripting';
+import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
+/**
+ * The canonical name behind a (possibly localized) typed function name, or `undefined` when the
+ * active pack does not localize it.
+ *
+ * @remarks
+ * Exported for `CalculationContext.getFunction`, so the COMPILE-side resolver answers the same
+ * names `bind` below accepts — the static passes (`rewriteUnknownFunctionCalls`, arity, the slot
+ * checks) consult that resolver, and a localized spelling they cannot see is a formula they
+ * misclassify (a `SUMME(…)` call re-shaped into a name application was the observed failure).
+ */
+export declare function localizedFunctionToCanonical(displayName: string): string | undefined;
+/**
+ * Provider for function symbols.
+ *
+ * @remarks
+ * The stableId for a known function is its canonical registered name (e.g. `"SUM"`).
+ * For unknown names (unregistered UDFs), a dead UUID is allocated and stored so that
+ * `bind` never returns `null`. When the UDF is later registered it will be found under
+ * its canonical name — a formula compiled before registration will need a recalc cycle.
+ *
+ * **Spreadsheet language (I18N-DESIGN.md Plane 3).** Formulas are STORED canonical
+ * (English) — localization happens only at this bind/resolve boundary, governed by the
+ * active language pack's `functions` map (user/view-scoped, like Excel):
+ * - `bind` accepts the localized name (`SUMME` → `SUM`) AND always the canonical English
+ *   (paste/round-trip never breaks; a collision prefers the localized meaning).
+ * - `resolve` displays the localized name; handles read the pack at `toString()` time,
+ *   so an already-resolved handle tracks a language switch.
+ * - Custom/UDF names are naturally untouched (packs only carry built-in names — Excel
+ *   does not localize UDF names either).
+ * `ctx.locale` (see `FunctionCtx`) is reserved for a future per-view override; the
+ * active language service is the authority today (same rule as command chrome).
+ */
+export declare class FunctionSymbolProvider implements ISymbolProvider {
+    private readonly _getCollection;
+    private readonly _deadIds;
+    constructor(getCollection: () => IFunctionCollection | undefined);
+    /** @inheritdoc ISymbolProvider.bind */
+    bind(displayName: string, _ctx: Record<string, unknown>): string;
+    /** @inheritdoc ISymbolProvider.resolve */
+    resolve(stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
+//# sourceMappingURL=FunctionSymbolProvider.d.ts.map

package/types/src/calculation/symbol/FunctionSymbolProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionSymbolProvider.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/symbol/FunctionSymbolProvider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA2B5E;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAE5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;IACvE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,aAAa,EAAE,MAAM,mBAAmB,GAAG,SAAS;IAIhE,uCAAuC;IACvC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAqBhE,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,GAAG,IAAI;CAgB9E"}

package/types/src/calculation/symbol/ISymbolRegistry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The type of symbol being resolved.
+ */
+export declare const SymbolType: {
+    readonly Sheet: "sheet";
+    readonly NamedFormula: "namedFormula";
+    readonly Table: "table";
+    readonly TableColumn: "tableColumn";
+    readonly Function: "function";
+};
+export type SymbolType = typeof SymbolType[keyof typeof SymbolType];
+export interface SheetCtx {
+}
+export interface NamedFormulaCtx {
+    /** The stableId of the sheet that owns the formula scope, if any. */
+    sheetId?: string;
+}
+export interface TableCtx {
+    /** Optional sheet scope — future-proofing; Excel enforces global uniqueness. */
+    sheetId?: string;
+}
+export interface ColumnCtx {
+    /** The stableId of the table that owns this column. Required. */
+    tableId: string;
+}
+export interface FunctionCtx {
+    /** BCP 47 locale tag (e.g. 'en', 'fr', 'de'). Defaults to English. */
+    locale?: string;
+    /**
+     * Resolve to the CANONICAL (English) name, suppressing display localization — the
+     * persistence/serialization form (files, undo snapshots, internal re-parses are always
+     * English; localization is a display/input boundary concern — I18N-DESIGN.md Plane 3).
+     */
+    canonical?: boolean;
+}
+/**
+ * A handle to a resolved symbol, returned by {@link ISymbolRegistry.resolve}.
+ *
+ * @remarks
+ * `toString()` returns the display name appropriate for the given context.
+ * Providers may extend this with type-specific fields.
+ */
+export interface SymbolHandle {
+    /** The stable, rename-proof identifier stored in the AST. */
+    readonly stableId: string;
+    /** Returns the current display name for this symbol. */
+    toString(): string;
+}
+/** A type-specific resolver registered with {@link ISymbolRegistry}. */
+export interface ISymbolProvider {
+    /**
+     * Forward lookup: display name → stableId.
+     *
+     * @remarks
+     * If the provider returns `null`, it means the ids is unresolvable.
+     */
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
+    /**
+     * Reverse lookup: stableId → {@link SymbolHandle}.
+     *
+     * @returns A handle whose `toString()` yields the current display name,
+     *          or `null` if the entity has been permanently deleted.
+     */
+    resolve(stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
+/**
+ * Central controller that delegates symbol resolution to per-type providers.
+ *
+ * @remarks
+ * Held by `Calculation` and accessible via `IContextContainer.getSymbols()`.
+ */
+export interface ISymbolRegistry {
+    /**
+     * Registers a provider for the given symbol type.
+     * Replaces any previously registered provider for that type.
+     */
+    registerProvider(type: SymbolType, provider: ISymbolProvider): void;
+    /**
+     * Forward lookup: converts a display name to a stableId.
+     *
+     * @returns The stableId, or `null` if no provider is registered for `type`
+     *          or the provider explicitly rejects the name.
+     */
+    bind(type: SymbolType, displayName: string, ctx?: Record<string, unknown>): string | null;
+    /**
+     * Reverse lookup: converts a stableId to a {@link SymbolHandle}.
+     *
+     * @returns The handle (with `toString()` for display), or `null` if the
+     *          entity no longer exists or no provider is registered for `type`.
+     */
+    resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
+//# sourceMappingURL=ISymbolRegistry.d.ts.map

package/types/src/calculation/symbol/ISymbolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISymbolRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/symbol/ISymbolRegistry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAOpE,MAAM,WAAW,QAAQ;CAExB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,IAAI,MAAM,CAAC;CACpB;AAMD,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IAExE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,GAAG,IAAI,CAAC;CAC/E;AAMD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAEpE;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IAE1F;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,GAAG,IAAI,CAAC;CACjG"}

package/types/src/calculation/symbol/IndirectSymbolProvider.d.ts

@@ -0,0 +1,144 @@
+import { INamed } from '../../named';
+import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
+/**
+ * A stable proxy that holds the fake UUID and a lazily-filled reference to the real item.
+ *
+ * @remarks
+ * `fakeId` is generated once and never changes. `_real` is null until the real item
+ * arrives in the collection, then set via `reconcile()`.
+ *
+ * @typeParam T - Any type that satisfies {@link INamed.INamedValue} (`getId` + `getName`).
+ *   For named formulas use `ICalculation.INamedFormula`; for tables use `INamed<ITable>`.
+ */
+export declare class IndirectProxy<T extends INamed.INamedValue = INamed.INamedValue> {
+    readonly fakeId: string;
+    lowerName: string;
+    displayName: string;
+    /**
+     * The scope of the item this proxy IS — `null` for a global one.
+     *
+     * @remarks
+     * Half of the identity, not decoration. Twelve sheet-scoped `MonthName`s are twelve items and
+     * must be twelve proxies; keying on the name alone gave them one shared virtual grid, so each
+     * definition overwrote the last and all twelve reported the final one's expression.
+     */
+    lowerScope: string | null;
+    /**
+     * The scope the FIRST reference was compiled from, kept for re-resolution — see
+     * {@link IndirectSymbolProvider.reconcile}. Distinct from {@link lowerScope}: a formula on
+     * `January` referring to a global name has `viewScope='january'` and `lowerScope=null`.
+     */
+    viewScope: string | null;
+    _real: T | null;
+    constructor(lowerName: string, displayName: string, real: T | null, lowerScope?: string | null, viewScope?: string | null);
+}
+/**
+ * Pre-allocating symbol provider that vends a stable fake UUID per name.
+ *
+ * @remarks
+ * - `bind` always returns the same fake UUID for a given name (Option A: indirect-first),
+ *   regardless of whether the real item exists yet. This guarantees one stableId per name
+ *   across all formulas, compiled at any time.
+ * - `_real` is populated on first `bind` if the item already exists, and updated
+ *   on `reconcile()` as the collection changes.
+ * - `resolve` always returns a handle (never null for a known proxy) so formulas can
+ *   display the last-known name even when the item is temporarily absent.
+ *
+ * @see {@link reconcile} for collection-change handling.
+ *
+ * @typeParam T - Any type that satisfies {@link INamed.INamedValue}. Defaults to
+ *   `INamed.INamedValue` so callers that only need `getId`/`getName` need no type arg.
+ */
+export declare class IndirectSymbolProvider<T extends INamed.INamedValue = INamed.INamedValue> implements ISymbolProvider {
+    /**
+     * `scope` is the sheet a REFERENCE is being resolved from, and the lookup is expected to apply
+     * shadowing (a name scoped to that sheet beats a global of the same name). Providers with no
+     * scoped items — tables — may ignore it.
+     */
+    private readonly _getByName;
+    private readonly _getById;
+    private _byName;
+    private _byId;
+    /**
+     * The proxy holding a given real item, keyed by THAT ITEM's own id.
+     *
+     * @remarks
+     * `_byName` is keyed by name + scope, and both halves move under it: a rename changes one, and a
+     * SHEET rename changes what the other spells without this provider being told anything. A `bind`
+     * arriving afterwards computes the new key, misses, and mints a second proxy — with a second fake
+     * id — for one item. That id is the virtual grid a definition compiles into, so the second one is
+     * an empty grid and every reference through it resolves `#NAME?`.
+     *
+     * So identity is tracked by id as well, and {@link bind} re-files rather than mints. Maintained
+     * wherever `_real` is set; entries are dropped when a proxy loses its item.
+     */
+    private _byRealId;
+    constructor(
+    /**
+     * `scope` is the sheet a REFERENCE is being resolved from, and the lookup is expected to apply
+     * shadowing (a name scoped to that sheet beats a global of the same name). Providers with no
+     * scoped items — tables — may ignore it.
+     */
+    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null);
+    /**
+     * @inheritdoc ISymbolProvider.bind
+     *
+     * @remarks
+     * Two callers with different intents, distinguished by `ctx.own`:
+     *
+     * - **Defining** a name (`own: true`) asks for the id of the name `(displayName, ctx.scope)`
+     *   ITSELF, so the key is that pair verbatim. This is the virtual grid the definition compiles
+     *   into, and it is why two same-named names on different sheets no longer collide.
+     * - **Referencing** a name from a formula asks what `displayName` resolves to when written on
+     *   sheet `ctx.scope`. Shadowing decides, then the key is the WINNER's identity — so `=MonthName`
+     *   on January and the `January!MonthName` definition land on one id, while the same text on
+     *   February lands on February's.
+     *
+     * An unresolvable reference keys as global and heals in {@link reconcile}, which re-keys if what
+     * it heals to turns out to be scoped.
+     *
+     * A miss on `_byName` is not proof the item has no proxy — see {@link _byRealId}.
+     */
+    bind(displayName: string, ctx?: Record<string, unknown>): string;
+    /** Points a proxy at its real item, keeping {@link _byRealId} in step. */
+    private _adopt;
+    /** Moves a proxy to the `_byName` key its current name/scope spell. */
+    private _rekey;
+    /** @inheritdoc ISymbolProvider.resolve */
+    resolve(stableId: string, _ctx?: Record<string, unknown>): SymbolHandle | null;
+    /**
+     * Returns the real `T` item for a given fake UUID, filling `_real` lazily.
+     *
+     * @remarks
+     * Used by callers that need the underlying model (e.g. `getStructureReferenceCoords`,
+     * `TableColumnSymbolProvider` resolve).
+     */
+    getRealById(fakeId: string): T | null;
+    /**
+     * Reconciles all proxy `_real` references against the live collection.
+     *
+     * @returns Fake UUIDs whose `_real` state changed (add, delete, or rename).
+     *
+     * @remarks
+     * Call on every `onCollectionChange`. Handles add, delete, rename and re-scope without
+     * needing the old key — they are detected by matching `_real.getId()` against
+     * the collection's current state. O(proxies) — safe for n ≤ ~100.
+     *
+     * Re-scoping (`setScope`) moves an item between keys exactly as a rename does, so both are one
+     * check against the identity pair rather than the name alone.
+     */
+    reconcile(): string[];
+    /**
+     * Returns shallow-cloned maps for undo snapshotting.
+     *
+     * @remarks
+     * Restore by assigning `provider._byName = snapshot.byName` etc.
+     * The `IndirectProxy` objects themselves are shared (not deep-copied).
+     */
+    cloneMaps(): {
+        byName: Map<string, IndirectProxy<T>>;
+        byId: Map<string, IndirectProxy<T>>;
+        byRealId: Map<string, IndirectProxy<T>>;
+    };
+}
+//# sourceMappingURL=IndirectSymbolProvider.d.ts.map

package/types/src/calculation/symbol/IndirectSymbolProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndirectSymbolProvider.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/symbol/IndirectSymbolProvider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;;;;;;;GASG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;gBAGd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,CAAC,GAAG,IAAI,EACd,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,SAAS,GAAE,MAAM,GAAG,IAAW;CASlC;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAE,YAAW,eAAe;IAoB7G;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAxB3B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,KAAK,CAAyC;IACtD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,CAAuC;;IAGtD;;;;OAIG;IACc,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,EAC7D,QAAQ,EAAI,CAAC,EAAE,EAAE,MAAM,KAAO,CAAC,GAAG,IAAI;IAGzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IA4EhE,0EAA0E;IAC1E,OAAO,CAAC,MAAM;IAKd,uEAAuE;IACvE,OAAO,CAAC,MAAM;IAWd,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,GAAG,IAAI;IAe9E;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAUrC;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,MAAM,EAAE;IAmCrB;;;;;;OAMG;IACH,SAAS,IAAI;QACX,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;KACzC;CAOF"}

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts

@@ -0,0 +1,18 @@
+import { IRange } from '@sheetxl/primitives';
+import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
+/**
+ * Strict provider for sheet symbols.
+ */
+export declare class SheetSymbolProvider implements ISymbolProvider {
+    private readonly _getId;
+    private readonly _getById;
+    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null);
+    /** @inheritdoc ISymbolProvider.bind */
+    bind(displayName: string, _ctx: Record<string, unknown>): string | null;
+    /** @inheritdoc ISymbolProvider.resolve */
+    resolve(stableId: string, _ctx: Record<string, unknown>): SheetSymbolHandle | null;
+}
+export interface SheetSymbolHandle extends SymbolHandle {
+    getEntireCoords(): IRange.Coords | null;
+}
+//# sourceMappingURL=SheetSymbolProvider.d.ts.map

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SheetSymbolProvider.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/symbol/SheetSymbolProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAGvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EAC9C,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,iBAAiB,GAAG,IAAI;IAG1E,uCAAuC;IACvC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI;IAQvE,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,GAAG,IAAI;CAMnF;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,eAAe,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;CACzC"}