@sheetxl/sdk 0.8.0-beta.14 → 0.8.0-beta.16

package/types/src/pivot/IPivotTableCollection.d.ts

@@ -1,13 +1,41 @@
+import { ICellRange } from '../cellRange';
+import { ITable } from '../table';
+import { ITransaction } from '../transaction';
 import { ICollection } from '../type';
 import { IPivotTable } from './IPivotTable';
 /**
  * Holds {@link IPivotTable | pivot tables} — a sheet's, or every sheet's in the workbook.
- *
- * @remarks
- * Read-only for now: a table is carried as it was read and written back unchanged. Adding,
- * deleting and refreshing wait on the table having a model of its own.
  */
 export interface IPivotTableCollection extends ICollection<IPivotTable> {
+    /**
+     * Adds a pivot table on this sheet, as one step that can be undone.
+     *
+     * @param source The cells to summarize, their first row the field names: a range, a table, or a
+     * table's or defined name's name. A table already summarizing the same source shares its cache
+     * unless the source was edited since, so they refresh together.
+     * @param location Where the table's top-left cell goes. Filters sit above it, a blank row between;
+     * at the top of a sheet the table moves down to make room for them.
+     * @param options The fields to place. With none, the table is empty and holds 18 rows by 3 columns.
+     *
+     * @remarks
+     * The cells the table needs, its filters' included, must hold no value, unless
+     * {@link IPivotTableCollection.AddOptions.discardValues} clears them. Another pivot table or an
+     * array's cells there always refuse it.
+     *
+     * @example
+     * ```ts
+     * const pivot = await sheet.getPivotTables().add('Data!A1:H500', 'A3', {
+     *   rows: ['Region'],
+     *   columns: ['Year'],
+     *   values: ['Sales', { field: 'Sales', function: 'average' }]
+     * });
+     * ```
+     *
+     * @throws When the cells it needs hold a value, an array or another pivot table, a field or the source does not
+     * exist, the source has no row of data, the name is taken on this sheet or the sheet is locked; and
+     * on the workbook's collection, which holds no sheet to add to.
+     */
+    add(source: IPivotTableCollection.Source, location: ICellRange.Address, options?: IPivotTableCollection.AddOptions): Promise<IPivotTable>;
     /**
      * Returns the pivot tables, in the order they were read; the workbook's walks its sheets in
      * sheet order.
@@ -17,9 +45,47 @@ export interface IPivotTableCollection extends ICollection<IPivotTable> {
      * Returns the pivot table with the given name, or `null` if there is none.
      *
      * @param name The name of the pivot table. This is case insensitive.
+     *
+     * @remarks
+     * A name is unique only on its sheet, so the workbook's collection returns the first table with
+     * that name in sheet order. Ask the sheet's collection to find one table for certain.
      */
     getByName(name: string): IPivotTable | null;
+    /**
+     * Refreshes every table ({@link IPivotTable.refresh}) as one step that can be undone.
+     *
+     * @remarks
+     * A table that cannot be refreshed refuses the whole step, and nothing changes.
+     */
+    refreshAll(options?: IPivotTable.RefreshOptions): Promise<void>;
     /** For runtime type checking. */
     readonly isIPivotTableCollection: true;
 }
+export declare namespace IPivotTableCollection {
+    /** What a pivot table summarizes. A string is a table's name, a defined name, or an address. */
+    type Source = ICellRange.Address | ITable;
+    /** Options for {@link IPivotTableCollection.add}. */
+    interface AddOptions extends ITransaction.OperationOptions {
+        /** Absent, `PivotTable` and one past the highest number the workbook's tables have. */
+        name?: string;
+        /** The fields down the rows, outermost first. */
+        rows?: readonly string[];
+        /** The fields across the columns, outermost first. */
+        columns?: readonly string[];
+        /** The fields above the table, each filtering it by an item. */
+        pages?: readonly string[];
+        /** The values. A field's name alone sums a column of numbers, blanks among them, and counts any other. */
+        values?: readonly (string | IPivotTable.IDataField.Input)[];
+        /** Absent, compact. */
+        form?: 'compact' | IPivotTable.PivotForm;
+        /** A pivot table style by name; absent, `PivotStyleLight16`. */
+        style?: string;
+        /**
+         * Whether values in the cells the table needs are cleared; `false` refuses the table instead.
+         *
+         * @defaultValue `false`
+         */
+        discardValues?: boolean;
+    }
+}
 //# sourceMappingURL=IPivotTableCollection.d.ts.map

package/types/src/pivot/PivotCache.d.ts

@@ -1,34 +1,118 @@
 import { IResource } from '../resource';
+import { ICellRange } from '../cellRange';
+import { ITable } from '../table';
 import { IEmbeddedPart } from '../io';
 import { AbstractMovableContent } from '../movable/AbstractMovableContent';
 import { IPivotTable } from './IPivotTable';
 /**
- * A pivot cache as the workbook holds it: the part it was read from, and its source held in the
- * calculation engine so it follows the cells it names.
+ * A pivot cache as the workbook holds it: its model and the part it was read from, and its source
+ * held in the calculation engine so it follows the cells it names.
  *
  * @remarks
  * The cache is workbook-level and shared by every table on it. Its `<cacheSource>
- * <worksheetSource ref sheet>` is the one thing in the part that names cells; it is held through
- * the seam of the sheet it names ({@link _hold}), once the sheets exist, and restated in place by
- * {@link getXML}. A source that is a defined name or an external book holds nothing and is
- * written as read.
+ * <worksheetSource>` is the one thing in the part that names cells. The reader types it as
+ * {@link IPivotTable.CacheJSON.source} whether or not the rest is modeled; it is held through the
+ * seam of the sheet it names ({@link _hold}), once the sheets exist, and {@link toJSON} gives it
+ * where it is now, for the writer to restate the part with. Excel's rules (`pivot-probes/probe-pivot-named-source.ps1`, 2026-10-24):
+ *
+ * - `ref sheet` follows the cells, as a formula's reference does;
+ * - `name`, naming a table, follows the table: a rename restates the name, and a table converted
+ *   to a range becomes the `ref sheet` it covered;
+ * - `name`, naming a defined name, is written as read: Excel does not follow a defined name's
+ *   rename or deletion either. An external book's source is written as read too.
  * @internal
  */
 export declare class PivotCache {
     readonly cacheId: number;
-    readonly part: IEmbeddedPart | null;
+    /** Where its contents live: the workbook's state, so a refresh is undone with the cells it wrote. */
+    private readonly _store;
     /** The source as the engine holds it; `null` while nothing is held. */
     private _source;
-    constructor(cacheId: number, part: IEmbeddedPart | null);
+    /**
+     * The contents the source's cells match: those read or refreshed since its last edit
+     * ({@link _watchSource}). A new set at each edit, so an undone refresh reads as stale.
+     */
+    private _fresh;
+    /** Stops watching the source; `null` while nothing is watched. */
+    private _unwatch;
+    constructor(cacheId: number, store: PivotCache.Store);
+    /** The contents of a cache's JSON. */
+    static dataOf(json: IPivotTable.CacheJSON, fromResourceId?: (resourceId: number) => IResource): PivotCache.Data;
+    /** The model of a cache's JSON, or `null` when it has none. */
+    static modelOf(json: IPivotTable.CacheJSON): PivotCache.Model | null;
+    /** The part as read, written while the cache is unchanged; `null` once it is refreshed. */
+    get part(): IEmbeddedPart | null;
+    /** The fields, items and records; `null` for a cache that is not modeled. */
+    private get _model();
+    /**
+     * The contents now, an immutable value: one identity per version, so what is derived from a
+     * cache can be kept against it.
+     */
+    _getData(): PivotCache.Data;
+    /**
+     * Replaces the contents with those a refresh from the source read, in the caller's commit: the
+     * part goes, and the cache is written from `model` from then on. The new contents match the
+     * source, and so do the old ones if nothing was edited since they were read.
+     */
+    _replace(model: PivotCache.Model): void;
+    /**
+     * Replaces the contents with the same records told apart differently, in the caller's commit: as
+     * {@link _replace}, but matching the source only if the old ones did.
+     */
+    _restate(model: PivotCache.Model): void;
     /**
      * Holds the source through the sheet it names. Asked once the sheets exist; a source naming no
      * sheet of the workbook is left as read.
      *
      * @param resolve The seam of the sheet with that name, or `null` when there is none.
+     * @param resolveTable The seam of the sheet the table with that name is on, or `null` when no
+     * table has it.
+     */
+    _hold(resolve: (sheetName: string) => AbstractMovableContent.AddWatch | null, resolveTable: (tableName: string) => AbstractMovableContent.AddWatch | null): void;
+    /** The source as read, the model's or, for a cache carried as its part, the one typed beside it; `null` when there is neither. */
+    private _sourceAsRead;
+    /**
+     * Marks the cache stale once its source's cells are edited: a value or formula written or
+     * cleared (an undo too), a row or column inserted or deleted inside it, or a table it names
+     * resized. A move that keeps its size does not, nor does a recalculation, nor a source naming no
+     * sheet or table of the workbook. Asked once the sheets exist; the records stay as they are, as
+     * Excel's do.
+     *
+     * @param resolve The range `ref` names on the sheet with that name, or `null` when there is none.
+     * @param resolveTable The table with that name, or `null` when there is none.
+     * @param resolveNamed The range a defined name refers to now, by its name and the sheet it is
+     * scoped to; `null` when there is no such name or it refers to no single range.
      */
-    _hold(resolve: (sheetName: string) => AbstractMovableContent.AddWatch | null): void;
-    /** The part's markup, its source restated where the engine has moved it. */
-    getXML(): string | null;
+    _watchSource(resolve: (sheetName: string, ref: string) => ICellRange | null, resolveTable: (tableName: string) => ITable | null, resolveNamed: (name: string, sheet: string | null) => ICellRange | null): void;
+    /** Whether the source's cells have been edited since the contents were read ({@link _watchSource}). */
+    _isStale(): boolean;
+    /** The source where the engine has moved it, or `null` while it is where it was read: `null` removes a key. */
+    private _moved;
+    /**
+     * The source where it is now: as read, restated where the engine has moved it; `null` when the
+     * cache names none.
+     */
+    _getSource(): IPivotTable.CacheSourceJSON | null;
     toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.CacheJSON;
 }
+export declare namespace PivotCache {
+    /** What a modeled cache's JSON holds besides its id and part. */
+    type Model = Omit<IPivotTable.CacheJSON, 'cacheId' | 'part' | 'partFormats'>;
+    /** A cache's contents: replaced whole, never changed in place. */
+    interface Data {
+        /** The part as read, written while the cache is unchanged. */
+        readonly part: IEmbeddedPart | null;
+        /** The fields, items and records; `null` for a cache that is not modeled. */
+        readonly model: Model | null;
+        /** What the part's format ids named when read, for a cache that is not modeled. */
+        readonly partFormats: IPivotTable.PartFormatsJSON | null;
+        /** The source as read, for a cache that is not modeled (a modeled one's is the model's). */
+        readonly source: IPivotTable.CacheSourceJSON | null;
+    }
+    /** Where a cache's contents are kept: read now, and replaced as a transactional change. */
+    interface Store {
+        get(): Data;
+        set(data: Data): void;
+    }
+}
 //# sourceMappingURL=PivotCache.d.ts.map

package/types/src/pivot/PivotDataField.d.ts

@@ -0,0 +1,73 @@
+import { ITransaction } from '../transaction';
+import { IPivotTable } from './IPivotTable';
+import { PivotTable } from './PivotTable';
+/**
+ * Implementation for {@link IPivotTable.IDataField}: a value of a table, found by its caption, which no
+ * other field of the table can hold, so it holds through moves and deletes of the others.
+ * @internal
+ */
+export declare class PivotDataField implements IPivotTable.IDataField {
+    private readonly _table;
+    private _name;
+    constructor(table: PivotTable, name: string);
+    /** Where it is in `model`. */
+    private _indexIn;
+    private _json;
+    /** Runs an edit over the field's place, and follows its caption. */
+    private _edit;
+    /** {@inheritDoc IPivotTable.IDataField.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.IDataField.setName} */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.getField} */
+    getField(): IPivotTable.IField;
+    /** {@inheritDoc IPivotTable.IDataField.getFunction} */
+    getFunction(): IPivotTable.IDataField.Function;
+    /** {@inheritDoc IPivotTable.IDataField.setFunction} */
+    setFunction(fn: IPivotTable.IDataField.Function, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.getCaptionFor} */
+    getCaptionFor(fn: IPivotTable.IDataField.Function): string;
+    /** {@inheritDoc IPivotTable.IDataField.getShowAs} */
+    getShowAs(): IPivotTable.IDataField.ShowAs | null;
+    /** {@inheritDoc IPivotTable.IDataField.setShowAs} */
+    setShowAs(rule: IPivotTable.IDataField.ShowAs | null, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.getNumberFormat} */
+    getNumberFormat(): string;
+    /** {@inheritDoc IPivotTable.IDataField.setNumberFormat} */
+    setNumberFormat(format: string | number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.getPosition} */
+    getPosition(): number;
+    /** {@inheritDoc IPivotTable.IDataField.setPosition} */
+    setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.delete} */
+    delete(options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IDataField.getPivotTable} */
+    getPivotTable(): IPivotTable;
+    /** {@inheritDoc IPivotTable.IDataField.isIPivotDataField} */
+    get isIPivotDataField(): true;
+}
+/**
+ * Implementation for {@link IPivotTable.IValuesField}: where a table's values sit.
+ * @internal
+ */
+export declare class PivotValuesField implements IPivotTable.IValuesField {
+    private readonly _table;
+    constructor(table: PivotTable);
+    /** {@inheritDoc IPivotTable.IValuesField.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.IValuesField.setName} */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IValuesField.getAxis} */
+    getAxis(): IPivotTable.Axis | null;
+    /** {@inheritDoc IPivotTable.IValuesField.setAxis} */
+    setAxis(axis: IPivotTable.Axis | null, position?: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IValuesField.getPosition} */
+    getPosition(): number | null;
+    /** {@inheritDoc IPivotTable.IValuesField.setPosition} */
+    setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IValuesField.getPivotTable} */
+    getPivotTable(): IPivotTable;
+    /** {@inheritDoc IPivotTable.IValuesField.isIPivotValuesField} */
+    get isIPivotValuesField(): true;
+}
+//# sourceMappingURL=PivotDataField.d.ts.map

package/types/src/pivot/PivotField.d.ts

@@ -0,0 +1,142 @@
+import { ITransaction } from '../transaction';
+import { IPivotTable } from './IPivotTable';
+import { PivotTable } from './PivotTable';
+/**
+ * Implementation for {@link IPivotTable.IField}: a field of a table by its index in the cache, reading
+ * the table's model on every call.
+ * @internal
+ */
+export declare class PivotField implements IPivotTable.IField {
+    readonly _table: PivotTable;
+    readonly _index: number;
+    constructor(table: PivotTable, index: number);
+    /** {@inheritDoc IPivotTable.IField.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.IField.getDataType} */
+    getDataType(): IPivotTable.IField.DataType;
+    /** {@inheritDoc IPivotTable.IField.getAxis} */
+    getAxis(): IPivotTable.Axis | null;
+    /** {@inheritDoc IPivotTable.IField.setAxis} */
+    setAxis(axis: IPivotTable.Axis | null, position?: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getPosition} */
+    getPosition(): number | null;
+    /** {@inheritDoc IPivotTable.IField.setPosition} */
+    setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** A property of the field's definition, or left out for `undefined`, laid out again. */
+    private _editField;
+    private _json;
+    /** {@inheritDoc IPivotTable.IField.getSubtotals} */
+    getSubtotals(): readonly IPivotTable.IField.Subtotal[];
+    /** {@inheritDoc IPivotTable.IField.setSubtotals} */
+    setSubtotals(subtotals: readonly IPivotTable.IField.Subtotal[], options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getForm} */
+    getForm(): 'compact' | IPivotTable.PivotForm;
+    /** {@inheritDoc IPivotTable.IField.setForm} */
+    setForm(form: 'compact' | IPivotTable.PivotForm, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getRepeatLabels} */
+    getRepeatLabels(): boolean;
+    /** {@inheritDoc IPivotTable.IField.setRepeatLabels} */
+    setRepeatLabels(repeat: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getBlankRowAfter} */
+    getBlankRowAfter(): boolean;
+    /** {@inheritDoc IPivotTable.IField.setBlankRowAfter} */
+    setBlankRowAfter(blank: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getSubtotalsOnTop} */
+    getSubtotalsOnTop(): boolean;
+    /** {@inheritDoc IPivotTable.IField.setSubtotalsOnTop} */
+    setSubtotalsOnTop(top: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** Whether every item is a number or date, the only fields a number format reaches. */
+    private _holdsOnlyNumbers;
+    /** {@inheritDoc IPivotTable.IField.getNumberFormat} */
+    getNumberFormat(): string;
+    /** {@inheritDoc IPivotTable.IField.setNumberFormat} */
+    setNumberFormat(format: string | number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getPivotTable} */
+    getPivotTable(): IPivotTable;
+    /** The captions of the field's items, by index into its listed items; `null` where an entry is not an item. */
+    _getCaptions(): (string | null)[];
+    /** The item listed at `rank`, by the cache item it is. */
+    private _itemAt;
+    /** {@inheritDoc IPivotTable.IField.getItems} */
+    getItems(): readonly IPivotTable.IItem[];
+    /** {@inheritDoc IPivotTable.IField.getItem} */
+    getItem(name: string): IPivotTable.IItem | null;
+    /** The index of each named item in the field's listed items. */
+    private _ranksOf;
+    /** {@inheritDoc IPivotTable.IField.setExpanded} */
+    setExpanded(expanded: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.setVisibleItems} */
+    setVisibleItems(names: readonly string[] | null, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getCurrentPage} */
+    getCurrentPage(): IPivotTable.IItem | null;
+    /** {@inheritDoc IPivotTable.IField.setCurrentPage} */
+    setCurrentPage(name: string | null, options?: ITransaction.OperationOptions): Promise<void>;
+    /** The field's definition in `model`. */
+    private _field;
+    /** Whether the field is on the rows or the columns, the axes a label, date or value filter and a sort apply to. */
+    private _isOnRowsOrColumns;
+    /** A data field's name: the table's, else its source field's. */
+    private _dataFieldName;
+    /** The data field with a name, by index. */
+    private _dataFieldOf;
+    /** The items shown when some are hidden by hand, or the page field's one pick; `null` when every item shows. */
+    private _shownByHand;
+    /** {@inheritDoc IPivotTable.IField.getFilters} */
+    getFilters(): IPivotTable.IField.Filters;
+    /** {@inheritDoc IPivotTable.IField.isFiltered} */
+    isFiltered(type?: IPivotTable.IField.FilterType): boolean;
+    /** {@inheritDoc IPivotTable.IField.applyFilter} */
+    applyFilter(filters: IPivotTable.IField.FilterInput, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.clearFilter} */
+    clearFilter(type: IPivotTable.IField.FilterType, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.clearAllFilters} */
+    clearAllFilters(options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getSort} */
+    getSort(): IPivotTable.IField.Sort | null;
+    /** {@inheritDoc IPivotTable.IField.sortByLabels} */
+    sortByLabels(order: 'ascending' | 'descending', options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.sortByValues} */
+    sortByValues(order: 'ascending' | 'descending', dataField: string, scope?: readonly string[] | null, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.getShowAllItems} */
+    getShowAllItems(): boolean;
+    /** {@inheritDoc IPivotTable.IField.setShowAllItems} */
+    setShowAllItems(showAllItems: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.setName} */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IField.isIPivotField} */
+    get isIPivotField(): true;
+}
+/**
+ * Implementation for {@link IPivotTable.IItem}: an item of a field by its index in the cache field's
+ * items, which a move or a sort of the listed items does not change.
+ * @internal
+ */
+export declare class PivotItem implements IPivotTable.IItem {
+    private readonly _field;
+    private readonly _index;
+    constructor(field: PivotField, index: number);
+    /** The item's place in the field's listed items, or -1 once it is listed no more. */
+    private _rank;
+    private _item;
+    /** {@inheritDoc IPivotTable.IItem.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.IItem.getField} */
+    getField(): IPivotTable.IField;
+    /** {@inheritDoc IPivotTable.IItem.isVisible} */
+    isVisible(): boolean;
+    /** {@inheritDoc IPivotTable.IItem.setVisible} */
+    setVisible(visible: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IItem.isExpanded} */
+    isExpanded(): boolean;
+    /** {@inheritDoc IPivotTable.IItem.setExpanded} */
+    setExpanded(expanded: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IItem.getPosition} */
+    getPosition(): number | null;
+    /** {@inheritDoc IPivotTable.IItem.setPosition} */
+    setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IItem.setName} */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.IItem.isIPivotItem} */
+    get isIPivotItem(): true;
+}
+//# sourceMappingURL=PivotField.d.ts.map