@particle-academy/holy-sheet 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -102,8 +102,8 @@ interface BuilderOptions {
     enclosure?: string;
 }
 
-/** Feature-parity baseline with PHP holy-sheet; bumped independently on npm. */
-declare const VERSION = "1.0.0";
+/** This package's own version, pinned to package.json by `version.test.ts`. */
+declare const VERSION = "2.3.0";
 type Any$5 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -119,9 +119,13 @@ declare const Agent: {
     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. */
+    /**
+     * Round-trip xlsx or ods bytes back to a schema. Universal. The format is
+     * told apart by content, never by name, and both describe to the same
+     * schema. Throws `UnsupportedFormatException` for anything else.
+     */
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
-    /** Round-trip an xlsx file on disk back to a schema (Node only). */
+    /** Round-trip an xlsx or ods 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;
@@ -140,7 +144,7 @@ type Any$4 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "1.0.0";
+    static readonly VERSION = "2.3.0";
     validate(schema: Any$4): ValidationError[];
     toBytes(schema: Any$4): Uint8Array;
     write(schema: Any$4, path: string): Promise<WriteResult>;
@@ -162,6 +166,23 @@ declare class SchemaException extends Error {
     static fromErrors(errors: ValidationError[]): SchemaException;
     getErrors(): ValidationError[];
 }
+/**
+ * Thrown by `Agent.read()` / `Agent.describe()` for a file that is neither an
+ * xlsx workbook nor an OpenDocument spreadsheet. Mirrors PHP
+ * `UnsupportedFormatException`.
+ *
+ * It extends Error, which is what an unreadable file threw before it existed,
+ * so an existing catch still catches it. `mimetype` carries what the package
+ * declared about itself when it declared anything (an OpenDocument TEXT file,
+ * say), so a caller can say "that is a document, not a spreadsheet".
+ */
+declare class UnsupportedFormatException extends Error {
+    readonly path: string | null;
+    readonly mimetype: string | null;
+    constructor(message: string, path?: string | null, mimetype?: string | null);
+    static notAZip(path?: string | null): UnsupportedFormatException;
+    static unknownPackage(path: string | null, mimetype: string | null): UnsupportedFormatException;
+}
 
 type Any$3 = any;
 /** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
@@ -372,12 +393,42 @@ declare class XlsxWriter {
 declare class XlsxReader {
     describe(bytes: Uint8Array): Record<string, unknown>;
     readWorkbook(bytes: Uint8Array): Workbook;
+    /** Read an already-unzipped package (name -> bytes), so a caller that sniffed it does not unzip twice. */
+    readFiles(files: Record<string, Uint8Array>): Workbook;
     private parseDocProps;
-    private workbookToSchema;
-    private sheetToSchema;
-    private cellToSchema;
 }
 
+/**
+ * OpenDocument Spreadsheet (.ods) reader — bytes → Holy Sheet schema, the same
+ * schema the xlsx reader returns. Mirrors PHP `Reader\OdsReader`, where what is
+ * and is not mapped is documented.
+ */
+declare class OdsReader {
+    describe(bytes: Uint8Array): Record<string, unknown>;
+    readWorkbook(bytes: Uint8Array): Workbook;
+    /** Read an already-unzipped package (name -> bytes). */
+    readFiles(files: Record<string, Uint8Array>): Workbook;
+    private readSheet;
+    private walkRows;
+    private readRow;
+}
+
+type SpreadsheetFormat = "xlsx" | "ods";
+/**
+ * Which reader a file needs, decided from its contents, never its extension.
+ * Mirrors PHP `Reader\FormatSniffer`.
+ *
+ * An OpenDocument package names itself in its `mimetype` entry; an xlsx has no
+ * such entry and is recognised by `xl/workbook.xml`. Anything else is refused
+ * by name. The unzipped entries are returned so the reader does not unzip again.
+ */
+declare const FormatSniffer: {
+    sniff(bytes: Uint8Array, path?: string | null): {
+        format: SpreadsheetFormat;
+        files: Record<string, Uint8Array>;
+    };
+};
+
 type Any = any;
 /**
  * Flat rows (+ optional headers) → Holy Sheet schema with inferred column types.
@@ -417,4 +468,4 @@ 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 };
+export { Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, Normalizer, OdsReader, type RepairResult, Repairer, type RowCell, SchemaException, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };

package/dist/index.d.ts

@@ -102,8 +102,8 @@ interface BuilderOptions {
     enclosure?: string;
 }
 
-/** Feature-parity baseline with PHP holy-sheet; bumped independently on npm. */
-declare const VERSION = "1.0.0";
+/** This package's own version, pinned to package.json by `version.test.ts`. */
+declare const VERSION = "2.3.0";
 type Any$5 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -119,9 +119,13 @@ declare const Agent: {
     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. */
+    /**
+     * Round-trip xlsx or ods bytes back to a schema. Universal. The format is
+     * told apart by content, never by name, and both describe to the same
+     * schema. Throws `UnsupportedFormatException` for anything else.
+     */
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
-    /** Round-trip an xlsx file on disk back to a schema (Node only). */
+    /** Round-trip an xlsx or ods 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;
@@ -140,7 +144,7 @@ type Any$4 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "1.0.0";
+    static readonly VERSION = "2.3.0";
     validate(schema: Any$4): ValidationError[];
     toBytes(schema: Any$4): Uint8Array;
     write(schema: Any$4, path: string): Promise<WriteResult>;
@@ -162,6 +166,23 @@ declare class SchemaException extends Error {
     static fromErrors(errors: ValidationError[]): SchemaException;
     getErrors(): ValidationError[];
 }
+/**
+ * Thrown by `Agent.read()` / `Agent.describe()` for a file that is neither an
+ * xlsx workbook nor an OpenDocument spreadsheet. Mirrors PHP
+ * `UnsupportedFormatException`.
+ *
+ * It extends Error, which is what an unreadable file threw before it existed,
+ * so an existing catch still catches it. `mimetype` carries what the package
+ * declared about itself when it declared anything (an OpenDocument TEXT file,
+ * say), so a caller can say "that is a document, not a spreadsheet".
+ */
+declare class UnsupportedFormatException extends Error {
+    readonly path: string | null;
+    readonly mimetype: string | null;
+    constructor(message: string, path?: string | null, mimetype?: string | null);
+    static notAZip(path?: string | null): UnsupportedFormatException;
+    static unknownPackage(path: string | null, mimetype: string | null): UnsupportedFormatException;
+}
 
 type Any$3 = any;
 /** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
@@ -372,12 +393,42 @@ declare class XlsxWriter {
 declare class XlsxReader {
     describe(bytes: Uint8Array): Record<string, unknown>;
     readWorkbook(bytes: Uint8Array): Workbook;
+    /** Read an already-unzipped package (name -> bytes), so a caller that sniffed it does not unzip twice. */
+    readFiles(files: Record<string, Uint8Array>): Workbook;
     private parseDocProps;
-    private workbookToSchema;
-    private sheetToSchema;
-    private cellToSchema;
 }
 
+/**
+ * OpenDocument Spreadsheet (.ods) reader — bytes → Holy Sheet schema, the same
+ * schema the xlsx reader returns. Mirrors PHP `Reader\OdsReader`, where what is
+ * and is not mapped is documented.
+ */
+declare class OdsReader {
+    describe(bytes: Uint8Array): Record<string, unknown>;
+    readWorkbook(bytes: Uint8Array): Workbook;
+    /** Read an already-unzipped package (name -> bytes). */
+    readFiles(files: Record<string, Uint8Array>): Workbook;
+    private readSheet;
+    private walkRows;
+    private readRow;
+}
+
+type SpreadsheetFormat = "xlsx" | "ods";
+/**
+ * Which reader a file needs, decided from its contents, never its extension.
+ * Mirrors PHP `Reader\FormatSniffer`.
+ *
+ * An OpenDocument package names itself in its `mimetype` entry; an xlsx has no
+ * such entry and is recognised by `xl/workbook.xml`. Anything else is refused
+ * by name. The unzipped entries are returned so the reader does not unzip again.
+ */
+declare const FormatSniffer: {
+    sniff(bytes: Uint8Array, path?: string | null): {
+        format: SpreadsheetFormat;
+        files: Record<string, Uint8Array>;
+    };
+};
+
 type Any = any;
 /**
  * Flat rows (+ optional headers) → Holy Sheet schema with inferred column types.
@@ -417,4 +468,4 @@ 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 };
+export { Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, Normalizer, OdsReader, type RepairResult, Repairer, type RowCell, SchemaException, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };