@sheetxl/sdk 0.7.28-beta.3 → 0.8.0-beta.1

package/types/src/anchored/IAnchored.d.ts

@@ -1,6 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
+import { ITransaction } from '../transaction';
 /**
  * `IAnchored` objects are anchored to one or more ranges.
  */
@@ -114,5 +115,31 @@ export declare namespace IAnchored {
         readonly TwoCell: "twoCell";
     };
     type Type = typeof Type[keyof typeof Type];
+    /**
+     * Options shared by the collections that add anchored items — conditional formats, data
+     * validations, protected ranges.
+     */
+    interface AddOptions extends ITransaction.OperationOptions {
+        /**
+         * Position in the collection. `0` is first — for a conditional format, the highest priority.
+         *
+         * @defaultValue 0 — a new item goes first, as in Excel.
+         */
+        index?: number;
+        /**
+         * Redefine the item already at `index` instead of inserting, when it is anchored to exactly
+         * the same ranges (discontiguous ranges compare area by area, in authored order).
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Only the item at `index` is considered, as in Excel. What counts as the same item is per
+         * collection: a data validation or protected range matches on ranges alone; a conditional
+         * format only redefines a scale rule (data bar, color scale, icon set) of the same kind —
+         * a style rule always inserts, since several may apply to one cell, whereas a second scale
+         * of one kind on the same ranges could never render.
+         */
+        replaceExisting?: boolean;
+    }
 }
 //# sourceMappingURL=IAnchored.d.ts.map

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

@@ -38,12 +38,26 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
     protected _calcExecutor: CalcExecutor;
     protected _cycleId: number;
+    protected _staticEpoch: number;
+    protected _precedentEpoch: number;
+    protected _epochSeenFormulas: ISpatialMap3D<FormulaSpatialValue> | null;
+    protected _epochSeenPrecedents: ISpatialMap3D<PrecedentSpatialValue> | null;
+    protected _epochSeenDynamics: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]> | null;
     protected _volatiles: Set<CalcNode>;
     protected _calculatedCommitId: string | null;
     protected _pendingActions: (() => Promise<unknown>)[] | null;
     protected _pendingPriority: (() => Promise<unknown>)[] | null;
     protected _draining: boolean;
     protected _drainScheduled: boolean;
+    protected _calcOwed: boolean;
+    /** {@link ICalculation.getCalculationMode} — gates the reactive pass in {@link _calculate}. */
+    protected _calcMode: ICalculation.CalculationMode;
+    /** {@link ICalculation.getIterativeCalculation} — handed to the executor per pass. */
+    protected _iterate: boolean;
+    protected _maxIterations: number;
+    protected _maxIterateChange: number;
+    /** The `calcPr` the file carried, kept whole so settings this engine ignores still round-trip. */
+    protected _calcJSON: ICalculation.JSON | null;
     protected _removeNamedItemsListeners: (() => void) | null;
     protected _namedDependents: Map<string, IRange.Coords[]> | null;
     protected _namedDependentsOf: ISpatialMap3D<FormulaSpatialValue> | null;
@@ -218,6 +232,18 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     stop(): Promise<void>;
     /** @inheritdoc ICalculation.getStatus */
     getStatus(): ICalculation.Status;
+    /** @inheritdoc ICalculation.getCalculationMode */
+    getCalculationMode(): ICalculation.CalculationMode;
+    /** @inheritdoc ICalculation.setCalculationMode */
+    setCalculationMode(mode: ICalculation.CalculationMode): this;
+    /** @inheritdoc ICalculation.isCalculationRequired */
+    isCalculationRequired(): boolean;
+    /** @inheritdoc ICalculation.getIterativeCalculation */
+    getIterativeCalculation(): ICalculation.IterativeCalculation;
+    /** @inheritdoc ICalculation.setIterativeCalculation */
+    setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+    /** @inheritdoc ICalculation.toJSON */
+    toJSON(): ICalculation.JSON;
     /** @inheritdoc ICalculation.ready */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
     /**
@@ -421,18 +447,6 @@ interface State extends AbstractModel.State {
      * Listeners to individual named items
      */
     itemRemoveListeners: (() => void)[];
-    /**
-     * Indicates if calculation will do iterative calcs
-     */
-    iterate: boolean;
-    /**
-     * The maximum number of iterations to perform when calculating.
-     */
-    maxIterations: number;
-    /**
-     * The maximum change allowed between iterations when performing iterative calculations.
-     */
-    maxIterateChange: number;
 }
 interface CommitView extends AbstractModel.CommitView {
 }

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

@@ -77,6 +77,63 @@ export interface ICalculation extends IModel {
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
     evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    /**
+     * When the engine recalculates on its own — Excel's Calculation Options.
+     *
+     * @remarks
+     * In {@link ICalculation.CalculationMode.Automatic} every commit that dirties a formula
+     * schedules a pass. In {@link ICalculation.CalculationMode.Manual} an edit only marks its
+     * dependents out of date ({@link isCalculationRequired}) and nothing is recalculated — volatile
+     * functions (`NOW`, `RAND`) stop re-rolling too — until {@link calculate}: Excel's F9 (every
+     * sheet), Shift+F9 (`scope`) and Ctrl+Alt+F9 (`full`). {@link ready} resolves at once in manual
+     * mode; a caller that wants current values calls {@link calculate}.
+     *
+     * @defaultValue {@link ICalculation.CalculationMode.Automatic}
+     */
+    getCalculationMode(): ICalculation.CalculationMode;
+    /**
+     * Sets the calculation mode.
+     *
+     * @remarks
+     * Leaving manual mode recalculates whatever is out of date, as Excel does.
+     * {@link ICalculation.CalculationMode.AutomaticExceptTables} is accepted for parity with the
+     * file format and Office Scripts; this engine has no what-if data tables, so it recalculates
+     * exactly as `Automatic` does.
+     */
+    setCalculationMode(mode: ICalculation.CalculationMode): this;
+    /**
+     * Whether any formula is out of date — Excel's `Calculate` indicator in the status bar.
+     *
+     * @remarks
+     * Meaningful in manual mode, where edits accumulate until {@link calculate}. In automatic
+     * mode it is `true` only between an edit and the pass it schedules.
+     */
+    isCalculationRequired(): boolean;
+    /**
+     * How a reference cycle is resolved — Excel's "Enable iterative calculation" and its limits.
+     *
+     * @see {@link ICalculation.IterativeCalculation}
+     */
+    getIterativeCalculation(): ICalculation.IterativeCalculation;
+    /**
+     * Enables, disables or configures iterative calculation.
+     *
+     * @param options `true`/`false` toggles `enabled` alone; an object updates the fields given and
+     * keeps the rest.
+     *
+     * @remarks
+     * Every cell in a cycle is recalculated when this changes: turning iteration on resolves the
+     * cycles the workbook shows as unresolved, turning it off writes `0` to them again.
+     */
+    setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+    /**
+     * The calculation settings as JSON — what an xlsx carries in `calcPr`.
+     *
+     * @remarks
+     * Sparse: a setting at its default is omitted. Settings a file carried that this engine does
+     * not act on (`calcOnSave`, `fullCalcOnLoad`, `fullPrecision`, …) are kept and written back.
+     */
+    toJSON(): ICalculation.JSON;
     /**
      * Add Listeners.
      *
@@ -105,6 +162,87 @@ export declare namespace ICalculation {
      * tokenizer, the AST, a formula input — is ever handed an expression of unbounded size.
      */
     const MAX_EXPRESSION_LENGTH = 8192;
+    /**
+     * A reference cycle — the answer to "why is this cell `0`".
+     *
+     * @remarks
+     * A cell is in a cycle when calculating it opens its own value, directly or through other cells
+     * — `=A1+1` in A1, `=OFFSET(A1,0,0)` in A1, `=SUMIF(B1,C1,A1)` in A1 while B1 matches C1. With
+     * iterative calculation off (the default, and Excel's) every cell in a cycle, and every cell
+     * downstream of one, evaluates to `0`; nothing on the value says why. This does.
+     *
+     * Reached from a cell — {@link ICell.getCircularReference} answers it for members and for
+     * downstream cells alike — and carried by the `ICellRange.Feature.Circular` regions, so a
+     * range, a sheet or the workbook is asked the way any other error is asked:
+     * `getCounts(Feature.Circular)` for how many, `getRegions(Feature.Circular)` for which, with
+     * this object as each region's payload. There is no list of cycles on the calculation: nobody
+     * starts from the cycle; they start from a cell or a range and want to know more.
+     *
+     * Live, not a snapshot: it reads the engine's cycle table on every call and drops members whose
+     * formula has since been edited away, so a stale handle answers `getMemberCount() === 0`.
+     * Persists until the last member is edited away.
+     */
+    interface ICircularReference {
+        /**
+         * The cell named for the cycle, the way Excel's status bar names one
+         * (`Worksheet.CircularReference` likewise answers a single cell): the first member in
+         * row-major order. `scope` is the sheet name, or `null` when the member lives in a named
+         * formula's body rather than on a sheet.
+         */
+        getRepresentative(): IRange.CellCoords | null;
+        /**
+         * Every cell IN the cycle, in row-major order, `scope` set to the sheet name. Small — a cycle
+         * is the cells that read each other, not everything that reads them (that is
+         * {@link getDownstreamCount}).
+         */
+        getMembers(): readonly IRange.CellCoords[];
+        /** How many cells are IN the cycle, the representative included. */
+        getMemberCount(): number;
+        /** How many cells read the cycle (transitively) and evaluate to `0` because of it. */
+        getDownstreamCount(): number;
+        /**
+         * Whether `coords` is IN the cycle, as opposed to downstream of it. A cell that reads a
+         * member's `0` answers `false` here but still resolves this cycle from
+         * {@link ICell.getCircularReference} — the tooltip for it says "reads a circular reference
+         * at A1", not "is one".
+         */
+        isMember(coords: IRange.CellCoords): boolean;
+        /**
+         * The cycle as a walk of reads from `from` back to itself — each cell reads the next, and
+         * the last reads the first. A cycle has no start, so it is told from the cell that asks:
+         * with `A1 = B1+1` and `B1 = A1+1`, asked from A1 it is `[A1, B1]` (A1 → B1 → A1), asked
+         * from B1 it is `[B1, A1]`. A cycle of one is `[A1]`.
+         *
+         * @remarks
+         * Exact, not inferred from formula text: it is the order the engine found the cycle in,
+         * which is the order the reads happened — a dynamic read (`INDIRECT`, `OFFSET`) is a step
+         * like any other. Interlocking cycles share members; the walk follows the read that closed
+         * the cycle `from` was found in, so it is ONE loop through that cell, not every member
+         * ({@link getMembers} is every member).
+         *
+         * Empty when `from` is not a live member — a downstream cell asks from
+         * {@link getRepresentative}.
+         */
+        getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+        /**
+         * Whether iterative calculation was on when the cycle was last evaluated. When `false` the
+         * cycle is unresolved and every member and downstream cell is `0`; the iteration answers
+         * below are then meaningless (`0` sweeps, no change).
+         */
+        isIterative(): boolean;
+        /**
+         * Whether iterative calculation settled it: every member moved by less than the workbook's
+         * `maxIterateChange` in the last sweep. Always `false` with iteration off.
+         */
+        isConverged(): boolean;
+        /** How many sweeps the last evaluation ran — up to the workbook's `maxIterations`. */
+        getIterationCount(): number;
+        /**
+         * The largest change any member made in the last sweep — what stopped the iteration when
+         * {@link isConverged}, what it never got under when not. `0` with iteration off.
+         */
+        getLastChange(): number;
+    }
     /**
      * Represents a formula that can be evaluated.
      */
@@ -783,8 +921,16 @@ export declare namespace ICalculation {
         /**
          * Called when the calculation has been updated and
          * a calculation has not been started.
+         *
+         * @remarks
+         * In manual mode this is every edit that leaves a formula out of date — see
+         * {@link ICalculation.isCalculationRequired}.
          */
         onStale?(source: ICalculation): void;
+        /**
+         * Called when the calculation mode or the iterative-calculation settings change.
+         */
+        onOptionsChange?(source: ICalculation): void;
         /**
          * Called when a calculation is starting.
          */
@@ -868,6 +1014,38 @@ export declare namespace ICalculation {
         readonly AutomaticExceptTables: "automaticExceptTables";
     };
     type CalculationMode = typeof CalculationMode[keyof typeof CalculationMode];
+    /**
+     * Iterative calculation — Excel's "Enable iterative calculation" with its two limits.
+     *
+     * @remarks
+     * With it off a reference cycle evaluates to `0` and is reported as unresolved. With it on the
+     * cells of the cycle are re-evaluated in turn, each read seeing the latest value, until no cell
+     * moved by {@link maxChange} or {@link maxIterations} sweeps ran — and the results persist into
+     * the next recalculation, which re-runs every cycle the way it re-runs `NOW()`: `=A1+1` in A1 is
+     * a counter that advances by `maxIterations` per recalc. A cycle that stops on the sweep cap is
+     * still reported ({@link ICircularReference.isConverged}); a converged one is not.
+     *
+     * Office Scripts calls the count `maxIteration`; the file format `iterateCount` / `iterateDelta`.
+     */
+    interface IterativeCalculation {
+        /**
+         * @defaultValue `false`
+         */
+        enabled: boolean;
+        /**
+         * The most sweeps one recalculation runs over a cycle.
+         *
+         * @defaultValue `100`
+         */
+        maxIterations: number;
+        /**
+         * Sweeps stop early once every cell in the cycle moved by less than this. A non-numeric
+         * change (text, error) never counts as settled.
+         *
+         * @defaultValue `0.001`
+         */
+        maxChange: number;
+    }
     /**
      * Represents the status of a calculation result
      */