@particle-academy/holy-sheet

Zero-dependency, isomorphic (browser + Node) .xlsx writer + reader + formula linter for agentic document creation. The Node/TypeScript mirror of the PHP particle-academy/holy-sheet — same schema in, same .xlsx out (feature-parity with PHP 1.2.0).

import { Agent } from "@particle-academy/holy-sheet";

const schema = {
  sheets: [
    {
      name: "Sales",
      columns: [
        { header: "Region", type: "string" },
        { header: "Revenue", type: "currency", currency: "USD" },
      ],
      rows: [
        ["North", 12000],
        ["South", 9800],
      ],
      totals: { Revenue: "sum" },
    },
  ],
};

// Universal — works in the browser and Node
const bytes: Uint8Array = Agent.toBytes(schema);

// Node only
await Agent.write(schema, "sales.xlsx");

API

Agent (static) mirrors the PHP surface:

• validate(schema) → structured errors {path, expected, got, value, hint}[]
• toBytes(schema) → Uint8Array (universal)
• write(schema, path) → {path, bytes, sheets} (Node only)
• validateAndRepair(schema) → {schema, errors, repairs}
• lint(schema) → formula problems {sheet, address, formula, error, hint}[]
• fromArray(rows, headers?, sheetName?, options?) → schema
• fromCsv(csvOrPath, options?) → schema
• describe(pathOrBytes) → schema (round-trip reader)
• toolDefinition() → JSON Schema for LLM tool-use
• version() → string

See docs/ for the full schema reference.