@cj-tech-master/excelts 5.0.6 → 5.1.0

package/dist/types/index.browser.d.ts

@@ -15,7 +15,7 @@ export { DataValidations } from "./modules/excel/data-validations.js";
 export { FormCheckbox } from "./modules/excel/form-control.js";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
-export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 import { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";
 import { WorkbookReader } from "./modules/excel/stream/workbook-reader.browser.js";

package/dist/types/index.d.ts

@@ -15,7 +15,7 @@ export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
 export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
-export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./modules/excel/stream/worksheet-reader.js";

package/dist/types/modules/excel/pivot-table.d.ts

@@ -6,21 +6,50 @@ import type { Table } from "./table.js";
 export interface PivotTableSource {
     /** Name of the worksheet containing the source data (used in pivotCacheDefinition) */
     name: string;
+    /**
+     * Name of the source Table (e.g., "SalesData").
+     * When present, pivotCacheDefinition uses `<worksheetSource name="..."/>` instead of ref+sheet.
+     */
+    tableName?: string;
     /** Get row values by 1-indexed row number */
     getRow(rowNumber: number): {
-        values: any[];
+        values: unknown[];
     };
     /** Get column values by 1-indexed column number */
     getColumn(columnNumber: number): {
-        values: any[];
+        values: unknown[];
     };
     /** Get all sheet values as a sparse 2D array */
-    getSheetValues(): any[][];
+    getSheetValues(): unknown[][];
     /** Dimensions with short range reference (e.g., "A1:E10") */
     dimensions: {
         shortRange: string;
     };
 }
+/**
+ * A value field specification with optional per-field metric override.
+ * Use this instead of a plain string when you need different aggregation
+ * metrics for individual value fields.
+ *
+ * @example
+ * ```ts
+ * values: [
+ *   { name: "Sales", metric: "sum" },
+ *   { name: "Quantity", metric: "count" },
+ *   { name: "Price", metric: "average" },
+ * ]
+ * ```
+ */
+export interface PivotTableValue {
+    /** Column name to aggregate */
+    name: string;
+    /**
+     * Aggregation metric for this specific value field.
+     * Overrides the table-wide `metric` when specified.
+     * @default inherited from PivotTableModel.metric (which defaults to 'sum')
+     */
+    metric?: PivotTableSubtotal;
+}
 /**
  * Model for creating a new pivot table.
  * Pass this to worksheet.addPivotTable() to create a pivot table.
@@ -42,18 +71,45 @@ export interface PivotTableModel {
     /**
      * Column names to use as column fields in the pivot table.
      * If omitted or empty, Excel will use "Values" as the column field.
+     * When multiple values are specified alongside columns, the synthetic
+     * "∑Values" pseudo-field is appended to the column axis automatically.
      * @default []
      */
     columns?: string[];
-    /** Column names to aggregate as values in the pivot table */
-    values: string[];
     /**
-     * Aggregation metric for the pivot table values.
-     * - 'sum': Sum of values (default)
-     * - 'count': Count of values
+     * Column names (or value field specifications) to aggregate in the pivot table.
+     * Each entry can be a plain string (column name) or a {@link PivotTableValue}
+     * object with a per-field metric override.
+     *
+     * @example
+     * ```ts
+     * // Simple: all values use the table-wide metric
+     * values: ["Sales", "Quantity"]
+     *
+     * // Per-value metrics
+     * values: [
+     *   { name: "Sales", metric: "sum" },
+     *   { name: "Quantity", metric: "count" },
+     *   { name: "Price", metric: "average" },
+     * ]
+     *
+     * // Mixed: plain strings inherit table-wide metric
+     * values: ["Sales", { name: "Quantity", metric: "count" }]
+     * ```
+     */
+    values: (string | PivotTableValue)[];
+    /**
+     * Column names to use as page fields (report filters) in the pivot table.
+     * Page fields appear as dropdown filters above the pivot table.
+     * @default []
+     */
+    pages?: string[];
+    /**
+     * Default aggregation metric for all value fields.
+     * Individual value fields can override this via {@link PivotTableValue.metric}.
      * @default 'sum'
      */
-    metric?: "sum" | "count";
+    metric?: PivotTableSubtotal;
     /**
      * Controls whether pivot table style overrides worksheet column widths.
      * - '0': Preserve worksheet column widths (useful for custom sizing)
@@ -62,6 +118,19 @@ export interface PivotTableModel {
      */
     applyWidthHeightFormats?: "0" | "1";
 }
+/** Allowed element types within CacheField.sharedItems */
+export type SharedItemValue = string | number | boolean | Date | PivotErrorValue | null;
+/**
+ * Wrapper for OOXML error values in sharedItems (e.g. `<e v="REF!"/>`).
+ * Distinguishes error strings from regular strings so they roundtrip as `<e>` not `<s>`.
+ */
+export declare class PivotErrorValue {
+    /** The error code without the leading '#' (e.g. "REF!", "VALUE!", "N/A") */
+    readonly code: string;
+    constructor(code: string);
+    /** Returns the display form with '#' prefix, e.g. "#REF!" */
+    toString(): string;
+}
 /**
  * Represents a cache field in a pivot table.
  * Cache fields store unique values from source columns for row/column grouping.
@@ -70,14 +139,42 @@ export interface CacheField {
     /** Name of the field (column header from source) */
     name: string;
     /** Unique values for row/column fields, null for value fields */
-    sharedItems: any[] | null;
+    sharedItems: SharedItemValue[] | null;
+    /** Whether the field contains numeric values (raw attribute string for roundtrip: "0" or "1") */
+    containsNumber?: string;
+    /** Whether the field contains only integer values (raw attribute string for roundtrip: "0" or "1") */
+    containsInteger?: string;
     /** Minimum value for numeric fields */
     minValue?: number;
     /** Maximum value for numeric fields */
     maxValue?: number;
+    /** Number format ID (preserved on roundtrip, defaults to "0") */
+    numFmtId?: string;
+    /** Original containsSemiMixedTypes attribute from loaded file */
+    containsSemiMixedTypes?: string;
+    /** Original containsNonDate attribute from loaded file */
+    containsNonDate?: string;
+    /** Original containsString attribute from loaded file */
+    containsString?: string;
+    /** Original containsBlank attribute from loaded file */
+    containsBlank?: string;
+    /** Original containsDate attribute from loaded file */
+    containsDate?: string;
+    /** Original containsMixedTypes attribute from loaded file */
+    containsMixedTypes?: string;
+    /** Flag indicating this cache field was loaded from file */
+    isLoaded?: boolean;
+    /** Preserved <fieldGroup> raw XML for roundtrip (loaded models only) */
+    fieldGroupXml?: string;
+    /** Bag of additional cacheField attributes not individually modeled (for roundtrip preservation) */
+    extraAttrs?: Record<string, string>;
 }
 /** Aggregation function types for pivot table data fields */
 export type PivotTableSubtotal = "sum" | "count" | "average" | "max" | "min" | "product" | "countNums" | "stdDev" | "stdDevP" | "var" | "varP";
+/** Map from PivotTableSubtotal to its Excel display name prefix */
+export declare const METRIC_DISPLAY_NAMES: Readonly<Record<PivotTableSubtotal, string>>;
+/** Set of all valid PivotTableSubtotal values (for runtime validation) */
+export declare const VALID_SUBTOTALS: ReadonlySet<string>;
 /**
  * Data field configuration for pivot table aggregation.
  * Defines how values are aggregated in the pivot table.
@@ -93,6 +190,8 @@ export interface DataField {
     baseItem?: number;
     /** Aggregation function (default: 'sum') */
     subtotal?: PivotTableSubtotal;
+    /** Number format ID (preserved on roundtrip for currency/date formatting) */
+    numFmtId?: number;
 }
 /**
  * Internal pivot table representation used by the library.
@@ -107,8 +206,12 @@ export interface PivotTable {
     columns: number[];
     /** Field indices for value fields */
     values: number[];
-    /** Aggregation metric */
-    metric: "sum" | "count";
+    /** Field indices for page fields (report filters) */
+    pages?: number[];
+    /** Default aggregation metric */
+    metric: PivotTableSubtotal;
+    /** Per-value metric overrides (parallel to `values` array). Falls back to `metric`. */
+    valueMetrics: PivotTableSubtotal[];
     /** Cache fields with shared items */
     cacheFields: CacheField[];
     /** Cache ID for linking to pivot cache */
@@ -117,6 +220,8 @@ export interface PivotTable {
     applyWidthHeightFormats: "0" | "1";
     /** 1-indexed table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.) */
     tableNumber: number;
+    /** Workbook relationship ID, assigned during write by addWorkbookRels() */
+    rId?: string;
     /** Flag indicating this pivot table was loaded from file (not newly created) */
     isLoaded?: boolean;
     /** Data fields for loaded pivot tables */
@@ -132,21 +237,67 @@ export interface PivotTable {
 export interface ParsedCacheDefinition {
     sourceRef?: string;
     sourceSheet?: string;
+    /** Source table name (name style - references a named Table) */
+    sourceTableName?: string;
+    /** Cache source type (default "worksheet") */
+    cacheSourceType?: string;
     cacheFields: CacheField[];
     recordCount?: number;
     rId?: string;
+    /** Additional attributes to preserve */
+    refreshOnLoad?: string;
+    createdVersion?: string;
+    refreshedVersion?: string;
+    minRefreshableVersion?: string;
     isLoaded?: boolean;
+    backgroundQuery?: string;
+    supportSubquery?: string;
+    supportAdvancedDrill?: string;
+    /** Bag of additional root attributes not individually modeled (for roundtrip) */
+    extraRootAttrs?: Record<string, string>;
+    /** worksheetSource r:id attribute (for external connections) */
+    worksheetSourceRId?: string;
+    extLstXml?: string;
+    /** Preserved unknown child elements XML for roundtrip (e.g. calculatedItems, cacheHierarchies) */
+    unknownElementsXml?: string;
+    /** Preserved raw XML for non-worksheetSource children inside <cacheSource> (e.g. <consolidation>) */
+    cacheSourceXml?: string;
 }
+/** Allowed element types within cache record values */
+export type RecordValue = {
+    type: "x";
+    value: number;
+} | {
+    type: "n";
+    value: number;
+} | {
+    type: "s";
+    value: string;
+} | {
+    type: "b";
+    value: boolean;
+} | {
+    type: "m";
+} | {
+    type: "d";
+    value: Date;
+} | {
+    type: "e";
+    value: string;
+};
 /**
  * Parsed cache records from loaded pivot table files.
  */
 export interface ParsedCacheRecords {
-    records: Array<Array<{
-        type: string;
-        value?: any;
-    }>>;
+    records: RecordValue[][];
     count: number;
     isLoaded?: boolean;
+    /** Extra root attributes beyond xmlns/xmlns:r/count (for roundtrip preservation) */
+    extraRootAttrs?: Record<string, string>;
 }
-declare function makePivotTable(worksheet: any, model: PivotTableModel): PivotTable;
+declare function makePivotTable(worksheet: {
+    workbook: {
+        pivotTables: PivotTable[];
+    };
+}, model: PivotTableModel): PivotTable;
 export { makePivotTable };

package/dist/types/modules/excel/types.d.ts

@@ -454,10 +454,6 @@ export interface ConditionalFormattingOptions {
     ref: string;
     rules: ConditionalFormattingRule[];
 }
-export interface ConditionalFormattingOptions {
-    ref: string;
-    rules: ConditionalFormattingRule[];
-}
 export interface TableStyleProperties {
     theme?: string;
     showFirstColumn?: boolean;

package/dist/types/modules/excel/workbook.d.ts

@@ -52,8 +52,6 @@ export interface WorkbookModel {
     themes?: unknown;
     media: WorkbookMedia[];
     pivotTables: PivotTable[];
-    /** Loaded pivot tables from file - used during reconciliation */
-    loadedPivotTables?: any[];
     calcProperties: Partial<CalculationProperties>;
     /** Passthrough files (charts, etc.) preserved for round-trip */
     passthrough?: Record<string, Uint8Array>;

package/dist/types/modules/excel/xlsx/xform/base-xform.d.ts

@@ -3,11 +3,11 @@ interface ParseEvent {
     eventType: string;
     value: any;
 }
-declare class BaseXform {
+declare class BaseXform<TModel = any> {
     map?: {
         [key: string]: any;
     };
-    model?: any;
+    model?: TModel;
     prepare(_model?: any, _options?: any): void;
     render(_xmlStream?: XmlStream, _model?: any): void;
     parseOpen(_node: any): void;
@@ -16,10 +16,10 @@ declare class BaseXform {
     reconcile(_model: any, _options?: any): void;
     reset(): void;
     mergeModel(obj: any): void;
-    parse(saxParser: AsyncIterable<ParseEvent[]>): Promise<any>;
-    parseStream(stream: any): Promise<any>;
+    parse(saxParser: AsyncIterable<ParseEvent[]>): Promise<TModel | undefined>;
+    parseStream(stream: any): Promise<TModel | undefined>;
     get xml(): string;
-    toXml(model: any): string;
+    toXml(model?: any): string;
     static toAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
     static toStringAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
     static toStringValue(attr: any, dflt?: any): any;

package/dist/types/modules/excel/xlsx/xform/comment/comment-xform.d.ts

@@ -13,8 +13,7 @@ interface CommentModel {
     ref: string;
     authorId?: number;
 }
-declare class CommentXform extends BaseXform {
-    model: CommentModel;
+declare class CommentXform extends BaseXform<CommentModel> {
     parser: any;
     private _richTextXform?;
     constructor(model?: CommentModel);

package/dist/types/modules/excel/xlsx/xform/comment/comments-xform.d.ts

@@ -3,12 +3,11 @@ import { CommentXform } from "./comment-xform.js";
 interface CommentsModel {
     comments: any[];
 }
-declare class CommentsXform extends BaseXform {
+declare class CommentsXform extends BaseXform<CommentsModel> {
     map: {
         [key: string]: CommentXform;
     };
     parser: any;
-    model: CommentsModel;
     constructor();
     render(xmlStream: any, model?: CommentsModel): void;
     parseOpen(node: any): boolean;

package/dist/types/modules/excel/xlsx/xform/comment/style/vml-position-xform.d.ts

@@ -1,9 +1,8 @@
 import { BaseXform } from "../../base-xform.js";
-declare class VmlPositionXform extends BaseXform {
+declare class VmlPositionXform extends BaseXform<{
+    [key: string]: boolean;
+}> {
     private _model;
-    model: {
-        [key: string]: boolean;
-    };
     constructor(model?: {
         tag?: string;
     });

package/dist/types/modules/excel/xlsx/xform/comment/vml-client-data-xform.d.ts

@@ -18,12 +18,11 @@ interface RenderModel {
         col: number;
     };
 }
-declare class VmlClientDataXform extends BaseXform {
+declare class VmlClientDataXform extends BaseXform<ClientDataModel> {
     map: {
         [key: string]: any;
     };
     parser: any;
-    model: ClientDataModel;
     constructor();
     get tag(): string;
     render(xmlStream: any, model: RenderModel): void;

package/dist/types/modules/excel/xlsx/xform/comment/vml-notes-xform.d.ts

@@ -2,12 +2,11 @@ import { BaseXform } from "../base-xform.js";
 interface VmlNotesModel {
     comments: any[];
 }
-declare class VmlNotesXform extends BaseXform {
+declare class VmlNotesXform extends BaseXform<VmlNotesModel> {
     map: {
         [key: string]: any;
     };
     parser: any;
-    model: VmlNotesModel;
     constructor();
     get tag(): string;
     render(xmlStream: any, model?: VmlNotesModel): void;

package/dist/types/modules/excel/xlsx/xform/comment/vml-textbox-xform.d.ts

@@ -9,8 +9,7 @@ interface TextboxModel {
     note?: NoteModel;
     inset?: number[];
 }
-declare class VmlTextboxXform extends BaseXform {
-    model: TextboxModel;
+declare class VmlTextboxXform extends BaseXform<TextboxModel> {
     constructor();
     get tag(): string;
     conversionUnit(value: string | number, multiple: number, unit: string): string;

package/dist/types/modules/excel/xlsx/xform/composite-xform.d.ts

@@ -1,5 +1,5 @@
 import { BaseXform } from "./base-xform.js";
-declare class CompositeXform extends BaseXform {
+declare class CompositeXform<TModel = any> extends BaseXform<TModel> {
     parser?: any;
     createNewModel(_node?: any): any;
     parseOpen(node: any): boolean;

package/dist/types/modules/excel/xlsx/xform/drawing/blip-xform.d.ts

@@ -2,8 +2,7 @@ import { BaseXform } from "../base-xform.js";
 interface BlipModel {
     rId: string;
 }
-declare class BlipXform extends BaseXform {
-    model: BlipModel;
+declare class BlipXform extends BaseXform<BlipModel> {
     constructor();
     get tag(): string;
     render(xmlStream: any, model: BlipModel): void;

package/dist/types/modules/excel/xlsx/xform/drawing/cell-position-xform.d.ts

@@ -6,13 +6,12 @@ interface PositionModel {
     nativeRow: number;
     nativeRowOff: number;
 }
-declare class CellPositionXform extends BaseXform {
+declare class CellPositionXform extends BaseXform<PositionModel> {
     private tag;
     map: {
         [key: string]: IntegerXform;
     };
     parser: any;
-    model: PositionModel;
     constructor(options: {
         tag: string;
     });

package/dist/types/modules/excel/xlsx/xform/drawing/ctrl-prop-xform.d.ts

@@ -6,8 +6,7 @@ import type { FormCheckboxModel } from "../../../form-control.js";
  * Each form control (checkbox, button, etc.) has an associated ctrlProp file
  * that stores its properties like objectType, checked state, and linked cell.
  */
-declare class CtrlPropXform extends BaseXform {
-    model: FormCheckboxModel;
+declare class CtrlPropXform extends BaseXform<FormCheckboxModel> {
     private _checkedToXmlValue;
     get tag(): string;
     render(xmlStream: any, model?: FormCheckboxModel): void;

package/dist/types/modules/excel/xlsx/xform/drawing/drawing-xform.d.ts

@@ -2,12 +2,11 @@ import { BaseXform } from "../base-xform.js";
 interface DrawingModel {
     anchors: any[];
 }
-declare class DrawingXform extends BaseXform {
+declare class DrawingXform extends BaseXform<DrawingModel> {
     map: {
         [key: string]: any;
     };
     parser: any;
-    model: DrawingModel;
     constructor();
     prepare(model: DrawingModel): void;
     get tag(): string;

package/dist/types/modules/excel/xlsx/xform/drawing/ext-xform.d.ts

@@ -3,12 +3,11 @@ interface ExtModel {
     width: number;
     height: number;
 }
-declare class ExtXform extends BaseXform {
+declare class ExtXform extends BaseXform<ExtModel> {
     private tag;
     map: {
         [key: string]: any;
     };
-    model: ExtModel;
     constructor(options: {
         tag: string;
     });

package/dist/types/modules/excel/xlsx/xform/drawing/vml-drawing-xform.d.ts

@@ -15,12 +15,11 @@ interface VmlDrawingModel {
     /** Form control checkboxes */
     formControls?: FormCheckboxModel[];
 }
-declare class VmlDrawingXform extends BaseXform {
+declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
     map: {
         [key: string]: any;
     };
     parser: any;
-    model: VmlDrawingModel;
     constructor();
     get tag(): string;
     /**

package/dist/types/modules/excel/xlsx/xform/list-xform.d.ts

@@ -9,7 +9,7 @@ interface ListXformOptions {
     childXform: any;
     maxItems?: number;
 }
-declare class ListXform extends BaseXform {
+declare class ListXform<TChild = any> extends BaseXform<TChild[]> {
     protected tag: string;
     protected always: boolean;
     protected count?: boolean;
@@ -19,7 +19,6 @@ declare class ListXform extends BaseXform {
     protected childXform: any;
     protected maxItems?: number;
     parser: any;
-    model: any[];
     constructor(options: ListXformOptions);
     prepare(model: any[], options: any): void;
     render(xmlStream: any, model?: any[]): void;

package/dist/types/modules/excel/xlsx/xform/pivot-table/cache-field-xform.d.ts

@@ -1,15 +1,5 @@
 import { BaseXform } from "../base-xform.js";
-/**
- * Parsed cache field model containing name and shared items (if any)
- */
-interface CacheFieldModel {
-    name: string;
-    sharedItems: any[] | null;
-    containsNumber?: boolean;
-    containsInteger?: boolean;
-    minValue?: number;
-    maxValue?: number;
-}
+import type { CacheField } from "../../../pivot-table.js";
 /**
  * Xform for parsing individual <cacheField> elements within a pivot cache definition.
  *
@@ -29,14 +19,14 @@ interface CacheFieldModel {
  * </cacheField>
  * ```
  */
-declare class CacheFieldXform extends BaseXform {
-    model: CacheFieldModel | null;
+declare class CacheFieldXform extends BaseXform<CacheField | null> {
     private inSharedItems;
+    private fieldGroupCollector;
     constructor();
     get tag(): string;
     reset(): void;
     parseOpen(node: any): boolean;
-    parseText(_text: string): void;
+    parseText(text: string): void;
     parseClose(name: string): boolean;
 }
-export { CacheFieldXform, type CacheFieldModel };
+export { CacheFieldXform };

package/dist/types/modules/excel/xlsx/xform/pivot-table/cache-field.d.ts

@@ -1,15 +1,14 @@
-interface CacheFieldConfig {
-    name: string;
-    sharedItems: any[] | null;
-    minValue?: number;
-    maxValue?: number;
-}
-declare class CacheField {
-    private name;
-    private sharedItems;
-    private minValue?;
-    private maxValue?;
-    constructor({ name, sharedItems, minValue, maxValue }: CacheFieldConfig);
-    render(): string;
-}
-export { CacheField };
+import type { CacheField as CacheFieldType } from "../../../pivot-table.js";
+/**
+ * Format a Date for OOXML pivot cache output.
+ * Excel expects `"2024-01-15T00:00:00"` — no milliseconds, no trailing "Z".
+ */
+declare function formatDateForExcel(date: Date): string;
+/**
+ * Render a single `<cacheField>` element as an XML string.
+ *
+ * This is a pure data-in → string-out transformation with no state or lifecycle,
+ * so it is a plain function rather than a class.
+ */
+declare function renderCacheField(cf: CacheFieldType): string;
+export { renderCacheField, formatDateForExcel };