@particle-academy/holy-sheet 2.2.1 → 2.3.1

package/dist/index.d.cts

@@ -103,7 +103,7 @@ interface BuilderOptions {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.2.1";
+declare const VERSION = "2.3.1";
 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 = "2.2.1";
+    static readonly VERSION = "2.3.1";
     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`. */
@@ -301,6 +322,12 @@ declare class Normalizer {
 declare class FormulaLinter {
     private index;
     private cache;
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    private sheetNames;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
@@ -316,6 +343,10 @@ declare class FormulaLinter {
     private parsePrimary;
     private resolveRefOrRange;
     private cleanRef;
+    /**
+     * Unwrap the single quotes Excel puts around a sheet name that needs them,
+     * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+     */
     private cleanSheetName;
     private resolveCell;
     private resolveRange;
@@ -332,6 +363,7 @@ declare class FormulaLinter {
     private minMax;
     private ifFn;
     private hint;
+    private hintRef;
     private hintValue;
 }
 
@@ -372,12 +404,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 +479,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

@@ -103,7 +103,7 @@ interface BuilderOptions {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.2.1";
+declare const VERSION = "2.3.1";
 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 = "2.2.1";
+    static readonly VERSION = "2.3.1";
     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`. */
@@ -301,6 +322,12 @@ declare class Normalizer {
 declare class FormulaLinter {
     private index;
     private cache;
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    private sheetNames;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
@@ -316,6 +343,10 @@ declare class FormulaLinter {
     private parsePrimary;
     private resolveRefOrRange;
     private cleanRef;
+    /**
+     * Unwrap the single quotes Excel puts around a sheet name that needs them,
+     * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+     */
     private cleanSheetName;
     private resolveCell;
     private resolveRange;
@@ -332,6 +363,7 @@ declare class FormulaLinter {
     private minMax;
     private ifFn;
     private hint;
+    private hintRef;
     private hintValue;
 }
 
@@ -372,12 +404,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 +479,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 };