@shbernal/ts-xlsx 1.0.0

package/dist/io/opc/read-opc.js

@@ -0,0 +1,153 @@
+// The OPC (Open Packaging Conventions) layer of the reader: resolving relationship targets to part
+// paths, reading a part's `.rels`, resolving a part's declared content type, and walking the transitive
+// closure of parts a preserved reference reaches. Every helper here is pure over the inflated package —
+// it takes part text/bytes accessors and returns paths or records, touching no Workbook model.
+import { strFromU8 } from 'fflate';
+import { openElements } from "../../xml/xml-read.js";
+import { extensionOf, relsPathFor } from "./part-paths.js";
+// Bind the part-lookup accessors over an inflated package (a part-path → bytes map).
+export function packageAccessors(files) {
+    return {
+        partText(path) {
+            const bytes = files[path];
+            return bytes === undefined ? undefined : strFromU8(bytes);
+        },
+        partBytes: (path) => files[path],
+    };
+}
+// Whether a <Relationship> carries a resolvable Target and its Type ends with `/<suffix>` (a
+// local-name match, so a namespaced or oddly-cased type still resolves). The type guard lets a
+// matching relationship's Target be read without a further presence check.
+function matchesType(attrs, suffix) {
+    return (attrs.Type !== undefined && attrs.Target !== undefined && attrs.Type.endsWith(`/${suffix}`));
+}
+// The Target of the first relationship whose Type ends with `/<suffix>`, or undefined when none is
+// declared — for a single expected reference, where the plural form below would over-gather.
+export function relationshipTargetByType(xml, suffix) {
+    return relationshipTargetsByType(xml, suffix)[0];
+}
+// Every Target whose Type ends with `/<suffix>`, in declaration order — for a part class a sheet may
+// reference more than once (a sheet can own several tables), where the singular helper's first-match
+// would miss all but one.
+export function relationshipTargetsByType(xml, suffix) {
+    const targets = [];
+    for (const { attrs } of openElements(xml, 'Relationship')) {
+        if (matchesType(attrs, suffix))
+            targets.push(attrs.Target);
+    }
+    return targets;
+}
+// The package part a sheet reaches through the first relationship of a given type, already resolved
+// relative to the sheet — the "load the sheet's rels, find the one relationship of this type, resolve
+// its target" preamble every single-part sheet lookup (notes, printer settings, drawing, background)
+// opens with. undefined when the sheet has no rels part or declares no such relationship.
+export function sheetRelTarget(sheetPath, partText, type) {
+    const relsXml = partText(relsPathFor(sheetPath));
+    if (relsXml === undefined)
+        return undefined;
+    const target = relationshipTargetByType(relsXml, type);
+    return target === undefined ? undefined : resolveRelativePart(sheetPath, target);
+}
+// Resolve a relationship target (relative to the referencing part's directory, or absolute from the
+// package root) into a package part path, collapsing `.`/`..` segments.
+export function resolveRelativePart(basePart, target) {
+    if (target.startsWith('/'))
+        return target.slice(1);
+    const baseDir = basePart.slice(0, basePart.lastIndexOf('/') + 1);
+    const out = [];
+    for (const segment of `${baseDir}${target}`.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out.join('/');
+}
+// A workbook relationship target is relative to the `xl/` directory (`worksheets/sheet1.xml`)
+// or absolute from the package root (`/xl/worksheets/sheet1.xml`); normalise both to a part path.
+export function resolveWorkbookPart(target) {
+    if (target.startsWith('/'))
+        return target.slice(1);
+    return `xl/${target.replace(/^\.\//, '')}`;
+}
+export function parseRelationships(xml) {
+    const rels = new Map();
+    for (const { attrs } of openElements(xml, 'Relationship')) {
+        if (attrs.Id !== undefined && attrs.Target !== undefined) {
+            rels.set(attrs.Id, attrs.Target);
+        }
+    }
+    return rels;
+}
+export function parseRelationshipRecords(xml) {
+    const records = [];
+    for (const { attrs } of openElements(xml, 'Relationship')) {
+        if (attrs.Id !== undefined && attrs.Type !== undefined && attrs.Target !== undefined) {
+            records.push({
+                id: attrs.Id,
+                type: attrs.Type,
+                target: attrs.Target,
+                external: attrs.TargetMode === 'External',
+            });
+        }
+    }
+    return records;
+}
+// Resolve a package part path to its declared content type the way OPC does: an `<Override>` naming
+// the exact part wins, else the `<Default>` registered for the part's extension. An unknown part
+// falls back to the generic binary type so re-declaring it never emits an empty content type.
+export function contentTypeResolver(contentTypesXml) {
+    const overrides = new Map();
+    const defaults = new Map();
+    for (const { local, attrs } of openElements(contentTypesXml, 'Override', 'Default')) {
+        if (local === 'Override' && attrs.PartName !== undefined && attrs.ContentType !== undefined) {
+            overrides.set(attrs.PartName, attrs.ContentType);
+        }
+        else if (local === 'Default' &&
+            attrs.Extension !== undefined &&
+            attrs.ContentType !== undefined) {
+            defaults.set(attrs.Extension.toLowerCase(), attrs.ContentType);
+        }
+    }
+    return (path) => overrides.get(`/${path}`) ??
+        defaults.get(extensionOf(path).toLowerCase()) ??
+        'application/octet-stream';
+}
+// Gather the transitive closure of package parts reachable from an entry part — the part itself, then
+// every internal part its relationships target, breadth-first — each with its raw bytes, content type,
+// and (internal) relationships. Returns undefined when the entry part is absent (a dangling reference
+// preserves nothing). A `visited` set dedupes shared parts and bounds the walk to the (finite,
+// inflate-capped) package, so a maliciously self-referential rels graph cannot loop.
+export function capturePartClosure(entryPath, partText, partBytes, contentTypeOf) {
+    const parts = [];
+    const visited = new Set();
+    const queue = [entryPath];
+    while (queue.length > 0) {
+        const path = queue.shift();
+        if (path === undefined || visited.has(path))
+            continue;
+        visited.add(path);
+        const bytes = partBytes(path);
+        if (bytes === undefined)
+            continue;
+        const relsXml = partText(relsPathFor(path));
+        const rels = [];
+        if (relsXml !== undefined) {
+            for (const rel of parseRelationshipRecords(relsXml)) {
+                if (rel.external) {
+                    // A linked workbook lives outside the package: keep the wiring verbatim (an externalLink
+                    // part's pointer to its source), but do not walk into it — there is no package part to visit.
+                    rels.push({ id: rel.id, type: rel.type, targetPath: rel.target, external: true });
+                    continue;
+                }
+                const targetPath = resolveRelativePart(path, rel.target);
+                rels.push({ id: rel.id, type: rel.type, targetPath });
+                queue.push(targetPath);
+            }
+        }
+        parts.push({ path, contentType: contentTypeOf(path), bytes, rels });
+    }
+    return parts.some((part) => part.path === entryPath) ? parts : undefined;
+}

package/dist/io/opc/read-options.d.ts

@@ -0,0 +1,10 @@
+export interface ReadXlsxOptions {
+    /**
+     * Maximum total uncompressed output, in bytes, produced while inflating the package.
+     * The bound is enforced by a running counter as bytes are decompressed — never read from
+     * the archive's (untrusted, forgeable) size headers — so a zip bomb that lies about its
+     * uncompressed size is rejected all the same. Defaults to 512 MiB.
+     */
+    readonly maxUncompressedBytes?: number;
+}
+export declare const DEFAULT_MAX_UNCOMPRESSED: number;

package/dist/io/opc/read-options.js

@@ -0,0 +1,7 @@
+// The one knob every reader takes, declared apart from any of them.
+//
+// `readXlsx`, `readXlsb`, and the row streamer all inflate the same OPC container under the same
+// bound, so the option bag belongs to none of them individually — and a reader that dispatches to
+// another (the `.xlsx` entry point hands a binary package to the `.xlsb` codec) cannot import it from
+// its peer without the two modules importing each other.
+export const DEFAULT_MAX_UNCOMPRESSED = 512 * 1024 * 1024;

package/dist/io/opc/rels.d.ts

@@ -0,0 +1,15 @@
+export declare function relationship(id: string, type: string, target: string, options?: {
+    external?: boolean;
+}): string;
+export declare function relationshipsPart(relationships: readonly string[]): string;
+export declare function preservedRelsXml(rels: readonly {
+    id: string;
+    type: string;
+    target: string;
+    external?: boolean;
+}[]): string;
+export declare function relsPartXml(rels: readonly {
+    id: string;
+    type: string;
+    target: string;
+}[]): string;

package/dist/io/opc/rels.js

@@ -0,0 +1,28 @@
+// The write side of the relationship graph: a single `<Relationship>` element and the `.rels` part
+// envelope that wraps a set of them. Pure OPC — a `.rels` part has the same shape whatever the parts
+// it wires together are spelled in, so this is stated once here rather than inside a codec.
+//
+// The reader's half of the same graph (resolving targets, walking a part closure) is in `read-opc.ts`.
+import { escapeAttr, XML_DECLARATION } from "../../xml/xml.js";
+import { PKG_RELS_NS } from "./namespaces.js";
+// A single `<Relationship>`. An `external` target lives outside the package (a hyperlink URL), so the
+// element carries `TargetMode="External"`; a package-internal target (the default) omits it. The caller
+// escapes the target when it is not a writer-controlled package path.
+export function relationship(id, type, target, options) {
+    const mode = options?.external ? ' TargetMode="External"' : '';
+    return `<Relationship Id="${id}" Type="${type}" Target="${target}"${mode}/>`;
+}
+// Wrap a part's `<Relationship>` elements in the OPC `.rels` envelope (XML declaration + the namespaced
+// `<Relationships>` root). Every `.rels` part the writer emits shares this envelope; only the elements
+// inside differ, so each caller builds its own list of {@link relationship} strings and hands them here.
+export function relationshipsPart(relationships) {
+    return `${XML_DECLARATION}<Relationships xmlns="${PKG_RELS_NS}">${relationships.join('')}</Relationships>`;
+}
+export function preservedRelsXml(rels) {
+    return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, escapeAttr(rel.target), rel.external ? { external: true } : {})));
+}
+// A `.rels` part for a generated part chain (pivot table → cache definition → cache records). Targets
+// are writer-controlled package paths, so no attribute escaping is needed.
+export function relsPartXml(rels) {
+    return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, rel.target)));
+}

package/dist/io/opc/sniff-format.d.ts

@@ -0,0 +1,27 @@
+import { UnsupportedFormatError } from './errors.ts';
+/** The container kind a leading magic-byte sniff distinguishes, before any inflation. */
+export type Container = 'cfb' | 'zip' | 'other';
+/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
+export declare function sniffContainer(data: Uint8Array): Container;
+/**
+ * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
+ * that is neither into a typed error before or instead of a raw zip failure:
+ * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
+ *   fflate never runs on it;
+ * - a non-ZIP blob → {@link UnsupportedFormatError} `'unknown'`, likewise caught before inflation;
+ * - a `PK`-headed blob that fflate then rejects as malformed → {@link PackageReadError}, with the
+ *   underlying zip message discarded so no internals (or path) leak.
+ *
+ * The bounded-inflation guard (a probable zip bomb) already raises {@link PackageReadError} with its
+ * own informative message, and is re-thrown unchanged.
+ */
+export declare function inflateSpreadsheetPackage(data: Uint8Array, cap: number): Record<string, Uint8Array>;
+/**
+ * The typed error for an inflated package that carries no `xl/workbook.xml`: a `.xlsb` if its binary
+ * `xl/workbook.bin` office document is present, otherwise an unrecognised (non-workbook) ZIP.
+ *
+ * The `.xlsb` branch takes the caller's own explanation, because whether a binary workbook is
+ * readable now depends on *which* entry point was asked: `readXlsx` reads one, the row streamer
+ * cannot yet. A single baked-in "not supported" message would be wrong for one of them.
+ */
+export declare function unsupportedWorkbookPart(partText: (path: string) => string | undefined, xlsbMessage: string): UnsupportedFormatError;

package/dist/io/opc/sniff-format.js

@@ -0,0 +1,92 @@
+// Front of the read pipe: format detection, the inflate bound both readers share, and the typed
+// rejection of everything that is neither an `.xlsx` nor an `.xlsb`.
+//
+// The reader's first job on an arbitrary blob is to reject what it cannot read with a clear, typed
+// error rather than a raw fflate crash. A cheap magic-byte sniff runs *before* the zip layer (so a
+// legacy `.xls` compound file or non-ZIP garbage fails fast, before fflate throws its opaque "end of
+// central directory" error — which can also leak an absolute path from below), and a malformed ZIP is
+// translated after it.
+//
+// The two outcomes are deliberately different types, because they answer different questions. A blob
+// the sniff rejects is the *wrong kind of thing* — {@link UnsupportedFormatError}, branchable on
+// `.format`. A `PK`-headed blob the zip layer then chokes on is the right kind of thing we cannot
+// unpack — {@link PackageReadError}. Whichever it is, the message states the check that actually ran,
+// and callers branch on the type, never on message text.
+//
+// The `.xlsx` and `.xlsb` serialisations share this whole layer — same container, same bound, same
+// rejections — so it is stated once here and neither reader owns it.
+import { PackageReadError, UnsupportedFormatError } from "./errors.js";
+import { inflatePackage } from "./inflate.js";
+// The OLE2 / Compound File Binary signature ([MS-CFB] 2.2) that opens every legacy `.xls` (and the
+// `.doc`/`.ppt` siblings). `src/vba/cfb.ts` reads this same magic for `vbaProject.bin`; here we need
+// only recognise it, not parse the container.
+const CFB_MAGIC = Uint8Array.of(0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1);
+// The ZIP local-file-header signature (`PK\x03\x04`) that opens every OPC package — `.xlsx`, `.xlsb`,
+// and the rest. An empty or spanned archive starts with a different `PK` marker, but a real workbook
+// package always leads with a local file header.
+const ZIP_LOCAL_FILE_MAGIC = Uint8Array.of(0x50, 0x4b, 0x03, 0x04);
+/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
+export function sniffContainer(data) {
+    if (startsWith(data, CFB_MAGIC))
+        return 'cfb';
+    if (startsWith(data, ZIP_LOCAL_FILE_MAGIC))
+        return 'zip';
+    return 'other';
+}
+function startsWith(data, magic) {
+    if (data.length < magic.length)
+        return false;
+    for (let i = 0; i < magic.length; i++) {
+        if (data[i] !== magic[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
+ * that is neither into a typed error before or instead of a raw zip failure:
+ * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
+ *   fflate never runs on it;
+ * - a non-ZIP blob → {@link UnsupportedFormatError} `'unknown'`, likewise caught before inflation;
+ * - a `PK`-headed blob that fflate then rejects as malformed → {@link PackageReadError}, with the
+ *   underlying zip message discarded so no internals (or path) leak.
+ *
+ * The bounded-inflation guard (a probable zip bomb) already raises {@link PackageReadError} with its
+ * own informative message, and is re-thrown unchanged.
+ */
+export function inflateSpreadsheetPackage(data, cap) {
+    const container = sniffContainer(data);
+    if (container === 'cfb')
+        throw new UnsupportedFormatError('xls');
+    // Not the default message: nothing here has looked for a workbook part, and saying so would point
+    // an investigation a layer past the one that actually refused.
+    if (container === 'other') {
+        throw new UnsupportedFormatError('unknown', 'not a valid .xlsx package: the input is not a ZIP');
+    }
+    try {
+        return inflatePackage(data, cap);
+    }
+    catch (err) {
+        // The bomb guard already throws the right type with a better message — surface it. Anything else
+        // is fflate reporting a malformed archive: same classification (a ZIP we cannot unpack), but its
+        // raw text is replaced wholesale rather than wrapped or attached as `cause`, because it comes from
+        // a layer whose strings may name internals — or an absolute path — that must not reach a caller.
+        if (err instanceof PackageReadError)
+            throw err;
+        throw new PackageReadError('not a readable .xlsx package: the ZIP container is corrupt or truncated and could not be inflated');
+    }
+}
+/**
+ * The typed error for an inflated package that carries no `xl/workbook.xml`: a `.xlsb` if its binary
+ * `xl/workbook.bin` office document is present, otherwise an unrecognised (non-workbook) ZIP.
+ *
+ * The `.xlsb` branch takes the caller's own explanation, because whether a binary workbook is
+ * readable now depends on *which* entry point was asked: `readXlsx` reads one, the row streamer
+ * cannot yet. A single baked-in "not supported" message would be wrong for one of them.
+ */
+export function unsupportedWorkbookPart(partText, xlsbMessage) {
+    if (partText('xl/workbook.bin') !== undefined) {
+        return new UnsupportedFormatError('xlsb', xlsbMessage);
+    }
+    return new UnsupportedFormatError('unknown');
+}

package/dist/io/style/xf-style.d.ts

@@ -0,0 +1,47 @@
+import { type Cell } from '../../core/cell.ts';
+import type { CellStyle, Font, NamedCellStyle } from '../../core/style.ts';
+/**
+ * What an xf resolves to: the {@link CellStyle} facet tuple, plus the two flags an xf carries that
+ * are not facets. Absent facets stay undefined, matching the contract that an unset facet is simply
+ * not present on the reconstructed cell.
+ *
+ * It *derives* the facets rather than listing them, so a seventh facet added to `CellStyle` reaches
+ * both readers the moment it joins. Re-declaring them here — the shape this replaced — meant a new
+ * facet silently stopped at the model and never appeared in a file we read back.
+ */
+export interface XfStyle extends CellStyle {
+    readonly quotePrefix?: boolean;
+    /** The `xfId` link into the named-style layer (`cellStyleXfs`); absent for the Normal default (0). */
+    readonly xfId?: number;
+}
+/** The parsed style table: the cell formats a cell/row/column `s` indexes, plus the named cell-style
+ * layer a cell's `xfId` links into. Each cellXfs entry is already merged with its named style, so a
+ * cell reading its `s` sees the effective facets; the `xfId` link is carried through for re-write. */
+export interface StyleTable {
+    readonly cellXfs: ReadonlyArray<XfStyle>;
+    readonly namedStyles: ReadonlyArray<NamedCellStyle>;
+    /**
+     * Font id 0 — the workbook's declared default font, the face every cell naming no font renders in.
+     * Surfaced separately from the fonts it was flattened onto because it is workbook-level state, not a
+     * cell format: a re-write must emit *this* face as font 0 rather than an assumed Calibri, or every
+     * empty cell changes face and every character-unit column width changes meaning. Absent when the
+     * file declares no font table.
+     */
+    readonly defaultFont?: Font;
+}
+/**
+ * The format code a number-format id denotes: the file's own `<numFmt>`/`BrtFmt` declaration if it
+ * has one, else the built-in Excel defines for that id. Id 0 is General — the absence of a format —
+ * and resolves to nothing so an ordinary cell carries no `numFmt`.
+ */
+export declare function numFmtCodeFor(id: number, custom: ReadonlyMap<number, string>): string | undefined;
+/**
+ * Apply a resolved xf's non-value facets to a cell — the six {@link CellStyle} facets through the
+ * shared {@link applyCellStyle}, plus the two links that live on the xf itself rather than in the
+ * facet tuple (`quotePrefix`, and the `xfId` pointer into the named-style layer).
+ *
+ * Shared by every path that commits a cell: the XML reader's ordinary and shared-formula-clone paths,
+ * and the BIFF12 reader — so a styled cell keeps its look regardless of which serialisation it came
+ * from, and the two cannot drift on what "applying a style" means.
+ */
+export declare function applyXfToCell(cell: Cell, style: XfStyle | undefined): void;

package/dist/io/style/xf-style.js

@@ -0,0 +1,95 @@
+// The resolved cell-format table both codecs read into: what an xf *is* once its id-indirection is
+// flattened, which of the two number-format tables an id resolves against, and what applying an xf to
+// a cell means.
+//
+// None of that is a property of how the style table is spelled — `xl/styles.xml` and `xl/styles.bin`
+// state the same model in XML and BIFF12 records — so it is stated once here, above both codecs. The
+// XML parsing lives in `../xlsx/read-styles.ts`, the record parsing in `../xlsb/read-styles.ts`, and
+// each hands back the same {@link StyleTable}.
+import { applyCellStyle } from "../../core/cell.js";
+import { NAMED_STYLE_ID } from "../../core/internal.js";
+// ECMA-376 reserves numFmt ids below 164 for formats every consumer knows implicitly, so a
+// foreign file may name one with no <numFmt> entry. This maps the standard ids to their
+// codes; id 0 (General) and any unknown id resolve to no format. The writer never emits
+// these — it always defines a custom id — but reading them keeps foreign files faithful.
+const BUILTIN_NUMFMTS = new Map([
+    [1, '0'],
+    [2, '0.00'],
+    [3, '#,##0'],
+    [4, '#,##0.00'],
+    [9, '0%'],
+    [10, '0.00%'],
+    [11, '0.00E+00'],
+    [12, '# ?/?'],
+    [13, '# ??/??'],
+    [14, 'mm-dd-yy'],
+    [15, 'd-mmm-yy'],
+    [16, 'd-mmm'],
+    [17, 'mmm-yy'],
+    [18, 'h:mm AM/PM'],
+    [19, 'h:mm:ss AM/PM'],
+    [20, 'h:mm'],
+    [21, 'h:mm:ss'],
+    [22, 'm/d/yy h:mm'],
+    [37, '#,##0 ;(#,##0)'],
+    [38, '#,##0 ;[Red](#,##0)'],
+    [39, '#,##0.00;(#,##0.00)'],
+    [40, '#,##0.00;[Red](#,##0.00)'],
+    [45, 'mm:ss'],
+    [46, '[h]:mm:ss'],
+    [47, 'mmss.0'],
+    [48, '##0.0E+0'],
+    [49, '@'],
+    // Ids 27..36 and 50..58 are reserved for locale-specific built-in East Asian date/time formats;
+    // a file authored in a CJK locale styles date cells with them and, being built-ins, emits no
+    // <numFmt>. The exact code is locale-defined — these are the representative Excel forms — but what
+    // matters for reading is that each resolves to a non-empty date/time code so the serial reads as a
+    // date rather than a bare number.
+    [27, '[$-404]e/m/d'],
+    [28, '[$-404]e"年"m"月"d"日"'],
+    [29, '[$-404]e"年"m"月"d"日"'],
+    [30, '[$-404]m/d/yy'],
+    [31, '[$-404]yyyy"年"m"月"d"日"'],
+    [32, '[$-404]h"時"mm"分"'],
+    [33, '[$-404]h"時"mm"分"ss"秒"'],
+    [34, '上午/下午h"時"mm"分"'],
+    [35, '上午/下午h"時"mm"分"ss"秒"'],
+    [36, '[$-404]e/m/d'],
+    [50, '[$-404]e/m/d'],
+    [51, '[$-404]e"年"m"月"d"日"'],
+    [52, '[$-404]yyyy"年"m"月"'],
+    [53, '[$-404]m"月"d"日"'],
+    [54, '[$-404]e"年"m"月"d"日"'],
+    [55, '上午/下午h"時"mm"分"'],
+    [56, '上午/下午h"時"mm"分"ss"秒"'],
+    [57, '[$-404]yyyy"年"m"月"'],
+    [58, '[$-404]m"月"d"日"'],
+]);
+/**
+ * The format code a number-format id denotes: the file's own `<numFmt>`/`BrtFmt` declaration if it
+ * has one, else the built-in Excel defines for that id. Id 0 is General — the absence of a format —
+ * and resolves to nothing so an ordinary cell carries no `numFmt`.
+ */
+export function numFmtCodeFor(id, custom) {
+    if (!Number.isInteger(id) || id === 0)
+        return undefined;
+    return custom.get(id) ?? BUILTIN_NUMFMTS.get(id);
+}
+/**
+ * Apply a resolved xf's non-value facets to a cell — the six {@link CellStyle} facets through the
+ * shared {@link applyCellStyle}, plus the two links that live on the xf itself rather than in the
+ * facet tuple (`quotePrefix`, and the `xfId` pointer into the named-style layer).
+ *
+ * Shared by every path that commits a cell: the XML reader's ordinary and shared-formula-clone paths,
+ * and the BIFF12 reader — so a styled cell keeps its look regardless of which serialisation it came
+ * from, and the two cannot drift on what "applying a style" means.
+ */
+export function applyXfToCell(cell, style) {
+    if (style === undefined)
+        return;
+    applyCellStyle(cell, style);
+    if (style.quotePrefix !== undefined)
+        cell.quotePrefix = style.quotePrefix;
+    if (style.xfId !== undefined)
+        cell[NAMED_STYLE_ID] = style.xfId;
+}

package/dist/io/xlsb/errors.d.ts

@@ -0,0 +1,15 @@
+import { XlsxError } from '../../errors.ts';
+/**
+ * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed — a record whose declared
+ * size runs past the end of its part, a truncated record header, or a structure that does not conform
+ * to [MS-XLSB].
+ *
+ * The record streams are hostile input (a spreadsheet library parses untrusted files), so a malformed
+ * part fails closed with this error rather than crashing, hanging, or over-allocating. It is distinct
+ * from {@link UnsupportedFormatError}, which reports that the *container* is not a format we read at
+ * all; by the time this is raised the input has already been recognised as an `.xlsb`.
+ */
+export declare class XlsbParseError extends XlsxError {
+    readonly name = "XlsbParseError";
+    readonly code = "malformed-input";
+}

package/dist/io/xlsb/errors.js

@@ -0,0 +1,15 @@
+import { XlsxError } from "../../errors.js";
+/**
+ * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed — a record whose declared
+ * size runs past the end of its part, a truncated record header, or a structure that does not conform
+ * to [MS-XLSB].
+ *
+ * The record streams are hostile input (a spreadsheet library parses untrusted files), so a malformed
+ * part fails closed with this error rather than crashing, hanging, or over-allocating. It is distinct
+ * from {@link UnsupportedFormatError}, which reports that the *container* is not a format we read at
+ * all; by the time this is raised the input has already been recognised as an `.xlsb`.
+ */
+export class XlsbParseError extends XlsxError {
+    name = 'XlsbParseError';
+    code = 'malformed-input';
+}

package/dist/io/xlsb/formula.d.ts

@@ -0,0 +1,48 @@
+/** One `Xti` ([MS-XLSB] 2.5.163): the span of sheets, in one supporting book, that an `ixti` names. */
+export interface ExternSheetRef {
+    readonly supBook: number;
+    /** Zero-based sheet index; the span is inclusive. */
+    readonly firstSheet: number;
+    readonly lastSheet: number;
+}
+/** The workbook-level tables a formula's references and names resolve through. */
+export interface FormulaScope {
+    /** Sheet names in workbook (tab) order — what an `Xti`'s sheet indices point into. */
+    readonly sheetNames: readonly string[];
+    /** The `BrtExternSheet` table, indexed by a 3-D token's `ixti`. */
+    readonly externSheets: readonly ExternSheetRef[];
+    /** The index of the supporting book that is this workbook, or `undefined` when the file declares a
+     * supporting book this reader does not recognise. A workbook with no external links declares
+     * exactly one — itself — so this is the ordinary case; anything else leaves the indices untrustworthy
+     * and no 3-D reference resolves, which drops those formulas rather than naming the wrong sheet. */
+    readonly selfSupBook: number | undefined;
+    /** Every `BrtName` in file order, function placeholders included — a `PtgName` cites one by
+     * **1-based** index, so filtering this list would misaddress every name reference. */
+    readonly names: readonly string[];
+}
+/** The cell a `PtgExp`/`PtgTbl` stream defers to: the top-left of the shared or array formula group. */
+export interface FormulaAnchor {
+    /** Zero-based. */
+    readonly row: number;
+    readonly column: number;
+}
+/**
+ * Decode a `CellParsedFormula`'s token stream into formula text, in the same on-disk spelling the XML
+ * form writes into `<f>` — `_xlfn.`-prefixed function names included, so the caller applies the same
+ * `unmangleFunctions` normalisation to either serialisation.
+ *
+ * @param rgce the token stream.
+ * @param rgcb the trailing extra-data block: the array constants, and the cell ranges a precomputed
+ *   range token refers to. Its entries are consumed in token order.
+ * @returns the formula text, or `undefined` if the stream uses a token this reader does not decode.
+ * @throws {XlsbParseError} if a token runs past the end of the stream (a malformed formula).
+ */
+export declare function decodeFormula(rgce: Uint8Array, rgcb: Uint8Array, scope: FormulaScope): string | undefined;
+/**
+ * The master cell a token stream defers to, when the stream is nothing but a `PtgExp` (a shared or
+ * array formula's member) or a `PtgTbl` (a data-table cell) rather than a formula of its own.
+ *
+ * The column lives in the extra-data block rather than the token, which is the one place BIFF12
+ * splits a single reference across the two halves of a `CellParsedFormula`.
+ */
+export declare function formulaAnchor(rgce: Uint8Array, rgcb: Uint8Array): FormulaAnchor | undefined;