@lotics/xlsx 0.1.0

package/src/ooxml_pivot.ts

@@ -0,0 +1,468 @@
+// =============================================================================
+// OOXML Pivot Table Parser
+// =============================================================================
+//
+// Parses pivot tables (`xl/pivotTables/*.xml`) and pivot caches
+// (`xl/pivotCache/*.xml`). Coverage matches the 80% subset documented in
+// `ooxml_pivot_types.ts`.
+// =============================================================================
+
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotAggregateFn,
+  PivotAxis,
+  PivotCacheField,
+  PivotCacheItem,
+  PivotCacheSource,
+  PivotDataField,
+  PivotDisplayOptions,
+  PivotFieldConfig,
+} from "./ooxml_pivot_types";
+
+// =============================================================================
+// PivotTable parser
+// =============================================================================
+
+export function parsePivotTableXml(
+  xml: string,
+  parseXml: (xml: string) => Record<string, unknown>,
+): ParsedPivotTable {
+  const doc = parseXml(xml);
+  const root = (doc["pivotTableDefinition"] ?? doc) as Record<string, unknown>;
+
+  const name = strAttr(root, "name") ?? "PivotTable1";
+  const cacheId = intAttr(root, "cacheId") ?? 0;
+
+  const location = (root["location"] ?? {}) as Record<string, unknown>;
+  const ref = strAttr(location, "ref") ?? "A1:A1";
+  const firstHeaderRow = intAttr(location, "firstHeaderRow") ?? 0;
+  const firstDataCol = intAttr(location, "firstDataCol") ?? 0;
+  const firstDataRow = intAttr(location, "firstDataRow") ?? 1;
+
+  const pageFields = parsePageFields(root);
+  const pageFieldIndices = pageFields.map((p) => p.fld);
+  const fields = parsePivotFields(root, pageFields);
+  const rowFieldIndices = parseFieldIndexList(root, "rowFields");
+  const colFieldIndices = parseFieldIndexList(root, "colFields");
+  const dataFields = parseDataFields(root);
+  const display = parseDisplayOptions(root);
+
+  const styleInfo = root["pivotTableStyleInfo"];
+  const styleName =
+    styleInfo && typeof styleInfo === "object"
+      ? strAttr(styleInfo as Record<string, unknown>, "name")
+      : undefined;
+
+  return {
+    name,
+    cacheId,
+    ref,
+    firstHeaderRow,
+    firstDataCol,
+    firstDataRow,
+    fields,
+    rowFieldIndices,
+    colFieldIndices,
+    pageFieldIndices,
+    dataFields,
+    styleName,
+    display,
+  };
+}
+
+function parsePivotFields(
+  root: Record<string, unknown>,
+  pageFields: ParsedPageField[],
+): PivotFieldConfig[] {
+  const wrapper = root["pivotFields"];
+  if (!wrapper || typeof wrapper !== "object") return [];
+  const nodes = ensureArray(
+    (wrapper as Record<string, unknown>)["pivotField"],
+  );
+
+  // Map field index → selected page item so each pivot field that's on the
+  // page axis can carry its filter selection.
+  const pageSelectionByFld = new Map<number, number | null | undefined>();
+  for (const p of pageFields) pageSelectionByFld.set(p.fld, p.selectedItem);
+
+  const out: PivotFieldConfig[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if (!node || typeof node !== "object") {
+      out.push(blankField());
+      continue;
+    }
+    const f = node as Record<string, unknown>;
+    const axisStr = strAttr(f, "axis");
+    out.push({
+      axis: axisFromOoxml(axisStr),
+      subtotalFunction: subtotalFromAttrs(f),
+      showSubtotal: boolAttr(f, "defaultSubtotal", true),
+      compact: boolAttr(f, "compact", true),
+      showAll: boolAttr(f, "showAll", false),
+      selectedPageItem: pageSelectionByFld.get(i),
+    });
+  }
+  return out;
+}
+
+function blankField(): PivotFieldConfig {
+  return {
+    showSubtotal: true,
+    compact: true,
+    showAll: false,
+  };
+}
+
+function axisFromOoxml(axis: string | undefined): PivotAxis | undefined {
+  switch (axis) {
+    case "axisRow":
+      return "row";
+    case "axisCol":
+      return "column";
+    case "axisPage":
+      return "page";
+    case "axisValues":
+      return "values";
+    default:
+      return undefined;
+  }
+}
+
+const SUBTOTAL_ATTR_TO_FN: Record<string, PivotAggregateFn> = {
+  sumSubtotal: "sum",
+  countSubtotal: "count",
+  countASubtotal: "count",
+  avgSubtotal: "average",
+  minSubtotal: "min",
+  maxSubtotal: "max",
+  productSubtotal: "product",
+};
+
+function subtotalFromAttrs(
+  f: Record<string, unknown>,
+): PivotAggregateFn | undefined {
+  for (const [attr, fn] of Object.entries(SUBTOTAL_ATTR_TO_FN)) {
+    if (boolAttr(f, attr, false)) return fn;
+  }
+  return undefined;
+}
+
+interface ParsedPageField {
+  fld: number;
+  /** Index into the cache items. `null` means "(All)" (no selection). */
+  selectedItem: number | null | undefined;
+}
+
+function parsePageItem(f: Record<string, unknown>): number | null | undefined {
+  // CT_PageField uses `@item` for the selected page item index. Absent or -1 → "(All)".
+  const v = f["@_item"];
+  if (v === undefined) return undefined;
+  if (typeof v === "number") return v < 0 ? null : v;
+  if (typeof v === "string") {
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? (n < 0 ? null : n) : undefined;
+  }
+  return undefined;
+}
+
+function parseFieldIndexList(
+  root: Record<string, unknown>,
+  key: string,
+): number[] {
+  const wrapper = root[key];
+  if (!wrapper || typeof wrapper !== "object") return [];
+  const nodes = ensureArray((wrapper as Record<string, unknown>)["field"]);
+  const out: number[] = [];
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") continue;
+    const idx = intAttr(node as Record<string, unknown>, "x");
+    if (idx !== undefined) out.push(idx);
+  }
+  return out;
+}
+
+function parsePageFields(root: Record<string, unknown>): ParsedPageField[] {
+  const wrapper = root["pageFields"];
+  if (!wrapper || typeof wrapper !== "object") return [];
+  const nodes = ensureArray((wrapper as Record<string, unknown>)["pageField"]);
+  const out: ParsedPageField[] = [];
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") continue;
+    const f = node as Record<string, unknown>;
+    const idx = intAttr(f, "fld");
+    if (idx === undefined) continue;
+    out.push({ fld: idx, selectedItem: parsePageItem(f) });
+  }
+  return out;
+}
+
+const SUBTOTAL_ENUM_TO_FN: Record<string, PivotAggregateFn> = {
+  sum: "sum",
+  count: "count",
+  countNums: "countNums",
+  average: "average",
+  min: "min",
+  max: "max",
+  product: "product",
+};
+
+function parseDataFields(root: Record<string, unknown>): PivotDataField[] {
+  const wrapper = root["dataFields"];
+  if (!wrapper || typeof wrapper !== "object") return [];
+  const nodes = ensureArray((wrapper as Record<string, unknown>)["dataField"]);
+  const out: PivotDataField[] = [];
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") continue;
+    const d = node as Record<string, unknown>;
+    const fieldIndex = intAttr(d, "fld");
+    if (fieldIndex === undefined) continue;
+    const subtotalRaw = strAttr(d, "subtotal") ?? "sum";
+    const subtotal = SUBTOTAL_ENUM_TO_FN[subtotalRaw] ?? "sum";
+    // OOXML CT_DataField writes a `numFmtId` referencing the styles table.
+    // Older / non-Excel writers occasionally emit a literal `numFmt` format
+    // string. Take whichever is present — `numFmtId` takes precedence.
+    const numFmt = strAttr(d, "numFmtId") ?? strAttr(d, "numFmt");
+    out.push({
+      name: strAttr(d, "name") ?? `Sum of field ${fieldIndex}`,
+      fieldIndex,
+      subtotal,
+      numFmt,
+    });
+  }
+  return out;
+}
+
+function parseDisplayOptions(
+  root: Record<string, unknown>,
+): PivotDisplayOptions {
+  // Grand totals live on the root element. Stripe flags live inside
+  // `<pivotTableStyleInfo>` (alongside the style name).
+  const styleInfo = root["pivotTableStyleInfo"];
+  const styleObj =
+    styleInfo && typeof styleInfo === "object"
+      ? (styleInfo as Record<string, unknown>)
+      : {};
+  return {
+    rowGrandTotals: boolAttr(root, "rowGrandTotals", true),
+    colGrandTotals: boolAttr(root, "colGrandTotals", true),
+    showRowStripes: boolAttr(styleObj, "showRowStripes", false),
+    showColStripes: boolAttr(styleObj, "showColStripes", false),
+  };
+}
+
+// =============================================================================
+// PivotCache parser
+// =============================================================================
+
+export function parsePivotCacheDefinitionXml(
+  xml: string,
+  cacheId: number,
+  parseXml: (xml: string) => Record<string, unknown>,
+): ParsedPivotCache {
+  const doc = parseXml(xml);
+  const root = (doc["pivotCacheDefinition"] ?? doc) as Record<string, unknown>;
+
+  const refreshOnLoad = boolAttr(root, "refreshOnLoad", false);
+  const source = parseCacheSource(root);
+  const fields = parseCacheFields(root);
+
+  return { id: cacheId, source, fields, refreshOnLoad };
+}
+
+function parseCacheSource(root: Record<string, unknown>): PivotCacheSource {
+  const cacheSource = root["cacheSource"];
+  if (!cacheSource || typeof cacheSource !== "object") {
+    return { type: "external" };
+  }
+  const cs = cacheSource as Record<string, unknown>;
+  const sourceType = strAttr(cs, "type") ?? "worksheet";
+  if (sourceType === "consolidation") return { type: "consolidation" };
+  if (sourceType === "external") return { type: "external" };
+
+  const ws = cs["worksheetSource"];
+  if (!ws || typeof ws !== "object") return { type: "external" };
+  const w = ws as Record<string, unknown>;
+  const named = strAttr(w, "name");
+  if (named) return { type: "named", name: named };
+  const sheetName = strAttr(w, "sheet") ?? "";
+  const ref = strAttr(w, "ref") ?? "A1:A1";
+  return { type: "worksheet", sheetName, ref };
+}
+
+function parseCacheFields(root: Record<string, unknown>): PivotCacheField[] {
+  const wrapper = root["cacheFields"];
+  if (!wrapper || typeof wrapper !== "object") return [];
+  const nodes = ensureArray((wrapper as Record<string, unknown>)["cacheField"]);
+  const out: PivotCacheField[] = [];
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") continue;
+    const f = node as Record<string, unknown>;
+    const name = strAttr(f, "name") ?? "";
+    const numFmtId = strAttr(f, "numFmtId");
+    const sharedItems = (f["sharedItems"] ?? {}) as Record<string, unknown>;
+    out.push({
+      name,
+      numFmt: numFmtId,
+      containsNumber: boolAttr(sharedItems, "containsNumber", false),
+      containsDate: boolAttr(sharedItems, "containsDate", false),
+      items: parseCacheItems(sharedItems),
+    });
+  }
+  return out;
+}
+
+function parseCacheItems(sharedItems: Record<string, unknown>): PivotCacheItem[] {
+  const out: PivotCacheItem[] = [];
+  // Each child of <sharedItems> is one of <s/>, <n/>, <b/>, <d/>, <e/>, <m/>
+  // and there can be zero or many of each interleaved. fast-xml-parser
+  // surfaces these as separate keys, so we walk every recognised key.
+  const sNodes = ensureArray(sharedItems["s"]);
+  for (const n of sNodes) {
+    const v = strAttr(asObj(n), "v");
+    if (v !== undefined) out.push({ kind: "string", value: v });
+  }
+  const nNodes = ensureArray(sharedItems["n"]);
+  for (const n of nNodes) {
+    const v = strAttr(asObj(n), "v");
+    const num = v !== undefined ? Number(v) : NaN;
+    if (Number.isFinite(num)) out.push({ kind: "number", value: num });
+  }
+  const bNodes = ensureArray(sharedItems["b"]);
+  for (const n of bNodes) {
+    const v = strAttr(asObj(n), "v");
+    out.push({ kind: "boolean", value: v === "1" || v === "true" });
+  }
+  const dNodes = ensureArray(sharedItems["d"]);
+  for (const n of dNodes) {
+    const v = strAttr(asObj(n), "v");
+    if (v !== undefined) out.push({ kind: "date", value: v });
+  }
+  const eNodes = ensureArray(sharedItems["e"]);
+  for (const n of eNodes) {
+    const v = strAttr(asObj(n), "v");
+    out.push({ kind: "error", value: v ?? "#N/A" });
+  }
+  const mNodes = ensureArray(sharedItems["m"]);
+  for (const _n of mNodes) {
+    out.push({ kind: "missing" });
+  }
+  return out;
+}
+
+// =============================================================================
+// Relationship helpers
+// =============================================================================
+
+/**
+ * From a sheet's rels file, return rId → pivot table xml path.
+ * Caller resolves the path to a parser input.
+ */
+export function extractPivotTableRIds(
+  rels: Record<string, unknown>,
+): Map<string, string> {
+  const result = new Map<string, string>();
+  const relationships = rels["Relationships"];
+  if (!relationships || typeof relationships !== "object") return result;
+
+  const relNodes = ensureArray(
+    (relationships as Record<string, unknown>)["Relationship"],
+  );
+  for (const rel of relNodes) {
+    if (!rel || typeof rel !== "object") continue;
+    const r = rel as Record<string, unknown>;
+    const type = strAttr(r, "Type");
+    if (type?.includes("/pivotTable")) {
+      const id = strAttr(r, "Id");
+      const target = strAttr(r, "Target");
+      if (id && target) result.set(id, target);
+    }
+  }
+  return result;
+}
+
+/**
+ * From a pivot table's rels file, return the pivotCacheDefinition path.
+ * Pivot tables reference exactly one cache.
+ */
+export function extractPivotCacheTarget(
+  rels: Record<string, unknown>,
+): string | undefined {
+  const relationships = rels["Relationships"];
+  if (!relationships || typeof relationships !== "object") return undefined;
+  const relNodes = ensureArray(
+    (relationships as Record<string, unknown>)["Relationship"],
+  );
+  for (const rel of relNodes) {
+    if (!rel || typeof rel !== "object") continue;
+    const r = rel as Record<string, unknown>;
+    const type = strAttr(r, "Type");
+    if (type?.includes("/pivotCacheDefinition")) {
+      return strAttr(r, "Target");
+    }
+  }
+  return undefined;
+}
+
+/**
+ * From `xl/workbook.xml`, return cacheId → pivotCacheDefinition rId.
+ * Both attributes live on `<pivotCache>` elements inside `<pivotCaches>`.
+ */
+export function extractWorkbookPivotCaches(
+  workbook: Record<string, unknown>,
+): Map<number, string> {
+  const out = new Map<number, string>();
+  const wb = (workbook["workbook"] ?? workbook) as Record<string, unknown>;
+  const caches = wb["pivotCaches"];
+  if (!caches || typeof caches !== "object") return out;
+  const nodes = ensureArray((caches as Record<string, unknown>)["pivotCache"]);
+  for (const n of nodes) {
+    if (!n || typeof n !== "object") continue;
+    const c = n as Record<string, unknown>;
+    const cacheId = intAttr(c, "cacheId");
+    // r:id stored as "@_r:id" by fast-xml-parser when colon namespaces preserved.
+    const rid = strAttr(c, "r:id") ?? strAttr(c, "rId");
+    if (cacheId !== undefined && rid) out.set(cacheId, rid);
+  }
+  return out;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function strAttr(obj: Record<string, unknown>, attr: string): string | undefined {
+  const val = obj[`@_${attr}`];
+  if (typeof val === "string") return val;
+  if (typeof val === "number") return String(val);
+  return undefined;
+}
+
+function intAttr(obj: Record<string, unknown>, attr: string): number | undefined {
+  const v = strAttr(obj, attr);
+  if (v === undefined) return undefined;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function boolAttr(
+  obj: Record<string, unknown>,
+  attr: string,
+  fallback: boolean,
+): boolean {
+  const v = strAttr(obj, attr);
+  if (v === undefined) return fallback;
+  if (v === "1" || v === "true") return true;
+  if (v === "0" || v === "false") return false;
+  return fallback;
+}
+
+function ensureArray(val: unknown): unknown[] {
+  if (val === undefined || val === null) return [];
+  return Array.isArray(val) ? val : [val];
+}
+
+function asObj(val: unknown): Record<string, unknown> {
+  return val && typeof val === "object" ? (val as Record<string, unknown>) : {};
+}

package/src/ooxml_pivot_types.ts

@@ -0,0 +1,165 @@
+// =============================================================================
+// OOXML Pivot Table Types
+// =============================================================================
+//
+// Types for parsed pivot tables (`xl/pivotTables/*.xml`) and their backing
+// caches (`xl/pivotCache/*.xml`). The model is intentionally close to the
+// OOXML shape so the writer can round-trip without heroic translation.
+//
+// Coverage targets the 80% subset:
+//   - row / column / value / page (filter) axes
+//   - subtotal aggregations: sum, count, average, min, max, product, countNums
+//   - source range from the same workbook (worksheetSource)
+//   - cached items: strings, numbers, dates, booleans, errors, missing
+//   - layout flags (banded rows/cols, grand totals, default style)
+//
+// Out of scope for this phase:
+//   - calculated fields (`<calculatedField>`)
+//   - calculated items
+//   - OLAP / cube sources (`<cacheHierarchies>`)
+//   - automatic date/time grouping
+//   - "showDataAs" non-default value transforms (% of total, running total, etc.)
+// =============================================================================
+
+/** Top-level pivot table parsed from `xl/pivotTables/pivotTableN.xml`. */
+export interface ParsedPivotTable {
+  /** `name` attribute. Excel-unique, used as anchor for r:embed lookups. */
+  name: string;
+  /** `cacheId` attribute, links to a pivotCacheDefinition by id. */
+  cacheId: number;
+  /** Bounding range on the host sheet, e.g. "A3:E12". */
+  ref: string;
+  /** Number of header rows in `ref` (defaults to 1). */
+  firstHeaderRow: number;
+  /** Column offset within `ref` where data starts. */
+  firstDataCol: number;
+  /** Row offset within `ref` where data starts. */
+  firstDataRow: number;
+  /** Per-field configuration ordered by cache-field index. */
+  fields: PivotFieldConfig[];
+  /** Indices into `fields` placed on the row axis, in order. */
+  rowFieldIndices: number[];
+  /** Indices into `fields` placed on the column axis, in order. */
+  colFieldIndices: number[];
+  /** Indices into `fields` placed on the page (filter) axis, in order. */
+  pageFieldIndices: number[];
+  /** One entry per displayed value. References a cache field index. */
+  dataFields: PivotDataField[];
+  /** Optional table style name (e.g. "PivotStyleLight16"). */
+  styleName?: string;
+  /** Display flags. */
+  display: PivotDisplayOptions;
+}
+
+/**
+ * Configuration for a single source field. Each entry corresponds 1:1 with
+ * a `cacheField` in the pivot cache. Order matches cache order.
+ */
+export interface PivotFieldConfig {
+  /** Where this field appears, if anywhere. */
+  axis?: PivotAxis;
+  /** Subtotal function applied when the field is on the row/col axis. */
+  subtotalFunction?: PivotAggregateFn;
+  /** Whether the field is configured to show subtotals. Default true. */
+  showSubtotal: boolean;
+  /** Whether the user has compacted this field in the layout. */
+  compact: boolean;
+  /** Whether to show all items (vs. only items with data). */
+  showAll: boolean;
+  /** When on the page axis, the chosen filter item index, or null for "(All)". */
+  selectedPageItem?: number | null;
+}
+
+/** A field placed on the values area, e.g. "Sum of Sales". */
+export interface PivotDataField {
+  /** Display name shown in the layout (e.g. "Sum of Sales"). */
+  name: string;
+  /** Index into the pivot table's field list (= cache field index). */
+  fieldIndex: number;
+  /** Aggregation. */
+  subtotal: PivotAggregateFn;
+  /** Optional number format applied to the result cells. */
+  numFmt?: string;
+}
+
+/** Where a field appears in the pivot layout. */
+export type PivotAxis = "row" | "column" | "page" | "values";
+
+/**
+ * Aggregation functions supported in this phase. Maps directly to OOXML
+ * `subtotal`/`subtotalFunction` enum values.
+ */
+export type PivotAggregateFn =
+  | "sum"
+  | "count"
+  | "countNums"
+  | "average"
+  | "min"
+  | "max"
+  | "product";
+
+/** Layout / display flags. */
+export interface PivotDisplayOptions {
+  /** Show grand total row (column-axis aggregate). Default true. */
+  rowGrandTotals: boolean;
+  /** Show grand total column (row-axis aggregate). Default true. */
+  colGrandTotals: boolean;
+  /** Banded rows (alternating fill). */
+  showRowStripes: boolean;
+  /** Banded columns (alternating fill). */
+  showColStripes: boolean;
+}
+
+/** Pivot cache parsed from `xl/pivotCache/pivotCacheDefinitionN.xml`. */
+export interface ParsedPivotCache {
+  /** Cache id used by pivot tables to reference this cache. */
+  id: number;
+  /** The source range that feeds the pivot. */
+  source: PivotCacheSource;
+  /** Cached field metadata. Index matches `pivotTable.fields[]` order. */
+  fields: PivotCacheField[];
+  /** Whether the cache requires a refresh on next open (refreshOnLoad). */
+  refreshOnLoad: boolean;
+}
+
+/** What feeds the cache. We support same-workbook ranges and named refs. */
+export type PivotCacheSource =
+  | { type: "worksheet"; sheetName: string; ref: string }
+  | { type: "named"; name: string }
+  | { type: "external" }
+  | { type: "consolidation" };
+
+/** One source-column's cached metadata. */
+export interface PivotCacheField {
+  /** Field caption (column header text). */
+  name: string;
+  /** Distinct items observed in this column. Order is the canonical sort
+   *  order Excel uses when laying out the field on row/col axis. */
+  items: PivotCacheItem[];
+  /** When the column is purely numeric, may carry a number format. */
+  numFmt?: string;
+  /** True when the column type is numeric (containsNumber). */
+  containsNumber: boolean;
+  /** True when the column contains date serials. */
+  containsDate: boolean;
+}
+
+/** A discrete value in a cache field. */
+export type PivotCacheItem =
+  | { kind: "string"; value: string }
+  | { kind: "number"; value: number }
+  | { kind: "boolean"; value: boolean }
+  | { kind: "date"; value: string } // ISO 8601
+  | { kind: "error"; value: string }
+  | { kind: "missing" };
+
+/**
+ * Map from sheet path (e.g. "xl/worksheets/sheet1.xml") to the pivot tables
+ * placed on that sheet, alongside the workbook's caches indexed by cacheId.
+ */
+export interface PivotBundle {
+  /** Pivot tables keyed by host sheet relative path. */
+  pivotsBySheet: Map<string, ParsedPivotTable[]>;
+  /** All pivot caches discovered, keyed by cacheId. */
+  caches: Map<number, ParsedPivotCache>;
+}