@shbernal/ts-xlsx 1.0.0

package/dist/io/csv/read.d.ts

@@ -0,0 +1,15 @@
+import type { CellValue } from '../../core/value.ts';
+import { Workbook } from '../../core/workbook.ts';
+export interface CsvReadOptions {
+    /** Field separator; defaults to a comma. A single character. */
+    readonly delimiter?: string;
+    /** Treat the first line as a header and drop it, leaving only data rows. */
+    readonly headers?: boolean;
+    /** Per-field transform replacing the default type coercion; receives the raw string and its
+     * 0-based column index. */
+    readonly map?: (value: string, index: number) => CellValue;
+    /** Name for the single worksheet produced; defaults to `"Sheet1"`. */
+    readonly sheetName?: string;
+}
+/** Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet. */
+export declare function readCsv(input: string | Uint8Array, options?: CsvReadOptions): Workbook;

package/dist/io/csv/read.js

@@ -0,0 +1,113 @@
+// CSV parsing — flat delimited text back into a one-sheet workbook.
+//
+// The hard part of reading CSV is not splitting fields; it is deciding a field's *type* without
+// corrupting data. The rules here are deliberate and lossless-by-default:
+//   - An empty field is the empty cell (`null`); a whitespace-only field is a string, never the
+//     number 0 that `Number("   ")` would silently produce.
+//   - A numeric-looking field becomes a number only when its magnitude is exactly representable
+//     (within the safe-integer range); an oversized id like a 20-digit account number is kept as
+//     its original string so no digits are lost.
+//   - Only a strictly-formatted ISO date (`YYYY-MM-DD`, optional time) becomes a Date; padded ids
+//     and dash-codes such as `2020-00001` or `1-3` stay strings.
+// A caller can override coercion wholesale with `map` (e.g. the identity function to keep every
+// field a raw string, preserving leading zeros).
+import { Workbook } from "../../core/workbook.js";
+import { AuthoringError } from "../../errors.js";
+/** Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet. */
+export function readCsv(input, options = {}) {
+    const text = stripBom(typeof input === 'string' ? input : Buffer.from(input).toString('utf8'));
+    const delimiter = options.delimiter ?? ',';
+    if (delimiter.length !== 1) {
+        throw new AuthoringError(`CSV delimiter must be a single character, got ${JSON.stringify(delimiter)}`);
+    }
+    let rows = parseCsvRows(text, delimiter);
+    if (options.headers)
+        rows = rows.slice(1);
+    const coerce = options.map ?? defaultCsvCoerce;
+    const workbook = new Workbook();
+    const sheet = workbook.addWorksheet(options.sheetName ?? 'Sheet1');
+    sheet.addRows(rows.map((fields) => fields.map((field, index) => coerce(field, index))));
+    return workbook;
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+// A character-scan parser: quotes toggle literal mode, a doubled quote inside a quoted field is one
+// quote, and a row ends on LF (a preceding CR is dropped, so CRLF and LF read the same). A final
+// trailing newline does not yield a spurious empty row.
+function parseCsvRows(text, delimiter) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += ch;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === delimiter) {
+            row.push(field);
+            field = '';
+        }
+        else if (ch === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else if (ch !== '\r') {
+            field += ch;
+        }
+    }
+    row.push(field);
+    const trailingNewline = text.endsWith('\n') || text.endsWith('\r');
+    if (!(trailingNewline && row.length === 1 && row[0] === ''))
+        rows.push(row);
+    return rows;
+}
+const NUMERIC = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+function defaultCsvCoerce(field) {
+    if (field === '')
+        return null;
+    if (NUMERIC.test(field)) {
+        const value = Number(field);
+        // Beyond the safe-integer range a double silently loses digits; keep the original text instead.
+        return Number.isFinite(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER ? value : field;
+    }
+    const iso = ISO_DATE.exec(field);
+    if (iso) {
+        const date = isoToDate(iso);
+        if (date !== null)
+            return date;
+    }
+    return field;
+}
+function isoToDate(match) {
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = match[4] === undefined ? 0 : Number(match[4]);
+    const minute = match[5] === undefined ? 0 : Number(match[5]);
+    const second = match[6] === undefined ? 0 : Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) {
+        return null;
+    }
+    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    return Number.isNaN(date.getTime()) ? null : date;
+}

package/dist/io/csv/write.d.ts

@@ -0,0 +1,28 @@
+import type { CellValue } from '../../core/value.ts';
+import type { Workbook } from '../../core/workbook.ts';
+export interface CsvWriteOptions {
+    /** Which worksheet to write; defaults to the first. A name matching no sheet throws rather than
+     * silently emitting an empty file. */
+    readonly sheetName?: string;
+    /** Field separator; defaults to a comma. */
+    readonly delimiter?: string;
+    /** Line separator between rows; defaults to `"\n"`. */
+    readonly rowDelimiter?: string;
+    /** A token format (e.g. `"MM/DD/YYYY"`) for Date cells; without it a Date renders as a full
+     * ISO-8601 timestamp. */
+    readonly dateFormat?: string;
+    /** Render Date cells in UTC rather than the runner's local time. */
+    readonly dateUTC?: boolean;
+    /** Byte encoding for {@link writeCsv}; defaults to `"utf8"`. */
+    readonly encoding?: BufferEncoding;
+    /** Prepend a UTF-8 byte-order mark (applies only to UTF-8); defaults to `true` for UTF-8. */
+    readonly bom?: boolean;
+    /** Per-field transform replacing the default value rendering; receives the cell's value (`null`
+     * for an unpopulated column) and its 0-based column index. Quoting (commas, quotes, newlines) is
+     * still applied to the returned text. */
+    readonly map?: (value: CellValue, index: number) => string;
+}
+/** The logical CSV text of one worksheet — no BOM, no byte encoding. */
+export declare function writeCsvText(workbook: Workbook, options?: CsvWriteOptions): string;
+/** The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default. */
+export declare function writeCsv(workbook: Workbook, options?: CsvWriteOptions): Uint8Array;

package/dist/io/csv/write.js

@@ -0,0 +1,124 @@
+// CSV serialization — the flat-text sibling of the XLSX writer.
+//
+// A worksheet is a rectangle of typed cells; CSV is that rectangle flattened to delimited
+// text. The lossy direction (styles, formulas-as-formulas, multiple sheets) is inherent to the
+// format, so this writer makes the honest choices explicit: one selected sheet, each row sized to
+// its own populated extent (never clamped to a sibling row's width), a formula rendered as its
+// cached result, a Date rendered by a caller-supplied format or a full ISO-8601 timestamp.
+//
+// `writeCsvText` yields the logical text; `writeCsv` encodes it to bytes and — for UTF-8, the
+// default — prepends a byte-order mark so a consumer such as Excel detects the encoding and does
+// not mangle non-ASCII on open. The BOM is a byte-level marker, not part of the logical text.
+import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from "../../core/value.js";
+import { AuthoringError } from "../../errors.js";
+const UTF8_BOM = Uint8Array.of(0xef, 0xbb, 0xbf);
+/** The logical CSV text of one worksheet — no BOM, no byte encoding. */
+export function writeCsvText(workbook, options = {}) {
+    const sheet = selectSheet(workbook, options.sheetName);
+    const delimiter = options.delimiter ?? ',';
+    const rowDelimiter = options.rowDelimiter ?? '\n';
+    const lines = [];
+    for (const { cells } of sheet.rows()) {
+        let width = 0;
+        const byColumn = new Map();
+        for (const cell of cells) {
+            byColumn.set(cell.col, cell);
+            if (cell.col > width)
+                width = cell.col;
+        }
+        const fields = [];
+        for (let column = 1; column <= width; column++) {
+            const value = byColumn.get(column)?.value ?? null;
+            const text = options.map ? options.map(value, column - 1) : csvFieldText(value, options);
+            fields.push(quoteField(text, delimiter));
+        }
+        lines.push(fields.join(delimiter));
+    }
+    return lines.join(rowDelimiter);
+}
+/** The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default. */
+export function writeCsv(workbook, options = {}) {
+    const text = writeCsvText(workbook, options);
+    const encoding = options.encoding ?? 'utf8';
+    const body = Buffer.from(text, encoding);
+    const wantBom = options.bom ?? encoding === 'utf8';
+    if (!wantBom || encoding !== 'utf8')
+        return Uint8Array.from(body);
+    const out = new Uint8Array(UTF8_BOM.length + body.length);
+    out.set(UTF8_BOM, 0);
+    out.set(body, UTF8_BOM.length);
+    return out;
+}
+function selectSheet(workbook, name) {
+    if (name === undefined) {
+        const first = workbook.worksheets[0];
+        if (first === undefined)
+            throw new AuthoringError('workbook has no worksheet to write as CSV');
+        return first;
+    }
+    const sheet = workbook.getWorksheet(name);
+    if (sheet === undefined)
+        throw new AuthoringError(`no worksheet named "${name}" to write as CSV`);
+    return sheet;
+}
+function csvFieldText(value, options) {
+    if (value === null)
+        return '';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Date)
+        return formatDate(value, options.dateFormat, options.dateUTC ?? false);
+    if (isErrorValue(value))
+        return value.error;
+    if (isRichTextValue(value))
+        return richTextToPlain(value);
+    if (isHyperlinkValue(value)) {
+        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
+    }
+    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+        return value.result === undefined ? '' : csvFieldText(value.result, options);
+    }
+    return '';
+}
+const DATE_TOKENS = /YYYY|YY|MM|DD|HH|mm|ss|M|D|H|m|s/g;
+function formatDate(date, format, utc) {
+    if (Number.isNaN(date.getTime()))
+        return '';
+    if (format === undefined)
+        return date.toISOString();
+    const year = utc ? date.getUTCFullYear() : date.getFullYear();
+    const month = (utc ? date.getUTCMonth() : date.getMonth()) + 1;
+    const day = utc ? date.getUTCDate() : date.getDate();
+    const hour = utc ? date.getUTCHours() : date.getHours();
+    const minute = utc ? date.getUTCMinutes() : date.getMinutes();
+    const second = utc ? date.getUTCSeconds() : date.getSeconds();
+    const pad = (n) => String(n).padStart(2, '0');
+    const tokens = {
+        YYYY: String(year),
+        YY: pad(year % 100),
+        MM: pad(month),
+        M: String(month),
+        DD: pad(day),
+        D: String(day),
+        HH: pad(hour),
+        H: String(hour),
+        mm: pad(minute),
+        m: String(minute),
+        ss: pad(second),
+        s: String(second),
+    };
+    return format.replace(DATE_TOKENS, (token) => tokens[token] ?? token);
+}
+function quoteField(field, delimiter) {
+    if (field.includes(delimiter) ||
+        field.includes('"') ||
+        field.includes('\n') ||
+        field.includes('\r')) {
+        return `"${field.replace(/"/g, '""')}"`;
+    }
+    return field;
+}

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

@@ -0,0 +1,46 @@
+import { XlsxError } from '../../errors.ts';
+/**
+ * Which unsupported input the reader recognised:
+ * - `'xls'` — a legacy BIFF `.xls` (an OLE2/CFB compound file), detected by its magic bytes.
+ * - `'xlsb'` — a binary BIFF12 `.xlsb`: the same OPC/ZIP container as `.xlsx`, but its office document
+ *   is `xl/workbook.bin` rather than `xl/workbook.xml`. `readXlsx`/`readXlsb` read one; the entry points
+ *   that cannot yet (the row streamer) report it under this format with their own message.
+ * - `'unknown'` — not a recognised spreadsheet at all: not a ZIP, or a ZIP carrying no OOXML workbook
+ *   part (nor a `.xlsb` binary one).
+ */
+export type UnsupportedFormat = 'xls' | 'xlsb' | 'unknown';
+/**
+ * Thrown when input is not a readable `.xlsx` package. The single {@link format} field is the branch a
+ * caller keys on (rather than a subclass per format), so a `catch` can distinguish a legacy `.xls`, a
+ * binary `.xlsb`, and an unrecognised blob without string-matching the message.
+ *
+ * The message never carries a filesystem path or the underlying zip library's internals — the whole
+ * point of the type is that the classification, not a leaked lower-layer string, is what the caller sees.
+ *
+ * {@link format} stays the branch for *which* unsupported input this was; the inherited
+ * {@link XlsxError.code} answers the coarser question of what kind of failure it is.
+ */
+export declare class UnsupportedFormatError extends XlsxError {
+    readonly name = "UnsupportedFormatError";
+    readonly code = "unsupported-format";
+    readonly format: UnsupportedFormat;
+    constructor(format: UnsupportedFormat, message?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the input *is* a ZIP container but it cannot be unpacked: the archive is corrupt or
+ * truncated, or inflating it would push total uncompressed output past the caller's bound (which is
+ * how a zip bomb presents).
+ *
+ * The neighbouring {@link UnsupportedFormatError} says the input is a different *kind* of thing; this
+ * one says it is the right kind and we will not (or cannot) unpack it. Keeping them apart is what
+ * lets a caller answer "should I try another reader, or reject this file?" — and it is what replaced
+ * the message-prefix match the bomb refusal used to be recognised by.
+ *
+ * The zip library's own failure text never survives into either the message or `cause`: it can name
+ * internals — or an absolute filesystem path — from the layer below, and this type carries the
+ * classification precisely so no lower-layer string has to.
+ */
+export declare class PackageReadError extends XlsxError {
+    readonly name = "PackageReadError";
+    readonly code = "malformed-input";
+}

package/dist/io/opc/errors.js

@@ -0,0 +1,49 @@
+// Typed errors the reader raises when it is handed something that is not a readable OOXML `.xlsx`
+// package. A spreadsheet library parses untrusted files, so the failure a caller sees must be a clear,
+// programmatically-branchable signal — not a raw zip-internals string (which is opaque, and can leak an
+// absolute filesystem path from the layer below). See the spec
+// `docs/knowledge/specs/unsupported-input-format-typed-error.md`.
+import { XlsxError } from "../../errors.js";
+const DEFAULT_MESSAGE = {
+    xls: 'the legacy .xls binary format (BIFF/OLE2 compound file) is not supported; only OOXML .xlsx is read',
+    xlsb: 'this entry point does not read the binary .xlsb format (BIFF12)',
+    unknown: 'not a valid .xlsx package: no OOXML workbook part was found',
+};
+/**
+ * Thrown when input is not a readable `.xlsx` package. The single {@link format} field is the branch a
+ * caller keys on (rather than a subclass per format), so a `catch` can distinguish a legacy `.xls`, a
+ * binary `.xlsb`, and an unrecognised blob without string-matching the message.
+ *
+ * The message never carries a filesystem path or the underlying zip library's internals — the whole
+ * point of the type is that the classification, not a leaked lower-layer string, is what the caller sees.
+ *
+ * {@link format} stays the branch for *which* unsupported input this was; the inherited
+ * {@link XlsxError.code} answers the coarser question of what kind of failure it is.
+ */
+export class UnsupportedFormatError extends XlsxError {
+    name = 'UnsupportedFormatError';
+    code = 'unsupported-format';
+    format;
+    constructor(format, message = DEFAULT_MESSAGE[format], options) {
+        super(message, options);
+        this.format = format;
+    }
+}
+/**
+ * Thrown when the input *is* a ZIP container but it cannot be unpacked: the archive is corrupt or
+ * truncated, or inflating it would push total uncompressed output past the caller's bound (which is
+ * how a zip bomb presents).
+ *
+ * The neighbouring {@link UnsupportedFormatError} says the input is a different *kind* of thing; this
+ * one says it is the right kind and we will not (or cannot) unpack it. Keeping them apart is what
+ * lets a caller answer "should I try another reader, or reject this file?" — and it is what replaced
+ * the message-prefix match the bomb refusal used to be recognised by.
+ *
+ * The zip library's own failure text never survives into either the message or `cause`: it can name
+ * internals — or an absolute filesystem path — from the layer below, and this type carries the
+ * classification precisely so no lower-layer string has to.
+ */
+export class PackageReadError extends XlsxError {
+    name = 'PackageReadError';
+    code = 'malformed-input';
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Inflate every part of an `.xlsx` zip package, enforcing a hard ceiling on total
+ * decompressed output.
+ *
+ * @param data The raw zip bytes.
+ * @param cap  Maximum total uncompressed output, in bytes, across all parts. Enforced
+ *   against bytes actually produced, never against the archive's declared sizes.
+ * @returns A map of part path to inflated bytes.
+ * @throws {@link PackageReadError} if inflation would exceed `cap` — a probable zip bomb.
+ * @throws {Error} raised by the zip layer if the archive is malformed or a part uses an unsupported
+ *   compression method. Callers reach this through {@link inflateSpreadsheetPackage}, which is where
+ *   those are classified; the raw error is deliberately not re-typed here, because its text is the
+ *   one thing that must not reach a caller unfiltered.
+ */
+export declare function inflatePackage(data: Uint8Array, cap: number): Record<string, Uint8Array>;

package/dist/io/opc/inflate.js

@@ -0,0 +1,91 @@
+// Bounded, streaming inflation of an OPC (`.xlsx`) zip package.
+//
+// Decompression is the reader's first hostile-input surface: a "zip bomb" ships a few
+// kilobytes that inflate to gigabytes. The zip's own size headers cannot be trusted to
+// bound this — they are attacker-controlled. A header that declares a *large* size makes a
+// naïve reader preallocate that much (an amplifier: tiny input, huge allocation); a header
+// that lies *small* makes a size-preallocating inflater silently truncate real data. So we
+// consult the declared sizes for nothing. Instead the compressed archive is fed to fflate's
+// streaming unzip in slices, the decompressor grows its output from the bytes it actually
+// produces, and a running counter of real output aborts the moment it crosses the cap.
+//
+// Because DEFLATE cannot expand input by more than ~1032:1, feeding at most INPUT_SLICE
+// compressed bytes before each counter check bounds the worst-case overshoot past the cap
+// to one slice's expansion — not the whole (possibly enormous) stream.
+import { Unzip, UnzipInflate } from 'fflate';
+import { PackageReadError } from "./errors.js";
+// Compressed input is pushed in slices this size so decompressed output arrives in
+// increments the running counter can check. Small enough that the worst-case overshoot
+// (slice × DEFLATE's ~1032:1 ceiling ≈ 16 MiB) is negligible against a sane cap; large
+// enough that a legitimate multi-hundred-megabyte package still streams in cheaply.
+const INPUT_SLICE = 1 << 14;
+/**
+ * Inflate every part of an `.xlsx` zip package, enforcing a hard ceiling on total
+ * decompressed output.
+ *
+ * @param data The raw zip bytes.
+ * @param cap  Maximum total uncompressed output, in bytes, across all parts. Enforced
+ *   against bytes actually produced, never against the archive's declared sizes.
+ * @returns A map of part path to inflated bytes.
+ * @throws {@link PackageReadError} if inflation would exceed `cap` — a probable zip bomb.
+ * @throws {Error} raised by the zip layer if the archive is malformed or a part uses an unsupported
+ *   compression method. Callers reach this through {@link inflateSpreadsheetPackage}, which is where
+ *   those are classified; the raw error is deliberately not re-typed here, because its text is the
+ *   one thing that must not reach a caller unfiltered.
+ */
+export function inflatePackage(data, cap) {
+    const files = {};
+    let total = 0;
+    let failure;
+    const unzip = new Unzip((file) => {
+        const chunks = [];
+        let size = 0;
+        file.ondata = (error, chunk, final) => {
+            if (failure)
+                return;
+            if (error) {
+                failure = error;
+                return;
+            }
+            total += chunk.length;
+            if (total > cap) {
+                failure = new PackageReadError(`refusing to inflate: uncompressed output exceeds ${cap} bytes (possible zip bomb)`);
+                return;
+            }
+            chunks.push(chunk);
+            size += chunk.length;
+            if (final)
+                files[file.name] = join(chunks, size);
+        };
+        // `start()` reports an unsupported compression method through `ondata` above, then
+        // throws trying to build the missing decoder. Keep the reported error (its message
+        // names the method) and swallow the raw follow-on throw.
+        try {
+            file.start();
+        }
+        catch (error) {
+            failure ??= error instanceof Error ? error : new Error(String(error));
+        }
+    });
+    unzip.register(UnzipInflate);
+    let offset = 0;
+    do {
+        const end = Math.min(offset + INPUT_SLICE, data.length);
+        unzip.push(data.subarray(offset, end), end === data.length);
+        offset = end;
+    } while (offset < data.length && !failure);
+    if (failure)
+        throw failure;
+    return files;
+}
+function join(chunks, size) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * The namespace URIs the Open Packaging Conventions layer itself owns — the ones that describe a
+ * *package* rather than the spreadsheet inside it. Every OOXML package carries these regardless of
+ * which serialisation its office document uses, so an `.xlsb` and an `.xlsx` agree on them exactly.
+ *
+ * The SpreadsheetML vocabulary (the main namespace, DrawingML, the Microsoft extension URIs) is a
+ * property of the XML codec and lives in `../xlsx/namespaces.ts`.
+ */
+/** The `xmlns` of every `.rels` package relationships part. */
+export declare const PKG_RELS_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
+/** The `xmlns` of the package's `[Content_Types].xml`. */
+export declare const CONTENT_TYPES_NS = "http://schemas.openxmlformats.org/package/2006/content-types";
+/**
+ * Scopes both the relationship *type* URIs a `.rels` part declares and the `r:id` references a part's
+ * body carries. Part-level rather than package-level in ECMA-376's own split, but it is the vocabulary
+ * the relationship graph is written in, so it belongs with the graph and not with either codec.
+ */
+export declare const RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";

package/dist/io/opc/namespaces.js

@@ -0,0 +1,18 @@
+/**
+ * The namespace URIs the Open Packaging Conventions layer itself owns — the ones that describe a
+ * *package* rather than the spreadsheet inside it. Every OOXML package carries these regardless of
+ * which serialisation its office document uses, so an `.xlsb` and an `.xlsx` agree on them exactly.
+ *
+ * The SpreadsheetML vocabulary (the main namespace, DrawingML, the Microsoft extension URIs) is a
+ * property of the XML codec and lives in `../xlsx/namespaces.ts`.
+ */
+/** The `xmlns` of every `.rels` package relationships part. */
+export const PKG_RELS_NS = 'http://schemas.openxmlformats.org/package/2006/relationships';
+/** The `xmlns` of the package's `[Content_Types].xml`. */
+export const CONTENT_TYPES_NS = 'http://schemas.openxmlformats.org/package/2006/content-types';
+/**
+ * Scopes both the relationship *type* URIs a `.rels` part declares and the `r:id` references a part's
+ * body carries. Part-level rather than package-level in ECMA-376's own split, but it is the vocabulary
+ * the relationship graph is written in, so it belongs with the graph and not with either codec.
+ */
+export const RELATIONSHIPS_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';

package/dist/io/opc/part-paths.d.ts

@@ -0,0 +1,4 @@
+export declare const THEME_PART_PATH = "xl/theme/theme1.xml";
+export declare function extensionOf(partPath: string): string;
+export declare function relsPathFor(partPath: string): string;
+export declare function relativePartPath(fromPath: string, toPath: string): string;

package/dist/io/opc/part-paths.js

@@ -0,0 +1,35 @@
+// The path algebra of an OPC package: a part's extension, where its relationships live, and how one
+// part names another. Pure string work over package-absolute paths, with no notion of what any part
+// contains — so the XML and BIFF12 codecs, and the readers and writers within each, share it.
+// Where the writer always puts the theme part. The workbook's theme relationship and the package's
+// content-type override both name this path unconditionally, so a theme preserved from a source
+// package that called its part something else is re-emitted here rather than at its original name.
+export const THEME_PART_PATH = 'xl/theme/theme1.xml';
+// The extension of a part path (`xl/media/image1.jpeg` → `jpeg`), or '' when it carries none.
+export function extensionOf(partPath) {
+    const dot = partPath.lastIndexOf('.');
+    const slash = partPath.lastIndexOf('/');
+    return dot > slash ? partPath.slice(dot + 1) : '';
+}
+// The relationships part path for `dir/name.ext` → `dir/_rels/name.ext.rels`.
+export function relsPathFor(partPath) {
+    const slash = partPath.lastIndexOf('/');
+    const dir = slash === -1 ? '' : partPath.slice(0, slash + 1);
+    const base = slash === -1 ? partPath : partPath.slice(slash + 1);
+    return `${dir}_rels/${base}.rels`;
+}
+// A relationship target expressed relative to the part that carries it: the `..` hops out of the
+// referencing part's directory up to the common ancestor, then down to the target. Both paths are
+// package-absolute (`xl/drawings/preservedP1.vml` → `xl/media/preservedP2.jpeg` → `../media/preservedP2.jpeg`).
+export function relativePartPath(fromPath, toPath) {
+    const fromDir = fromPath.split('/').slice(0, -1);
+    const toSegments = toPath.split('/');
+    let common = 0;
+    while (common < fromDir.length &&
+        common < toSegments.length - 1 &&
+        fromDir[common] === toSegments[common]) {
+        common++;
+    }
+    const up = fromDir.length - common;
+    return [...Array(up).fill('..'), ...toSegments.slice(common)].join('/');
+}

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

@@ -0,0 +1,24 @@
+import type { PreservedPart } from '../../core/preserved.ts';
+export interface PackageAccessors {
+    /** A part's decoded text, or undefined when the package holds no such part. Decodes lazily, so a
+     * part the reader never asks for is never stringified. */
+    partText(path: string): string | undefined;
+    /** A part's raw bytes, or undefined when the package holds no such part. */
+    partBytes(path: string): Uint8Array | undefined;
+}
+export declare function packageAccessors(files: Record<string, Uint8Array>): PackageAccessors;
+export declare function relationshipTargetByType(xml: string, suffix: string): string | undefined;
+export declare function relationshipTargetsByType(xml: string, suffix: string): string[];
+export declare function sheetRelTarget(sheetPath: string, partText: (path: string) => string | undefined, type: string): string | undefined;
+export declare function resolveRelativePart(basePart: string, target: string): string;
+export declare function resolveWorkbookPart(target: string): string;
+export declare function parseRelationships(xml: string): Map<string, string>;
+export interface RelationshipRecord {
+    readonly id: string;
+    readonly type: string;
+    readonly target: string;
+    readonly external: boolean;
+}
+export declare function parseRelationshipRecords(xml: string): RelationshipRecord[];
+export declare function contentTypeResolver(contentTypesXml: string): (path: string) => string;
+export declare function capturePartClosure(entryPath: string, partText: (path: string) => string | undefined, partBytes: (path: string) => Uint8Array | undefined, contentTypeOf: (path: string) => string): readonly PreservedPart[] | undefined;