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

package/types/src/calculation/grid/CalcGridUtils.d.ts

@@ -12,6 +12,39 @@ export declare function anchorCompareValues(a: ISpatialMap.Entry<FormulaSpatialV
  * @param range The range to compare
  */
 export declare function isTopLeft(rowIndex: number, colIndex: number, range: IRange.Coords): boolean;
+/**
+ * Keeps a grid's error index — `errorSpatial`, what `ICalcGrid.hasErrorIn` answers from — in
+ * step with a write of `tuples` into its values grid: every written run leaves the index, then
+ * each error member written re-enters it (a run of like errors as one entry).
+ *
+ * @remarks
+ * EVERY write into a calc grid's values goes through this or {@link indexWrittenRuns} — inputs,
+ * load, the calc commit, spills, a moved block — because the index is what a reference's
+ * `hasError` trusts instead of scanning; a missed write is a stale answer, which the
+ * reference's verification mode (`_setReferenceErrorIndexAssert`) catches in tests. Errors are
+ * rare, so the common write pays an emptiness check per run plus a scan of what it wrote.
+ */
+export declare function indexWrittenTuples(errorSpatial: ISpatialMap<string>, tuples: Tuple.GridTuple<Scalar> | null | undefined, isColumn: boolean): void;
+/**
+ * The cells of `tuples` that hold an error VALUE, as entries for the model's index of them
+ * (`true` = an error value lives here, whichever error it is).
+ *
+ * @remarks
+ * Read from what was WRITTEN, not from what the caller meant to write: a value the write path
+ * normalizes on its way in (a `NaN` becoming `#NUM!`) is an error by the time it reaches the run,
+ * and a check made before that normalization misses it. The engine keeps its own index of the
+ * same cells per label ({@link indexWrittenTuples}); this one says only that there is one.
+ */
+export declare function errorValueEntries(tuples: Tuple.GridTuple<Scalar> | null | undefined, isColumn: boolean): ISpatialMap.Entry<boolean>[];
+/** The {@link errorValueEntries} of a whole values grid: one scan, for the reconciled view. */
+export declare function errorValueEntriesOf(grid: ISparseGrid<Scalar>): ISpatialMap.Entry<boolean>[];
+/**
+ * The {@link indexWrittenTuples} of a region written some other way (a block copied in): the
+ * region leaves the index and its runs are re-read for errors.
+ */
+export declare function indexWrittenRuns(errorSpatial: ISpatialMap<string>, grid: ISparseGrid<Scalar>, bounds: IRange.Coords): void;
+/** Removes a cleared region from the error index (a spill's old extent, a deleted range). */
+export declare function clearErrorIndex(errorSpatial: ISpatialMap<string>, coords: IRange.Coords): void;
 /**
  * Updates contentful and invalidates spills.
  *
@@ -27,20 +60,22 @@ circularSpatial?: ISpatialMap<CircularEntry>): IRange.Coords | null;
  * @remarks
  * This is here because of the ILikeLike dependency.
  */
-export declare function tuplesToA1Map<T = any>(boundedTuples: Tuple.BoundedTuples<T> | undefined, axis?: IRange.Axis): Map<string, T>;
+export declare function tuplesToA1Map<T = any>(boundedTuples: Tuple.Region<T> | undefined, axis?: IRange.Axis): Map<string, T>;
 /**
- * Utility used by fromJSON hydration to build the initial dynamic precedent entries for
- * spill ranges loaded from saved state. Distinct from `container.addDynamicPrecedent`,
- * which is live-cycle only; this version accumulates into a caller-owned map so the entries
- * can be bulk-loaded into precedentSpatial in one pass.
+ * Adds one dynamic precedent to a block-keyed accumulator: the executor's per-cycle pending map, or
+ * the map fromJSON hydration builds for saved spill ranges before bulk-loading it into
+ * precedentSpatial.
  *
  * @remarks
- * Keyed by block and unioned per (block, kind) exactly as the live path does, because that is the
- * shape the dynamic registry (`IContextContainer.getDynamics`) can express. Anything that replaces
- * a block — an edit, a named recompile — evicts its dynamics through that map, so a block holding
- * an unregistered entry would leave it behind in precedentSpatial pointing at the dead block. The
- * dirty walk still reaches it, collects the dead block's CalcNodes alongside the live replacement's,
- * and the value builder then sees one cell pushed twice (`OutOfOrderError`).
+ * One entry per (block, kind, grid); another range of the same kind on the same grid grows that
+ * entry's bounding box. That is the shape the dynamic registry (`IContextContainer.getDynamics`) can
+ * express. Anything that replaces a block — an edit, a named recompile — evicts its dynamics through
+ * that map, so a block holding an unregistered entry would leave it behind in precedentSpatial
+ * pointing at the dead block. The dirty walk still reaches it, collects the dead block's CalcNodes
+ * alongside the live replacement's, and the value builder then sees one cell pushed twice
+ * (`OutOfOrderError`).
+ *
+ * Without a `range` the node's own cell stands in; without a scope the range is on the node's grid.
  */
 export declare function addDynamicPrecedent(entries: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>, node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
 /**
@@ -67,12 +102,17 @@ export interface EndpointAbs {
     $absRowEnd: boolean;
 }
 /**
- * TODO - CalcGrid.fromJSON has this code
+ * TODO - CalcGridBackend.fromJSON has this code
  */
 export declare function addPrecedents(asEntry: ISpatialMap.Entry<FormulaSpatialValue>, precedentsInsert: ISpatialMap.Entry<PrecedentSpatialValue>[], precedentsRet?: IRange.Coords[] | null): void;
 export interface PrecedentFormulaUpdates {
     precedents: ISpatialMap.Updates<PrecedentSpatialValue>;
     formulas: ISpatialMap.Updates<FormulaSpatialValue>;
+    /**
+     * The formulas whose DYNAMIC precedent the change dropped. They re-register when they next
+     * evaluate, but until then no precedent leads the dirty sweep to them.
+     */
+    dynamicDependents?: ISpatialMap.Entry<FormulaSpatialValue>[];
 }
 /**
  * Splits precedents at the insertion boundary.
@@ -158,6 +198,16 @@ export declare function movePrecedents(precedentSpatial: ISpatialMap3D<Precedent
  * TODO - document and/or rationalize with visitDependencyBlock
  */
 export declare const visitPrecedentBlock: (entryBlock: ISpatialMap.Entry<FormulaSpatialValue>, intersect: IRange.Coords, callbackFn: (calc: CalcNode, rowIndex: number, colIndex: number) => void) => void;
+/**
+ * Asks every fixed (array-entered) block the shift touches whether it can move whole
+ * (`SpillEntry.checkShift`) and throws `ExpectedError` for the first that cannot.
+ *
+ * @remarks
+ * Hoisted, not moved: the rule is the node's. It is asked here because {@link markFixedSpills}
+ * lifts every spill the shift intersects before the map shifts, so a partially covered block would
+ * otherwise never reach `SpillEntry.getShifted`. Run before any state is touched.
+ */
+export declare function checkFixedSpillsShift(spillSpatial: ISpatialMap<SpillEntry>, intersect: IRange.Coords, isColumn: boolean, isInsert: boolean): void;
 /**
  * Finds all spills that intersect a range and removes them for operations.
  *

package/types/src/calculation/grid/FormulaEntry.d.ts

@@ -0,0 +1,129 @@
+import { IRange, FormulaError } from '@sheetxl/primitives';
+import { ISpatialMap } from '../../collections';
+import { ICalculation } from '../ICalculation';
+import { ReferenceCoords } from '../Types';
+import { IFormulaBlockView } from '../formula';
+/**
+ * A formula the sheet holds: the model's text and the engine's view of the compiled block, one
+ * entry per run of cells that share a formula.
+ *
+ * @remarks
+ * The two halves are owned by different sides. `a1` and `ref` are the MODEL's: the canonical A1
+ * text anchored at the run's top-left, the shape the JSON persists, present in every engine state.
+ * `block` is the ENGINE's: the read view of the compiled block ({@link IFormulaBlockView}), vended
+ * when it compiles the entry, `null` until then. A pending entry (`block === null`) is a legal
+ * state at any time; a read that finds no block answers from the text, so nothing about a formula
+ * read branches on an engine being present.
+ *
+ * An entry answers as a block over its own text ({@link IFormulaBlockView}). With a block, every
+ * read is the block's. Without one, the text is re-anchored to the asked-for cell by the address
+ * emitter: the same rule the write path conflates runs on and the xlsx reader loads with, and
+ * measured exact against the compiled block on 144,964 distinct real-world formulas. Tokens and
+ * the parse error need a block, so a pending entry answers with none.
+ *
+ * An entry carries its own `ref`: a cell iterator reuses its coords object, and a sort clears the
+ * range before writing captured cells back, so a captured entry has to know where it was.
+ */
+export declare class FormulaEntry implements ISpatialMap.IUpdatableValue<FormulaEntry>, IFormulaBlockView {
+    /** Canonical A1 text, no leading `=`, anchored at `ref`'s top-left. See {@link imageAtAnchor}. */
+    a1: string;
+    /** The run this entry covers. */
+    readonly ref: IRange.Coords;
+    /** The engine's view of the compiled formula, or `null` while the entry is pending. */
+    block: IFormulaBlockView | null;
+    /** Lazily derived from `a1`: the address emitter's tokens, anchored at `ref`. */
+    private _tokens;
+    /** Lazily derived from `a1`: the relative (R1C1) form, the key two entries merge on. */
+    private _r1c1;
+    constructor(a1: string, ref: IRange.Coords, block: IFormulaBlockView | null);
+    /** `true` once the engine has vended a block for this entry. */
+    isCompiled(): boolean;
+    /**
+     * Adopt the block the engine vended, and the canonical text it images at the anchor.
+     */
+    setBlock(block: IFormulaBlockView | null): void;
+    /** The block's text at the anchor: what {@link setBlock} would make of `a1`. */
+    imageBlock(block: IFormulaBlockView): string;
+    /**
+     * Images this entry's own text at its anchor, so every cell of the run reads one way before the
+     * compile: `sum(a1)*2` entered reads `sum(A1)*2`, as the cells below it already do.
+     *
+     * @remarks
+     * The spelling of a REFERENCE is geometry, so the emitter owns it. The spelling of a function
+     * is the symbol table's - a called LET / LAMBDA variable, a named lambda and a UDF keep their
+     * case - so `sum(` is left as typed until the compile answers for it.
+     *
+     * The tokens and the relative form are not touched: the image differs from the text only in
+     * how it spells a reference, which is what both were derived from.
+     */
+    imageAtAnchor(): this;
+    /** The relative (R1C1) form of the text: two cells hold the same formula when these match. */
+    relativeForm(): string;
+    private _emitterTokens;
+    /**
+     * The text imaged at a cell by the address emitter, with no block.
+     *
+     * @remarks
+     * A relative axis driven below the sheet's origin images `#REF!` for the reference, as the
+     * compiled block does; the emitter's own resolver does not bound it.
+     */
+    private _emitTextAt;
+    /** {@inheritDoc IFormulaBlockView.getTextAt} */
+    getTextAt(row: number, column: number, r1c1?: boolean, evalIndex?: number, target?: ICalculation.FormulaTarget): string;
+    /** {@inheritDoc IFormulaBlockView.getTokensAt} */
+    getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
+    /** {@inheritDoc IFormulaBlockView.isReferenceOnly} */
+    isReferenceOnly(): boolean;
+    /** {@inheritDoc IFormulaBlockView.getError} */
+    getError(): FormulaError.Parse | null;
+    /** {@inheritDoc IFormulaBlockView.getReferencesAt} */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    /**
+     * A piece of this entry over `coords`, its text re-anchored at the piece's top-left.
+     */
+    protected _pieceAt(coords: IRange.Coords): FormulaEntry;
+    /** {@inheritDoc ISpatialMap.IUpdatableValue.getSplit} */
+    getSplit(destination: readonly [IRange.Coords, IRange.Coords], _axis: IRange.Axis, _offset: number): [FormulaEntry, FormulaEntry];
+    /**
+     * {@inheritDoc ISpatialMap.IUpdatableValue.getMerged}
+     *
+     * @remarks
+     * Two runs merge when their relative forms agree: `=A1*2` at B1 and `=A2*2` at B2 are one
+     * formula filled down. The merged entry keeps the top-left's text and block.
+     */
+    getMerged(other: FormulaEntry, coords: IRange.Coords, _axis: IRange.Axis): FormulaEntry | undefined;
+    /**
+     * {@inheritDoc ISpatialMap.IUpdatableValue.getShifted}
+     *
+     * @remarks
+     * The entry moves and its block is cleared: the engine re-images the text of a moved formula
+     * (references across the shift boundary, `#REF!`) and vends the result. Until then the entry
+     * reads as its pre-shift text at its new cell.
+     */
+    getShifted(options: ISpatialMap.ShiftDetails<FormulaEntry>): ISpatialMap.Entry<FormulaEntry> | null;
+    /**
+     * {@inheritDoc ISpatialMap.IUpdatableValue.copyTo}
+     *
+     * @remarks
+     * A copy is a fill: the text is re-anchored at the destination. A cut keeps its text, which is
+     * what a cut formula does for every reference outside the cut; a reference into the cut range
+     * moves with it, and the engine's vend carries that.
+     */
+    copyTo(destination: IRange.Coords, options?: FormulaEntry.CopyOptions): ISpatialMap.Entry<FormulaEntry> | undefined;
+    /** {@inheritDoc ISpatialMap.IUpdatableValue.canTile} */
+    canTile(_destination: IRange.Coords, _options?: ISpatialMap.CopyOptions): boolean;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+export declare namespace FormulaEntry {
+    /**
+     * Options for {@link FormulaEntry.copyTo}.
+     */
+    interface CopyOptions extends ISpatialMap.CopyOptions {
+        /**
+         * The range a cut is moving from. A cut keeps its text; a copy re-anchors it.
+         */
+        cutFrom?: IRange.Coords;
+    }
+}
+//# sourceMappingURL=FormulaEntry.d.ts.map

package/types/src/calculation/grid/FormulaHost.d.ts

@@ -0,0 +1,236 @@
+import { IRange, IFormulaContext, Scalar } from '@sheetxl/primitives';
+import { ISparseGrid } from '../../collections';
+import { ITransaction } from '../../transaction';
+import { IContextContainer } from '../state';
+import { IFormulaBlockView } from '../formula';
+import { ICalcGrid } from './ICalcGrid';
+import { CalcGrid } from './CalcGrid';
+import { FormulaEntry } from './FormulaEntry';
+/**
+ * A grid that holds exactly one formula block.
+ *
+ * @remarks
+ * A named formula, the editor's in-flight formula and a watch each keep a formula in a grid of
+ * their own, so that it can live beside the sheets' formulas in the one graph: precedents, dirty
+ * marking, the rewrite a structural change does and undo all reach it the way they reach a cell
+ * formula. This is the handle those owners hold: a grid as a sheet holds one, that is in no sheet
+ * list. It owns the model's grid ({@link ICalcGrid}, versioned in the model's store as a sheet's
+ * is), writes the body through its verbs and reads what the engine answers from it; what the
+ * engine pushes after a pass arrives through {@link _onComplete}.
+ */
+export declare class FormulaHost {
+    protected readonly _id: string;
+    protected readonly _grid: CalcGrid;
+    protected readonly _transactions: ITransaction.IStore | null;
+    protected readonly _container: IContextContainer;
+    protected readonly _context: IFormulaContext;
+    /**
+     * The body as this side knows it: what was last handed to the grid, refined by what the grid
+     * answered. Held here so that the owner of a formula never has to read it back out of the grid -
+     * the grid may not have answered yet, or may not be there at all.
+     */
+    protected _body: FormulaHost.Body | null;
+    /** The body's blank region as the last pass left it: see {@link getBlankRegion}. */
+    protected _blank: ICalcGrid.BlankRegion | null;
+    /**
+     * The last body written as authored, until a write of text replaces it: what is sent again when
+     * the engine never answered it (written while `Off`, which records nothing). See {@link _restart}.
+     */
+    protected _bodyRequest: {
+        options: ICalcGrid.BodyOptions;
+        onAnswered?: () => void;
+    } | null;
+    /** The last body written as authored has not been answered: the grid's entry predates it. */
+    protected _bodyPending: boolean;
+    protected readonly _onDispose: (() => void) | undefined;
+    protected readonly _onCalculated: ((results: ICalcGrid.Results) => void) | undefined;
+    constructor(options: FormulaHost.ConstructorOptions);
+    /** The grid's id. */
+    getId(): string;
+    /**
+     * Write the body.
+     *
+     * @remarks
+     * A request: the engine compiles the expression where it was authored, so relative references
+     * encode their offsets from there; binds every bare reference to `scopeGridId`, which is what
+     * makes a body in a grid of its own read a sheet; and images the result at `coords`' top-left,
+     * which re-expresses the offsets from where the body starts (a name stores its body at (0,0); a
+     * multi-area watch fills its second area from the first's origin). The body is pending until the
+     * engine answers with it.
+     *
+     * @param onAnswered Told when the engine answers with the body - this write's answer, or the
+     * answer to the same write sent again when the engine never answered it.
+     * @returns The grid's write.
+     */
+    setBody(options: FormulaHost.BodyOptions, onAnswered?: () => void): Promise<ICalcGrid.Results>;
+    protected _sendBody(request: {
+        options: ICalcGrid.BodyOptions;
+        onAnswered?: () => void;
+    }): Promise<ICalcGrid.Results>;
+    /**
+     * Send the body to an engine grid made since it was written - a start's, a rebuild's - from what
+     * this side holds: the body as authored while the engine has not answered it, the body as
+     * answered otherwise. Nothing is written to the model's grid.
+     *
+     * @returns The write, or `null` when there is nothing to send.
+     * @internal
+     */
+    _restart(): Promise<ICalcGrid.Results> | null;
+    /**
+     * The body as last written and last answered, without asking the grid: where it is, and its
+     * text at its own top-left. `null` when nothing is written.
+     *
+     * @remarks
+     * A write is reflected at once, as written; the grid's answer - the canonical text, and any
+     * rewrite a structural change made since - replaces it when it arrives.
+     */
+    getBody(): FormulaHost.Body | null;
+    /**
+     * What the engine pushed after a pass over the body: a rewrite nobody asked for (a structural
+     * change on the sheet the body reads), and the blank region.
+     * @internal
+     */
+    _onComplete(results: ICalcGrid.Results): void;
+    /**
+     * Take what the grid reports about the body: the answer to a write, or a rewrite nobody asked
+     * for (a structural change on the sheet the body reads).
+     * @internal
+     */
+    _refine(results: ICalcGrid.Results): void;
+    /**
+     * Take the body as the grid holds it in the snapshot the store is now at - what a revert
+     * answers with, since it changes the grid and reports nothing.
+     * @internal
+     */
+    _resync(): void;
+    /**
+     * The body's text as the engine's own bookkeeping rewrites it (a table re-fit): written as a
+     * body is, so the model's grid holds the new text before the engine answers.
+     * @internal
+     */
+    _rewrite(coords: IRange.Coords, text: string): Promise<ICalcGrid.Results>;
+    protected _write(coords: IRange.Coords, text: string): Promise<ICalcGrid.Results>;
+    /**
+     * Replace the body with a literal, keeping the block where it is.
+     *
+     * @remarks
+     * A deleted name keeps its grid with `#NAME?` at its origin so that dependents keep their edge to
+     * it; the block is still there, its value is the error.
+     *
+     * @param text The formula text to write - an error literal, typically.
+     */
+    setPlaceholder(text: string): Promise<ICalcGrid.Results>;
+    /**
+     * Move the body: the block's text, read at its own top-left, written over `coords`.
+     *
+     * @remarks
+     * Read at its OWN top-left, not imaged at the destination: the text there names the cells the
+     * body reads today, and writing that text at `coords` keeps it reading them (a cut formula's
+     * rule). A relative offset is then re-expressed from the new top-left by the write. The old
+     * block is cleared first, since the two may not overlap.
+     *
+     * @returns The write, or `null` when there is no body.
+     */
+    moveBody(coords: IRange.Coords): Promise<ICalcGrid.Results> | null;
+    /**
+     * Ask for the pass that evaluates the body, once the current flush is over.
+     *
+     * @remarks
+     * Posted, not run: every host that asks during one synchronous flush is evaluated by one pass.
+     * A request, recorded whatever the engine's status: an `Off` engine's start runs it.
+     */
+    requestPass(): void;
+    /**
+     * Take the body out, as a cell clear - which is what takes its precedents off the sheets.
+     */
+    clear(): Promise<ICalcGrid.Results>;
+    /**
+     * Where the body is, or `null` when nothing is written.
+     */
+    getCoords(): IRange.Coords | null;
+    protected _coordsOf(entry: IRange.Coords): IRange.Coords;
+    /**
+     * The body as the engine answered it, or `null` when nothing is written or the engine has not
+     * answered yet.
+     */
+    getBlock(): IFormulaBlockView | null;
+    /** The model's grid the body lives in. @internal */
+    _getCalcGrid(): CalcGrid;
+    /**
+     * The body as the model's grid holds it, answered or not: its text is the engine's once the
+     * engine has answered, and the text as written until then. `null` when nothing is written.
+     */
+    getView(): IFormulaBlockView | null;
+    /**
+     * The value of the body at a cell, coerced to one scalar - a defined name's `evaluate()`: a
+     * request, answered once the engine has calculated what it owes.
+     * @internal
+     */
+    _evaluateScalarAt(row: number, column: number, evalIndex?: number): Promise<Scalar>;
+    /** The grid's stored values: what a watch compares between passes. */
+    getValueGrid(): ISparseGrid<Scalar>;
+    /**
+     * The body's blank region: the cells of the body the pass shares one answer for rather than
+     * writing, and that answer. `null` when nothing is shared.
+     */
+    getBlankRegion(): ICalcGrid.BlankRegion | null;
+    /**
+     * What a cell of `coords` that the grid does not store reads as: the blank region's shared
+     * value when a region is shared and `coords` lie inside the body, `null` otherwise.
+     */
+    getBlankValueWithin(coords: IRange.Coords): Scalar;
+    /**
+     * The body's values, `(0, 0)` at the body's top-left.
+     *
+     * @remarks
+     * A read over the grid's own values, never a copy: whatever the grid stores is what a read sees,
+     * and a cell of the body's blank region - which the pass shares one answer for rather than
+     * writing - reads that answer as the range's empty value, so the range is dense however little
+     * the grid holds. `null` when nothing is written.
+     *
+     * @param coords Read over these instead of the block's extent - a watch reads over its location,
+     *               which is the block's extent once the two have been reconciled.
+     */
+    getValues(coords?: IRange.Coords): IRange | null;
+    /**
+     * Take the grid out of the graph: the body first (a clear takes its precedents off the sheets;
+     * `delete` alone leaves them, and the next dirty sweep would follow one back to a grid that no
+     * longer exists), then the grid.
+     */
+    dispose(): void;
+    /**
+     * A write to the model's grid, inside the operation that makes it; one made while no operation
+     * is open - a name wired as the engine comes up - is folded into the commit the store is at,
+     * never an undo step of its own.
+     */
+    protected _amendCurrent<T>(write: () => T): T;
+    protected _getEntry(): (IRange.Coords & {
+        value: FormulaEntry;
+    }) | null;
+}
+export declare namespace FormulaHost {
+    interface ConstructorOptions {
+        /** The id of the grid. */
+        id: string;
+        /** The model's grid the body lives in. */
+        grid: CalcGrid;
+        /** The store the grid is versioned in: a write made outside an operation amends its current commit. */
+        transactions?: ITransaction.IStore | null;
+        container: IContextContainer;
+        context: IFormulaContext;
+        /** Called when the host is disposed, for whoever keeps track of live hosts. */
+        onDispose?: () => void;
+        /** Told after every pass that wrote the grid. */
+        onCalculated?: (results: ICalcGrid.Results) => void;
+    }
+    /** A body as its host holds it. */
+    interface Body {
+        /** The block's extent. */
+        readonly coords: IRange.Coords;
+        /** The block's text at its own top-left, as it is written into the grid. */
+        readonly text: string;
+    }
+    /** See {@link ICalcGrid.BodyOptions}. */
+    type BodyOptions = ICalcGrid.BodyOptions;
+}
+//# sourceMappingURL=FormulaHost.d.ts.map