@shbernal/ts-xlsx 1.0.0

package/dist/xml/errors.js

@@ -0,0 +1,15 @@
+import { XlsxError } from "../errors.js";
+/**
+ * Thrown when XML text cannot be scanned into parse events — an unterminated tag, comment, CDATA
+ * section, markup declaration or processing instruction.
+ *
+ * This is a *typed* failure rather than the native `SyntaxError` it reads like, because the text
+ * being parsed is almost always a part lifted out of an untrusted `.xlsx`. A caller wrapping
+ * `readXlsx` needs to tell "the file I was handed is corrupt" from "something in my own code threw a
+ * `SyntaxError`", and a native error gives them no way to. The message still names the construct that
+ * did not terminate; only the type changed.
+ */
+export class XmlParseError extends XlsxError {
+    name = 'XmlParseError';
+    code = 'malformed-input';
+}

package/dist/xml/xml-read.d.ts

@@ -0,0 +1,107 @@
+export interface XmlAttributes {
+    readonly [name: string]: string;
+}
+export interface SaxHandlers {
+    /** An element start. `selfClosing` is true for `<x/>`; no matching {@link onClose} fires for it. */
+    onOpen(name: string, attrs: XmlAttributes, selfClosing: boolean): void;
+    /** A run of character data (already entity-decoded; CDATA delivered verbatim). Omit to ignore text. */
+    onText?(text: string): void;
+    /** An element end (`</x>`); the synthetic end of a self-closing element is *not* reported here.
+     * Omit to ignore closes. */
+    onClose?(name: string): void;
+}
+/**
+ * One parse event from {@link xmlEvents}. The payloads match {@link SaxHandlers} exactly: `text`
+ * is already entity-decoded (or verbatim CDATA), and a `<x/>` yields one `open` with
+ * `selfClosing: true` and no matching `close`. The discriminated `kind` lets a *pull* consumer
+ * drive the parse — the shape the streaming reader needs, where a push callback cannot `yield`.
+ */
+export type XmlEvent = {
+    readonly kind: 'open';
+    readonly name: string;
+    readonly attrs: XmlAttributes;
+    readonly selfClosing: boolean;
+} | {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'close';
+    readonly name: string;
+};
+/**
+ * Decode XML character references and the five predefined entities. An unrecognised
+ * `&name;` is left verbatim rather than expanded — there is no DTD, so there is nothing
+ * to expand it to, and refusing to invent one is what makes entity-expansion attacks
+ * impossible.
+ */
+export declare function decodeEntities(value: string): string;
+/**
+ * Scan an XML document as a *pull* stream of {@link XmlEvent}s in a single O(n) pass with no
+ * recursion. This is the parser's core; {@link parseXml} is a thin push adapter over it. A
+ * consumer that must produce output incrementally (the streaming row reader) pulls events and
+ * yields as it goes, holding only its own running state — a push callback cannot.
+ *
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export declare function xmlEvents(source: string): Generator<XmlEvent>;
+/** An element start surfaced by {@link openElements}: its qualified `name`, the namespace-stripped
+ * `local` name the filter matched on, and its already-decoded `attrs`. */
+export interface OpenElement {
+    readonly name: string;
+    readonly local: string;
+    readonly attrs: XmlAttributes;
+}
+/**
+ * Yield each element start in `source` as an {@link OpenElement}, optionally restricted to the given
+ * local names. This is the pull shape for the ubiquitous "scan opens, read attributes" pass: a caller
+ * writes a plain `for..of` and reads `attrs` directly, instead of threading a mutable accumulator out
+ * through a {@link parseXml} `onOpen` closure. With no names every start is yielded; with one or more,
+ * only starts whose namespace-stripped name matches one. Text and close events are skipped.
+ *
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export declare function openElements(source: string, ...localNames: string[]): Generator<OpenElement>;
+/**
+ * Wrap an {@link XmlEvent} stream so a self-closing `<x/>` whose local name is in `names` is
+ * presented as an open (with `selfClosing: false`) immediately followed by a close — the exact
+ * event shape of `<x></x>`. This lets a consumer commit such an element from its close handling
+ * alone, instead of hand-coding a parallel self-closing branch: {@link xmlEvents} fires no close
+ * for `<x/>`, and forgetting that branch silently drops the empty element. Names not in the set
+ * pass through untouched, so an element whose close would wrongly act on absent content — an empty
+ * `<v/>`/`<f/>` that must not commit captured text — is left as a bare self-closing open.
+ */
+export declare function closeEmptyElements(events: Iterable<XmlEvent>, names: ReadonlySet<string>): Generator<XmlEvent>;
+/** Options for {@link parseXml}. */
+export interface ParseXmlOptions {
+    /**
+     * Local names whose self-closing form should also fire {@link SaxHandlers.onClose}. For each name
+     * listed, `<x/>` is delivered as an open followed by a close (via {@link closeEmptyElements}), so a
+     * handler commits the element once in `onClose` rather than duplicating that logic in a self-closing
+     * branch. Only name elements the handler is safe to run on close when empty.
+     */
+    readonly closeEmptyElements?: ReadonlySet<string>;
+}
+/**
+ * Parse an XML document, dispatching SAX events to `handlers`. A thin push adapter over
+ * {@link xmlEvents} — one scanning core serves both the callback and the pull consumers.
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export declare function parseXml(source: string, handlers: SaxHandlers, options?: ParseXmlOptions): void;
+/** Strip a namespace prefix from a qualified name (`r:id` → `id`, `sheet` → `sheet`). */
+export declare function localName(qualified: string): string;
+/** An OOXML boolean that is on when present with no value (`<b/>` is bold) and off only on an
+ * explicit `"0"`/`"false"`; absence reads as on. */
+export declare function boolPresent(val: string | undefined): boolean;
+/** An OOXML boolean that is on only when explicitly `"1"`/`"true"`; anything else — including
+ * absence and a truthy-looking `"0"` — is off. */
+export declare function boolStrict(val: string | undefined): boolean;
+/** An optional OOXML boolean: `undefined` when the attribute is absent or carries an unrecognised
+ * token, otherwise its `"1"`/`"true"` vs `"0"`/`"false"` value. Lets a caller store only the
+ * attributes the source actually carried, so a re-write stays byte-clean. */
+export declare function boolTristate(val: string | undefined): boolean | undefined;
+/** Read an operand's text as a number only when it is a canonical decimal literal (optional sign,
+ * digits, optional fraction). A cell reference, defined name, expression, or exotically-spelled
+ * number (`1E5`, hex) keeps its verbatim text, so it is neither coerced to `NaN` and lost nor
+ * re-spelled into a number that would not re-write byte-clean. Callers layer their own type rules
+ * (a data-validation `list`/`custom` operand stays a string regardless of what it looks like). */
+export declare function coerceNumericLiteral(text: string): string | number;

package/dist/xml/xml-read.js

@@ -0,0 +1,283 @@
+// A lean, hostile-input-safe SAX pull parser for the read path.
+//
+// OOXML uses a small, regular subset of XML, so the reader does not need — and must not
+// pay for — a general-purpose DOM library (see ADR 0004). This scans the source in a
+// single O(n) pass with no recursion, emitting open/text/close events; the OOXML reader
+// consumes them and builds only the model, so peak memory tracks real content rather
+// than document structure.
+//
+// Security posture: entities are *decoded, never expanded*. Only the five predefined
+// entities and numeric character references are recognised; DTDs and `<!ENTITY>`
+// definitions are skipped, so entity-expansion (billion-laughs) and external-entity
+// (XXE) attacks are structurally impossible here, not merely mitigated.
+import { XmlParseError } from "./errors.js";
+const PREDEFINED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+const ENTITY = /&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g;
+/**
+ * Decode XML character references and the five predefined entities. An unrecognised
+ * `&name;` is left verbatim rather than expanded — there is no DTD, so there is nothing
+ * to expand it to, and refusing to invent one is what makes entity-expansion attacks
+ * impossible.
+ */
+export function decodeEntities(value) {
+    if (!value.includes('&'))
+        return value;
+    return value.replace(ENTITY, (match, body) => {
+        if (body.charCodeAt(0) === 0x23 /* # */) {
+            const codePoint = body.charCodeAt(1) === 0x78 /* x */
+                ? parseInt(body.slice(2), 16)
+                : parseInt(body.slice(1), 10);
+            if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
+                return match;
+            try {
+                return String.fromCodePoint(codePoint);
+            }
+            catch {
+                return match;
+            }
+        }
+        const named = PREDEFINED_ENTITIES[body];
+        return named ?? match;
+    });
+}
+// Attribute values cannot contain their own delimiter and cannot contain a literal `<`,
+// so a delimiter-respecting scan finds a tag's end even when an attribute value holds a
+// `>` (legal but rare). Names may carry a namespace prefix (`r:id`, `xml:space`).
+const ATTRIBUTE = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+function parseAttributes(source) {
+    const attrs = {};
+    ATTRIBUTE.lastIndex = 0;
+    let match = ATTRIBUTE.exec(source);
+    while (match !== null) {
+        const value = match[2] ?? match[3] ?? '';
+        attrs[match[1]] = decodeEntities(value);
+        match = ATTRIBUTE.exec(source);
+    }
+    return attrs;
+}
+// Scan to the tag's closing `>`, honouring quoted attribute values so a `>` inside a
+// value does not end the tag prematurely.
+function findTagEnd(source, start) {
+    let quote = '';
+    for (let i = start + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (quote !== '') {
+            if (ch === quote)
+                quote = '';
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '>') {
+            return i;
+        }
+    }
+    throw new XmlParseError('unterminated tag: missing ">"');
+}
+// A `<!DOCTYPE …>` may contain a bracketed internal subset with its own `>`; balance the
+// brackets so the declaration is skipped whole. We never act on its contents.
+function skipDeclaration(source, start) {
+    let depth = 0;
+    for (let i = start; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '[')
+            depth++;
+        else if (ch === ']')
+            depth--;
+        else if (ch === '>' && depth <= 0)
+            return i + 1;
+    }
+    throw new XmlParseError('unterminated markup declaration: missing ">"');
+}
+/**
+ * Scan an XML document as a *pull* stream of {@link XmlEvent}s in a single O(n) pass with no
+ * recursion. This is the parser's core; {@link parseXml} is a thin push adapter over it. A
+ * consumer that must produce output incrementally (the streaming row reader) pulls events and
+ * yields as it goes, holding only its own running state — a push callback cannot.
+ *
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export function* xmlEvents(source) {
+    const length = source.length;
+    let i = 0;
+    while (i < length) {
+        const lt = source.indexOf('<', i);
+        if (lt === -1) {
+            const chunk = source.slice(i);
+            if (chunk.length > 0)
+                yield { kind: 'text', text: decodeEntities(normalizeLineEndings(chunk)) };
+            return;
+        }
+        if (lt > i) {
+            const chunk = source.slice(i, lt);
+            if (chunk.length > 0)
+                yield { kind: 'text', text: decodeEntities(normalizeLineEndings(chunk)) };
+        }
+        if (source.startsWith('<!--', lt)) {
+            const end = source.indexOf('-->', lt + 4);
+            if (end === -1)
+                throw new XmlParseError('unterminated comment');
+            i = end + 3;
+            continue;
+        }
+        if (source.startsWith('<![CDATA[', lt)) {
+            const end = source.indexOf(']]>', lt + 9);
+            if (end === -1)
+                throw new XmlParseError('unterminated CDATA section');
+            yield { kind: 'text', text: source.slice(lt + 9, end) };
+            i = end + 3;
+            continue;
+        }
+        if (source.startsWith('<?', lt)) {
+            const end = source.indexOf('?>', lt + 2);
+            if (end === -1)
+                throw new XmlParseError('unterminated processing instruction');
+            i = end + 2;
+            continue;
+        }
+        if (source.startsWith('<!', lt)) {
+            i = skipDeclaration(source, lt);
+            continue;
+        }
+        const gt = findTagEnd(source, lt);
+        const raw = source.slice(lt + 1, gt);
+        if (raw.charCodeAt(0) === 0x2f /* / */) {
+            yield { kind: 'close', name: raw.slice(1).trim() };
+        }
+        else {
+            const selfClosing = raw.charCodeAt(raw.length - 1) === 0x2f;
+            const body = selfClosing ? raw.slice(0, -1) : raw;
+            const nameEnd = firstWhitespace(body);
+            const name = nameEnd === -1 ? body : body.slice(0, nameEnd);
+            const attrs = nameEnd === -1 ? {} : parseAttributes(body.slice(nameEnd));
+            yield { kind: 'open', name, attrs, selfClosing };
+        }
+        i = gt + 1;
+    }
+}
+/**
+ * Yield each element start in `source` as an {@link OpenElement}, optionally restricted to the given
+ * local names. This is the pull shape for the ubiquitous "scan opens, read attributes" pass: a caller
+ * writes a plain `for..of` and reads `attrs` directly, instead of threading a mutable accumulator out
+ * through a {@link parseXml} `onOpen` closure. With no names every start is yielded; with one or more,
+ * only starts whose namespace-stripped name matches one. Text and close events are skipped.
+ *
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export function* openElements(source, ...localNames) {
+    const filter = localNames.length > 0 ? new Set(localNames) : undefined;
+    for (const event of xmlEvents(source)) {
+        if (event.kind !== 'open')
+            continue;
+        const local = localName(event.name);
+        if (filter !== undefined && !filter.has(local))
+            continue;
+        yield { name: event.name, local, attrs: event.attrs };
+    }
+}
+/**
+ * Wrap an {@link XmlEvent} stream so a self-closing `<x/>` whose local name is in `names` is
+ * presented as an open (with `selfClosing: false`) immediately followed by a close — the exact
+ * event shape of `<x></x>`. This lets a consumer commit such an element from its close handling
+ * alone, instead of hand-coding a parallel self-closing branch: {@link xmlEvents} fires no close
+ * for `<x/>`, and forgetting that branch silently drops the empty element. Names not in the set
+ * pass through untouched, so an element whose close would wrongly act on absent content — an empty
+ * `<v/>`/`<f/>` that must not commit captured text — is left as a bare self-closing open.
+ */
+export function* closeEmptyElements(events, names) {
+    for (const event of events) {
+        if (event.kind === 'open' && event.selfClosing && names.has(localName(event.name))) {
+            yield { kind: 'open', name: event.name, attrs: event.attrs, selfClosing: false };
+            yield { kind: 'close', name: event.name };
+        }
+        else {
+            yield event;
+        }
+    }
+}
+/**
+ * Parse an XML document, dispatching SAX events to `handlers`. A thin push adapter over
+ * {@link xmlEvents} — one scanning core serves both the callback and the pull consumers.
+ * Throws {@link XmlParseError} on malformed markup.
+ */
+export function parseXml(source, handlers, options) {
+    const events = options?.closeEmptyElements
+        ? closeEmptyElements(xmlEvents(source), options.closeEmptyElements)
+        : xmlEvents(source);
+    for (const event of events) {
+        switch (event.kind) {
+            case 'open':
+                handlers.onOpen(event.name, event.attrs, event.selfClosing);
+                break;
+            case 'text':
+                handlers.onText?.(event.text);
+                break;
+            case 'close':
+                handlers.onClose?.(event.name);
+                break;
+        }
+    }
+}
+// XML end-of-line handling (spec §2.11): a literal CRLF or lone CR in character data is
+// normalized to a single LF, so a value's in-cell line breaks read back identically whatever
+// newline convention the producer wrote. Normalization precedes entity decoding, so a
+// deliberately-encoded carriage return (&#13;) survives it — the escape hatch for a real CR.
+// CDATA is delivered verbatim (it bypasses this), matching the reader's CDATA contract.
+function normalizeLineEndings(chunk) {
+    if (!chunk.includes('\r'))
+        return chunk;
+    return chunk.replace(/\r\n?/g, '\n');
+}
+function firstWhitespace(source) {
+    for (let i = 0; i < source.length; i++) {
+        const code = source.charCodeAt(i);
+        if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d)
+            return i;
+    }
+    return -1;
+}
+/** Strip a namespace prefix from a qualified name (`r:id` → `id`, `sheet` → `sheet`). */
+export function localName(qualified) {
+    const colon = qualified.indexOf(':');
+    return colon === -1 ? qualified : qualified.slice(colon + 1);
+}
+// OOXML spells booleans three ways, and the reader needs all three. A `<b/>`-style font flag
+// defaults to on when present with no value, so its absence is meaningful (`boolPresent`). Most
+// attributes are plain xsd:booleans that are off unless an explicit "1"/"true" turns them on
+// (`boolStrict`). An optional attribute that must round-trip byte-clean has to distinguish absent
+// from present-and-false and drop an unrecognised token rather than coerce it (`boolTristate`).
+/** An OOXML boolean that is on when present with no value (`<b/>` is bold) and off only on an
+ * explicit `"0"`/`"false"`; absence reads as on. */
+export function boolPresent(val) {
+    return val === undefined || (val !== '0' && val !== 'false');
+}
+/** An OOXML boolean that is on only when explicitly `"1"`/`"true"`; anything else — including
+ * absence and a truthy-looking `"0"` — is off. */
+export function boolStrict(val) {
+    return val === '1' || val === 'true';
+}
+/** An optional OOXML boolean: `undefined` when the attribute is absent or carries an unrecognised
+ * token, otherwise its `"1"`/`"true"` vs `"0"`/`"false"` value. Lets a caller store only the
+ * attributes the source actually carried, so a re-write stays byte-clean. */
+export function boolTristate(val) {
+    if (val === '1' || val === 'true')
+        return true;
+    if (val === '0' || val === 'false')
+        return false;
+    return undefined;
+}
+/** Read an operand's text as a number only when it is a canonical decimal literal (optional sign,
+ * digits, optional fraction). A cell reference, defined name, expression, or exotically-spelled
+ * number (`1E5`, hex) keeps its verbatim text, so it is neither coerced to `NaN` and lost nor
+ * re-spelled into a number that would not re-write byte-clean. Callers layer their own type rules
+ * (a data-validation `list`/`custom` operand stays a string regardless of what it looks like). */
+export function coerceNumericLiteral(text) {
+    const trimmed = text.trim();
+    return /^-?\d+(?:\.\d+)?$/.test(trimmed) ? Number(trimmed) : text;
+}

package/dist/xml/xml.d.ts

@@ -0,0 +1,41 @@
+/** Escape a string for use as XML element text. */
+export declare function escapeText(value: string): string;
+/** Escape a string for use inside a double-quoted XML attribute value. */
+export declare function escapeAttr(value: string): string;
+/**
+ * Whether an element's text must be wrapped with `xml:space="preserve"` to survive a
+ * round-trip. Leading/trailing whitespace is otherwise collapsed by consumers, so a
+ * string cell value that begins or ends with a space needs the marker.
+ */
+export declare function needsSpacePreserve(value: string): boolean;
+/**
+ * A `<t>` text element carrying an escaped string, marked `xml:space="preserve"` when its
+ * whitespace would otherwise be collapsed. Shared by every string-bearing element — a plain
+ * inline string cell, a rich-text run — so all decode identically on the way back.
+ */
+export declare function textElement(value: string): string;
+/**
+ * Render a formula operand for serialisation: a number becomes its literal, a string is stripped of
+ * the single optional leading '=' an author may write (OOXML stores the expression without it, e.g.
+ * `=A1>0` on disk is `A1>0`). The result is unescaped — the caller escapes it for its target,
+ * whether that is element text or an attribute value.
+ */
+export declare function stripFormulaEquals(value: string | number): string;
+/**
+ * A boolean attribute rendered with a leading space (` name="1"` / ` name="0"`), or '' when the value
+ * is undefined. OOXML booleans serialise as 1/0; emitting the explicit `="0"` lets a writer force a
+ * flag off against a consumer's default, while an unset (undefined) flag stays out of the element
+ * entirely — the two-state-plus-absent contract every flag writer here shares.
+ */
+export declare function boolAttr(name: string, value: boolean | undefined): string;
+/**
+ * A numeric attribute rendered with a leading space (` name="42"`), or '' when the value is undefined
+ * — so a count an author never set stays out of the element rather than fabricating a default.
+ */
+export declare function attr(name: string, value: number | undefined): string;
+/**
+ * A finite number serialises as its shortest round-trippable decimal; a non-finite one
+ * has no OOXML numeric representation, so the writer refuses it rather than emit `NaN`.
+ */
+export declare function numberText(value: number): string;
+export declare const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";

package/dist/xml/xml.js

@@ -0,0 +1,86 @@
+// Minimal XML serialisation helpers for the write path.
+//
+// Writing OOXML needs only correct escaping and well-formed structure; parsing (the
+// reader's concern) is a separate, later decision, so no XML library is on the write
+// path. Escaping is the one hard, security-relevant requirement — an unescaped `<`,
+// `&`, or `"` produces a malformed package a consumer rejects — so it lives here,
+// audited once, rather than sprinkled through the part emitters.
+import { AuthoringError } from "../errors.js";
+const TEXT_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+};
+const ATTR_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&apos;',
+    '\n': '&#10;',
+    '\r': '&#13;',
+    '\t': '&#9;',
+};
+/** Escape a string for use as XML element text. */
+export function escapeText(value) {
+    return value.replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
+}
+/** Escape a string for use inside a double-quoted XML attribute value. */
+export function escapeAttr(value) {
+    return value.replace(/[&<>"'\n\r\t]/g, (ch) => ATTR_ESCAPES[ch]);
+}
+/**
+ * Whether an element's text must be wrapped with `xml:space="preserve"` to survive a
+ * round-trip. Leading/trailing whitespace is otherwise collapsed by consumers, so a
+ * string cell value that begins or ends with a space needs the marker.
+ */
+export function needsSpacePreserve(value) {
+    return value.length > 0 && (value !== value.trim() || /[\n\r\t]/.test(value));
+}
+/**
+ * A `<t>` text element carrying an escaped string, marked `xml:space="preserve"` when its
+ * whitespace would otherwise be collapsed. Shared by every string-bearing element — a plain
+ * inline string cell, a rich-text run — so all decode identically on the way back.
+ */
+export function textElement(value) {
+    const space = needsSpacePreserve(value) ? ' xml:space="preserve"' : '';
+    return `<t${space}>${escapeText(value)}</t>`;
+}
+/**
+ * Render a formula operand for serialisation: a number becomes its literal, a string is stripped of
+ * the single optional leading '=' an author may write (OOXML stores the expression without it, e.g.
+ * `=A1>0` on disk is `A1>0`). The result is unescaped — the caller escapes it for its target,
+ * whether that is element text or an attribute value.
+ */
+export function stripFormulaEquals(value) {
+    if (typeof value === 'number')
+        return String(value);
+    return value.startsWith('=') ? value.slice(1) : value;
+}
+/**
+ * A boolean attribute rendered with a leading space (` name="1"` / ` name="0"`), or '' when the value
+ * is undefined. OOXML booleans serialise as 1/0; emitting the explicit `="0"` lets a writer force a
+ * flag off against a consumer's default, while an unset (undefined) flag stays out of the element
+ * entirely — the two-state-plus-absent contract every flag writer here shares.
+ */
+export function boolAttr(name, value) {
+    return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
+}
+/**
+ * A numeric attribute rendered with a leading space (` name="42"`), or '' when the value is undefined
+ * — so a count an author never set stays out of the element rather than fabricating a default.
+ */
+export function attr(name, value) {
+    return value === undefined ? '' : ` ${name}="${value}"`;
+}
+/**
+ * A finite number serialises as its shortest round-trippable decimal; a non-finite one
+ * has no OOXML numeric representation, so the writer refuses it rather than emit `NaN`.
+ */
+export function numberText(value) {
+    if (!Number.isFinite(value)) {
+        throw new AuthoringError(`cannot write a non-finite number (${value}) — it has no OOXML representation`);
+    }
+    return String(value);
+}
+export const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@shbernal/ts-xlsx",
+  "version": "1.0.0",
+  "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
+  "license": "MIT",
+  "author": "shbernal",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shbernal/ts-xlsx.git"
+  },
+  "homepage": "https://github.com/shbernal/ts-xlsx#readme",
+  "bugs": {
+    "url": "https://github.com/shbernal/ts-xlsx/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.11.0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/entries/core.d.ts",
+      "default": "./dist/entries/core.js"
+    },
+    "./xlsx": {
+      "types": "./dist/entries/xlsx.d.ts",
+      "default": "./dist/entries/xlsx.js"
+    },
+    "./xlsb": {
+      "types": "./dist/entries/xlsb.d.ts",
+      "default": "./dist/entries/xlsb.js"
+    },
+    "./csv": {
+      "types": "./dist/entries/csv.d.ts",
+      "default": "./dist/entries/csv.js"
+    },
+    "./vba": {
+      "types": "./dist/entries/vba.d.ts",
+      "default": "./dist/entries/vba.js"
+    },
+    "./customui": {
+      "types": "./dist/entries/customui.d.ts",
+      "default": "./dist/entries/customui.js"
+    },
+    "./errors": {
+      "types": "./dist/entries/errors.d.ts",
+      "default": "./dist/entries/errors.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepare": "lefthook install",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "size": "node scripts/size-budget.ts",
+    "smoke:dist": "node scripts/smoke-dist.ts",
+    "docs": "node scripts/gen-docs.ts",
+    "docs:check": "node scripts/gen-docs.ts && git add --intent-to-add -- docs/api && git diff --exit-code -- docs/api",
+    "constitution:check": "node scripts/check-constitution.ts",
+    "layering:check": "node scripts/check-layering.ts",
+    "entries:check": "node scripts/check-entries.ts",
+    "lint": "biome check --error-on-warnings src scripts test tools",
+    "lint:fix": "biome check --write --error-on-warnings src scripts test tools",
+    "format": "biome format --write src scripts test tools",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "test:src": "node --test \"src/**/*.test.ts\"",
+    "test:coverage": "node --test --experimental-test-coverage \"src/**/*.test.ts\"",
+    "corpus": "node test/corpus/run.ts",
+    "corpus:dist": "node test/corpus/run.ts --target dist",
+    "verify": "node scripts/verify.ts --full",
+    "verify:quick": "node scripts/verify.ts --quick",
+    "test": "node scripts/verify.ts --full",
+    "prepublishOnly": "pnpm run build && pnpm run test && pnpm run smoke:dist && pnpm run size",
+    "validate:ooxml": "node scripts/ooxml-validator.ts",
+    "test:ooxml": "node test/ooxml-validation/run.ts",
+    "harvest": "node scripts/harvest/fetch-issue.ts",
+    "harvest:list": "node scripts/harvest/list-backlog.ts",
+    "harvest:all": "node scripts/harvest/harvest-all.ts",
+    "harvest:status": "node scripts/harvest/status.ts"
+  },
+  "keywords": [
+    "xlsx",
+    "ooxml",
+    "excel",
+    "spreadsheet",
+    "csv",
+    "typescript",
+    "workbook",
+    "streaming"
+  ],
+  "dependencies": {
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.4",
+    "@types/node": "^24.13.3",
+    "jszip": "^3.10.1",
+    "lefthook": "^2.1.10",
+    "typescript": "^6.0.3"
+  }
+}