@shbernal/ts-xlsx 2.1.0 → 3.1.0

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

@@ -0,0 +1,78 @@
+export interface XmlAttributes {
+    readonly [name: string]: string;
+}
+/**
+ * One parse event from {@link xmlEvents}. The payloads are what the push adapter in `xml-read.ts`
+ * hands a handler triple, unchanged: `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.
+ *
+ * A reference naming a code point XML 1.0 has no representation for is left verbatim too, on the
+ * same grounds as one naming no code point at all. `&#1;` is not an escape for U+0001, it is another
+ * way of spelling an ill-formed document, and decoding it puts in the model a character the writer
+ * is *guaranteed* to refuse: a hostile file would then read cleanly and fail on the next save with
+ * an `AuthoringError` blaming the caller, several layers from the input that caused it. The bound
+ * comes from `./xml-chars.ts` rather than from the writer's own guard so that this half of the
+ * codec keeps importing none of the serialisation vocabulary.
+ */
+export declare function decodeEntities(value: string): string;
+export declare function parseAttributes(source: string): XmlAttributes;
+export type Markup = {
+    readonly kind: 'comment' | 'pi' | 'declaration';
+    readonly next: number;
+} | {
+    readonly kind: 'cdata';
+    readonly contentStart: number;
+    readonly contentEnd: number;
+    readonly next: number;
+};
+export declare function markupAt(source: string, lt: number): Markup | undefined;
+export interface Tag {
+    readonly close: boolean;
+    readonly name: string;
+    readonly attrSource: string;
+    readonly selfClosing: boolean;
+    /** One past the tag's `>`, so a caller capturing verbatim source can slice up to it. */
+    readonly next: number;
+}
+export declare function tagAt(source: string, lt: number): Tag;
+/**
+ * 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>;
+/** 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;

package/dist/xml/xml-scan.js

@@ -0,0 +1,180 @@
+import { XmlParseError } from './errors.js';
+import { isRepresentableCodePoint, stripUnrepresentable } from './xml-chars.js';
+const PREDEFINED_ENTITIES = new Map([
+    ['amp', '&'],
+    ['lt', '<'],
+    ['gt', '>'],
+    ['quot', '"'],
+    ['apos', "'"],
+]);
+const ENTITY = /&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g;
+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
+                ? Number.parseInt(body.slice(2), 16)
+                : Number.parseInt(body.slice(1), 10);
+            if (!isRepresentableCodePoint(codePoint))
+                return match;
+            return String.fromCodePoint(codePoint);
+        }
+        return PREDEFINED_ENTITIES.get(body) ?? match;
+    });
+}
+function admitText(value) {
+    return stripUnrepresentable(decodeEntities(value));
+}
+const ATTRIBUTE = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+export function parseAttributes(source) {
+    const attrs = Object.create(null);
+    ATTRIBUTE.lastIndex = 0;
+    let match = ATTRIBUTE.exec(source);
+    while (match !== null) {
+        const value = match[2] ?? match[3] ?? '';
+        attrs[match[1]] = admitText(value);
+        match = ATTRIBUTE.exec(source);
+    }
+    return attrs;
+}
+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 ">"');
+}
+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 ">"');
+}
+export function markupAt(source, lt) {
+    if (source.startsWith('<!--', lt)) {
+        const end = source.indexOf('-->', lt + 4);
+        if (end === -1)
+            throw new XmlParseError('unterminated comment');
+        return { kind: 'comment', next: end + 3 };
+    }
+    if (source.startsWith('<![CDATA[', lt)) {
+        const end = source.indexOf(']]>', lt + 9);
+        if (end === -1)
+            throw new XmlParseError('unterminated CDATA section');
+        return { kind: 'cdata', contentStart: lt + 9, contentEnd: end, next: end + 3 };
+    }
+    if (source.startsWith('<?', lt)) {
+        const end = source.indexOf('?>', lt + 2);
+        if (end === -1)
+            throw new XmlParseError('unterminated processing instruction');
+        return { kind: 'pi', next: end + 2 };
+    }
+    if (source.startsWith('<!', lt))
+        return { kind: 'declaration', next: skipDeclaration(source, lt) };
+    return undefined;
+}
+export function tagAt(source, lt) {
+    const gt = findTagEnd(source, lt);
+    const raw = source.slice(lt + 1, gt);
+    const next = gt + 1;
+    if (raw.charCodeAt(0) === 0x2f) {
+        return { close: true, name: raw.slice(1).trim(), attrSource: '', selfClosing: false, next };
+    }
+    const selfClosing = raw.charCodeAt(raw.length - 1) === 0x2f;
+    const body = selfClosing ? raw.slice(0, -1) : raw;
+    const nameEnd = firstWhitespace(body);
+    return {
+        close: false,
+        name: nameEnd === -1 ? body : body.slice(0, nameEnd),
+        attrSource: nameEnd === -1 ? '' : body.slice(nameEnd),
+        selfClosing,
+        next,
+    };
+}
+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: admitText(normalizeLineEndings(chunk)) };
+            return;
+        }
+        if (lt > i) {
+            const chunk = source.slice(i, lt);
+            if (chunk.length > 0)
+                yield { kind: 'text', text: admitText(normalizeLineEndings(chunk)) };
+        }
+        const markup = markupAt(source, lt);
+        if (markup !== undefined) {
+            if (markup.kind === 'cdata') {
+                yield {
+                    kind: 'text',
+                    text: stripUnrepresentable(source.slice(markup.contentStart, markup.contentEnd)),
+                };
+            }
+            i = markup.next;
+            continue;
+        }
+        const tag = tagAt(source, lt);
+        yield tag.close
+            ? { kind: 'close', name: tag.name }
+            : {
+                kind: 'open',
+                name: tag.name,
+                attrs: parseAttributes(tag.attrSource),
+                selfClosing: tag.selfClosing,
+            };
+        i = tag.next;
+    }
+}
+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;
+}
+export function localName(qualified) {
+    const colon = qualified.indexOf(':');
+    return colon === -1 ? qualified : qualified.slice(colon + 1);
+}
+export function boolPresent(val) {
+    return val === undefined || (val !== '0' && val !== 'false');
+}
+export function boolStrict(val) {
+    return val === '1' || val === 'true';
+}
+export function boolTristate(val) {
+    if (val === '1' || val === 'true')
+        return true;
+    if (val === '0' || val === 'false')
+        return false;
+    return undefined;
+}

package/dist/xml/xml.d.ts

@@ -1,18 +1,24 @@
-/**
- * Refuse a string that XML cannot carry, naming the character and where it is so the author
- * can find it in a value they never inspected. These arrive from a database column or a CSV
- * field, not from a literal in the calling code.
- *
- * Exported for the one escape that cannot be {@link escapeAttr}: a number format code escapes
- * everything but the apostrophe, and needs this guard just the same.
- *
- * @throws {AuthoringError} naming the code point and its offset.
- */
-export declare function assertRepresentable(value: string): void;
 /** 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;
+/**
+ * {@link escapeAttr} for a number format code: the same escapes minus the apostrophe.
+ *
+ * A format code can legitimately contain `"` (a quoted literal like `"$"`), `<` and `&`, and Excel
+ * writes one with bare apostrophes. `'` is not markup-significant inside a double-quoted attribute,
+ * so leaving it keeps a round-tripped code byte-identical to the source; that divergence is the whole
+ * reason this exists.
+ *
+ * It is built by *omitting* one entry from {@link ATTR_ESCAPES} rather than by listing the escapes it
+ * does want, which is how it used to be written, in `io/xlsx/style-elements.ts`. An independently
+ * maintained list does not stay a one-character divergence: that one silently dropped the tab, line
+ * feed and carriage return escapes as well, and XML 1.0 3.3.3 requires a parser to normalise all
+ * three in an attribute value to a space, so Excel read back a format code with a space where the
+ * author wrote a tab. Our own reader preserved the raw character, so a round trip through this
+ * library returned it unchanged and no test here could see the loss.
+ */
+export declare function escapeFormatCode(code: string): string;
 /**
  * Escape a cell value: the `_xHHHH_` convention first, then XML's own escapes.
  *
@@ -25,7 +31,7 @@ export declare function escapeAttr(value: string): string;
  * `escapeText` runs last and sees no unrepresentable character left, so its guard is a
  * standing proof that the escape was complete rather than a second check of the same thing.
  *
- * Reversed by `decodeSpreadsheetText` in `./xml-read.ts`, whose single left-to-right pass is what
+ * Reversed by `decodeSpreadsheetText` in `./xml-scan.ts`, whose single left-to-right pass is what
  * makes the `_x005F_` step above reversible. Change either and read its comment first.
  */
 export declare function escapeSpreadsheetText(value: string): string;
@@ -36,13 +42,6 @@ export declare function escapeSpreadsheetText(value: string): string;
  * 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
@@ -85,18 +84,20 @@ export declare function checkedToken(value: string, isValid: (candidate: string)
  */
 export declare function numAttr(name: string, value: number | undefined): string;
 /**
- * Refuse a number OOXML cannot spell. Every numeric attribute in the format is `xsd:double`,
- * `xsd:unsignedInt` or a bounded flavour of one, and none of those lexical spaces has a form for a
- * NaN or an infinity, so a value that reaches the file as `NaN` is a package Excel reports as
- * damaged.
+ * Refuse a `Date` OOXML cannot spell, naming the property that carries it.
  *
- * Exported for the callers that must refuse before they write. A number can be unwritable and still
- * be read on the way to the bytes: compared, summed, walked. A comparison against `NaN` or an
- * infinity silently takes the wrong branch long before the value would have been serialised.
+ * Two ways a `Date` fails to have a `dcterms:W3CDTF` / `xsd:dateTime` spelling, and neither is
+ * caught by the types. An **Invalid Date** is truthy and is an instance of `Date`, so it passes
+ * every guard short of this one and reaches `toISOString()`, which throws a bare
+ * `RangeError: Invalid time value` -- outside this taxonomy, and naming neither the property nor
+ * the document it was being written into. A year **outside 0000-9999** has no four-digit form, so
+ * `toISOString()` falls back to ISO 8601's expanded `+275760-09-13T…` notation, which is not in
+ * the lexical space of either type; that one does not throw at all, it writes a package Excel
+ * offers to repair.
  *
- * @throws {AuthoringError} naming the value.
+ * @throws {AuthoringError} naming the property.
  */
-export declare function assertWritableNumber(value: number): void;
+export declare function assertWritableDate(date: Date, property: string): void;
 /**
  * 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`.

package/dist/xml/xml.js

@@ -1,4 +1,5 @@
-import { AuthoringError } from '../errors.js';
+import { assertWritableNumber, AuthoringError, codePointHex, invalidToken, unrepresentable, } from '../errors.js';
+import { XML_UNREPRESENTABLE, XML_UNREPRESENTABLE_GLOBAL } from './xml-chars.js';
 const TEXT_ESCAPES = {
     '&': '&',
     '<': '&lt;',
@@ -14,18 +15,12 @@ const ATTR_ESCAPES = {
     '\r': '&#13;',
     '\t': '&#9;',
 };
-const UNREPRESENTABLE = /[\u{0}-\u{8}\u{B}\u{C}\u{E}-\u{1F}\u{FFFE}\u{FFFF}\u{D800}-\u{DFFF}]/u;
-const UNREPRESENTABLE_GLOBAL = new RegExp(UNREPRESENTABLE.source, 'gu');
-function codePointHex(codePoint) {
-    return codePoint.toString(16).toUpperCase().padStart(4, '0');
-}
-export function assertRepresentable(value) {
-    const found = UNREPRESENTABLE.exec(value);
-    if (found === null)
-        return;
-    throw new AuthoringError(`cannot write U+${codePointHex(value.codePointAt(found.index))} at offset ${found.index}: ` +
-        'XML 1.0 has no representation for it, and the _xHHHH_ escape that would carry it is a ' +
-        'convention of cell values only');
+const XML_REFUSAL = 'XML 1.0 has no representation for it, and the _xHHHH_ escape that would carry it is a ' +
+    'convention of cell values only';
+function assertRepresentable(value) {
+    const error = unrepresentable(value, XML_UNREPRESENTABLE, XML_REFUSAL);
+    if (error !== undefined)
+        throw error;
 }
 export function escapeText(value) {
     assertRepresentable(value);
@@ -35,10 +30,14 @@ export function escapeAttr(value) {
     assertRepresentable(value);
     return value.replace(/[&<>"'\n\r\t]/g, (ch) => ATTR_ESCAPES[ch]);
 }
+export function escapeFormatCode(code) {
+    assertRepresentable(code);
+    return code.replace(/[&<>"\n\r\t]/g, (ch) => ATTR_ESCAPES[ch]);
+}
 export function escapeSpreadsheetText(value) {
     return escapeText(value
         .replace(/_(x[0-9A-Fa-f]{4}_)/g, '_x005F_$1')
-        .replace(UNREPRESENTABLE_GLOBAL, (ch) => `_x${codePointHex(ch.codePointAt(0))}_`));
+        .replace(XML_UNREPRESENTABLE_GLOBAL, (ch) => `_x${codePointHex(ch.codePointAt(0))}_`));
 }
 function needsSpacePreserve(value) {
     return value.length > 0 && (value !== value.trim() || /[\n\r\t]/.test(value));
@@ -47,11 +46,6 @@ export function textElement(value) {
     const space = needsSpacePreserve(value) ? ' xml:space="preserve"' : '';
     return `<t${space}>${escapeSpreadsheetText(value)}</t>`;
 }
-export function stripFormulaEquals(value) {
-    if (typeof value === 'number')
-        return String(value);
-    return value.startsWith('=') ? value.slice(1) : value;
-}
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
 }
@@ -60,17 +54,23 @@ export function textAttr(name, value) {
 }
 export function checkedToken(value, isValid, kind) {
     if (!isValid(value)) {
-        throw new AuthoringError(`Invalid ${kind} ${JSON.stringify(value)}: not a value the OOXML enumeration allows`);
+        throw invalidToken(kind, value);
     }
     return value;
 }
 export function numAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${numberText(value)}"`;
 }
-export function assertWritableNumber(value) {
-    if (Number.isFinite(value))
-        return;
-    throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
+export function assertWritableDate(date, property) {
+    const time = date.getTime();
+    if (Number.isNaN(time)) {
+        throw new AuthoringError(`cannot write ${property}: it is an Invalid Date`);
+    }
+    const year = date.getUTCFullYear();
+    if (year < 0 || year > 9999) {
+        throw new AuthoringError(`cannot write ${property}: the year ${year} is outside the 0000-9999 range a W3CDTF ` +
+            'timestamp can spell');
+    }
 }
 export function numberText(value) {
     assertWritableNumber(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "keywords": [
     "csv",
@@ -77,8 +77,7 @@
   },
   "scripts": {
     "prepare": "node scripts/install-hooks.ts",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.build.dts.json",
+    "build": "node scripts/build.ts",
     "size": "node scripts/size-budget.ts",
     "smoke:dist": "node scripts/smoke-dist.ts",
     "site:prepare": "node www/scripts/sync-docs.ts",
@@ -92,10 +91,14 @@
     "constitution:check": "node scripts/check-constitution.ts",
     "layering:check": "node scripts/check-layering.ts",
     "entries:check": "node scripts/check-entries.ts",
+    "public-types:check": "node scripts/check-public-types.ts",
+    "facet-register:check": "node scripts/check-facet-register.ts",
+    "tsconfig-coverage:check": "node scripts/check-tsconfig-coverage.ts",
     "browser:check": "node scripts/check-browser-safe.ts",
     "source-text:check": "node scripts/check-source-text.ts",
+    "error-messages:check": "node scripts/check-error-messages.ts",
     "chars:check": "charcheck",
-    "lint": "node node_modules/oxlint/bin/oxlint src scripts test tools www charcheck.config.ts --type-aware --deny-warnings --report-unused-disable-directives",
+    "lint": "node scripts/lint.ts",
     "lint:fix": "pnpm run lint --fix",
     "format": "node scripts/format.ts --write",
     "format:check": "node scripts/format.ts --check",
@@ -104,7 +107,8 @@
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "typecheck:dist": "tsc --noEmit -p tsconfig.dist.json",
     "typecheck:site": "tsc --noEmit -p www/tsconfig.json",
-    "test:src": "node --test \"src/**/*.test.ts\"",
+    "test:src": "node scripts/test-src.ts",
+    "test:harness": "node --test \"scripts/**/*.test.ts\"",
     "test:site": "node --test \"www/**/*.test.ts\"",
     "coverage": "node scripts/coverage.ts",
     "corpus": "node test/corpus/run.ts",
@@ -121,17 +125,17 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "charcheck": "^0.3.0",
+    "charcheck": "^0.4.0",
     "jszip": "^3.10.1",
-    "lefthook": "^2.1.10",
+    "lefthook": "^2.1.12",
     "ooxml-validate": "^0.0.3",
-    "oxfmt": "^0.64.0",
+    "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
     "oxlint-tsgolint": "7.0.2001",
     "shiki": "^4.4.3",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4",
-    "vue": "^3.5.41"
+    "vue": "^3.5.42"
   },
   "engines": {
     "node": ">=24"