@particle-academy/holy-sheet 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+/**
+ * Public input schema + result types. Mirrors the PHP package's array shapes.
+ * Inputs are intentionally permissive (agents emit loose JSON) — the Validator
+ * is the gate, not the type system.
+ */
+type ThemeKey = "default" | "minimal" | "plain" | "business";
+type ColumnType = "auto" | "string" | "number" | "integer" | "boolean" | "date" | "datetime" | "currency" | "percent" | "formula";
+interface ColumnSchema {
+    header: string;
+    type?: ColumnType;
+    currency?: string;
+    decimals?: number;
+    format?: string;
+    width?: number;
+}
+type DisplayFormat = "auto" | "text" | "number" | "date" | "datetime" | "percentage" | "currency";
+interface CellFormatInput {
+    bold?: boolean;
+    italic?: boolean;
+    textAlign?: "left" | "center" | "right";
+    displayFormat?: DisplayFormat;
+    decimals?: number;
+    color?: string;
+    backgroundColor?: string;
+    fontSize?: number;
+    borderTop?: string | null;
+    borderRight?: string | null;
+    borderBottom?: string | null;
+    borderLeft?: string | null;
+    currency?: string;
+}
+interface CommentInput {
+    text: string;
+    author?: string;
+    color?: string;
+}
+type CellPrimitive = string | number | boolean | null;
+interface CellData {
+    value?: CellPrimitive;
+    formula?: string;
+    computedValue?: CellPrimitive;
+    format?: CellFormatInput;
+    comment?: CommentInput;
+}
+type RowCell = CellPrimitive | CellData;
+type AggOp = "sum" | "avg" | "count" | "min" | "max";
+interface SheetSchema {
+    name: string;
+    columns?: ColumnSchema[];
+    rows?: RowCell[][];
+    theme?: ThemeKey;
+    totals?: Record<string, AggOp | string>;
+    cells?: Record<string, CellData>;
+    mergedRegions?: {
+        start: string;
+        end: string;
+    }[];
+    columnWidths?: Record<number | string, number>;
+    frozenRows?: number;
+    frozenCols?: number;
+}
+interface HolySheetSchema {
+    sheets: SheetSchema[];
+    meta?: {
+        creator?: string;
+        created?: string;
+    };
+}
+interface ValidationError {
+    path: string;
+    expected: string;
+    got: string;
+    value: unknown;
+    hint: string;
+}
+interface FormulaProblem {
+    sheet: string;
+    address: string;
+    formula: string;
+    error: string;
+    hint: string;
+}
+interface WriteResult {
+    path: string;
+    bytes: number;
+    sheets: number;
+}
+interface RepairResult {
+    schema: Record<string, unknown>;
+    errors: ValidationError[];
+    repairs: string[];
+}
+/** Options passed through ArrayBuilder / CsvBuilder. */
+interface BuilderOptions {
+    theme?: ThemeKey;
+    currency?: string;
+    totals?: Record<string, AggOp | string>;
+    frozenRows?: number;
+    frozenCols?: number;
+    sheetName?: string;
+    delimiter?: string;
+    enclosure?: string;
+}
+
+/** Feature-parity baseline with PHP holy-sheet; bumped independently on npm. */
+declare const VERSION = "1.0.0";
+type Any$5 = any;
+/**
+ * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
+ * Universal methods are synchronous; file-touching methods (`write`,
+ * `describe`-from-path) are async and Node-only (browsers have no sync FS).
+ */
+declare const Agent: {
+    /** Validate a schema without writing. Empty array = valid. */
+    validate(schema: Any$5): ValidationError[];
+    /** xlsx bytes without touching disk. Universal. Throws SchemaException if invalid. */
+    toBytes(schema: Any$5): Uint8Array;
+    /** Write a workbook to disk (Node only). Throws SchemaException if invalid. */
+    write(schema: Any$5, path: string): Promise<WriteResult>;
+    /** JSON Schema for LLM tool-use. */
+    toolDefinition(): Record<string, unknown>;
+    /** Round-trip xlsx bytes back to a schema. Universal. */
+    read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    /** Round-trip an xlsx file on disk back to a schema (Node only). */
+    describe(path: string): Promise<Record<string, unknown>>;
+    /** Validate + conservative repairs in one call. */
+    validateAndRepair(schema: Any$5): RepairResult;
+    /** Build a schema from a flat array of rows (+ optional headers). */
+    fromArray(rows: Any$5[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+    /** Build a schema from CSV content (read files yourself in Node). */
+    fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
+    /** Evaluate every formula and report Excel-style errors. Empty array = clean. */
+    lint(schema: Any$5): FormulaProblem[];
+    version(): string;
+};
+
+type Any$4 = any;
+/**
+ * Holy Sheet — instance entry point mirroring PHP `HolySheet`. Thin wrappers
+ * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
+ */
+declare class HolySheet {
+    static readonly VERSION = "1.0.0";
+    validate(schema: Any$4): ValidationError[];
+    toBytes(schema: Any$4): Uint8Array;
+    write(schema: Any$4, path: string): Promise<WriteResult>;
+    toolDefinition(): Record<string, unknown>;
+    read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    describe(path: string): Promise<Record<string, unknown>>;
+    validateAndRepair(schema: Any$4): RepairResult;
+    fromArray(rows: Any$4[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+    fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
+    lint(schema: Any$4): FormulaProblem[];
+    getVersion(): string;
+    static version(): string;
+}
+
+/** Thrown when a Holy Sheet schema fails validation. Mirrors PHP `SchemaException`. */
+declare class SchemaException extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[], message?: string);
+    static fromErrors(errors: ValidationError[]): SchemaException;
+    getErrors(): ValidationError[];
+}
+
+type Any$3 = any;
+/** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
+declare class Validator {
+    validate(schema: Any$3): ValidationError[];
+    assert(schema: Any$3): void;
+    validateAndRepair(schema: Any$3): RepairResult;
+    private validateSheet;
+    private validateColumn;
+}
+
+type Any$2 = any;
+/**
+ * Conservative, high-confidence schema repairs. Mirrors PHP `Schema\Repairer`.
+ * Returns [repairedSchema, repairs].
+ */
+declare class Repairer {
+    private repairs;
+    repair(schema: Any$2): [Record<string, unknown>, string[]];
+    private repairTopLevel;
+    private repairSheet;
+    private repairColumnTypeInference;
+    private repairStringifiedNumerics;
+}
+
+declare class CellComment {
+    readonly text: string;
+    readonly author: string | null;
+    readonly color: string | null;
+    constructor(text: string, author?: string | null, color?: string | null);
+}
+
+interface CellFormatProps {
+    bold?: boolean;
+    italic?: boolean;
+    textAlign?: string | null;
+    displayFormat?: DisplayFormat | null;
+    decimals?: number | null;
+    color?: string | null;
+    backgroundColor?: string | null;
+    fontSize?: number | null;
+    borderTop?: string | null;
+    borderRight?: string | null;
+    borderBottom?: string | null;
+    borderLeft?: string | null;
+    currency?: string | null;
+}
+/**
+ * Per-cell format. The writer's StylesRegistry deduplicates equal formats.
+ * Mirrors PHP `Workbook\CellFormat` (PHP named args → an options object here).
+ */
+declare class CellFormat {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly textAlign: string | null;
+    readonly displayFormat: DisplayFormat | null;
+    readonly decimals: number | null;
+    readonly color: string | null;
+    readonly backgroundColor: string | null;
+    readonly fontSize: number | null;
+    readonly borderTop: string | null;
+    readonly borderRight: string | null;
+    readonly borderBottom: string | null;
+    readonly borderLeft: string | null;
+    readonly currency: string | null;
+    constructor(p?: CellFormatProps);
+    /** Stable dedup key (JSON of ordered fields — replaces PHP md5(serialize)). */
+    key(): string;
+    isEmpty(): boolean;
+    static fromInput(a: CellFormatInput): CellFormat;
+    /** Merge another format on top of this one (other wins where set). */
+    mergeWith(other: CellFormat | null): CellFormat;
+}
+
+type ExcelType = "str" | "inlineStr" | "b" | "n";
+/** A single cell. Mirrors PHP `Workbook\Cell`. */
+declare class Cell {
+    readonly address: string;
+    readonly value: CellPrimitive;
+    readonly formula: string | null;
+    readonly format: CellFormat | null;
+    readonly comment: CellComment | null;
+    readonly cachedValue: CellPrimitive;
+    constructor(address: string, value: CellPrimitive, formula?: string | null, format?: CellFormat | null, comment?: CellComment | null, cachedValue?: CellPrimitive);
+    excelType(): ExcelType;
+}
+
+declare class MergedRegion {
+    readonly start: string;
+    readonly end: string;
+    constructor(start: string, end: string);
+    ref(): string;
+}
+
+/** A worksheet. Mirrors PHP `Workbook\Sheet`. Cells are an A1-keyed map. */
+declare class Sheet {
+    readonly name: string;
+    readonly cells: Map<string, Cell>;
+    readonly mergedRegions: MergedRegion[];
+    readonly columnWidths: Map<number, number>;
+    readonly frozenRows: number;
+    readonly frozenCols: number;
+    constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number);
+    /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
+    rows(): Map<number, Map<string, Cell>>;
+    hasComments(): boolean;
+    comments(): {
+        address: string;
+        comment: CellComment;
+    }[];
+}
+
+/** Internal canonical workbook value object. Mirrors PHP `Workbook\Workbook`. */
+declare class Workbook {
+    readonly sheets: Sheet[];
+    readonly meta: Record<string, unknown>;
+    constructor(sheets: Sheet[], meta?: Record<string, unknown>);
+}
+
+type Any$1 = any;
+/** Schema → canonical Workbook. Mirrors PHP `Schema\Normalizer`. */
+declare class Normalizer {
+    normalize(schema: Any$1): Workbook;
+    private normalizeSheet;
+    private normalizeCellMap;
+    private normalizeMerges;
+    private normalizeColumnWidths;
+    private columnFormat;
+    private buildCell;
+    private coerceValue;
+}
+
+/**
+ * Evaluates every formula and reports Excel-style errors. Mirrors PHP
+ * `Schema\FormulaLinter` rule-for-rule.
+ */
+declare class FormulaLinter {
+    private index;
+    private cache;
+    lint(schema: unknown): FormulaProblem[];
+    private buildIndex;
+    private isError;
+    private evaluate;
+    private tokenize;
+    private peek;
+    private isOp;
+    private parseExpr;
+    private parseConcat;
+    private parseArith;
+    private parseTerm;
+    private parseUnary;
+    private parsePrimary;
+    private resolveRefOrRange;
+    private cleanRef;
+    private cleanSheetName;
+    private resolveCell;
+    private resolveRange;
+    private expectOp;
+    private coerceNumber;
+    private coerceString;
+    private compare;
+    private cmpVal;
+    private callFunction;
+    private flatten;
+    private isNumericLike;
+    private maybeNum;
+    private avg;
+    private minMax;
+    private ifFn;
+    private hint;
+    private hintValue;
+}
+
+declare const Inference: {
+    detect(columnValues: unknown[], headerName: string, options?: BuilderOptions): ColumnSchema;
+};
+
+/** Theme presets — pre-baked CellFormat sets. Mirrors PHP `Schema\Theme`. */
+declare class Theme {
+    readonly key: string;
+    constructor(key: string);
+    headerFormat(): CellFormat | null;
+    dataFormat(rowIndexZeroBased: number): CellFormat | null;
+    totalsFormat(): CellFormat | null;
+}
+
+/**
+ * XLSX writer — emits a complete OOXML SpreadsheetML package as bytes.
+ * Mirrors PHP `Writer\XlsxWriter` (file I/O moved to the Agent for isomorphism).
+ */
+declare class XlsxWriter {
+    toBytes(workbook: Workbook): Uint8Array;
+    private contentTypesXml;
+    private rootRelsXml;
+    private workbookXml;
+    private workbookRelsXml;
+    private sheetRelsXml;
+    private sheetXml;
+    private cellXml;
+    private commentsXml;
+    private vmlDrawingXml;
+    private coreXml;
+    private appXml;
+    private escape;
+}
+
+/** XLSX reader — bytes → Holy Sheet schema. Mirrors PHP `Reader\XlsxReader`. */
+declare class XlsxReader {
+    describe(bytes: Uint8Array): Record<string, unknown>;
+    readWorkbook(bytes: Uint8Array): Workbook;
+    private parseDocProps;
+    private workbookToSchema;
+    private sheetToSchema;
+    private cellToSchema;
+}
+
+type Any = any;
+/**
+ * Flat rows (+ optional headers) → Holy Sheet schema with inferred column types.
+ * Mirrors PHP `Helpers\ArrayBuilder`.
+ */
+declare const ArrayBuilder: {
+    build(rows: Any[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+};
+
+/**
+ * CSV string → Holy Sheet schema. Mirrors PHP `Helpers\CsvBuilder`, but takes
+ * CSV *content* (isomorphic). To convert a file in Node, read it yourself and
+ * pass the string. First row is treated as headers.
+ */
+declare const CsvBuilder: {
+    build(csv: string, options?: BuilderOptions): HolySheetSchema;
+};
+
+/**
+ * A1 cell address utilities — column-letter ↔ 0-based index conversion,
+ * address parsing. Mirrors PHP `Workbook\CellAddress`.
+ */
+declare const CellAddress: {
+    /** 0-based column index → Excel-style letters. */
+    letter(index: number): string;
+    /** Column-letters → 0-based index. */
+    index(letters: string): number;
+    /** Parse an A1 address into [columnIndex, rowNumber] (1-based row), or null. */
+    parse(address: string): [number, number] | null;
+};
+
+interface ZipFile {
+    name: string;
+    data: Uint8Array;
+}
+declare function zipSync(files: ZipFile[]): Uint8Array;
+
+declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+
+export { Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DisplayFormat, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, Normalizer, type RepairResult, Repairer, type RowCell, SchemaException, type SheetSchema, Theme, type ThemeKey, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };