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

package/types/src/type/AbstractCollection.d.ts

@@ -0,0 +1,101 @@
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { ICollection } from './ICollection';
+/**
+ * Base for every {@link ICollection}.
+ *
+ * @remarks
+ * A subclass supplies {@link _getItems} — how its items are stored is its own business, keyed or
+ * ordered, held here or fronted from elsewhere — and gets iteration, the count and every read
+ * helper from that one call. A subclass with a cheaper count overrides {@link getCount}.
+ *
+ * Listeners are uniform: {@link addListeners} on the base, and {@link _notifyCollectionChange} /
+ * {@link _notifyInvalidated} for the subclass to announce with. A subclass that fronts another
+ * collection and forwards its events overrides `addListeners` instead of keeping a second
+ * emitter.
+ */
+export declare abstract class AbstractCollection<T, O extends ICollection.GetItemsOptions = ICollection.GetItemsOptions> implements ICollection<T> {
+    /**
+     * The store transactional listeners are versioned in; `undefined` gives the emitter a transient
+     * store of its own.
+     */
+    protected _transactions: ITransaction.IStore | undefined;
+    /** Created on first use — most collections are never listened to. */
+    private _collectionEmitter;
+    private _closed;
+    constructor(transactions?: ITransaction.IStore);
+    /** {@inheritDoc ICollection.isClosed} */
+    isClosed(): boolean;
+    /**
+     * Closes the collection: flips {@link isClosed} and announces
+     * {@link ICollection.Events.onClose} once.
+     *
+     * @remarks
+     * The base owns the fire so that the event can never be declared and not delivered. A
+     * subclass that is closable calls this from its public `close()` and does its own cleanup
+     * after; a second call is a no-op. The flag flips before the announcement, so a listener asking
+     * `isClosed()` while being told is told the truth.
+     */
+    protected _close(): void;
+    /**
+     * Returns the items, optionally filtered.
+     *
+     * @param options The subclass's own options; `undefined` is every item, in the collection's
+     * order.
+     *
+     * @remarks
+     * Return an array the caller may keep — a fresh one, or one the collection never mutates
+     * after handing it out — never the collection's own mutable storage. Every read on the base is
+     * over what this returns, and {@link toArray} returns it as-is.
+     */
+    protected abstract _getItems(options?: O): T[];
+    /** {@inheritDoc ICollection."[iterator]"} */
+    [Symbol.iterator](): IterableIterator<T>;
+    /** {@inheritDoc ICollection.getItems} */
+    getItems(options?: O): T[];
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc ICollection.at} */
+    at(index: number): T | undefined;
+    /** {@inheritDoc ICollection.indexOf} */
+    indexOf(item: T): number;
+    /** {@inheritDoc ICollection.find} */
+    find<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S | undefined;
+    find(predicate: (value: T, index: number, items: readonly T[]) => boolean): T | undefined;
+    /** {@inheritDoc ICollection.findIndex} */
+    findIndex(predicate: (value: T, index: number, items: readonly T[]) => boolean): number;
+    /** {@inheritDoc ICollection.filter} */
+    filter<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S[];
+    filter(predicate: (value: T, index: number, items: readonly T[]) => boolean): T[];
+    /** {@inheritDoc ICollection.map} */
+    map<U>(fn: (value: T, index: number, items: readonly T[]) => U): U[];
+    /** {@inheritDoc ICollection.forEach} */
+    forEach(fn: (value: T, index: number, items: readonly T[]) => void): void;
+    /** {@inheritDoc ICollection.some} */
+    some(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /** {@inheritDoc ICollection.every} */
+    every(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /** {@inheritDoc ICollection.toArray} */
+    toArray(): T[];
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _getCollectionEmitter(): ListenerEmitter<this, ICollection.Events>;
+    /**
+     * Announces {@link ICollection.Events.onCollectionChange}.
+     *
+     * @remarks
+     * Nothing is created for a collection nobody has listened to.
+     */
+    protected _notifyCollectionChange(): void;
+    /**
+     * Announces {@link ICollection.Events.onInvalidated}.
+     *
+     * @remarks
+     * Nothing is created for a collection nobody has listened to.
+     */
+    protected _notifyInvalidated(): void;
+    /** {@inheritDoc ICollection.isICollection} */
+    get isICollection(): true;
+}
+//# sourceMappingURL=AbstractCollection.d.ts.map

package/types/src/type/ICollection.d.ts

@@ -2,6 +2,16 @@ import { JSONSerializableAsync } from '@sheetxl/utils';
 import { IListener } from '../listener';
 /**
  * Interface used for all ICollections.
+ *
+ * @remarks
+ * A collection is the read side of a `ReadonlyArray` without the index operator: it iterates,
+ * counts, and offers the familiar helpers (`at`, `find`, `filter`, `map`, ...), but it is not an
+ * array and has no `[i]` or `length`. Call {@link toArray} when an array is really wanted.
+ *
+ * Iteration order is the collection's own order — insertion order for the ordered collections
+ * (sheets, tables, movables) and unspecified for the keyed ones (resources, functions). Every
+ * read is over a snapshot: neither {@link getItems} nor the helpers observe a change made while
+ * they run.
  */
 export interface ICollection<T> {
     /**
@@ -19,6 +29,11 @@ export interface ICollection<T> {
     [Symbol.iterator](): IterableIterator<T>;
     /**
      * Returns the items in the collection.
+     *
+     * @remarks
+     * The optioned call — filtering, ordering, anything parameterized — and a snapshot: the array
+     * returned does not follow later changes to the collection. For the unfiltered items as a plain
+     * array prefer {@link toArray}.
      */
     getItems(options?: ICollection.GetItemsOptions): T[];
     /**
@@ -28,6 +43,100 @@ export interface ICollection<T> {
      * returns the total number of items available.
      */
     getCount(): number;
+    /**
+     * Returns the item at the given index, or `undefined` if there is none.
+     *
+     * @param index The position in iteration order. A negative index counts back from the end, as
+     * `Array.prototype.at` does.
+     */
+    at(index: number): T | undefined;
+    /**
+     * Returns the index of the item in iteration order, or `-1` if it is not in the collection.
+     *
+     * @param item The item to find.
+     */
+    indexOf(item: T): number;
+    /**
+     * Returns the first item the predicate accepts, or `undefined` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    find<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S | undefined;
+    /**
+     * Returns the first item the predicate accepts, or `undefined` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    find(predicate: (value: T, index: number, items: readonly T[]) => boolean): T | undefined;
+    /**
+     * Returns the index of the first item the predicate accepts, or `-1` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    findIndex(predicate: (value: T, index: number, items: readonly T[]) => boolean): number;
+    /**
+     * Returns the items the predicate accepts, in iteration order.
+     *
+     * @param predicate Called once per item.
+     */
+    filter<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S[];
+    /**
+     * Returns the items the predicate accepts, in iteration order.
+     *
+     * @param predicate Called once per item.
+     */
+    filter(predicate: (value: T, index: number, items: readonly T[]) => boolean): T[];
+    /**
+     * Returns the result of calling the function on every item, in iteration order.
+     *
+     * @param fn Called once per item.
+     */
+    map<U>(fn: (value: T, index: number, items: readonly T[]) => U): U[];
+    /**
+     * Calls the function once per item, in iteration order.
+     *
+     * @param fn Called once per item.
+     */
+    forEach(fn: (value: T, index: number, items: readonly T[]) => void): void;
+    /**
+     * Returns `true` if the predicate accepts at least one item.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    some(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /**
+     * Returns `true` if the predicate accepts every item, including when there are none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `false`.
+     */
+    every(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /**
+     * Returns the items as a fresh array, in iteration order.
+     *
+     * @remarks
+     * The call to make when an array is really wanted. The array is the caller's: changing it does
+     * not change the collection, and it does not follow later changes to the collection.
+     */
+    toArray(): T[];
+    /**
+     * Returns `true` once the collection has been closed.
+     *
+     * @remarks
+     * A closed collection is empty and announces nothing further. Collections that are closed by
+     * their owner (the workbook's names, functions and modules, when the workbook closes) announce
+     * it once with {@link ICollection.Events.onClose}; the others are never closed and always
+     * return `false`.
+     */
+    isClosed(): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isICollection: true;
 }
 /**
  * {@inheritDoc ICollection}
@@ -103,6 +212,14 @@ export declare namespace ICollection {
          * Called when the collection has been updated due to a undo/redo and a rerender is required.
          */
         onInvalidated?(source: ICollection<any>): void;
+        /**
+         * Called once, when the collection is closed.
+         *
+         * @remarks
+         * {@link ICollection.isClosed} is already `true` when this is delivered, and nothing is
+         * announced after it. Only the collections an owner closes ever fire it.
+         */
+        onClose?(source: ICollection<any>): void;
     }
     interface IListeners extends IListener.Callbacks<ICollection<any>, ICollection.Events> {
     }

package/types/src/type/ITypes.d.ts

@@ -30,16 +30,18 @@ export declare namespace ITypes {
      *
      * * `dynamic` - the extent is *derived from* the result. It spills, and it resizes when the
      *   result shape changes.
-     * * `dynamicSpillError` - a `dynamic` formula whose spill is currently blocked. The recorded
+     * * `error` - a `dynamic` formula whose spill is currently blocked (`#SPILL!`). The recorded
      *   extent collapses to the anchor cell.
-     * * `static` - legacy array-entered (Ctrl+Shift+Enter). The extent is *authoritative* and the
-     *   result is fitted to it; it never spills and never resizes.
+     * * `fixed` - array-entered (Ctrl+Shift+Enter). The extent is *authoritative* and the result is
+     *   fitted to it (a dimension of 1 broadcasts, a longer one is clipped, a shorter one is padded
+     *   with `#N/A`); it never spills and never resizes. Written through
+     *   {@link ICellRange.SetValuesOptions.arrayFixed}.
      *
-     * `static + spillError` is not a state: a stored fixed block owns its cells, so a spill
-     * collision is rejected at entry rather than detected at calc. That is what lets these three be
-     * one enum rather than two booleans.
+     * `fixed + error` is not a state: a fixed block owns its cells, so a write into part of it is
+     * refused at the write site rather than detected at calc. That is what lets these three be one
+     * enum rather than two booleans.
      */
-    type FormulaArrayKind = 'dynamic' | 'dynamicSpillError' | 'static';
+    type FormulaArrayKind = 'dynamic' | 'fixed' | 'error';
     /**
      * Options for controlling selection behavior, including scrolling and focus.
      */

package/types/src/type/index.d.ts

@@ -1,5 +1,6 @@
 export * from './ITypes';
 export * from './IProperties';
 export * from './ICollection';
+export * from './AbstractCollection';
 export * from './Registry';
 //# sourceMappingURL=index.d.ts.map

package/types/src/utils/_CSSUtils.d.ts

@@ -4,7 +4,7 @@ import { IColor } from '../color';
 import { IFill } from '../fill';
 import { IFont } from '../font';
 import { ITextFrame } from '../text';
-import { IBorder } from '../border';
+import { IBorders } from '../border';
 export interface ParsedFont {
     family: string | null;
     size?: string | null;
@@ -118,8 +118,8 @@ export declare function parsePattern(value: string): Partial<IFill.PatternProper
  */
 export declare const toCSSGradient: (gradientFill: IFill.IGradient, mode?: IColor.CSSMode, size?: Size | null) => string | null;
 export declare function toCSSPattern(patternType: IFill.BuiltInSheetPattern): string;
-export declare function toCSSBorderStroke(stroke: IBorder.IStroke): string | null;
-export declare function parseBorderStroke(value: string, parseColor?: (str: string) => string): IBorder.StrokeProperties | null;
+export declare function toCSSBorderStroke(stroke: IBorders.IStroke): string | null;
+export declare function parseBorderStroke(value: string, parseColor?: (str: string) => string): IBorders.StrokeProperties | null;
 /**
  * @see
  * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/text-align}

package/types/src/workbook/IWorkbook.d.ts

@@ -1,16 +1,17 @@
 import { Scalar, IRange, IRangeStats, IRuntime, LocaleProfileOverrides } from '@sheetxl/primitives';
-import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { IResourceCollection, IResource } from '../resource';
 import { IStringCollection } from '../string';
 import { ICalculation } from '../calculation';
-import { IScript, IModule } from '../scripting';
+import { IScript, IModule, IModuleCollection } from '../scripting';
 import { ICell } from '../cell';
 import { ICellRange, ICellRanges } from '../cellRange';
-import { IComment } from '../comment';
+import { ICommentCollection } from '../comment';
+import { IPerson, IPersonCollection } from '../person';
 import { INamedCollection } from '../named';
 import { IExternalBook, IExternalBookCollection } from '../externalBook';
+import { IPivotTable, IPivotTableCollection } from '../pivot';
 import { ITheme } from '../theme';
 import { IStyleCollection } from '../style';
 import { ISheet, ISheetCollection, ICellContainerOptions } from '../sheet';
@@ -230,19 +231,22 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *
      * @remarks
      * A workbook has no intrinsic name (like Excel: a workbook's name *is* its file name). Display
-     * fallbacks (a localized "Untitled") are a UI concern. Renaming is an origin/document-level
-     * operation (see `WorkbookDocument.setName`), never a model edit — it is not undoable.
+     * fallbacks (a localized "Untitled") are a UI concern. Renaming is an origin-level operation
+     * (see {@link IWorkbookIO.Origin.setName}), never a model edit — it is not undoable.
      */
     getName(): string | null;
     /**
-     * Returns the workbook's {@link IWorkbookIO.Origin | origin} — the virtual file handle it maps to.
+     * Returns the workbook's {@link IWorkbookIO.Origin | origin} — the file handle it lives in.
      *
      * @remarks
-     * Read-only and always present: the *reference* is stable for the workbook's lifetime (a new
-     * in-memory workbook holds an *unbound* origin — `getPath()` `null`). The origin **object** is
-     * updated in place by its IO/store owner (e.g. a first save resolving a destination), like the
-     * DOM's `document.URL` — the model itself never mutates it, and it is not part of the persisted
-     * document ({@link toJSON}); a copy mints a fresh unbound origin.
+     * Always present: a new in-memory workbook holds an *unbound* origin (`getPath()` `null`). Like
+     * the DOM's `document.URL`, *which* origin can change — a save that resolves a new destination (a
+     * first save, a Save As) moves the workbook to the file it wrote, firing
+     * {@link IWorkbook.Events.onOriginChange | onOriginChange}. So read it when needed rather than
+     * holding it; to follow the current file, listen for `onOriginChange`.
+     *
+     * The model never mutates its origin, and the origin is not part of the persisted document
+     * ({@link toJSON}); a copy mints a fresh unbound origin.
      */
     getOrigin(): IWorkbookIO.Origin;
     /**
@@ -332,6 +336,18 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the protection object for the workbook.
      */
     getProtection(): IWorkbookProtection;
+    /**
+     * The workbook's VBA code name — conventionally `ThisWorkbook` — or `null` if it has none.
+     *
+     * @defaultValue null
+     *
+     * @remarks
+     * The workbook-level counterpart to {@link ISheet.getCodeName}: the identifier VBA binds the
+     * workbook's own document module through, where workbook event handlers such as `Workbook_Open`
+     * live. Like a sheet's, it is carried from the file and **read-only** — see
+     * {@link ISheet.getCodeName} for why SheetXL never mints one.
+     */
+    getCodeName(): string | null;
     /**
      * **Every** {@link INamed} in the workbook — global names, every sheet's scoped names, and every
      * table — sorted by type then by name.
@@ -347,10 +363,51 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * as `[n]Sheet1!$A$1`. In `[n]` order.
      *
      * @remarks
-     * Read-only for now: this phase reads and models the parts, nothing more. Formula text still
-     * carries `[n]` as opaque characters — this collection is not yet wired to it.
+     * A link is made by a formula — typing `'C:\path\[Budget.xlsx]Sheet1'!A1` adds a book here —
+     * and removed by breaking it ({@link IExternalBookCollection.breakLink}). Each book lists the
+     * formulas that cite it ({@link IExternalBook.getDependents}). The engine's collection, so
+     * available once the calculation is constructed, which is before any sheet is.
      */
     getExternalBooks(): IExternalBookCollection;
+    /**
+     * Returns the pivot tables on every sheet, in sheet order.
+     *
+     * @remarks
+     * A view over each sheet's {@link ISheet.getPivotTables}; `getByName` searches them all.
+     * Read-only for now: each table is carried as it was read and written back unchanged.
+     */
+    getPivotTables(): IPivotTableCollection;
+    /**
+     * Returns the comments and notes on every sheet, in sheet order.
+     *
+     * @remarks
+     * A view over each sheet's {@link ISheet.getComments}; `getById` and `getByReplyId` search
+     * them all. A comment is added on a sheet's collection.
+     */
+    getComments(): ICommentCollection;
+    /**
+     * Returns the people the workbook knows: the authors of its comments.
+     *
+     * @see {@link IComment.getAuthor}
+     */
+    getPeople(): IPersonCollection;
+    /**
+     * When the cached values of {@link getExternalBooks} should be re-read from their sources on
+     * open, or `null` where the source file said nothing (which Excel reads as `userSet`).
+     *
+     * @remarks
+     * Carried, not obeyed — SheetXL never refreshes a link, so every mode behaves as `never` until
+     * a resolver exists. Round-trips as `workbookPr@updateLinks`.
+     *
+     * The mode is {@link IExternalBookCollection.UpdateLinks}: it governs the books as a set, and no
+     * single book has one. It is read and written HERE because it is a property of the workbook in
+     * both Excel's object model and the file, not of the collection the books live in.
+     */
+    getUpdateLinks(): IExternalBookCollection.UpdateLinks | null;
+    /**
+     * Sets {@link getUpdateLinks}. `null` writes no attribute at all.
+     */
+    setUpdateLinks(updateLinks: IExternalBookCollection.UpdateLinks | null): this;
     /**
      * Returns the {@link ICalculation} for the workbook.
      */
@@ -360,15 +417,16 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *
      * @param expression The formula expression to parse.
      * @param coords Optional anchor coordinates.
+     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
      *
      * @remarks
-     * This is a convenience method for `getCalculation().createFormula(expression, coords)`.
+     * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`.
      * A bare reference (`A2`) resolves against the active cell's sheet; use
      * {@link ISheet.createFormula} to anchor against a specific sheet.
      *
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Evaluates a formula in the context of the sheet and returns the resulting value.
      *
@@ -378,18 +436,37 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
-    evaluate(formula: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(formula: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /**
      * Returns when all calculations are complete and there are no pending calculations.
      *
      * @remarks
-     * * This is a convenience method `getCalculation().ready()`.
+     * * Also waits for the load-time start: the pass {@link ICellContainerOptions.calcOnLoad} asks
+     *   for and the workbook's scripts. This is the settle point after constructing from JSON.
+     * * Otherwise a convenience method for `getCalculation().ready()`, which starts the engine if
+     *   it has not been started.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
     /**
      * Returns any user defined functions stored with the workbook.
      */
     getScripts(): IScript;
+    /**
+     * Returns the modules this workbook owns.
+     *
+     * @remarks
+     * The workbook half of {@link ISheet.getModules}, and the same collection
+     * `getScripts().getModules()` answers with — modules belong to the model, whereas
+     * {@link IScript} is what runs them.
+     *
+     * Holds the globally scoped modules, whose functions ARE in the formula namespace, and the
+     * workbook-scoped ones, whose functions are not ({@link IModule.getScope}). A sheet's modules
+     * are not in here at all; they hang off the sheet.
+     *
+     * Like every module collection, this filters to TypeScript unless asked otherwise; imported VBA
+     * is read with `getItems({ language: 'vba' })`.
+     */
+    getModules(): IModuleCollection;
     /**
      * Serialize the workbook to a JSON.
      *
@@ -479,6 +556,18 @@ export declare namespace IWorkbook {
          * Called when the workbook theme has changed.
          */
         onThemeChange?(source: IWorkbook): void;
+        /**
+         * Called when a workbook setting that governs how values are PRESENTED has changed - the
+         * locale, its overrides, or the date system.
+         *
+         * @remarks
+         * Nothing a cell holds has moved; what it paints for what it holds has. A consumer that has
+         * measured rendered text - a fitted column width, a cached layout - has to re-derive it.
+         *
+         * The active UI language does the same thing from outside the workbook, and is announced by
+         * {@link DefaultLanguagePackService} rather than here.
+         */
+        onRegionalChange?(source: IWorkbook): void;
         /**
          * Called when the workbook protection has changed.
          *
@@ -511,10 +600,20 @@ export declare namespace IWorkbook {
          */
         onViewChange?(source: IWorkbook): void;
         /**
-         * Called when the display name changes — a convenience proxy of the origin's `onChange`
-         * (non-transactional; renames are not model edits and never enter the undo stack).
+         * Called when the display name changes — a rename of the origin, or a move to a new one (see
+         * {@link onOriginChange}). Non-transactional; renames are not model edits and never enter the
+         * undo stack.
          */
         onNameChange?(source: IWorkbook): void;
+        /**
+         * Called when the workbook moves to a different {@link IWorkbook.getOrigin | origin} — a save
+         * that resolved a new destination (a first save, a Save As). Non-transactional.
+         *
+         * @remarks
+         * Changes *within* the current origin (its size after a save, a rename) are that origin's own
+         * `onChange`; a listener on the old origin hears nothing further about this workbook.
+         */
+        onOriginChange?(source: IWorkbook): void;
         /**
          * Called when the scripts associated with the workbook have change.
          */
@@ -589,6 +688,18 @@ export declare namespace IWorkbook {
          * A unique name for the sheet.
          */
         name: string;
+        /**
+         * The origin format's own identifier for this sheet, preserved so a round trip does not
+         * renumber it.
+         *
+         * @remarks
+         * Interop only — nothing in the model reads it and nothing references it by value. It is
+         * arbitrary and sparse (a workbook's edit history leaves gaps, so `Jan=3, Feb=28, Mar=29` is
+         * ordinary) and is **not** the sheet's position: `localSheetId` on a defined name is a
+         * position and is resolved separately. Absent for a sheet that was never loaded from a file;
+         * a writer assigns one in that case.
+         */
+        sheetId?: number;
         /**
          * @defaultValue ISheet.Visibility.Visible
          */
@@ -606,7 +717,12 @@ export declare namespace IWorkbook {
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
-        people?: IComment.PersonJSON[];
+        /**
+         * The people the workbook knows.
+         *
+         * @see {@link IWorkbook.getPeople}
+         */
+        people?: IPerson.JSON[];
         view?: IWorkbookView.JSON;
         theme?: ITheme.JSON;
         names?: INamedCollection.JSON;
@@ -616,10 +732,38 @@ export declare namespace IWorkbook {
          * position still counts, only the content does not.
          */
         externalBooks?: (IExternalBook.JSON | null)[];
-        scripts?: Record<string, IModule.JSON>;
+        /**
+         * What should happen to the cached values of {@link externalBooks} when the workbook is opened.
+         *
+         * @remarks
+         * Carried, not obeyed: SheetXL never refreshes a link, so every mode behaves as `never` today.
+         * Absent when the source said nothing, which Excel reads as `userSet`.
+         */
+        updateLinks?: IExternalBookCollection.UpdateLinks;
+        /**
+         * The workbook's pivot caches — the source snapshots its pivot tables summarize, each shared
+         * by every table that references its id.
+         *
+         * @remarks
+         * Carried, not modeled — see {@link IPivotTable.CacheJSON}. The tables that summarize a cache
+         * are the modeled side; a table names its cache by {@link IPivotTable.getCacheId}.
+         */
+        pivotCaches?: IPivotTable.CacheJSON[];
+        /**
+         * The workbook's own modules, keyed by module name.
+         *
+         * @see {@link IWorkbook.getModules}
+         */
+        modules?: Record<string, IModule.JSON>;
         calc?: ICalculation.JSON;
         protection?: IWorkbookProtection.JSON;
         date1904?: boolean;
+        /**
+         * The workbook's VBA code name. Absent when it has none.
+         *
+         * @see {@link IWorkbook.getCodeName}
+         */
+        codeName?: string;
         /**
          * The regional locale as a BCP 47 tag, e.g. `de-DE`.
          *
@@ -662,23 +806,6 @@ export declare namespace IWorkbook {
      * Options available when creating an IWorkbook.
      */
     interface ConstructorOptions extends ICellContainerOptions {
-        /**
-         * Additional custom formula function providers, bound after the built-ins (so they override
-         * built-ins on name collision). Each provider is the `initialize` binder produced by the
-         * FormulaCompiler (`@sheetxl/scripting`) for a folder of formula sources.
-         *
-         * @see {@link FunctionProvider}
-         */
-        functions?: readonly FunctionProvider[];
-        /**
-         * A structural transform applied once to each formula parsed from `json` — cell formulas
-         * AND defined names. This is the READ half of the format-dialect hook: a format reader
-         * (e.g. xlsx) supplies its legacy unwrap here; it is a LOAD-time pass only and is never
-         * applied to text typed or set after construction.
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
         /**
          * Hook to allow for custom sheet creation.
          */
@@ -695,9 +822,13 @@ export declare namespace IWorkbook {
          * shorthand for an unbound origin with that display name.
          *
          * @remarks
-         * The reference is stable for the workbook's lifetime; see {@link IWorkbook.getOrigin}.
+         * The initial origin; a save that resolves a new destination replaces it (see
+         * {@link IWorkbook.getOrigin}).
+         *
+         * A host with its own save flow can pass an {@link IWorkbookIO.OriginProvider} instead and move
+         * it itself; the IO layer then leaves the workbook's origin to that host.
          */
-        origin?: IWorkbookIO.Origin | string | null;
+        origin?: IWorkbookIO.Origin | IWorkbookIO.OriginProvider | string | null;
         /**
          * A theme for the workbook.
          */