@niicojs/excel 0.2.2 → 0.2.4

package/package.json

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

package/src/index.ts

@@ -8,6 +8,18 @@ export { Styles } from './styles';
 export { PivotTable } from './pivot-table';
 export { PivotCache } from './pivot-cache';
 
+// Address utilities
+export {
+  parseAddress,
+  toAddress,
+  parseRange,
+  toRange,
+  colToLetter,
+  letterToCol,
+  normalizeRange,
+  isInRange,
+} from './utils/address';
+
 // Type exports
 export type {
   CellValue,
@@ -20,16 +32,20 @@ export type {
   BorderStyle,
   BorderType,
   Alignment,
+  DateHandling,
   // Pivot table types
   PivotTableConfig,
   PivotValueConfig,
   AggregationType,
   PivotFieldAxis,
+  PivotSortOrder,
+  PivotFieldFilter,
   // Sheet from data types
   SheetFromDataConfig,
   ColumnConfig,
   RichCellValue,
+  // Sheet to JSON types
+  SheetToJsonConfig,
 } from './types';
 
 // Utility exports
-export { parseAddress, toAddress, parseRange, toRange } from './utils/address';

package/src/pivot-cache.ts

@@ -13,6 +13,7 @@ export class PivotCache {
   private _records: CellValue[][] = [];
   private _recordCount = 0;
   private _refreshOnLoad = true; // Default to true
+  private _dateGrouping = false;
 
   constructor(cacheId: number, sourceSheet: string, sourceRange: string) {
     this._cacheId = cacheId;
@@ -126,6 +127,9 @@ export class PivotCache {
       }
     }
 
+    // Enable date grouping flag if any date field exists
+    this._dateGrouping = this._fields.some((field) => field.isDate);
+
     // Store records
     this._records = data;
   }
@@ -160,6 +164,8 @@ export class PivotCache {
         for (const item of field.sharedItems) {
           sharedItemChildren.push(createElement('s', { v: item }, []));
         }
+      } else if (field.isDate) {
+        sharedItemsAttrs.containsDate = '1';
       } else if (field.isNumeric) {
         // Numeric field - use "0"/"1" for boolean attributes as Excel expects
         sharedItemsAttrs.containsSemiMixedTypes = '0';
@@ -187,7 +193,11 @@ export class PivotCache {
       { ref: this._sourceRange, sheet: this._sourceSheet },
       [],
     );
-    const cacheSourceNode = createElement('cacheSource', { type: 'worksheet' }, [worksheetSourceNode]);
+    const cacheSourceAttrs: Record<string, string> = { type: 'worksheet' };
+    if (this._dateGrouping) {
+      cacheSourceAttrs.grouping = '1';
+    }
+    const cacheSourceNode = createElement('cacheSource', cacheSourceAttrs, [worksheetSourceNode]);
 
     // Build attributes - refreshOnLoad should come early per OOXML schema
     const definitionAttrs: Record<string, string> = {

package/src/pivot-table.ts

@@ -1,4 +1,4 @@
-import type { AggregationType, PivotFieldAxis } from './types';
+import type { AggregationType, PivotFieldAxis, PivotFieldFilter, PivotSortOrder } from './types';
 import { PivotCache } from './pivot-cache';
 import { createElement, stringifyXml, XmlNode } from './utils/xml';
 
@@ -11,6 +11,8 @@ interface FieldAssignment {
   axis: PivotFieldAxis;
   aggregation?: AggregationType;
   displayName?: string;
+  sortOrder?: PivotSortOrder;
+  filter?: PivotFieldFilter;
 }
 
 /**
@@ -29,6 +31,8 @@ export class PivotTable {
   private _valueFields: FieldAssignment[] = [];
   private _filterFields: FieldAssignment[] = [];
 
+  private _fieldAssignments: Map<number, FieldAssignment> = new Map();
+
   private _pivotTableIndex: number;
 
   constructor(
@@ -94,11 +98,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;
   }
@@ -113,11 +119,13 @@ 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;
   }
@@ -136,13 +144,15 @@ export class PivotTable {
 
     const defaultName = `${aggregation.charAt(0).toUpperCase() + aggregation.slice(1)} of ${fieldName}`;
 
-    this._valueFields.push({
+    const assignment: FieldAssignment = {
       fieldName,
       fieldIndex,
       axis: 'value',
       aggregation,
       displayName: displayName || defaultName,
-    });
+    };
+    this._valueFields.push(assignment);
+    this._fieldAssignments.set(fieldIndex, assignment);
 
     return this;
   }
@@ -157,12 +167,54 @@ 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/column field
+   */
+  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 || (assignment.axis !== 'row' && assignment.axis !== 'column')) {
+      throw new Error(`Field is not assigned to row or column axis: ${fieldName}`);
+    }
 
+    assignment.sortOrder = order;
+    return this;
+  }
+
+  /**
+   * Filter items for a field (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('Pivot field filter cannot use both include and exclude');
+    }
+
+    assignment.filter = filter;
     return this;
   }
 
@@ -328,15 +380,27 @@ export class PivotTable {
     const filterField = this._filterFields.find((f) => f.fieldIndex === fieldIndex);
     const valueField = this._valueFields.find((f) => f.fieldIndex === fieldIndex);
 
+    const assignment = this._fieldAssignments.get(fieldIndex);
+
     if (rowField) {
       attrs.axis = 'axisRow';
       attrs.showAll = '0';
+      if (assignment?.sortOrder) {
+        attrs.sortType = 'ascending';
+        attrs.sortOrder = assignment.sortOrder === 'asc' ? 'ascending' : 'descending';
+      }
       // Add items for shared values
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
         const itemNodes: XmlNode[] = [];
+        const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
         for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
+          const shouldInclude = allowedIndexes.has(i);
+          const itemAttrs: Record<string, string> = { x: String(i) };
+          if (!shouldInclude) {
+            itemAttrs.h = '1';
+          }
+          itemNodes.push(createElement('item', itemAttrs, []));
         }
         // Add default subtotal item
         itemNodes.push(createElement('item', { t: 'default' }, []));
@@ -345,11 +409,21 @@ export class PivotTable {
     } else if (colField) {
       attrs.axis = 'axisCol';
       attrs.showAll = '0';
+      if (assignment?.sortOrder) {
+        attrs.sortType = 'ascending';
+        attrs.sortOrder = assignment.sortOrder === 'asc' ? 'ascending' : 'descending';
+      }
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
         const itemNodes: XmlNode[] = [];
+        const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
         for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
+          const shouldInclude = allowedIndexes.has(i);
+          const itemAttrs: Record<string, string> = { x: String(i) };
+          if (!shouldInclude) {
+            itemAttrs.h = '1';
+          }
+          itemNodes.push(createElement('item', itemAttrs, []));
         }
         itemNodes.push(createElement('item', { t: 'default' }, []));
         children.push(createElement('items', { count: String(itemNodes.length) }, itemNodes));
@@ -360,8 +434,14 @@ export class PivotTable {
       const cacheField = this._cache.fields[fieldIndex];
       if (cacheField && cacheField.sharedItems.length > 0) {
         const itemNodes: XmlNode[] = [];
+        const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
         for (let i = 0; i < cacheField.sharedItems.length; i++) {
-          itemNodes.push(createElement('item', { x: String(i) }, []));
+          const shouldInclude = allowedIndexes.has(i);
+          const itemAttrs: Record<string, string> = { x: String(i) };
+          if (!shouldInclude) {
+            itemAttrs.h = '1';
+          }
+          itemNodes.push(createElement('item', itemAttrs, []));
         }
         itemNodes.push(createElement('item', { t: 'default' }, []));
         children.push(createElement('items', { count: String(itemNodes.length) }, itemNodes));
@@ -376,6 +456,36 @@ export class PivotTable {
     return createElement('pivotField', attrs, children);
   }
 
+  private _resolveItemFilter(items: string[], filter?: PivotFieldFilter): Set<number> {
+    const allowed = new Set<number>();
+
+    if (!filter || (!filter.include && !filter.exclude)) {
+      for (let i = 0; i < items.length; i++) {
+        allowed.add(i);
+      }
+      return allowed;
+    }
+
+    if (filter.include) {
+      for (let i = 0; i < items.length; i++) {
+        if (filter.include.includes(items[i])) {
+          allowed.add(i);
+        }
+      }
+      return allowed;
+    }
+
+    if (filter.exclude) {
+      for (let i = 0; i < items.length; i++) {
+        if (!filter.exclude.includes(items[i])) {
+          allowed.add(i);
+        }
+      }
+    }
+
+    return allowed;
+  }
+
   /**
    * 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/styles.ts

@@ -35,6 +35,52 @@ export class Styles {
 
   // Cache for style deduplication
   private _styleCache: Map<string, number> = new Map();
+  private _styleObjectCache: Map<number, CellStyle> = new Map();
+
+  /**
+   * Generate a deterministic cache key for a style object.
+   * More efficient than JSON.stringify as it avoids the overhead of
+   * full JSON serialization and produces a consistent key regardless
+   * of property order.
+   */
+  private _getStyleKey(style: CellStyle): string {
+    // Use a delimiter that won't appear in values
+    const SEP = '\x00';
+
+    // Build key from all style properties in a fixed order
+    const parts: string[] = [
+      style.bold ? '1' : '0',
+      style.italic ? '1' : '0',
+      style.underline === true ? '1' : style.underline === 'single' ? 's' : style.underline === 'double' ? 'd' : '0',
+      style.strike ? '1' : '0',
+      style.fontSize?.toString() ?? '',
+      style.fontName ?? '',
+      style.fontColor ?? '',
+      style.fill ?? '',
+      style.numberFormat ?? '',
+    ];
+
+    // Border properties
+    if (style.border) {
+      parts.push(style.border.top ?? '', style.border.bottom ?? '', style.border.left ?? '', style.border.right ?? '');
+    } else {
+      parts.push('', '', '', '');
+    }
+
+    // Alignment properties
+    if (style.alignment) {
+      parts.push(
+        style.alignment.horizontal ?? '',
+        style.alignment.vertical ?? '',
+        style.alignment.wrapText ? '1' : '0',
+        style.alignment.textRotation?.toString() ?? '',
+      );
+    } else {
+      parts.push('', '', '0', '');
+    }
+
+    return parts.join(SEP);
+  }
 
   /**
    * Parse styles from XML content
@@ -228,6 +274,9 @@ export class Styles {
    * Get a style by index
    */
   getStyle(index: number): CellStyle {
+    const cached = this._styleObjectCache.get(index);
+    if (cached) return { ...cached };
+
     const xf = this._cellXfs[index];
     if (!xf) return {};
 
@@ -276,6 +325,7 @@ export class Styles {
       };
     }
 
+    this._styleObjectCache.set(index, { ...style });
     return style;
   }
 
@@ -284,7 +334,7 @@ export class Styles {
    * Uses caching to deduplicate identical styles
    */
   createStyle(style: CellStyle): number {
-    const key = JSON.stringify(style);
+    const key = this._getStyleKey(style);
     const cached = this._styleCache.get(key);
     if (cached !== undefined) {
       return cached;
@@ -324,10 +374,19 @@ export class Styles {
     const index = this._cellXfs.length;
     this._cellXfs.push(xf);
     this._styleCache.set(key, index);
+    this._styleObjectCache.set(index, { ...style });
 
     return index;
   }
 
+  /**
+   * Clone an existing style by index, optionally overriding fields.
+   */
+  cloneStyle(index: number, overrides: Partial<CellStyle> = {}): number {
+    const baseStyle = this.getStyle(index);
+    return this.createStyle({ ...baseStyle, ...overrides });
+  }
+
   private _findOrCreateFont(style: CellStyle): number {
     const font: StyleFont = {
       bold: style.bold || false,

package/src/types.ts

@@ -17,6 +17,11 @@ export type ErrorType = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' |
  */
 export type CellType = 'number' | 'string' | 'boolean' | 'date' | 'error' | 'empty';
 
+/**
+ * Date handling strategy when serializing cell values.
+ */
+export type DateHandling = 'jsDate' | 'excelSerial' | 'isoString';
+
 /**
  * Style definition for cells
  */
@@ -113,6 +118,19 @@ export interface Relationship {
  */
 export type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
 
+/**
+ * Sort order for pivot fields.
+ */
+export type PivotSortOrder = 'asc' | 'desc';
+
+/**
+ * Filter configuration for pivot fields.
+ */
+export interface PivotFieldFilter {
+  include?: string[];
+  exclude?: string[];
+}
+
 /**
  * Configuration for a value field in a pivot table
  */
@@ -204,3 +222,47 @@ export interface RichCellValue {
   /** Cell style */
   style?: CellStyle;
 }
+
+/**
+ * Configuration for converting a sheet to JSON objects.
+ */
+export interface SheetToJsonConfig {
+  /**
+   * Field names to use for each column.
+   * If provided, the first row of data starts at row 1 (or startRow).
+   * If not provided, the first row is used as field names.
+   */
+  fields?: string[];
+
+  /**
+   * Starting row (0-based). Defaults to 0.
+   * If fields are not provided, this row contains the headers.
+   * If fields are provided, this is the first data row.
+   */
+  startRow?: number;
+
+  /**
+   * Starting column (0-based). Defaults to 0.
+   */
+  startCol?: number;
+
+  /**
+   * Ending row (0-based, inclusive). Defaults to the last row with data.
+   */
+  endRow?: number;
+
+  /**
+   * Ending column (0-based, inclusive). Defaults to the last column with data.
+   */
+  endCol?: number;
+
+  /**
+   * If true, stop reading when an empty row is encountered. Defaults to true.
+   */
+  stopOnEmptyRow?: boolean;
+
+  /**
+   * How to serialize Date values. Defaults to 'jsDate'.
+   */
+  dateHandling?: DateHandling;
+}

package/src/utils/address.ts

@@ -41,8 +41,11 @@ export const parseAddress = (address: string): CellAddress => {
   if (!match) {
     throw new Error(`Invalid cell address: ${address}`);
   }
+  const rowNumber = +match[2];
+  if (rowNumber <= 0) throw new Error(`Invalid cell address: ${address}`);
+
   const col = letterToCol(match[1].toUpperCase());
-  const row = parseInt(match[2], 10) - 1; // Convert to 0-based
+  const row = rowNumber - 1; // Convert to 0-based
   return { row, col };
 };
 

package/src/utils/xml.ts

@@ -138,10 +138,3 @@ export const createElement = (tagName: string, attrs?: Record<string, string>, c
 export const createText = (text: string): XmlNode => {
   return { '#text': text } as unknown as XmlNode;
 };
-
-/**
- * Adds XML declaration to the start of an XML string
- */
-export const addXmlDeclaration = (xml: string): string => {
-  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${xml}`;
-};

package/src/workbook.ts

@@ -7,6 +7,7 @@ import type {
   SheetFromDataConfig,
   ColumnConfig,
   RichCellValue,
+  DateHandling,
 } from './types';
 import { Worksheet } from './worksheet';
 import { SharedStrings } from './shared-strings';
@@ -34,6 +35,9 @@ export class Workbook {
   private _pivotCaches: PivotCache[] = [];
   private _nextCacheId = 0;
 
+  // Date serialization handling
+  private _dateHandling: DateHandling = 'jsDate';
+
   private constructor() {
     this._sharedStrings = new SharedStrings();
     this._styles = Styles.createDefault();
@@ -119,6 +123,20 @@ export class Workbook {
     return this._styles;
   }
 
+  /**
+   * Get the workbook date handling strategy.
+   */
+  get dateHandling(): DateHandling {
+    return this._dateHandling;
+  }
+
+  /**
+   * Set the workbook date handling strategy.
+   */
+  set dateHandling(value: DateHandling) {
+    this._dateHandling = value;
+  }
+
   /**
    * Get a worksheet by name or index
    */