@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.11

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

@@ -7,7 +7,7 @@ import { ICalculation } from '../calculation';
 import { IFontCollection } from '../font';
 import { IScript, IModule, IModuleCollection } from '../scripting';
 import { ICell } from '../cell';
-import { ICellRange, ICellRanges } from '../cellRange';
+import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
 import { ICommentCollection } from '../comment';
 import { IPerson, IPersonCollection } from '../person';
 import { INamedCollection } from '../named';
@@ -15,57 +15,120 @@ import { IExternalBook, IExternalBookCollection } from '../externalBook';
 import { IPivotTable, IPivotTableCollection } from '../pivot';
 import { ITheme } from '../theme';
 import { IStyleCollection } from '../style';
-import { ISheet, ISheetCollection, ICellContainerOptions } from '../sheet';
+import { ISheet, IOpaqueSheet, IWorksheet, IWorksheetCollection, ICellContainerOptions } from '../sheet';
 import { IWorkbookView } from '../workbookView';
 import { IWorkbookProtection } from '../workbookProtection';
+import { IDocumentProperties } from '../documentProperties';
 import { IWorkbookIO } from '../io';
 /**
- * An `IWorkbook` represents a collection of {@link ISheet | sheets}, along with shared resources.
+ * An `IWorkbook` represents a collection of {@link IWorksheet | sheets}, along with shared resources.
  *
  * This interface provides methods for accessing its elements and event handling.
  *
  * @remarks
- * Most interactions with a {@link IWorkbook | workbook} or {@link ISheet | sheet} are done through a
+ * Most interactions with a {@link IWorkbook | workbook} or {@link IWorksheet | sheet} are done through a
  * {@link ICellRange | workbook range}.
  *
  * @see
- * * {@link getRange} - For interacting with cell values and formatting on a single {@link ISheet | sheet}.
- * * {@link getSheets} - For managing {@link ISheet | sheet}.
+ * * {@link getRange} - For interacting with cell values and formatting on a single {@link IWorksheet | sheet}.
+ * * {@link getWorksheets} - For managing {@link IWorksheet | sheet}.
  * * {@link getNames} - For managing items with defined names.
  */
 export interface IWorkbook extends ITransaction.ITransactional, IListener.ISource<IWorkbook, IWorkbook.IListeners> {
     /**
-     * Returns the collection of sheets within the workbook.
+     * Returns every sheet in tab order, of every kind: worksheets, chart sheets, macro sheets and
+     * dialog sheets.
+     *
+     * @param options Which sheets to return; by default the visible ones.
+     *
+     * @remarks
+     * Use {@link getWorksheets} for the grids alone.
+     */
+    getSheets(options?: IWorkbook.GetSheetsOptions): ISheet[];
+    /**
+     * Returns the sheet of any kind with the given name, or the selected sheet when no name is
+     * given.
+     *
+     * @param name The name of the sheet, ignoring case.
+     *
+     * @remarks
+     * Throws when there is no sheet with that name. Use {@link getWorksheet} when the sheet must be a
+     * grid.
+     */
+    getSheet(name?: string): ISheet;
+    /**
+     * Returns the active tab, whatever its kind.
+     *
+     * @remarks
+     * Use {@link getSelectedWorksheet} for the active grid.
+     */
+    getSelectedSheet(): ISheet;
+    /**
+     * Returns the collection of worksheets within the workbook.
+     *
+     * @remarks
+     * Only the grids. Use {@link getSheets} for every tab, chart sheets included.
      */
-    getSheets(): ISheetCollection;
+    getWorksheets(): IWorksheetCollection;
     /**
      * Adds a new sheet to the workbook.
      *
      * @remarks
-     * This is a convenience method that wraps `{@link ISheetCollection.add}`.
+     * This is a convenience method that wraps `{@link IWorksheetCollection.add}`.
      */
-    addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet;
+    addWorksheet(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
     /**
-     * Returns the sheet at the given offset.
+     * Returns the worksheet at the given offset among the worksheets.
      *
-     * @param index A 0-based index of the sheet.
+     * @param index A 0-based index into the worksheets with the given visibility. Sheets of other
+     * kinds are not counted, so this is not the tab position ({@link ISheet.getIndex}).
      * @param visibility The visibility of the sheet.
      */
-    getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet;
+    getWorksheetAt(index: number, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the sheet for the given name, or the selected sheet when no name is given.
+     * Returns the worksheet for the given name, or the selected worksheet when no name is given.
      *
      * @param name The name of the sheet. Omit for the selected sheet — "the sheet", unqualified,
-     * is the one the user (or agent) is looking at. `getSelectedSheet` remains the explicit form.
+     * is the one the user (or agent) is looking at. `getSelectedWorksheet` remains the explicit form.
      * @param visibility The visibility of the sheet.
+     *
+     * @remarks
+     * Throws when the sheet is not a worksheet: a chart sheet, say, or the selected tab when that is
+     * not a worksheet. Use {@link getSheet} for any kind.
      */
-    getSheet(name?: string, visibility?: ISheet.Visibility): ISheet;
+    getWorksheet(name?: string, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the currently active sheet within the workbook.
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getWorksheetAt}.
+     * @hidden
      */
-    getSelectedSheet(): ISheet;
+    getWorksheet(index: number, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the currently active sheet index within the workbook.
+     * Returns the active worksheet, or `null` when the active tab is not a worksheet.
+     *
+     * @remarks
+     * A chart sheet (or a macro or dialog sheet) can be the active tab, and then there is no active
+     * worksheet: like VBA's `ActiveCell`, this is `null` rather than some other worksheet.
+     * {@link getSelectedSheet} returns the active tab whatever its kind.
+     */
+    getSelectedWorksheet(): IWorksheet | null;
+    /**
+     * Exists to have api parity with Google Apps Script.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveSheet(): IWorksheet | null;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveWorksheet(): IWorksheet | null;
+    /**
+     * Returns the position of the active tab among the visible sheets of every kind.
      */
     getSelectedSheetIndex(): number;
     /**
@@ -116,7 +179,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * default `'throw'` policy treats one as a fault when aggregating.
      *
      * @remarks
-     * The workbook form of {@link ISheet.getStats}: every sheet's used range contributes,
+     * The workbook form of {@link IWorksheet.getStats}: every sheet's used range contributes,
      * including hidden and very-hidden sheets — visibility is a display concern, not a data
      * one. A workbook with no used cells returns empty statistics (`getSize() === 0`),
      * never `null`.
@@ -127,16 +190,40 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * {@link ICellRange.getStats}
      */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /**
+     * Returns the regions of the `anomalies` feature across every sheet, in reading order.
+     *
+     * @example
+     * ```ts
+     * wb.getAnomalies({ checks: ['linkLabelMismatch', 'styleRole'], limit: 25 });
+     * ```
+     *
+     * @remarks
+     * The workbook form of {@link ICellRange.getAnomalies}: every sheet contributes, hidden and
+     * very hidden included, in one order, and each region's address names its sheet. The listing
+     * spans sheets, so its {@link ICellRegions.getRange} is the selected sheet's; each region is
+     * clipped against its own sheet.
+     */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /**
      * Returns a range of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /**
      * Returns ranges of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
     /**
      * Returns the selected cell.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedCell(): ICell;
     /**
@@ -159,14 +246,16 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      */
     replace(cells: Iterator<ICell>, replace: ICell.Update | ((original: ICell) => ICell.Update), options?: IWorkbook.ReplaceOptions): IWorkbook.ReplaceResults;
     /**
-     * Returns the next sheet in the sheets collection. If the last one it will return the first.
+     * Returns the next visible sheet, of any kind, after the given tab position. If the last one it
+     * will return the first.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
      */
     getNextSheet(index: number): ISheet;
     /**
-     * Returns the previous sheet in the sheets collection. If the first one it will return the last.
+     * Returns the previous visible sheet, of any kind, before the given tab position. If the first
+     * one it will return the last.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
@@ -210,6 +299,62 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the current shared resources.
      */
     getTransactions(): ITransaction.IStore;
+    /**
+     * Performs a set of operations as one: one commit, one undo step, one round of events.
+     *
+     * @param callback Performs the operations. Handed the commit being written and `workbook`,
+     * this workbook bound to the batch.
+     * @param options Description of the operation or additional options. Used for undo/redo and
+     * history.
+     *
+     * @remarks
+     * Work through `workbook` rather than this one. Everything reached through it - sheets, ranges,
+     * tables - is part of the batch, and a listener added through it takes part in the batch by
+     * default ({@link IListener.Options.transactional}). A range listener added through it hears each
+     * operation as it is made, rather than once when the batch lands, and what it writes joins the
+     * batch ({@link ICellRange.ListenerOptions.transactional}). A listener added any other way, while
+     * the batch is open, is outside it.
+     *
+     * The objects reached through `workbook` are not `===` to the ones reached through this workbook,
+     * though the same object always compares equal to itself. They can be passed to any method of
+     * either.
+     *
+     * A batch that performs no writes is elided: the commit id is unchanged, no events fire, and
+     * nothing is added to the undo stack or commit log.
+     *
+     * @example
+     * ```ts
+     * await workbook.doBatch(async (_commit, wb) => {
+     *   const cell = wb.getSelectedWorksheet()!.getRange('A1');
+     *   cell.addListener(() => console.log('A1 changed'));
+     *   cell.setValue(1); // logs 'A1 changed' before the next line runs
+     * });
+     * ```
+     */
+    doBatch<R = any>(callback: (commit: ITransaction.ICommit, workbook: this) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
+    /**
+     * What a commit wrote: the {@link IWorksheet.ChangeEvent}s it announced, one for each sheet and
+     * {@link IWorksheet.ChangeEvent.getKind | kind} (data, formatting, merges, spills).
+     *
+     * @param commitId The commit to describe. Omit for the current one.
+     * @returns Empty for a commit that changed no cells (a view, a name, a chart).
+     *
+     * @remarks
+     * The same events the sheets announced when the commit landed, read afterwards: the
+     * previous commit is its parent, and an undo is reported as the commit it moved to, so
+     * {@link IWorksheet.ChangeEvent.isUndo} is always `false` here.
+     *
+     * @throws If the store no longer has the commit.
+     *
+     * @example
+     * ```ts
+     * for (const change of wb.getChanges()) {
+     *   if (change.getKind() !== 'onDataChange') continue; // values and formulas, not formatting
+     *   console.log(change.getSheet().getName(), change.getRanges()?.toString());
+     * }
+     * ```
+     */
+    getChanges(commitId?: string): IWorksheet.ChangeEvent[];
     /**
      * Get the current theme.
      */
@@ -337,16 +482,20 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the protection object for the workbook.
      */
     getProtection(): IWorkbookProtection;
+    /**
+     * The workbook's document properties: author, title, company and the like.
+     */
+    getProperties(): IDocumentProperties;
     /**
      * 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
+     * The workbook-level counterpart to {@link IWorksheet.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.
+     * {@link IWorksheet.getCodeName} for why SheetXL never mints one.
      */
     getCodeName(): string | null;
     /**
@@ -356,7 +505,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * The name-manager view: what EXISTS, not what any one sheet can see. A global name and a
      * sheet-scoped name that share a name are two items here and both are returned; ask
-     * {@link ISheet.getNames} for the one a formula on that sheet would resolve to.
+     * {@link IWorksheet.getNames} for the one a formula on that sheet would resolve to.
      */
     getNames(): INamedCollection;
     /**
@@ -374,7 +523,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the pivot tables on every sheet, in sheet order.
      *
      * @remarks
-     * A view over each sheet's {@link ISheet.getPivotTables}; `getByName` searches them all.
+     * A view over each sheet's {@link IWorksheet.getPivotTables}; `getByName` searches them all.
      * Read-only for now: each table is carried as it was read and written back unchanged.
      */
     getPivotTables(): IPivotTableCollection;
@@ -382,7 +531,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * 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
+     * A view over each sheet's {@link IWorksheet.getComments}; `getById` and `getByReplyId` search
      * them all. A comment is added on a sheet's collection.
      */
     getComments(): ICommentCollection;
@@ -431,7 +580,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * 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.
+     * {@link IWorksheet.createFormula} to anchor against a specific sheet.
      *
      * @see {@link ICalculation.createFormula}
      */
@@ -456,6 +605,23 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *   it has not been started.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /**
+     * Returns when every font the workbook measures with has loaded and every autofit that was
+     * taken with a stand-in meanwhile has been taken again.
+     *
+     * @remarks
+     * Measuring never waits: a style naming a face not yet loaded measures with a related or
+     * built-in one and the lookup starts the load, the way a browser paints with a fallback until
+     * a web font arrives. This is the point after which sizes are final. Fonts are shared, so this
+     * also waits for faces other workbooks started loading; a load that fails leaves its stand-in
+     * and still settles.
+     */
+    whenFontsReady(): Promise<void>;
+    /**
+     * Returns when the workbook is settled: {@link whenCalculationReady} and {@link whenFontsReady}
+     * both hold.
+     */
+    whenReady(): Promise<void>;
     /**
      * Returns any user defined functions stored with the workbook.
      */
@@ -464,7 +630,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the modules this workbook owns.
      *
      * @remarks
-     * The workbook half of {@link ISheet.getModules}, and the same collection
+     * The workbook half of {@link IWorksheet.getModules}, and the same collection
      * `getScripts().getModules()` answers with — modules belong to the model, whereas
      * {@link IScript} is what runs them.
      *
@@ -481,7 +647,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *
      * @param options Options to control the JSON output.
      */
-    toJSON(options?: ISheet.ToJSONOptions): Promise<IWorkbook.JSON>;
+    toJSON(options?: IWorksheet.ToJSONOptions): Promise<IWorkbook.JSON>;
     /**
      * Returns any custom workbook options that are provided in constructor.
      */
@@ -690,9 +856,24 @@ export declare namespace IWorkbook {
         last: ICell | null;
     }
     /**
-     * Used for persisting metadata about a `ISheet`.
+     * Options for {@link IWorkbook.getSheets}.
      */
-    interface SheetRefJSON {
+    interface GetSheetsOptions {
+        /**
+         * The least visible sheets to include: `Hidden` includes the hidden sheets, `VeryHidden` every
+         * sheet.
+         *
+         * @defaultValue ISheet.Visibility.Visible
+         */
+        visibility?: ISheet.Visibility;
+    }
+    /**
+     * Used for persisting an {@link ISheet}: its tab, and its body as {@link SheetRefJSON.kind} says.
+     *
+     * @typeParam T The body: {@link IWorksheet.JSON} for a worksheet, {@link IOpaqueSheet.JSON} for
+     * the other kinds.
+     */
+    interface SheetRefJSON<T extends ISheet.JSON = IWorksheet.JSON | IOpaqueSheet.JSON> {
         /**
          * A unique name for the sheet.
          */
@@ -714,9 +895,15 @@ export declare namespace IWorkbook {
          */
         visibility?: ISheet.Visibility;
         /**
-         * The actual sheet.
+         * What the sheet holds, and so what {@link sheet} is.
+         *
+         * @defaultValue ISheet.Kind.Worksheet
+         */
+        kind?: ISheet.Kind;
+        /**
+         * The sheet's body.
          */
-        sheet?: ISheet.JSON;
+        sheet?: T;
     }
     /**
      * JSON representation of an `IWorkbook` used for serialization and deserialization.
@@ -766,6 +953,10 @@ export declare namespace IWorkbook {
         modules?: Record<string, IModule.JSON>;
         calc?: ICalculation.JSON;
         protection?: IWorkbookProtection.JSON;
+        /**
+         * @see {@link IWorkbook.getProperties}
+         */
+        properties?: IDocumentProperties.JSON;
         date1904?: boolean;
         /**
          * The workbook's VBA code name. Absent when it has none.
@@ -792,12 +983,12 @@ export declare namespace IWorkbook {
     /**
      * Callback to allow for custom `ISheets`. The Workbook provides a default implementation.
      */
-    interface CreateSheetCallback {
+    interface CreateWorksheetCallback {
         (
         /**
          * Options used for creating the Sheet instance.
          */
-        options: ISheet.ConstructorOptions, 
+        options: IWorksheet.ConstructorOptions, 
         /**
          * The name of the new  sheet.
          */
@@ -809,7 +1000,7 @@ export declare namespace IWorkbook {
         /**
          * @defaultValue ISheet.Visibility.Visible
          */
-        visibility: ISheet.Visibility): ISheet;
+        visibility: ISheet.Visibility): IWorksheet;
     }
     /**
      * Options available when creating an IWorkbook.
@@ -818,7 +1009,7 @@ export declare namespace IWorkbook {
         /**
          * Hook to allow for custom sheet creation.
          */
-        createSheetCallback?: CreateSheetCallback;
+        createWorksheetCallback?: CreateWorksheetCallback;
         /**
          * Returns a human readable sheet name given a 0-based index.
          *