xlsx-pivot-chart-parser

Parse Excel .xlsx pivot tables and charts into evaluator-friendly JSON.

This library is built only for the part that many spreadsheet importers miss: pivot table metadata and chart metadata. It is useful when your system already parses normal workbook content such as cells, formulas, styles, and sheets, but still needs to inspect pivots and charts.

If you need formula parsing, formula evaluation, cell extraction, style conversion, or full workbook conversion, use another library alongside this package. For example, use LuckyExcel, SheetJS, ExcelJS, or your existing importer for normal workbook content, then use this package for pivot tables and charts.

This package does not emulate Excel. It does not render charts, recalculate pivot table results, or evaluate formulas. It reads the .xlsx OOXML structure and returns structured JSON that an evaluator can inspect.

Install

npm install xlsx-pivot-chart-parser

Quick Usage

import { readFile } from "node:fs/promises";
import { parseXlsxObjects } from "xlsx-pivot-chart-parser";

const buffer = await readFile("workbook.xlsx");
const result = await parseXlsxObjects(buffer);

console.log(result.charts);
console.log(result.pivotTables);
console.log(result.warnings);

Browser usage:

import { parseXlsxObjects } from "xlsx-pivot-chart-parser";

const arrayBuffer = await file.arrayBuffer();
const result = await parseXlsxObjects(arrayBuffer);

Methods

parseXlsxObjects(input, options?)

Parses an .xlsx file from an ArrayBuffer or Uint8Array.

const result = await parseXlsxObjects(input, {
  includeRawParts: true,
});

Parameters:

• input: .xlsx file data as ArrayBuffer or Uint8Array
• options.includeRawParts: include indexes of discovered OOXML parts; defaults to true

Returns:

{
  sheets: SheetObjects[];
  charts: ChartObject[];
  pivotTables: PivotTableObject[];
  warnings: ParseWarning[];
  rawParts: RawPartIndex;
}

Output Example

{
  sheets: [
    {
      name: "Summary",
      path: "xl/worksheets/sheet1.xml",
      charts: [],
      pivotTables: []
    }
  ],
  charts: [
    {
      id: "chart1",
      sheetName: "Summary",
      type: "bar",
      title: "Revenue by Region",
      rangeRefs: ["Summary!$A$2:$A$3", "Summary!$B$2:$B$3"],
      series: [],
      axes: [],
      rawXmlPath: "xl/charts/chart1.xml"
    }
  ],
  pivotTables: [
    {
      id: "pivotTable1",
      name: "PivotTable1",
      sheetName: "Summary",
      source: {
        worksheetSource: {
          sheet: "Data",
          ref: "A1:C10"
        }
      },
      cacheFields: [],
      rowFields: [],
      columnFields: [],
      pageFields: [],
      dataFields: [],
      unsupportedFeatures: [],
      rawXmlPath: "xl/pivotTables/pivotTable1.xml"
    }
  ],
  warnings: []
}

What It Extracts

Charts:

• sheet name and OOXML part path
• chart type, including combo chart types as bar+line
• chart title
• drawing anchor position
• series order/index
• category, value, and name formulas
• cached series values when present
• axis ids, positions, and titles
• raw XML path for traceability

Pivot tables:

• sheet name and OOXML part path
• pivot table name
• pivot cache id
• source worksheet range or named source
• cache fields and field names
• row fields
• column fields
• page/filter fields
• value/data fields and subtotal type
• calculated field detection
• unsupported feature markers
• raw XML path for traceability

How It Works

An .xlsx file is a ZIP package containing XML files. This library opens the ZIP, reads the workbook XML, follows OOXML relationship files, and connects objects back to their sheets.

Relationship flow:

workbook -> worksheet
worksheet -> drawing -> chart
worksheet -> pivot table -> pivot cache

Important OOXML parts:

xl/workbook.xml
xl/worksheets/sheet*.xml
xl/worksheets/_rels/sheet*.xml.rels
xl/drawings/drawing*.xml
xl/drawings/_rels/drawing*.xml.rels
xl/charts/chart*.xml
xl/pivotTables/pivotTable*.xml
xl/pivotCache/pivotCacheDefinition*.xml
xl/pivotCache/pivotCacheRecords*.xml

Scope

Good fit:

• checking whether a workbook contains required charts or pivots
• validating chart titles, types, and source ranges
• validating pivot row, column, filter, and value fields
• detecting unsupported pivot/chart features
• preserving raw OOXML paths for deeper debugging
• combining with another workbook parser in an evaluator system

Not a fit:

• parsing or evaluating formulas
• extracting all normal worksheet cells
• converting all Excel styles
• rendering charts
• recalculating pivot table results
• fully reproducing Excel layout/theme behavior
• replacing LuckyExcel, SheetJS, or ExcelJS for general workbook import

Development

npm install
npm run typecheck
npm test
npm run build

Before publishing:

npm pack --dry-run