@sheetxl/sdk 0.7.28-beta.3 → 0.7.28-beta.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/sdk",
   "description": "SDK - A high-performance, embeddable spreadsheet engine.",
-  "version": "0.7.28-beta.3",
+  "version": "0.7.28-beta.4",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -43,11 +43,11 @@
     "automation"
   ],
   "dependencies": {
-    "@sheetxl/formulas": "^0.7.28-beta.3",
-    "@sheetxl/formulas-extended": "^0.7.28-beta.3",
-    "@sheetxl/primitives": "^0.7.28-beta.3",
-    "@sheetxl/scripting": "^0.7.28-beta.3",
-    "@sheetxl/utils": "^0.7.28-beta.3",
+    "@sheetxl/formulas": "^0.7.28-beta.4",
+    "@sheetxl/formulas-extended": "^0.7.28-beta.4",
+    "@sheetxl/primitives": "^0.7.28-beta.4",
+    "@sheetxl/scripting": "^0.7.28-beta.4",
+    "@sheetxl/utils": "^0.7.28-beta.4",
     "bahttext": "^2.4.0",
     "bessel": "^1.0.2",
     "chalk": "^6.0.0",

package/types/scripting-enums.json

@@ -183,6 +183,7 @@
       "AutoTable": "autoTable",
       "Border": "border",
       "CalcError": "calcError",
+      "Circular": "circular",
       "Comments": "comments",
       "Conditionals": "conditionals",
       "Contentful": "contentful",
@@ -841,6 +842,7 @@
       "ArrowsGray5": "5ArrowsGray",
       "Boxes5": "5Boxes",
       "Flags3": "3Flags",
+      "NoIcons": "NoIcons",
       "Quarters5": "5Quarters",
       "Rating4": "4Rating",
       "Rating5": "5Rating",

package/types/scripting.d.ts

@@ -1707,6 +1707,32 @@ declare global {
             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;
+        }
     }
 
     /**
@@ -2192,6 +2218,63 @@ declare global {
          * 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.
          *
@@ -2221,6 +2304,87 @@ declare global {
          * 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.
          */
@@ -2899,8 +3063,16 @@ declare global {
             /**
              * 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.
              */
@@ -2984,6 +3156,38 @@ declare global {
             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
          */
@@ -3246,12 +3450,28 @@ declare global {
          *
          * @remarks
          * Warnings differ from errors in that they may alter the display of the cell's value or type.
+         * A cell in a reference cycle, or downstream of one, carries one here — the text form of
+         * {@link getCircularReference}: the walk from this cell around the cycle and back
+         * ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".
          */
         getWarnings(): readonly string[];
         /**
          * Retrieves any errors attached to the cell.
          */
         getErrors(): readonly string[];
+        /**
+         * The reference cycle this cell is in, or downstream of — or `null` when it is neither.
+         *
+         * @remarks
+         * Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is `0`
+         * (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle
+         * whether this cell is a member or a reader ({@link ICalculation.ICircularReference.isMember})
+         * and, under iterative calculation, whether it converged.
+         *
+         * The range-level view is `ICellRange.Feature.Circular` — `getCounts` for how many cells,
+         * `getRegions` for which, each region carrying this same object as its payload.
+         */
+        getCircularReference(): ICalculation.ICircularReference | null;
         /**
          * Returns the style information applied to the cell.
          *
@@ -6614,11 +6834,20 @@ declare global {
             /** Cells inside a dynamic-array spill zone. Writing into one is a real failure mode. */
             readonly Spills: "spills";
             /**
-             * Evaluated state: cells whose calculation itself failed — mostly circular references.
-             * Distinct from {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE
-             * (the `Error` kind); `CalcError` is the engine failing to evaluate at all.
+             * Evaluated state: cells whose calculation itself failed. Distinct from
+             * {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE (the `Error`
+             * kind); `CalcError` is the engine failing to evaluate at all. A reference cycle is not a
+             * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
              */
             readonly CalcError: "calcError";
+            /**
+             * Evaluated state: cells in a reference cycle, or downstream of one. Both evaluate to `0`
+             * (Excel, iterative calculation off) with nothing else to show for it — this is the marker.
+             * Regions group by cycle and by kind (`member` | `downstream`), so a block that reads one bad
+             * cell is ONE region, and each region's payload is the cycle itself
+             * (`ICalculation.ICircularReference` — members, counts, whether iteration settled it).
+             */
+            readonly Circular: "circular";
             /** Direct fill. */
             readonly Fill: "fill";
             /** Direct borders. */
@@ -9908,8 +10137,11 @@ declare global {
          * Only the keys named are touched. An explicit `null` **clears** a key — required when switching
          * a rule between its two shapes, since `condition`+`style` and `scale` are mutually exclusive
          * (setting one side also clears the other unless the caller named both).
+         *
+         * Passing another rule takes its whole definition — every key, cleared where the other rule
+         * has none — so the shape switches with it. The anchor is not part of it.
          */
-        update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+        update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
         /**
          * Returns a snapshot of the conditional that can be used for copying and archiving.
          */
@@ -10339,8 +10571,12 @@ declare global {
     export namespace IConditionalFormatCollection {
         /**
          * Options for adding a {@link IConditionalFormat}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the rule at `index` only when it is a scale rule of the same
+         * kind on exactly the same ranges — see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IConditionalFormat.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IConditionalFormat.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IConditionalFormat}s.
@@ -10724,8 +10960,12 @@ declare global {
     export namespace IDataValidationCollection {
         /**
          * Options for adding a data validation to the collection.
+         *
+         * @remarks
+         * `replaceExisting` redefines the validation at `index` when it covers exactly the same ranges —
+         * see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IDataValidation.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IDataValidation.Properties, IAnchored.AddOptions {
         }
         interface GetItemsOptions {
             /**
@@ -14021,7 +14261,9 @@ declare global {
          * @remarks
          * This has no counterpart in Excel; it is ours and applies to links opened in a browser.
          *
-         * @defaultValue `_self` for a location within this workbook, otherwise `_blank`.
+         * @defaultValue `_self` for a location within this workbook or a `mailto:`/`tel:`/`sms:`
+         * address (handled by another application, so there is nothing to show in a new tab),
+         * otherwise `_blank`.
          */
         getTarget(): string;
         /**
@@ -16363,8 +16605,13 @@ declare global {
     export namespace IProtectedRangeCollection {
         /**
          * Options for adding an {@link IProtectedRange}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the entry at `index` when it covers exactly the same ranges; the
+         * entry keeps its name unless a free one is supplied — see
+         * {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IProtectedRange.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IProtectedRange.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IProtectedRange}s.
@@ -22094,6 +22341,11 @@ declare global {
             readonly Quarters5: "5Quarters";
             readonly Rating5: "5Rating";
             readonly Boxes5: "5Boxes";
+            /**
+             * Not a set to apply — the x14 name Excel writes for a band whose custom icon is
+             * "No Cell Icon" (`iconSet="NoIcons" iconId="0"`). It holds zero icons.
+             */
+            readonly NoIcons: "NoIcons";
         };
         type IconSet = typeof IconSet[keyof typeof IconSet];
     }
@@ -27899,6 +28151,11 @@ declare global {
         getCpuCount(): number;
         getMemory(): number;
         isEval(): boolean;
+        /**
+         * `true` when the licensed product may run `feature` without the license watermark: a valid
+         * license with no exceptions, or an evaluation on localhost / in a dev build. An evaluation on
+         * any other host answers `false` so the watermark shows.
+         */
         isValidFor: (feature: string) => boolean;
         getDeveloperCount(): number;
         getType(): string;

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

@@ -44,6 +44,15 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     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 +227,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 +442,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 {
 }