@niicojs/excel 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@niicojs/excel",
+  "version": "0.1.0",
+  "description": "typescript library to manipulate excel files",
+  "homepage": "https://github.com/niicojs/excel#readme",
+  "bugs": {
+    "url": "https://github.com/niicojs/excel/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niicojs/excel.git"
+  },
+  "license": "MIT",
+  "author": "niico",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "tsdx dev",
+    "build": "tsdx build",
+    "test": "tsdx test",
+    "test:watch": "tsdx test --watch",
+    "lint": "tsdx lint",
+    "format": "tsdx format",
+    "format:check": "tsdx format --check",
+    "typecheck": "tsdx typecheck",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.3.3",
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "bunchee": "^6.9.4",
+    "tsdx": "latest",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cell.ts

@@ -0,0 +1,318 @@
+import type { CellValue, CellType, CellStyle, CellData, ErrorType } from './types';
+import type { Worksheet } from './worksheet';
+import { parseAddress, toAddress } from './utils/address';
+
+// Excel epoch: December 30, 1899 (accounting for the 1900 leap year bug)
+const EXCEL_EPOCH = new Date(Date.UTC(1899, 11, 30));
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Excel error types
+const ERROR_TYPES: Set<string> = new Set([
+  '#NULL!',
+  '#DIV/0!',
+  '#VALUE!',
+  '#REF!',
+  '#NAME?',
+  '#NUM!',
+  '#N/A',
+  '#GETTING_DATA',
+]);
+
+/**
+ * Represents a single cell in a worksheet
+ */
+export class Cell {
+  private _row: number;
+  private _col: number;
+  private _data: CellData;
+  private _worksheet: Worksheet;
+  private _dirty = false;
+
+  constructor(worksheet: Worksheet, row: number, col: number, data?: CellData) {
+    this._worksheet = worksheet;
+    this._row = row;
+    this._col = col;
+    this._data = data || {};
+  }
+
+  /**
+   * Get the cell address (e.g., 'A1')
+   */
+  get address(): string {
+    return toAddress(this._row, this._col);
+  }
+
+  /**
+   * Get the 0-based row index
+   */
+  get row(): number {
+    return this._row;
+  }
+
+  /**
+   * Get the 0-based column index
+   */
+  get col(): number {
+    return this._col;
+  }
+
+  /**
+   * Get the cell type
+   */
+  get type(): CellType {
+    const t = this._data.t;
+    if (!t && this._data.v === undefined && !this._data.f) {
+      return 'empty';
+    }
+    switch (t) {
+      case 'n':
+        return 'number';
+      case 's':
+      case 'str':
+        return 'string';
+      case 'b':
+        return 'boolean';
+      case 'e':
+        return 'error';
+      case 'd':
+        return 'date';
+      default:
+        // If no type but has value, infer from value
+        if (typeof this._data.v === 'number') return 'number';
+        if (typeof this._data.v === 'string') return 'string';
+        if (typeof this._data.v === 'boolean') return 'boolean';
+        return 'empty';
+    }
+  }
+
+  /**
+   * Get the cell value
+   */
+  get value(): CellValue {
+    const t = this._data.t;
+    const v = this._data.v;
+
+    if (v === undefined && !this._data.f) {
+      return null;
+    }
+
+    switch (t) {
+      case 'n':
+        return typeof v === 'number' ? v : parseFloat(String(v));
+      case 's':
+        // Shared string reference
+        if (typeof v === 'number') {
+          return this._worksheet.workbook.sharedStrings.getString(v) ?? '';
+        }
+        return String(v);
+      case 'str':
+        // Inline string
+        return String(v);
+      case 'b':
+        return v === 1 || v === '1' || v === true;
+      case 'e':
+        return { error: String(v) as ErrorType };
+      case 'd':
+        // ISO 8601 date string
+        return new Date(String(v));
+      default:
+        // No type specified - try to infer
+        if (typeof v === 'number') {
+          // Check if this might be a date based on number format
+          if (this._isDateFormat()) {
+            return this._excelDateToJs(v);
+          }
+          return v;
+        }
+        if (typeof v === 'string') {
+          if (ERROR_TYPES.has(v)) {
+            return { error: v as ErrorType };
+          }
+          return v;
+        }
+        if (typeof v === 'boolean') return v;
+        return null;
+    }
+  }
+
+  /**
+   * Set the cell value
+   */
+  set value(val: CellValue) {
+    this._dirty = true;
+
+    if (val === null || val === undefined) {
+      this._data.v = undefined;
+      this._data.t = undefined;
+      this._data.f = undefined;
+      return;
+    }
+
+    if (typeof val === 'number') {
+      this._data.v = val;
+      this._data.t = 'n';
+    } else if (typeof val === 'string') {
+      // Store as shared string
+      const index = this._worksheet.workbook.sharedStrings.addString(val);
+      this._data.v = index;
+      this._data.t = 's';
+    } else if (typeof val === 'boolean') {
+      this._data.v = val ? 1 : 0;
+      this._data.t = 'b';
+    } else if (val instanceof Date) {
+      // Store as ISO date string with 'd' type
+      this._data.v = val.toISOString();
+      this._data.t = 'd';
+    } else if ('error' in val) {
+      this._data.v = val.error;
+      this._data.t = 'e';
+    }
+
+    // Clear formula when setting value directly
+    this._data.f = undefined;
+  }
+
+  /**
+   * Write a 2D array of values starting at this cell
+   */
+  set values(data: CellValue[][]) {
+    for (let r = 0; r < data.length; r++) {
+      const row = data[r];
+      for (let c = 0; c < row.length; c++) {
+        const cell = this._worksheet.cell(this._row + r, this._col + c);
+        cell.value = row[c];
+      }
+    }
+  }
+
+  /**
+   * Get the formula (without leading '=')
+   */
+  get formula(): string | undefined {
+    return this._data.f;
+  }
+
+  /**
+   * Set the formula (without leading '=')
+   */
+  set formula(f: string | undefined) {
+    this._dirty = true;
+    if (f === undefined) {
+      this._data.f = undefined;
+    } else {
+      // Remove leading '=' if present
+      this._data.f = f.startsWith('=') ? f.slice(1) : f;
+    }
+  }
+
+  /**
+   * Get the formatted text (as displayed in Excel)
+   */
+  get text(): string {
+    if (this._data.w) {
+      return this._data.w;
+    }
+    const val = this.value;
+    if (val === null) return '';
+    if (typeof val === 'object' && 'error' in val) return val.error;
+    if (val instanceof Date) return val.toISOString().split('T')[0];
+    return String(val);
+  }
+
+  /**
+   * Get the style index
+   */
+  get styleIndex(): number | undefined {
+    return this._data.s;
+  }
+
+  /**
+   * Set the style index
+   */
+  set styleIndex(index: number | undefined) {
+    this._dirty = true;
+    this._data.s = index;
+  }
+
+  /**
+   * Get the cell style
+   */
+  get style(): CellStyle {
+    if (this._data.s === undefined) {
+      return {};
+    }
+    return this._worksheet.workbook.styles.getStyle(this._data.s);
+  }
+
+  /**
+   * Set the cell style (merges with existing)
+   */
+  set style(style: CellStyle) {
+    this._dirty = true;
+    const currentStyle = this.style;
+    const merged = { ...currentStyle, ...style };
+    this._data.s = this._worksheet.workbook.styles.createStyle(merged);
+  }
+
+  /**
+   * Check if cell has been modified
+   */
+  get dirty(): boolean {
+    return this._dirty;
+  }
+
+  /**
+   * Get internal cell data
+   */
+  get data(): CellData {
+    return this._data;
+  }
+
+  /**
+   * Check if this cell has a date number format
+   */
+  private _isDateFormat(): boolean {
+    // TODO: Check actual number format from styles
+    // For now, return false - dates should be explicitly typed
+    return false;
+  }
+
+  /**
+   * Convert Excel serial date to JavaScript Date
+   * Used when reading dates stored as numbers with date formats
+   */
+  _excelDateToJs(serial: number): Date {
+    // Excel incorrectly considers 1900 a leap year
+    // Dates after Feb 28, 1900 need adjustment
+    const adjusted = serial > 60 ? serial - 1 : serial;
+    const ms = Math.round((adjusted - 1) * MS_PER_DAY);
+    return new Date(EXCEL_EPOCH.getTime() + ms);
+  }
+
+  /**
+   * Convert JavaScript Date to Excel serial date
+   * Used when writing dates as numbers for Excel compatibility
+   */
+  _jsDateToExcel(date: Date): number {
+    const ms = date.getTime() - EXCEL_EPOCH.getTime();
+    let serial = ms / MS_PER_DAY + 1;
+    // Account for Excel's 1900 leap year bug
+    if (serial > 60) {
+      serial += 1;
+    }
+    return serial;
+  }
+}
+
+/**
+ * Parse a cell address or row/col to get row and col indices
+ */
+export const parseCellRef = (rowOrAddress: number | string, col?: number): { row: number; col: number } => {
+  if (typeof rowOrAddress === 'string') {
+    return parseAddress(rowOrAddress);
+  }
+  if (col === undefined) {
+    throw new Error('Column must be provided when row is a number');
+  }
+  return { row: rowOrAddress, col };
+};

package/src/index.ts

@@ -0,0 +1,31 @@
+// Main exports
+export { Workbook } from './workbook';
+export { Worksheet } from './worksheet';
+export { Cell } from './cell';
+export { Range } from './range';
+export { SharedStrings } from './shared-strings';
+export { Styles } from './styles';
+export { PivotTable } from './pivot-table';
+export { PivotCache } from './pivot-cache';
+
+// Type exports
+export type {
+  CellValue,
+  CellType,
+  CellStyle,
+  CellError,
+  ErrorType,
+  CellAddress,
+  RangeAddress,
+  BorderStyle,
+  BorderType,
+  Alignment,
+  // Pivot table types
+  PivotTableConfig,
+  PivotValueConfig,
+  AggregationType,
+  PivotFieldAxis,
+} from './types';
+
+// Utility exports
+export { parseAddress, toAddress, parseRange, toRange } from './utils/address';

package/src/pivot-cache.ts

@@ -0,0 +1,268 @@
+import type { PivotCacheField, CellValue } from './types';
+import { createElement, stringifyXml, XmlNode } from './utils/xml';
+
+/**
+ * Manages the pivot cache (definition and records) for a pivot table.
+ * The cache stores source data metadata and cached values.
+ */
+export class PivotCache {
+  private _cacheId: number;
+  private _sourceSheet: string;
+  private _sourceRange: string;
+  private _fields: PivotCacheField[] = [];
+  private _records: CellValue[][] = [];
+  private _recordCount = 0;
+  private _refreshOnLoad = true; // Default to true
+
+  constructor(cacheId: number, sourceSheet: string, sourceRange: string) {
+    this._cacheId = cacheId;
+    this._sourceSheet = sourceSheet;
+    this._sourceRange = sourceRange;
+  }
+
+  /**
+   * Get the cache ID
+   */
+  get cacheId(): number {
+    return this._cacheId;
+  }
+
+  /**
+   * Set refreshOnLoad option
+   */
+  set refreshOnLoad(value: boolean) {
+    this._refreshOnLoad = value;
+  }
+
+  /**
+   * Get refreshOnLoad option
+   */
+  get refreshOnLoad(): boolean {
+    return this._refreshOnLoad;
+  }
+
+  /**
+   * Get the source sheet name
+   */
+  get sourceSheet(): string {
+    return this._sourceSheet;
+  }
+
+  /**
+   * Get the source range
+   */
+  get sourceRange(): string {
+    return this._sourceRange;
+  }
+
+  /**
+   * Get the full source reference (Sheet!Range)
+   */
+  get sourceRef(): string {
+    return `${this._sourceSheet}!${this._sourceRange}`;
+  }
+
+  /**
+   * Get the fields in this cache
+   */
+  get fields(): PivotCacheField[] {
+    return this._fields;
+  }
+
+  /**
+   * Get the number of data records
+   */
+  get recordCount(): number {
+    return this._recordCount;
+  }
+
+  /**
+   * Build the cache from source data.
+   * @param headers - Array of column header names
+   * @param data - 2D array of data rows (excluding headers)
+   */
+  buildFromData(headers: string[], data: CellValue[][]): void {
+    this._recordCount = data.length;
+
+    // Initialize fields from headers
+    this._fields = headers.map((name, index) => ({
+      name,
+      index,
+      isNumeric: true,
+      isDate: false,
+      sharedItems: [],
+      minValue: undefined,
+      maxValue: undefined,
+    }));
+
+    // Analyze data to determine field types and collect unique values
+    for (const row of data) {
+      for (let colIdx = 0; colIdx < row.length && colIdx < this._fields.length; colIdx++) {
+        const value = row[colIdx];
+        const field = this._fields[colIdx];
+
+        if (value === null || value === undefined) {
+          continue;
+        }
+
+        if (typeof value === 'string') {
+          field.isNumeric = false;
+          if (!field.sharedItems.includes(value)) {
+            field.sharedItems.push(value);
+          }
+        } else if (typeof value === 'number') {
+          if (field.minValue === undefined || value < field.minValue) {
+            field.minValue = value;
+          }
+          if (field.maxValue === undefined || value > field.maxValue) {
+            field.maxValue = value;
+          }
+        } else if (value instanceof Date) {
+          field.isDate = true;
+          field.isNumeric = false;
+        } else if (typeof value === 'boolean') {
+          field.isNumeric = false;
+        }
+      }
+    }
+
+    // Store records
+    this._records = data;
+  }
+
+  /**
+   * Get field by name
+   */
+  getField(name: string): PivotCacheField | undefined {
+    return this._fields.find((f) => f.name === name);
+  }
+
+  /**
+   * Get field index by name
+   */
+  getFieldIndex(name: string): number {
+    const field = this._fields.find((f) => f.name === name);
+    return field ? field.index : -1;
+  }
+
+  /**
+   * Generate the pivotCacheDefinition XML
+   */
+  toDefinitionXml(recordsRelId: string): string {
+    const cacheFieldNodes: XmlNode[] = this._fields.map((field) => {
+      const sharedItemsAttrs: Record<string, string> = {};
+      const sharedItemChildren: XmlNode[] = [];
+
+      if (field.sharedItems.length > 0) {
+        // String field with shared items - Excel just uses count attribute
+        sharedItemsAttrs.count = String(field.sharedItems.length);
+
+        for (const item of field.sharedItems) {
+          sharedItemChildren.push(createElement('s', { v: item }, []));
+        }
+      } else if (field.isNumeric) {
+        // Numeric field - use "0"/"1" for boolean attributes as Excel expects
+        sharedItemsAttrs.containsSemiMixedTypes = '0';
+        sharedItemsAttrs.containsString = '0';
+        sharedItemsAttrs.containsNumber = '1';
+        // Check if all values are integers
+        if (field.minValue !== undefined && field.maxValue !== undefined) {
+          const isInteger = Number.isInteger(field.minValue) && Number.isInteger(field.maxValue);
+          if (isInteger) {
+            sharedItemsAttrs.containsInteger = '1';
+          }
+          sharedItemsAttrs.minValue = String(field.minValue);
+          sharedItemsAttrs.maxValue = String(field.maxValue);
+        }
+      }
+
+      const sharedItemsNode = createElement('sharedItems', sharedItemsAttrs, sharedItemChildren);
+      return createElement('cacheField', { name: field.name, numFmtId: '0' }, [sharedItemsNode]);
+    });
+
+    const cacheFieldsNode = createElement('cacheFields', { count: String(this._fields.length) }, cacheFieldNodes);
+
+    const worksheetSourceNode = createElement(
+      'worksheetSource',
+      { ref: this._sourceRange, sheet: this._sourceSheet },
+      [],
+    );
+    const cacheSourceNode = createElement('cacheSource', { type: 'worksheet' }, [worksheetSourceNode]);
+
+    // Build attributes - refreshOnLoad should come early per OOXML schema
+    const definitionAttrs: Record<string, string> = {
+      xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+      'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+      'r:id': recordsRelId,
+    };
+
+    // Add refreshOnLoad early in attributes (default is true)
+    if (this._refreshOnLoad) {
+      definitionAttrs.refreshOnLoad = '1';
+    }
+
+    // Continue with remaining attributes
+    definitionAttrs.refreshedBy = 'User';
+    definitionAttrs.refreshedVersion = '8';
+    definitionAttrs.minRefreshableVersion = '3';
+    definitionAttrs.createdVersion = '8';
+    definitionAttrs.recordCount = String(this._recordCount);
+
+    const definitionNode = createElement('pivotCacheDefinition', definitionAttrs, [cacheSourceNode, cacheFieldsNode]);
+
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([definitionNode])}`;
+  }
+
+  /**
+   * Generate the pivotCacheRecords XML
+   */
+  toRecordsXml(): string {
+    const recordNodes: XmlNode[] = [];
+
+    for (const row of this._records) {
+      const fieldNodes: XmlNode[] = [];
+
+      for (let colIdx = 0; colIdx < this._fields.length; colIdx++) {
+        const field = this._fields[colIdx];
+        const value = colIdx < row.length ? row[colIdx] : null;
+
+        if (value === null || value === undefined) {
+          // Missing value
+          fieldNodes.push(createElement('m', {}, []));
+        } else if (typeof value === 'string') {
+          // String value - use index into sharedItems
+          const idx = field.sharedItems.indexOf(value);
+          if (idx >= 0) {
+            fieldNodes.push(createElement('x', { v: String(idx) }, []));
+          } else {
+            // Direct string value (shouldn't happen if cache is built correctly)
+            fieldNodes.push(createElement('s', { v: value }, []));
+          }
+        } else if (typeof value === 'number') {
+          fieldNodes.push(createElement('n', { v: String(value) }, []));
+        } else if (typeof value === 'boolean') {
+          fieldNodes.push(createElement('b', { v: value ? '1' : '0' }, []));
+        } else if (value instanceof Date) {
+          fieldNodes.push(createElement('d', { v: value.toISOString() }, []));
+        } else {
+          // Unknown type, treat as missing
+          fieldNodes.push(createElement('m', {}, []));
+        }
+      }
+
+      recordNodes.push(createElement('r', {}, fieldNodes));
+    }
+
+    const recordsNode = createElement(
+      'pivotCacheRecords',
+      {
+        xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+        'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+        count: String(this._recordCount),
+      },
+      recordNodes,
+    );
+
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([recordsNode])}`;
+  }
+}