@niicojs/excel 0.2.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niicojs/excel",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "typescript library to manipulate excel files",
   "homepage": "https://github.com/niicojs/excel#readme",
   "bugs": {

package/src/index.ts

@@ -7,6 +7,8 @@ export { SharedStrings } from './shared-strings';
 export { Styles } from './styles';
 export { PivotTable } from './pivot-table';
 export { PivotCache } from './pivot-cache';
+export { Table } from './table';
+export { parseAddress, toAddress, parseRange, toRange } from './utils/address';
 
 // Type exports
 export type {
@@ -20,11 +22,18 @@ export type {
   BorderStyle,
   BorderType,
   Alignment,
+  DateHandling,
   // Pivot table types
   PivotTableConfig,
   PivotValueConfig,
   AggregationType,
   PivotFieldAxis,
+  PivotSortOrder,
+  PivotFieldFilter,
+  // Table types
+  TableConfig,
+  TableStyleConfig,
+  TableTotalFunction,
   // Sheet from data types
   SheetFromDataConfig,
   ColumnConfig,
@@ -34,4 +43,3 @@ export type {
 } from './types';
 
 // Utility exports
-export { parseAddress, toAddress, parseRange, toRange } from './utils/address';

package/src/pivot-cache.ts

@@ -7,6 +7,7 @@ import { createElement, stringifyXml, XmlNode } from './utils/xml';
  */
 export class PivotCache {
   private _cacheId: number;
+  private _fileIndex: number;
   private _sourceSheet: string;
   private _sourceRange: string;
   private _fields: PivotCacheField[] = [];
@@ -16,8 +17,9 @@ export class PivotCache {
   // Optimized lookup: Map<fieldIndex, Map<stringValue, sharedItemsIndex>>
   private _sharedItemsIndexMap: Map<number, Map<string, number>> = new Map();
 
-  constructor(cacheId: number, sourceSheet: string, sourceRange: string) {
+  constructor(cacheId: number, sourceSheet: string, sourceRange: string, fileIndex: number) {
     this._cacheId = cacheId;
+    this._fileIndex = fileIndex;
     this._sourceSheet = sourceSheet;
     this._sourceRange = sourceRange;
   }
@@ -29,6 +31,13 @@ export class PivotCache {
     return this._cacheId;
   }
 
+  /**
+   * Get the file index for this cache (used for file naming).
+   */
+  get fileIndex(): number {
+    return this._fileIndex;
+  }
+
   /**
    * Set refreshOnLoad option
    */

package/src/pivot-table.ts

@@ -1,4 +1,4 @@
-import type { AggregationType, PivotFieldAxis } from './types';
+import type { AggregationType, PivotFieldAxis, PivotFieldFilter, PivotSortOrder, PivotValueConfig } from './types';
 import type { Styles } from './styles';
 import { PivotCache } from './pivot-cache';
 import { createElement, stringifyXml, XmlNode } from './utils/xml';
@@ -12,7 +12,9 @@ interface FieldAssignment {
   axis: PivotFieldAxis;
   aggregation?: AggregationType;
   displayName?: string;
-  numberFormat?: string;
+  numFmtId?: number;
+  sortOrder?: PivotSortOrder;
+  filter?: PivotFieldFilter;
 }
 
 /**
@@ -30,8 +32,10 @@ export class PivotTable {
   private _columnFields: FieldAssignment[] = [];
   private _valueFields: FieldAssignment[] = [];
   private _filterFields: FieldAssignment[] = [];
+  private _fieldAssignments: Map<number, FieldAssignment> = new Map();
 
   private _pivotTableIndex: number;
+  private _cacheFileIndex: number;
   private _styles: Styles | null = null;
 
   constructor(
@@ -42,6 +46,7 @@ export class PivotTable {
     targetRow: number,
     targetCol: number,
     pivotTableIndex: number,
+    cacheFileIndex: number,
   ) {
     this._name = name;
     this._cache = cache;
@@ -50,6 +55,7 @@ export class PivotTable {
     this._targetRow = targetRow;
     this._targetCol = targetCol;
     this._pivotTableIndex = pivotTableIndex;
+    this._cacheFileIndex = cacheFileIndex;
   }
 
   /**
@@ -87,6 +93,14 @@ export class PivotTable {
     return this._pivotTableIndex;
   }
 
+  /**
+   * Get the pivot cache file index used for rels.
+   * @internal
+   */
+  get cacheFileIndex(): number {
+    return this._cacheFileIndex;
+  }
+
   /**
    * Set the styles reference for number format resolution
    * @internal
@@ -106,11 +120,13 @@ export class PivotTable {
       throw new Error(`Field not found in source data: ${fieldName}`);
     }
 
-    this._rowFields.push({
+    const assignment: FieldAssignment = {
       fieldName,
       fieldIndex,
       axis: 'row',
-    });
+    };
+    this._rowFields.push(assignment);
+    this._fieldAssignments.set(fieldIndex, assignment);
 
     return this;
   }
@@ -125,43 +141,80 @@ export class PivotTable {
       throw new Error(`Field not found in source data: ${fieldName}`);
     }
 
-    this._columnFields.push({
+    const assignment: FieldAssignment = {
       fieldName,
       fieldIndex,
       axis: 'column',
-    });
+    };
+    this._columnFields.push(assignment);
+    this._fieldAssignments.set(fieldIndex, assignment);
 
     return this;
   }
 
   /**
-   * Add a field to the values area with aggregation
-   * @param fieldName - Name of the source field (column header)
-   * @param aggregation - Aggregation function (sum, count, average, min, max)
-   * @param displayName - Optional display name (defaults to "Sum of FieldName")
-   * @param numberFormat - Optional number format (e.g., '$#,##0.00', '0.00%')
+   * Add a field to the values area with aggregation.
+   *
+   * Supports two call signatures:
+   * - Positional: `addValueField(fieldName, aggregation?, displayName?, numberFormat?)`
+   * - Object: `addValueField({ field, aggregation?, name?, numberFormat? })`
+   *
+   * @example
+   * // Positional arguments
+   * pivot.addValueField('Sales', 'sum', 'Total Sales', '$#,##0.00');
+   *
+   * // Object form
+   * pivot.addValueField({ field: 'Sales', aggregation: 'sum', name: 'Total Sales', numberFormat: '$#,##0.00' });
    */
+  addValueField(config: PivotValueConfig): this;
+  addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string, numberFormat?: string): this;
   addValueField(
-    fieldName: string,
+    fieldNameOrConfig: string | PivotValueConfig,
     aggregation: AggregationType = 'sum',
     displayName?: string,
     numberFormat?: string,
   ): this {
+    // Normalize arguments to a common form
+    let fieldName: string;
+    let agg: AggregationType;
+    let name: string | undefined;
+    let format: string | undefined;
+
+    if (typeof fieldNameOrConfig === 'object') {
+      fieldName = fieldNameOrConfig.field;
+      agg = fieldNameOrConfig.aggregation ?? 'sum';
+      name = fieldNameOrConfig.name;
+      format = fieldNameOrConfig.numberFormat;
+    } else {
+      fieldName = fieldNameOrConfig;
+      agg = aggregation;
+      name = displayName;
+      format = numberFormat;
+    }
+
     const fieldIndex = this._cache.getFieldIndex(fieldName);
     if (fieldIndex < 0) {
       throw new Error(`Field not found in source data: ${fieldName}`);
     }
 
-    const defaultName = `${aggregation.charAt(0).toUpperCase() + aggregation.slice(1)} of ${fieldName}`;
+    const defaultName = `${agg.charAt(0).toUpperCase() + agg.slice(1)} of ${fieldName}`;
+
+    // Resolve numFmtId immediately if format is provided and styles are available
+    let numFmtId: number | undefined;
+    if (format && this._styles) {
+      numFmtId = this._styles.getOrCreateNumFmtId(format);
+    }
 
-    this._valueFields.push({
+    const assignment: FieldAssignment = {
       fieldName,
       fieldIndex,
       axis: 'value',
-      aggregation,
-      displayName: displayName || defaultName,
-      numberFormat,
-    });
+      aggregation: agg,
+      displayName: name || defaultName,
+      numFmtId,
+    };
+    this._valueFields.push(assignment);
+    this._fieldAssignments.set(fieldIndex, assignment);
 
     return this;
   }
@@ -176,12 +229,61 @@ export class PivotTable {
       throw new Error(`Field not found in source data: ${fieldName}`);
     }
 
-    this._filterFields.push({
+    const assignment: FieldAssignment = {
       fieldName,
       fieldIndex,
       axis: 'filter',
-    });
+    };
+    this._filterFields.push(assignment);
+    this._fieldAssignments.set(fieldIndex, assignment);
+
+    return this;
+  }
+
+  /**
+   * Set a sort order for a row or column field
+   * @param fieldName - Name of the field to sort
+   * @param order - Sort order ('asc' or 'desc')
+   */
+  sortField(fieldName: string, order: PivotSortOrder): this {
+    const fieldIndex = this._cache.getFieldIndex(fieldName);
+    if (fieldIndex < 0) {
+      throw new Error(`Field not found in source data: ${fieldName}`);
+    }
+
+    const assignment = this._fieldAssignments.get(fieldIndex);
+    if (!assignment) {
+      throw new Error(`Field is not assigned to pivot table: ${fieldName}`);
+    }
+    if (assignment.axis !== 'row' && assignment.axis !== 'column') {
+      throw new Error(`Sort is only supported for row or column fields: ${fieldName}`);
+    }
+
+    assignment.sortOrder = order;
+    return this;
+  }
+
+  /**
+   * Filter items for a row, column, or filter field
+   * @param fieldName - Name of the field to filter
+   * @param filter - Filter configuration with include or exclude list
+   */
+  filterField(fieldName: string, filter: PivotFieldFilter): this {
+    const fieldIndex = this._cache.getFieldIndex(fieldName);
+    if (fieldIndex < 0) {
+      throw new Error(`Field not found in source data: ${fieldName}`);
+    }
+
+    const assignment = this._fieldAssignments.get(fieldIndex);
+    if (!assignment) {
+      throw new Error(`Field is not assigned to pivot table: ${fieldName}`);
+    }
+
+    if (filter.include && filter.exclude) {
+      throw new Error('Cannot use both include and exclude in the same filter');
+    }
 
+    assignment.filter = filter;
     return this;
   }
 
@@ -279,9 +381,9 @@ export class PivotTable {
           subtotal: f.aggregation || 'sum',
         };
 
-        // Add numFmtId if format specified and styles available
-        if (f.numberFormat && this._styles) {
-          attrs.numFmtId = String(this._styles.getOrCreateNumFmtId(f.numberFormat));
+        // Add numFmtId if it was resolved during addValueField
+        if (f.numFmtId !== undefined) {
+          attrs.numFmtId = String(f.numFmtId);
         }
 
         return createElement('dataField', attrs, []);
@@ -290,7 +392,7 @@ export class PivotTable {
     }
 
     // Check if any value field has a number format
-    const hasNumberFormats = this._valueFields.some((f) => f.numberFormat);
+    const hasNumberFormats = this._valueFields.some((f) => f.numFmtId !== undefined);
 
     // Pivot table style
     children.push(
@@ -353,30 +455,36 @@ export class PivotTable {
     const filterField = this._filterFields.find((f) => f.fieldIndex === fieldIndex);
     const valueField = this._valueFields.find((f) => f.fieldIndex === fieldIndex);
 
+    // Get the assignment to check for sort/filter options
+    const assignment = rowField || colField || filterField;
+
     if (rowField) {
       attrs.axis = 'axisRow';
       attrs.showAll = '0';
+
+      // Add sort order if specified
+      if (rowField.sortOrder) {
+        attrs.sortType = rowField.sortOrder === 'asc' ? 'ascending' : 'descending';
+      }
+
       // Add items for shared values
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
-        const itemNodes: XmlNode[] = [];
-        for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
-        }
-        // Add default subtotal item
-        itemNodes.push(createElement('item', { t: 'default' }, []));
+        const itemNodes = this._buildItemNodes(cacheField.sharedItems, assignment?.filter);
         children.push(createElement('items', { count: String(itemNodes.length) }, itemNodes));
       }
     } else if (colField) {
       attrs.axis = 'axisCol';
       attrs.showAll = '0';
+
+      // Add sort order if specified
+      if (colField.sortOrder) {
+        attrs.sortType = colField.sortOrder === 'asc' ? 'ascending' : 'descending';
+      }
+
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
-        const itemNodes: XmlNode[] = [];
-        for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
-        }
-        itemNodes.push(createElement('item', { t: 'default' }, []));
+        const itemNodes = this._buildItemNodes(cacheField.sharedItems, assignment?.filter);
         children.push(createElement('items', { count: String(itemNodes.length) }, itemNodes));
       }
     } else if (filterField) {
@@ -384,11 +492,7 @@ export class PivotTable {
       attrs.showAll = '0';
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
-        const itemNodes: XmlNode[] = [];
-        for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
-        }
-        itemNodes.push(createElement('item', { t: 'default' }, []));
+        const itemNodes = this._buildItemNodes(cacheField.sharedItems, assignment?.filter);
         children.push(createElement('items', { count: String(itemNodes.length) }, itemNodes));
       }
     } else if (valueField) {
@@ -401,6 +505,38 @@ export class PivotTable {
     return createElement('pivotField', attrs, children);
   }
 
+  /**
+   * Build item nodes for a pivot field, with optional filtering
+   */
+  private _buildItemNodes(sharedItems: string[], filter?: PivotFieldFilter): XmlNode[] {
+    const itemNodes: XmlNode[] = [];
+
+    for (let i = 0; i < sharedItems.length; i++) {
+      const itemValue = sharedItems[i];
+      const itemAttrs: Record<string, string> = { x: String(i) };
+
+      // Check if this item should be hidden
+      if (filter) {
+        let hidden = false;
+        if (filter.exclude && filter.exclude.includes(itemValue)) {
+          hidden = true;
+        } else if (filter.include && !filter.include.includes(itemValue)) {
+          hidden = true;
+        }
+        if (hidden) {
+          itemAttrs.h = '1';
+        }
+      }
+
+      itemNodes.push(createElement('item', itemAttrs, []));
+    }
+
+    // Add default subtotal item
+    itemNodes.push(createElement('item', { t: 'default' }, []));
+
+    return itemNodes;
+  }
+
   /**
    * Build row items based on unique values in row fields
    */

package/src/range.ts

@@ -42,12 +42,25 @@ export class Range {
    * Get all values in the range as a 2D array
    */
   get values(): CellValue[][] {
+    return this.getValues();
+  }
+
+  /**
+   * Get all values in the range as a 2D array with options
+   */
+  getValues(options: { createMissing?: boolean } = {}): CellValue[][] {
+    const { createMissing = true } = options;
     const result: CellValue[][] = [];
     for (let r = this._range.start.row; r <= this._range.end.row; r++) {
       const row: CellValue[] = [];
       for (let c = this._range.start.col; c <= this._range.end.col; c++) {
-        const cell = this._worksheet.cell(r, c);
-        row.push(cell.value);
+        if (createMissing) {
+          const cell = this._worksheet.cell(r, c);
+          row.push(cell.value);
+        } else {
+          const cell = this._worksheet.getCellIfExists(r, c);
+          row.push(cell?.value ?? null);
+        }
       }
       result.push(row);
     }

package/src/shared-strings.ts

@@ -1,13 +1,23 @@
-import { parseXml, findElement, getChildren, XmlNode, stringifyXml, createElement, createText } from './utils/xml';
+import {
+  parseXml,
+  findElement,
+  getChildren,
+  getAttr,
+  XmlNode,
+  stringifyXml,
+  createElement,
+  createText,
+} from './utils/xml';
 
 /**
  * Manages the shared strings table from xl/sharedStrings.xml
  * Excel stores strings in a shared table to reduce file size
  */
 export class SharedStrings {
-  private strings: string[] = [];
+  private entries: SharedStringEntry[] = [];
   private stringToIndex: Map<string, number> = new Map();
   private _dirty = false;
+  private _totalCount = 0;
 
   /**
    * Parse shared strings from XML content
@@ -18,16 +28,28 @@ export class SharedStrings {
     const sst = findElement(parsed, 'sst');
     if (!sst) return ss;
 
+    const countAttr = getAttr(sst, 'count');
+    if (countAttr) {
+      const total = parseInt(countAttr, 10);
+      if (Number.isFinite(total) && total >= 0) {
+        ss._totalCount = total;
+      }
+    }
+
     const children = getChildren(sst, 'sst');
     for (const child of children) {
       if ('si' in child) {
         const siChildren = getChildren(child, 'si');
         const text = ss.extractText(siChildren);
-        ss.strings.push(text);
-        ss.stringToIndex.set(text, ss.strings.length - 1);
+        ss.entries.push({ text, node: child });
+        ss.stringToIndex.set(text, ss.entries.length - 1);
       }
     }
 
+    if (ss._totalCount === 0 && ss.entries.length > 0) {
+      ss._totalCount = ss.entries.length;
+    }
+
     return ss;
   }
 
@@ -68,7 +90,7 @@ export class SharedStrings {
    * Get a string by index
    */
   getString(index: number): string | undefined {
-    return this.strings[index];
+    return this.entries[index]?.text;
   }
 
   /**
@@ -78,11 +100,18 @@ export class SharedStrings {
   addString(str: string): number {
     const existing = this.stringToIndex.get(str);
     if (existing !== undefined) {
+      this._totalCount++;
+      this._dirty = true;
       return existing;
     }
-    const index = this.strings.length;
-    this.strings.push(str);
+    const index = this.entries.length;
+    const tElement = createElement('t', str.startsWith(' ') || str.endsWith(' ') ? { 'xml:space': 'preserve' } : {}, [
+      createText(str),
+    ]);
+    const siElement = createElement('si', {}, [tElement]);
+    this.entries.push({ text: str, node: siElement });
     this.stringToIndex.set(str, index);
+    this._totalCount++;
     this._dirty = true;
     return index;
   }
@@ -98,7 +127,14 @@ export class SharedStrings {
    * Get the count of strings
    */
   get count(): number {
-    return this.strings.length;
+    return this.entries.length;
+  }
+
+  /**
+   * Get total usage count of shared strings
+   */
+  get totalCount(): number {
+    return Math.max(this._totalCount, this.entries.length);
   }
 
   /**
@@ -106,20 +142,28 @@ export class SharedStrings {
    */
   toXml(): string {
     const siElements: XmlNode[] = [];
-    for (const str of this.strings) {
-      const tElement = createElement('t', str.startsWith(' ') || str.endsWith(' ') ? { 'xml:space': 'preserve' } : {}, [
-        createText(str),
-      ]);
-      const siElement = createElement('si', {}, [tElement]);
-      siElements.push(siElement);
+    for (const entry of this.entries) {
+      if (entry.node) {
+        siElements.push(entry.node);
+      } else {
+        const str = entry.text;
+        const tElement = createElement(
+          't',
+          str.startsWith(' ') || str.endsWith(' ') ? { 'xml:space': 'preserve' } : {},
+          [createText(str)],
+        );
+        const siElement = createElement('si', {}, [tElement]);
+        siElements.push(siElement);
+      }
     }
 
+    const totalCount = Math.max(this._totalCount, this.entries.length);
     const sst = createElement(
       'sst',
       {
         xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
-        count: String(this.strings.length),
-        uniqueCount: String(this.strings.length),
+        count: String(totalCount),
+        uniqueCount: String(this.entries.length),
       },
       siElements,
     );
@@ -127,3 +171,8 @@ export class SharedStrings {
     return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([sst])}`;
   }
 }
+
+interface SharedStringEntry {
+  text: string;
+  node?: XmlNode;
+}