@paperjsx/json-to-xlsx

Generate .xlsx workbooks from a JSON-friendly TypeScript document model.

Current engine capabilities:

• strings via shared strings or inline strings
• numbers and booleans
• dates with automatic yyyy-mm-dd formatting
• null omission
• multiple sheets
• fonts, fills, borders, alignment, and number formats
• style presets
• rich text inline strings
• formulas with pass-through serialization and Phase 3 cached evaluation support
• merges, freeze panes, filters, validations, hyperlinks, named ranges, and print setup
• conditional formatting (cellIs, colorScale, dataBar, top10, duplicateValues, uniqueValues)
• native Excel tables with totals rows and table styles
• deterministic output by default
• preflight workload analysis and string-strategy recommendations
• workbook-level validation, repair, and validate-and-repair APIs for generated or third-party .xlsx buffers including content-type rebuilds, orphan-relationship cleanup, style-index clamping, unsafe-artifact stripping, duplicate table-name normalization, table-ref clipping, merge repair, worksheet-dimension recalculation, invalid hyperlink removal, data-validation-range clipping, and invalid defined-name removal for clearly broken references
• richer preflight quality reports with verdicts, findings, and estimated size/memory/style pressure
• render-plan inspection via SpreadsheetEngine.plan(...)
• render-time metrics via SpreadsheetEngine.renderWithMetrics(...)
• streamed ZIP output via SpreadsheetEngine.renderStream(...)
• template parsing and inspection via SpreadsheetEngine.parseTemplate(...) and SpreadsheetEngine.inspectTemplate(...)
• clean-template assembly via SpreadsheetEngine.assembleFromTemplate(...)
• streamed template assembly output via SpreadsheetEngine.assembleFromTemplateStream(...)
• token-aware formula row shifting via shiftFormulaRows(...) and offsetFormulaRows(...)
• single-row named-range expansion for clean templates, including formula-bearing template rows
• multiple distinct row-expansion anchors on the same sheet
• table-aware template row expansion for existing template table ranges

import { SpreadsheetEngine } from "@paperjsx/json-to-xlsx";

const buffer = await SpreadsheetEngine.render({
  meta: {
    title: "Revenue Report",
    creator: "PaperJSX",
  },
  sheets: [
    {
      name: "Revenue",
      rows: [
        {
          cells: [
            { value: "Quarter" },
            { value: "Revenue" },
            { value: "Closed" },
            { value: "As Of" },
          ],
        },
        {
          cells: [
            { value: "Q1 2026" },
            { value: 420000 },
            { value: true },
            { value: new Date("2026-03-31T00:00:00.000Z") },
          ],
        },
      ],
    },
  ],
});

If you want pure AST validation before rendering, use SpreadsheetEngine.validateDocument(...) or validateSpreadsheetDocument(...). If you have already validated a document and want to skip repeating schema validation on a hot path, use SpreadsheetEngine.renderValidated(validatedDocument).

For Phase 4 and Phase 5 workflows, SpreadsheetEngine.preflight(...) now returns a richer quality report with verdict, findings, render recommendation, and projected size/memory/style pressure; SpreadsheetEngine.plan(...) returns staged part and sheet planning metadata; SpreadsheetEngine.renderWithMetrics(...) returns the output buffer plus chunk, part, and timing metrics; SpreadsheetEngine.renderStream(...) returns a real streamed ZIP output path for large-workbook delivery; SpreadsheetEngine.validate(buffer) inspects finished workbooks; SpreadsheetEngine.repair(buffer) applies conservative package repairs; SpreadsheetEngine.validateAndRepair(buffer) performs validate-repair-revalidate orchestration; SpreadsheetEngine.parseTemplate(...) / SpreadsheetEngine.inspectTemplate(...) expose template inventories and sanitization reports for existing workbooks; SpreadsheetEngine.render(...) can author native Excel tables through sheet-level tables; and SpreadsheetEngine.assembleFromTemplate(...) / SpreadsheetEngine.assembleFromTemplateStream(...) support clean-template named-range/direct-cell injection plus same-sheet row expansion across multiple distinct single-row anchors, including formula-bearing template rows and table-ref shifting for existing template tables. Those same validation and repair entry points now back the MCP spreadsheet tools in /Users/jake/plain/theplainworks/paperjsx.com/packages/mcp-server.

Notes

• The public stream APIs now exist, but the engine still materializes worksheet XML and package parts in memory before ZIP streaming. A fuller low-memory, backpressure-tuned pipeline is still active Phase 4/5 work.
• Broader repair coverage, broader row-expansion edge handling, broader table-aware mutation, and structured-reference ergonomics are still active Phase 4/5 work.
• Unsupported future-facing AST fields are rejected with structured validation errors instead of being silently ignored.
• The rigorous benchmark and chaos-lab intentionally exit non-zero when hard failures remain. The latest generated reports are written to:
  • /Users/jake/plain/theplainworks/paperjsx.com/packages/xlsx/output/benchmarks/rigorous-report.json
  • /Users/jake/plain/theplainworks/paperjsx.com/packages/xlsx/output/chaos/xlsx-chaos-report.json
  • /Users/jake/plain/theplainworks/paperjsx.com/docs/paperjsx-xlsx/XLSX_RIGOROUS_BENCHMARK_REPORT.md
  • /Users/jake/plain/theplainworks/paperjsx.com/docs/paperjsx-xlsx/XLSX_CHAOS_LAB_REPORT.md

Local Tooling

• pnpm --filter @paperjsx/json-to-xlsx validate:fixtures
• pnpm --filter @paperjsx/json-to-xlsx validate:fixtures:large
• pnpm --filter @paperjsx/json-to-xlsx export:fixtures
• pnpm --filter @paperjsx/json-to-xlsx export:fixtures:large
• pnpm --filter @paperjsx/json-to-xlsx benchmark:phase1 -- --iterations 2
• pnpm --filter @paperjsx/json-to-xlsx benchmark:phase2 -- --iterations 1
• pnpm --filter @paperjsx/json-to-xlsx benchmark:rigorous
• pnpm --filter @paperjsx/json-to-xlsx chaos:run