@office-kit/xlsx 0.8.0

package/dist/escape-DFTE7ZJc.mjs

@@ -0,0 +1,51 @@
+//#region src/utils/escape.ts
+const ILLEGAL_RE = /[\x00-\x1F\ud800-\udfff]/g;
+const ESCAPED_PATTERN_RE = /(_)(x[0-9A-Fa-f]{4}_)/g;
+const toHex4 = (n) => n.toString(16).toUpperCase().padStart(4, "0");
+/**
+* Escape a string for safe storage in an OOXML cell. Already-escaped
+* sequences (`_xHHHH_`) are protected by escaping their leading
+* underscore; illegal codepoints are replaced with their `_xHHHH_`
+* representation.
+*/
+function escapeCellString(s) {
+	return s.replace(ESCAPED_PATTERN_RE, "_x005F_$2").replace(ILLEGAL_RE, (ch) => `_x${toHex4(ch.charCodeAt(0))}_`);
+}
+const UNESCAPE_RE = /_x([0-9A-Fa-f]{4})_/g;
+/**
+* Inverse of {@link escapeCellString}. Looking from left to right
+* we replace any `_xHHHH_` sequence with the corresponding code unit;
+* the protected `_x005F_` becomes a literal underscore which the
+* subsequent replacements skip safely (replace's regex is non-overlapping).
+*/
+function unescapeCellString(s) {
+	return s.replace(UNESCAPE_RE, (_full, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+/**
+* Escape a string for safe placement in an XML text node. Replaces the three
+* codepoints that would otherwise terminate the text region or open a markup
+* sequence (`&`, `<`, `>`); `"` and `'` are not legal markup terminators
+* inside text and stay verbatim.
+*/
+function escapeXmlText(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+* Escape a string for safe placement inside a `"`-quoted XML attribute.
+* Handles `&`, `<`, `>` and the `"` that would otherwise close the value.
+*
+* Note: this deliberately does NOT escape `\r` / `\n` / `\t` to numeric
+* character references. XML 1.0 attribute-value normalisation would
+* collapse them to spaces in theory, but the parser used on the read side
+* (fast-xml-parser) does not decode numeric character references, so a
+* write-then-read round-trip would surface the literal `&#9;` instead of
+* recovering the original tab. Leaving the whitespace bytes literal keeps
+* the round-trip stable and matches what Excel itself emits.
+*/
+function escapeXmlAttr(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+//#endregion
+export { unescapeCellString as i, escapeXmlAttr as n, escapeXmlText as r, escapeCellString as t };
+
+//# sourceMappingURL=escape-DFTE7ZJc.mjs.map

package/dist/escape-DFTE7ZJc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-DFTE7ZJc.mjs","names":[],"sources":["../src/utils/escape.ts"],"sourcesContent":["// XML 1.0 cell-string escaping. Mirrors openpyxl/openpyxl/utils/escape.py.\n//\n// Excel emits cell strings with control characters and other illegal\n// XML 1.0 codepoints encoded as `_xHHHH_` (uppercase hex). The\n// underscore itself is a literal in normal text but a sequence opener\n// in escape position; an existing `_xHHHH_` in the input is therefore\n// re-escaped to `_x005F_xHHHH_` so it round-trips losslessly.\n\n// Escape every C0 control character (U+0000 through U+001F) plus the\n// surrogate range U+D800–U+DFFF. NUL is invalid in XML 1.0 entirely.\n// This range deliberately covers `\\t` (U+0009), `\\n` (U+000A) and `\\r`\n// (U+000D) even though XML 1.0 considers them legal whitespace — XML\n// parsers normalise CRLF / lone CR to LF on read, so a cell string\n// containing `\\r` would silently lose its CR without the `_x000D_`\n// encoding. openpyxl escapes the same `\\x01-\\x19` range; we add NUL\n// to keep the writer well-formed when callers feed in binary data.\nconst ILLEGAL_RE =\n  // biome-ignore lint/suspicious/noControlCharactersInRegex: by design — these are the codepoints we replace\n  /[\\x00-\\x1F\\ud800-\\udfff]/g;\nconst ESCAPED_PATTERN_RE = /(_)(x[0-9A-Fa-f]{4}_)/g;\n\nconst toHex4 = (n: number): string => n.toString(16).toUpperCase().padStart(4, '0');\n\n/**\n * Escape a string for safe storage in an OOXML cell. Already-escaped\n * sequences (`_xHHHH_`) are protected by escaping their leading\n * underscore; illegal codepoints are replaced with their `_xHHHH_`\n * representation.\n */\nexport function escapeCellString(s: string): string {\n  // Re-escape any existing `_xHHHH_` so it round-trips; the underscore\n  // becomes `_x005F_` and the rest of the sequence is left as-is.\n  const protectedString = s.replace(ESCAPED_PATTERN_RE, '_x005F_$2');\n  return protectedString.replace(ILLEGAL_RE, (ch) => `_x${toHex4(ch.charCodeAt(0))}_`);\n}\n\nconst UNESCAPE_RE = /_x([0-9A-Fa-f]{4})_/g;\n\n/**\n * Inverse of {@link escapeCellString}. Looking from left to right\n * we replace any `_xHHHH_` sequence with the corresponding code unit;\n * the protected `_x005F_` becomes a literal underscore which the\n * subsequent replacements skip safely (replace's regex is non-overlapping).\n */\nexport function unescapeCellString(s: string): string {\n  return s.replace(UNESCAPE_RE, (_full, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)));\n}\n\n// ---- XML escape helpers ----------------------------------------------------\n//\n// One canonical implementation for text-node and attribute escaping. The\n// previous codebase carried three near-identical copies (one each in save.ts,\n// xml/serializer.ts, xml/stream-writer.ts); they disagreed about `>`-in-attribute\n// handling and would have drifted further apart over time. Keeping them in a\n// single place also makes future fixes (e.g. surrogate-pair scrubbing) land\n// once rather than three times.\n\n/**\n * Escape a string for safe placement in an XML text node. Replaces the three\n * codepoints that would otherwise terminate the text region or open a markup\n * sequence (`&`, `<`, `>`); `\"` and `'` are not legal markup terminators\n * inside text and stay verbatim.\n */\nexport function escapeXmlText(s: string): string {\n  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');\n}\n\n/**\n * Escape a string for safe placement inside a `\"`-quoted XML attribute.\n * Handles `&`, `<`, `>` and the `\"` that would otherwise close the value.\n *\n * Note: this deliberately does NOT escape `\\r` / `\\n` / `\\t` to numeric\n * character references. XML 1.0 attribute-value normalisation would\n * collapse them to spaces in theory, but the parser used on the read side\n * (fast-xml-parser) does not decode numeric character references, so a\n * write-then-read round-trip would surface the literal `&#9;` instead of\n * recovering the original tab. Leaving the whitespace bytes literal keeps\n * the round-trip stable and matches what Excel itself emits.\n */\nexport function escapeXmlAttr(s: string): string {\n  return s\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n"],"mappings":";AAgBA,MAAM,aAEJ;AACF,MAAM,qBAAqB;AAE3B,MAAM,UAAU,MAAsB,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,GAAG;;;;;;;AAQlF,SAAgB,iBAAiB,GAAmB;CAIlD,OADwB,EAAE,QAAQ,oBAAoB,WACjC,EAAE,QAAQ,aAAa,OAAO,KAAK,OAAO,GAAG,WAAW,CAAC,CAAC,EAAE,EAAE;AACrF;AAEA,MAAM,cAAc;;;;;;;AAQpB,SAAgB,mBAAmB,GAAmB;CACpD,OAAO,EAAE,QAAQ,cAAc,OAAO,QAAgB,OAAO,aAAa,OAAO,SAAS,KAAK,EAAE,CAAC,CAAC;AACrG;;;;;;;AAiBA,SAAgB,cAAc,GAAmB;CAC/C,OAAO,EAAE,QAAQ,MAAM,OAAO,EAAE,QAAQ,MAAM,MAAM,EAAE,QAAQ,MAAM,MAAM;AAC5E;;;;;;;;;;;;;AAcA,SAAgB,cAAc,GAAmB;CAC/C,OAAO,EACJ,QAAQ,MAAM,OAAO,EACrB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,QAAQ;AAC3B"}

package/dist/exceptions-D-CFwxgm.mjs

@@ -0,0 +1,37 @@
+//#region src/utils/exceptions.ts
+var OpenXmlError = class extends Error {
+	name = "OpenXmlError";
+	constructor(message, options) {
+		super(message, options);
+	}
+};
+/** Thrown for ZIP, file system, network or stream-level failures. */
+var OpenXmlIoError = class extends OpenXmlError {
+	name = "OpenXmlIoError";
+};
+/** Thrown when an OOXML payload violates structural / schema invariants. */
+var OpenXmlSchemaError = class extends OpenXmlError {
+	name = "OpenXmlSchemaError";
+};
+/** Thrown when a workbook is structurally valid OOXML but semantically broken. */
+var OpenXmlInvalidWorkbookError = class extends OpenXmlError {
+	name = "OpenXmlInvalidWorkbookError";
+};
+/** Thrown for features the port has chosen not to implement (yet). */
+var OpenXmlNotImplementedError = class extends OpenXmlError {
+	name = "OpenXmlNotImplementedError";
+};
+/**
+* Thrown when an archive trips the decompression-bomb safeguards configured on
+* {@link openZip} / {@link loadWorkbook} / {@link loadWorkbookStream}. Subclass
+* of {@link OpenXmlIoError} so existing `catch (OpenXmlIoError)` paths still
+* see it, while letting callers branch on bomb-specific recovery (reject the
+* upload, log a security event, etc.).
+*/
+var OpenXmlDecompressionBombError = class extends OpenXmlIoError {
+	name = "OpenXmlDecompressionBombError";
+};
+//#endregion
+export { OpenXmlNotImplementedError as a, OpenXmlIoError as i, OpenXmlError as n, OpenXmlSchemaError as o, OpenXmlInvalidWorkbookError as r, OpenXmlDecompressionBombError as t };
+
+//# sourceMappingURL=exceptions-D-CFwxgm.mjs.map

package/dist/exceptions-D-CFwxgm.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions-D-CFwxgm.mjs","names":[],"sources":["../src/utils/exceptions.ts"],"sourcesContent":["// Error hierarchy for @office-kit/xlsx. Public APIs throw subclasses of OpenXmlError;\n// internals chain via the `cause` option (Node 18+ / modern browsers all\n// support Error.cause).\n//\n// Class is the one explicitly allowed exception to the no-class rule because\n// Error subclasses are how `instanceof` discrimination is expressed in JS.\n\nexport interface OpenXmlErrorOptions {\n  /** Underlying cause; preserved on the standard `cause` property. */\n  cause?: unknown;\n}\n\nexport class OpenXmlError extends Error {\n  override readonly name: string = 'OpenXmlError';\n\n  constructor(message: string, options?: OpenXmlErrorOptions) {\n    super(message, options as ErrorOptions);\n  }\n}\n\n/** Thrown for ZIP, file system, network or stream-level failures. */\nexport class OpenXmlIoError extends OpenXmlError {\n  override readonly name: string = 'OpenXmlIoError';\n}\n\n/** Thrown when an OOXML payload violates structural / schema invariants. */\nexport class OpenXmlSchemaError extends OpenXmlError {\n  override readonly name = 'OpenXmlSchemaError';\n}\n\n/** Thrown when a workbook is structurally valid OOXML but semantically broken. */\nexport class OpenXmlInvalidWorkbookError extends OpenXmlError {\n  override readonly name = 'OpenXmlInvalidWorkbookError';\n}\n\n/** Thrown for features the port has chosen not to implement (yet). */\nexport class OpenXmlNotImplementedError extends OpenXmlError {\n  override readonly name = 'OpenXmlNotImplementedError';\n}\n\n/**\n * Thrown when an archive trips the decompression-bomb safeguards configured on\n * {@link openZip} / {@link loadWorkbook} / {@link loadWorkbookStream}. Subclass\n * of {@link OpenXmlIoError} so existing `catch (OpenXmlIoError)` paths still\n * see it, while letting callers branch on bomb-specific recovery (reject the\n * upload, log a security event, etc.).\n */\nexport class OpenXmlDecompressionBombError extends OpenXmlIoError {\n  override readonly name = 'OpenXmlDecompressionBombError';\n}\n"],"mappings":";AAYA,IAAa,eAAb,cAAkC,MAAM;CACtC,OAAiC;CAEjC,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS,OAAuB;CACxC;AACF;;AAGA,IAAa,iBAAb,cAAoC,aAAa;CAC/C,OAAiC;AACnC;;AAGA,IAAa,qBAAb,cAAwC,aAAa;CACnD,OAAyB;AAC3B;;AAGA,IAAa,8BAAb,cAAiD,aAAa;CAC5D,OAAyB;AAC3B;;AAGA,IAAa,6BAAb,cAAgD,aAAa;CAC3D,OAAyB;AAC3B;;;;;;;;AASA,IAAa,gCAAb,cAAmD,eAAe;CAChE,OAAyB;AAC3B"}

package/dist/formula/tokenizer.d.ts

@@ -0,0 +1,61 @@
+import { OpenXmlError } from '../utils/exceptions';
+export declare class TokenizerError extends OpenXmlError {
+    readonly name = "TokenizerError";
+}
+export declare const LITERAL = "LITERAL";
+export declare const OPERAND = "OPERAND";
+export declare const FUNC = "FUNC";
+export declare const ARRAY = "ARRAY";
+export declare const PAREN = "PAREN";
+export declare const SEP = "SEP";
+export declare const OP_PRE = "OPERATOR-PREFIX";
+export declare const OP_IN = "OPERATOR-INFIX";
+export declare const OP_POST = "OPERATOR-POSTFIX";
+export declare const WSPACE = "WHITE-SPACE";
+type TokenType = typeof LITERAL | typeof OPERAND | typeof FUNC | typeof ARRAY | typeof PAREN | typeof SEP | typeof OP_PRE | typeof OP_IN | typeof OP_POST | typeof WSPACE;
+export declare const TEXT = "TEXT";
+export declare const NUMBER = "NUMBER";
+export declare const LOGICAL = "LOGICAL";
+export declare const ERROR = "ERROR";
+export declare const RANGE = "RANGE";
+export declare const OPEN = "OPEN";
+export declare const CLOSE = "CLOSE";
+export declare const ARG = "ARG";
+export declare const ROW = "ROW";
+type TokenSubtype = '' | typeof TEXT | typeof NUMBER | typeof LOGICAL | typeof ERROR | typeof RANGE | typeof OPEN | typeof CLOSE | typeof ARG | typeof ROW;
+export interface Token {
+    value: string;
+    type: TokenType;
+    subtype: TokenSubtype;
+}
+/** Build an OPERAND token, deriving the subtype from the value's shape. */
+export declare function makeOperand(value: string): Token;
+/**
+ * Build a "subexpression" token (FUNC / PAREN / ARRAY, OPEN or CLOSE).
+ *
+ * `value` must end with one of `{ } ( )`. If `func` is true, the type is forced
+ * to FUNC regardless of the bare-bracket heuristic — mirrors the `func=True`
+ * overload in openpyxl `Token.make_subexp`.
+ */
+export declare function makeSubexp(value: string, func?: boolean): Token;
+/** Build a SEP token (',' → ARG, ';' → ROW). */
+export declare function makeSeparator(value: ',' | ';'): Token;
+/** Scientific-notation guard: matches a coefficient ending in `[Ee]`. */
+export declare const SN_RE: RegExp;
+/** Whitespace run (space + LF, per Excel formula whitespace rules). */
+export declare const WSPACE_RE: RegExp;
+/** "..."-delimited string literal. Internal `""` is an escaped quote. */
+export declare const STRING_DOUBLE_RE: RegExp;
+/** '...'-delimited link / sheet name. Internal `''` is an escaped apostrophe. */
+export declare const STRING_SINGLE_RE: RegExp;
+/**
+ * Tokenize a formula string into a flat list of `Token`s.
+ *
+ * Mirrors `openpyxl.formula.tokenizer.Tokenizer(formula).items`. A formula that
+ * does not start with `=` becomes a single LITERAL token. Empty input yields
+ * the empty array.
+ */
+export declare function tokenize(formula: string): Token[];
+/** Render a token list back into the original formula string. */
+export declare function renderTokens(items: ReadonlyArray<Token>): string;
+export {};

package/dist/formula/translate.d.ts

@@ -0,0 +1,67 @@
+import { OpenXmlError } from '../utils/exceptions';
+import { type Token } from './tokenizer';
+export declare class TranslatorError extends OpenXmlError {
+    readonly name = "TranslatorError";
+}
+/** `1:1`, `$1234:78910`, etc. — pure-row range. */
+export declare const ROW_RANGE_RE: RegExp;
+/** `A:A`, `$ABC:AZZ` — pure-column range. */
+export declare const COL_RANGE_RE: RegExp;
+/** `A1`, `$AB$15` — single cell ref. */
+export declare const CELL_REF_RE: RegExp;
+/**
+ * Shift a row-snippet (`"3"` or `"$3"`) by `rdelta` rows. Absolute
+ * anchors return verbatim; falling below row 1 raises `TranslatorError`.
+ */
+export declare function translateRow(rowStr: string, rdelta: number): string;
+/**
+ * Shift a column-snippet (`"A"` or `"$A"`) by `cdelta` columns. Absolute
+ * anchors return verbatim; out-of-range raises `TranslatorError`.
+ */
+export declare function translateCol(colStr: string, cdelta: number): string;
+/**
+ * Split `Sheet!A1` into `["Sheet!", "A1"]`. Multi-`!` sheet names are not
+ * supported by Excel itself, so we just `rsplit('!', 1)`.
+ */
+export declare function stripWsName(rangeStr: string): [string, string];
+/**
+ * Translate an A1-style range reference (potentially worksheet-prefixed,
+ * potentially a named range) by `(rdelta, cdelta)`. Mirrors openpyxl
+ * `Translator.translate_range` exactly:
+ *
+ * - `1:1` / `$1234:78910` → row-range, only rows shift
+ * - `A:A` / `$ABC:AZZ` → col-range, only cols shift
+ * - `A1:B2` (with `:`) → recurse on each side, allowing named-range endpoints
+ * - `A1` → cell ref
+ * - anything else → assumed named range, returned verbatim
+ */
+export declare function translateRange(rangeStr: string, rdelta: number, cdelta: number): string;
+export interface TranslateOptions {
+    /** Destination cell address ("B2"). When set, derives `rowDelta`/`colDelta` from `origin`. */
+    dest?: string;
+    /** Explicit row delta. Ignored if `dest` is provided. */
+    rowDelta?: number;
+    /** Explicit col delta. Ignored if `dest` is provided. */
+    colDelta?: number;
+}
+/**
+ * Translate `formula` (defined at `origin`, e.g. "A1") to its destination
+ * cell. Pass either `{ dest }` or `{ rowDelta, colDelta }`. LITERAL
+ * formulas (input that does not start with `=`) and empty input pass
+ * through untouched.
+ */
+export declare function translateFormula(formula: string, origin: string, opts?: TranslateOptions): string;
+/**
+ * Convenience: tokenize once, expose the parsed list + the same translate
+ * helpers bound to a fixed origin. Mirrors openpyxl's `Translator` object.
+ */
+export interface Translator {
+    formula: string;
+    origin: string;
+    row: number;
+    col: number;
+    tokens: Token[];
+}
+export declare function makeTranslator(formula: string, origin: string): Translator;
+/** Render the translator's tokens back to the source string (sanity check). */
+export declare function translatorRender(t: Translator): string;

package/dist/inference-B3ES3KEJ.mjs

@@ -0,0 +1,42 @@
+//#region src/utils/inference.ts
+/** Excel error tokens. Anything outside this set is treated as a string. */
+const ERROR_CODES = new Set([
+	"#NULL!",
+	"#DIV/0!",
+	"#VALUE!",
+	"#REF!",
+	"#NAME?",
+	"#NUM!",
+	"#N/A",
+	"#GETTING_DATA"
+]);
+/**
+* Infer the cell `t` attribute for a runtime value.
+*
+* - `boolean` → 'b'
+* - `number` → 'n' (incl. integer numerics; date inference is left to
+*   the caller because Excel decides on type via the cell's number
+*   format, not the raw value)
+* - `Date` → 'd'
+* - string starting with `=` → 'f' (formula)
+* - string in {@link ERROR_CODES} → 'e'
+* - any other string → 's'
+* - `null` / `undefined` → 'n' (empty)
+*
+* Throws nothing — returns 'n' as the no-information fallback.
+*/
+function inferCellType(value) {
+	if (typeof value === "boolean") return "b";
+	if (typeof value === "number") return "n";
+	if (value instanceof Date) return "d";
+	if (typeof value === "string") {
+		if (value.length > 0 && value.charCodeAt(0) === 61) return "f";
+		if (ERROR_CODES.has(value)) return "e";
+		return "s";
+	}
+	return "n";
+}
+//#endregion
+export { inferCellType as n, ERROR_CODES as t };
+
+//# sourceMappingURL=inference-B3ES3KEJ.mjs.map

package/dist/inference-B3ES3KEJ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-B3ES3KEJ.mjs","names":[],"sources":["../src/utils/inference.ts"],"sourcesContent":["// Cell-value type inference. Maps a JS runtime value to the OOXML cell\n// `t` attribute value. Mirrors openpyxl's `Cell._bind_value` /\n// `_TYPES` / error-code path in openpyxl/openpyxl/cell/cell.py.\n\n/**\n * OOXML `t` attribute values. Note that 'inlineStr' is treated\n * separately — the writer chooses between 's' (shared string) and\n * 'inlineStr' based on workbook settings, not the value itself.\n */\nexport type CellDataType = 'n' | 's' | 'b' | 'd' | 'f' | 'e';\n\n/** Excel error tokens. Anything outside this set is treated as a string. */\nexport const ERROR_CODES: ReadonlySet<string> = new Set([\n  '#NULL!',\n  '#DIV/0!',\n  '#VALUE!',\n  '#REF!',\n  '#NAME?',\n  '#NUM!',\n  '#N/A',\n  '#GETTING_DATA',\n]);\n\n/**\n * Infer the cell `t` attribute for a runtime value.\n *\n * - `boolean` → 'b'\n * - `number` → 'n' (incl. integer numerics; date inference is left to\n *   the caller because Excel decides on type via the cell's number\n *   format, not the raw value)\n * - `Date` → 'd'\n * - string starting with `=` → 'f' (formula)\n * - string in {@link ERROR_CODES} → 'e'\n * - any other string → 's'\n * - `null` / `undefined` → 'n' (empty)\n *\n * Throws nothing — returns 'n' as the no-information fallback.\n */\nexport function inferCellType(value: unknown): CellDataType {\n  if (typeof value === 'boolean') return 'b';\n  if (typeof value === 'number') return 'n';\n  if (value instanceof Date) return 'd';\n  if (typeof value === 'string') {\n    if (value.length > 0 && value.charCodeAt(0) === 61 /* '=' */) return 'f';\n    if (ERROR_CODES.has(value)) return 'e';\n    return 's';\n  }\n  return 'n';\n}\n"],"mappings":";;AAYA,MAAa,cAAmC,IAAI,IAAI;CACtD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;;;;;;;;;;AAiBD,SAAgB,cAAc,OAA8B;CAC1D,IAAI,OAAO,UAAU,WAAW,OAAO;CACvC,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,iBAAiB,MAAM,OAAO;CAClC,IAAI,OAAO,UAAU,UAAU;EAC7B,IAAI,MAAM,SAAS,KAAK,MAAM,WAAW,CAAC,MAAM,IAAc,OAAO;EACrE,IAAI,YAAY,IAAI,KAAK,GAAG,OAAO;EACnC,OAAO;CACT;CACA,OAAO;AACT"}

package/dist/io/browser.d.ts

@@ -0,0 +1,41 @@
+import type { BufferedSinkWriter, XlsxSink } from './sink';
+import type { XlsxSource } from './source';
+/**
+ * Wrap a Blob (or File, since File extends Blob) as an XlsxSource. The
+ * source materialises bytes lazily on the first {@link XlsxSource.toBytes}
+ * call.
+ */
+export declare function fromBlob(blob: Blob): XlsxSource;
+/**
+ * Wrap a fetch {@link Response} as an XlsxSource. `toBytes` collects
+ * the entire response body via `Response.arrayBuffer()`; `toStream`
+ * returns `response.body` directly so the ZIP reader can pull chunks
+ * lazily from the network. The Response can have been fetched with
+ * any method and content-type; this helper does no validation.
+ */
+export declare function fromResponse(response: Response): XlsxSource;
+/**
+ * Wrap a Web {@link ReadableStream} of bytes as an XlsxSource. `toStream`
+ * returns the stream directly; `toBytes` drains it once and caches the
+ * bytes. Streams can only be consumed once — calling `toBytes` after
+ * `toStream` (or vice versa) on the same source throws.
+ */
+export declare function fromStream(stream: ReadableStream<Uint8Array>): XlsxSource;
+/**
+ * Wrap an ArrayBuffer or Uint8Array. The bytes are referenced (Uint8Array
+ * input) or wrapped without copy (ArrayBuffer input).
+ */
+export declare function fromArrayBuffer(buf: ArrayBuffer | Uint8Array): XlsxSource;
+/**
+ * In-memory Blob sink. Convenience `result()` returns the accumulated
+ * payload as a Blob with the supplied MIME type.
+ */
+export declare function toBlob(mime?: string): XlsxSink & {
+    toBytes(): BufferedSinkWriter;
+    result(): Blob;
+};
+/** In-memory ArrayBuffer sink. */
+export declare function toArrayBuffer(): XlsxSink & {
+    toBytes(): BufferedSinkWriter;
+    result(): ArrayBuffer;
+};

package/dist/io/index.d.ts

@@ -0,0 +1,7 @@
+export type { BufferedSinkWriter, XlsxSink } from './sink';
+export type { XlsxSource } from './source';
+export { fromArrayBuffer, fromBlob, fromResponse, fromStream, toArrayBuffer, toBlob, } from './browser';
+export type { LoadOptions } from './load';
+export { loadWorkbook } from './load';
+export type { SaveOptions } from './save';
+export { saveWorkbook, workbookToBytes } from './save';

package/dist/io/load.d.ts

@@ -0,0 +1,46 @@
+import type { XlsxSource } from '../io/source';
+import { type SheetState, type Workbook } from '../workbook/workbook';
+import { type XmlNode } from '../xml/tree';
+import type { DecompressionLimits } from '../zip/decompression-guard';
+/**
+ * Options for {@link loadWorkbook}. Earlier drafts exposed `readOnly` /
+ * `keepLinks` / `keepVba` / `dataOnly` / `richText` placeholders that the
+ * loader silently ignored; those were removed to keep the surface honest.
+ * Future toggles land here once their behavior is implemented.
+ */
+export interface LoadOptions {
+    /**
+     * Decompression-bomb safeguards applied while inflating zip entries.
+     * Defaults to limits that fit any legitimate xlsx; pass `false` to disable
+     * (only safe for fully trusted sources). See
+     * {@link DecompressionLimits} for the individual knobs.
+     */
+    decompressionLimits?: DecompressionLimits | false;
+}
+/**
+ * Resolve an OPC relationship target against its source part path.
+ *
+ * - Targets starting with `/` are package-absolute.
+ * - Otherwise the target is relative to the source part's parent directory.
+ * - `..` segments collapse normally.
+ */
+export declare function resolveRelTarget(sourcePartPath: string, target: string): string;
+interface SheetEntry {
+    /** Display name (`sheet/@name`). */
+    name: string;
+    /** Workbook-scope sheetId (`sheet/@sheetId`). */
+    sheetId: number;
+    /** Workbook rels Id (`sheet/@r:id`). */
+    rId: string;
+    /** Visibility state — defaults to `'visible'` when the attribute is absent. */
+    state: SheetState;
+}
+/** Extract the `<sheets>/<sheet>` entries from a parsed `xl/workbook.xml`. */
+export declare function parseSheetEntries(workbookRoot: XmlNode): SheetEntry[];
+/**
+ * Load a workbook from any {@link XlsxSource}. Currently produces a scaffold
+ * Workbook: each Worksheet is empty (no cells / styles / shared strings / theme
+ * yet). The next phase-3 iterations layer those in atop the same skeleton.
+ */
+export declare function loadWorkbook(source: XlsxSource, opts?: LoadOptions): Promise<Workbook>;
+export {};

package/dist/io/node-fs.d.ts

@@ -0,0 +1,62 @@
+import { Readable, Writable } from 'node:stream';
+import type { BufferedSinkWriter, XlsxSink } from './sink';
+import type { XlsxSource } from './source';
+/**
+ * Wrap a filesystem path as an XlsxSource. `toBytes` reads the whole file into
+ * memory; `toStream` opens a `fs.createReadStream` and bridges it to a Web
+ * {@link ReadableStream} via `Readable.toWeb` so the ZIP reader can iterate
+ * without loading the entire xlsx up front.
+ */
+export declare function fromFile(path: string): XlsxSource;
+/**
+ * Synchronous variant of {@link fromFile}. Convenience for tooling / scripts
+ * where the cost of `await fs.readFile` outweighs the ergonomic gain. The
+ * returned source's `toBytes` resolves immediately with the bytes already in
+ * memory.
+ */
+export declare function fromFileSync(path: string): XlsxSource;
+/**
+ * Filesystem sink. Each `write(chunk)` call streams the bytes to disk via
+ * `fs.createWriteStream`, honouring backpressure: the actual `writable.write`
+ * for each chunk is queued behind any pending `drain`, so the writable's
+ * internal buffer never grows past its `highWaterMark` (default 16 KB) no
+ * matter how fast the producer hands chunks over.
+ *
+ * Note on the producer-side memory budget: the sink contract is
+ * intentionally synchronous (`write(chunk): void`), so a producer that races
+ * ahead without yielding will let chunk references pile up in the queue.
+ * That keeps `writable`'s buffer bounded but does not bound the queue
+ * itself. Producers that need a hard ceiling should yield between writes
+ * (`await new Promise(setImmediate)` is enough) or use a sink with an async
+ * write contract.
+ *
+ * `result()` returns the destination path; `finish()` resolves with an empty
+ * `Uint8Array` once the stream has flushed. Callers that need the on-disk
+ * bytes should `readFile()` the returned path themselves — re-reading inside
+ * `finish()` would defeat the "streamed to disk, never resident" guarantee.
+ */
+export declare function toFile(path: string): XlsxSink & {
+    toBytes(): BufferedSinkWriter;
+    result(): string;
+};
+/**
+ * Wrap a Node.js {@link Readable} as an XlsxSource. `toBytes` consumes the
+ * entire stream synchronously (collecting chunks); `toStream` bridges to a Web
+ * ReadableStream via `Readable.toWeb` so the ZIP reader can pull chunks lazily.
+ */
+export declare function fromReadable(readable: Readable): XlsxSource;
+/**
+ * Wrap a Node.js {@link Writable} as an XlsxSink. The actual
+ * `writable.write` for each chunk is queued behind any pending `drain`, so
+ * the writable's internal buffer never exceeds its `highWaterMark` regardless
+ * of how fast the producer is. See {@link toFile} for the same caveat about
+ * producer-side memory: the synchronous `write(chunk)` API does not let
+ * backpressure flow back to the caller, so a tight non-yielding producer can
+ * still let chunk references accumulate in the queue.
+ *
+ * `result()` returns the writable itself for downstream chaining.
+ */
+export declare function toWritable(writable: Writable): XlsxSink & {
+    toBytes(): BufferedSinkWriter;
+    result(): Writable;
+};

package/dist/io/node-save.d.ts

@@ -0,0 +1,3 @@
+import type { Workbook } from '../workbook/workbook';
+import { type SaveOptions } from './save';
+export declare function workbookToBuffer(wb: Workbook, opts?: SaveOptions): Promise<Buffer>;

package/dist/io/node.d.ts

@@ -0,0 +1,17 @@
+import type { BufferedSinkWriter, XlsxSink } from './sink';
+import type { XlsxSource } from './source';
+/**
+ * Wrap a Buffer or Uint8Array as an XlsxSource. The underlying bytes are
+ * referenced — no copy — so callers must not mutate them while the source is in
+ * use.
+ */
+export declare function fromBuffer(buf: Buffer | Uint8Array): XlsxSource;
+/**
+ * In-memory Buffer sink. The buffered path concatenates appended chunks into a
+ * single allocation when {@link BufferedSinkWriter.finish} resolves; the
+ * convenience `result()` returns it as a Node Buffer.
+ */
+export declare function toBuffer(): XlsxSink & {
+    toBytes(): BufferedSinkWriter;
+    result(): Buffer;
+};

package/dist/io/save.d.ts

@@ -0,0 +1,14 @@
+import type { XlsxSink } from '../io/sink';
+import { type Workbook } from '../workbook/workbook';
+export interface SaveOptions {
+    /** Reserved — passes through to the underlying ZIP writer when implemented. */
+    compressionLevel?: number;
+}
+/** Convenience: serialise a Workbook to an in-memory `Uint8Array` xlsx.
+ *
+ * Browser-safe: this path uses an in-memory `Uint8Array` sink and never
+ * touches Node's `Buffer` global, so it works unchanged in browser bundles.
+ */
+export declare function workbookToBytes(wb: Workbook, opts?: SaveOptions): Promise<Uint8Array>;
+/** Save a workbook through the given sink. Returns once `finalize()` resolves. */
+export declare function saveWorkbook(wb: Workbook, sink: XlsxSink, _opts?: SaveOptions): Promise<void>;

package/dist/io/sink.d.ts

@@ -0,0 +1,54 @@
+export interface BufferedSinkWriter {
+    /** Append a chunk. Must not throw under normal use; errors surface in {@link finish}. */
+    write(chunk: Uint8Array): void;
+    /**
+     * Signal that no more chunks are coming. For in-memory sinks (`toBuffer` /
+     * `toBlob` / `toArrayBuffer`) the resolved `Uint8Array` is the full payload;
+     * for streaming sinks (`toFile` / `toWritable`) the resolved value is an
+     * empty `Uint8Array(0)` once the underlying writable has flushed — the bytes
+     * have already been forwarded to disk / the wrapped Writable and are
+     * deliberately not buffered for re-emission here. Read the destination via
+     * the sink's own `result()` instead.
+     */
+    finish(): Promise<Uint8Array>;
+    /**
+     * Abandon the writer. Called by the ZIP writer (and `saveWorkbook` /
+     * `loadWorkbookStream` writers) when the surrounding pipeline throws before
+     * `finish()` runs. Implementations must release any underlying resource:
+     * `toFile` destroys the Node `WriteStream` and best-effort removes the
+     * half-written file; `toWritable` destroys the wrapped Writable; in-memory
+     * sinks simply drop their buffered chunks.
+     *
+     * Idempotent. Must not throw — the surrounding catch already has the cause
+     * the caller cares about; obscuring it with a cleanup error helps nobody.
+     * Optional for backwards compatibility, but writers should provide it.
+     */
+    abort?(cause?: unknown): void | Promise<void>;
+}
+export interface XlsxSink {
+    /**
+     * Chunked-write API. Returns a writer with `write(chunk)` + `finish()`.
+     *
+     * The name is historical: this is the only entry the ZIP writer drives, and
+     * the underlying object can either accumulate chunks in memory (buffered
+     * sinks) or forward them to disk / a Writable as they arrive (streaming
+     * sinks). The ZIP writer never holds the full archive itself, so the choice
+     * of sink decides whether peak memory is "compressed archive size" or
+     * "single chunk + deflate scratch".
+     *
+     * Required: `createZipWriter` calls this on every sink. The method stayed
+     * `?:` historically while a `toStream()` alternative was being prototyped,
+     * but the streaming-WritableStream variant never landed and leaving it
+     * optional only masked the runtime "sink does not expose toBytes()" error
+     * behind a missing-property exception.
+     */
+    toBytes(): BufferedSinkWriter;
+    /**
+     * Streaming mode: returns a WritableStream into which the writer pipes
+     * chunks. Backpressure is honoured by the underlying sink. Currently
+     * unused by the ZIP writer (see {@link toBytes}); kept optional so that
+     * future writer paths can opt into a `WritableStream`-shaped backend
+     * without breaking existing sink implementations.
+     */
+    toStream?(): WritableStream<Uint8Array>;
+}

package/dist/io/source.d.ts

@@ -0,0 +1,14 @@
+export interface XlsxSource {
+    /**
+     * Resolve the full payload as a single Uint8Array. Memory-bounded; acceptable
+     * for all xlsx parts up to ~hundreds of MB. For larger payloads use {@link
+     * toStream}.
+     */
+    toBytes(): Promise<Uint8Array>;
+    /**
+     * Sequential byte stream. Optional — implementations that have no cheap
+     * streaming representation may omit it. Consumers should fall back to {@link
+     * toBytes} when undefined.
+     */
+    toStream?(): ReadableStream<Uint8Array>;
+}