@shbernal/ts-xlsx 2.1.0 → 3.0.0

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

@@ -0,0 +1,100 @@
+export interface XmlAttributes {
+    readonly [name: string]: string;
+}
+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;
+/**
+ * The SpreadsheetML `_xHHHH_` escape, in the only place it may appear: a complete cell-text value.
+ *
+ * The mirror of `escapeSpreadsheetText` in `./xml.ts`, and it sits here rather than beside it for
+ * the same reason `decodeEntities` sits apart from `escapeText`: the write helpers carry an
+ * `AuthoringError` and a whole serialisation vocabulary the reader has no business importing.
+ *
+ * **One left-to-right pass, and that is load-bearing.** `005F` maps to `_` like any other code
+ * point, with no special case, because a single pass already gives the underscore escape its
+ * meaning: in `_x005F_x0041_` the match at 0 yields `_` and scanning resumes at `x0041_`, which has
+ * no leading underscore left to start an escape. So the value reads back as the literal seven
+ * characters `_x0041_` the author wrote. Decoding `_x005F_` in a pass of its own, before or after
+ * the rest, collapses that to `A` and loses the distinction the encoder went to trouble to keep.
+ * Excel agrees: it reads that cell as `_x0041_`.
+ *
+ * The decode is unconditional, not a repair of characters XML cannot carry. Excel reads
+ * `a_x0009_b` as a tab even though a literal tab would have been perfectly legal there, so a
+ * decoder that only handled the illegal range would disagree with Excel on files Excel wrote.
+ */
+export declare function decodeSpreadsheetText(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;
+/** An OOXML integer attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, fractional, not a number, or below the floor. Integers past
+ * `Number.MAX_SAFE_INTEGER` read as `undefined` too: no index or count is usable out there, and
+ * arithmetic on one silently lies. */
+export declare function numInteger(val: string | undefined, min?: number): number | undefined;
+/** An OOXML decimal attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, not a number, or below the floor. Infinities are not finite numbers
+ * and read as `undefined`. */
+export declare function numFinite(val: string | undefined, min?: number): number | 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;
+/** Narrow an enumerated attribute through its guard; `undefined` when absent or not a member. */
+export declare function enumToken<T extends string>(val: string | undefined, isMember: (candidate: string) => candidate is T): T | undefined;

package/dist/xml/xml-scan.js

@@ -0,0 +1,208 @@
+import { XmlParseError } from './errors.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 (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
+                return match;
+            try {
+                return String.fromCodePoint(codePoint);
+            }
+            catch {
+                return match;
+            }
+        }
+        return PREDEFINED_ENTITIES.get(body) ?? match;
+    });
+}
+export function decodeSpreadsheetText(value) {
+    if (!value.includes('_'))
+        return value;
+    return value.replace(/_x([0-9A-Fa-f]{4})_/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+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]] = decodeEntities(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: decodeEntities(normalizeLineEndings(chunk)) };
+            return;
+        }
+        if (lt > i) {
+            const chunk = source.slice(i, lt);
+            if (chunk.length > 0)
+                yield { kind: 'text', text: decodeEntities(normalizeLineEndings(chunk)) };
+        }
+        const markup = markupAt(source, lt);
+        if (markup !== undefined) {
+            if (markup.kind === 'cdata') {
+                yield { kind: 'text', text: 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;
+}
+export function numInteger(val, min = -Number.MAX_SAFE_INTEGER) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || !Number.isSafeInteger(n) || n < min)
+        return undefined;
+    return n;
+}
+export function numFinite(val, min = -Infinity) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || n < min)
+        return undefined;
+    return n;
+}
+function parseAttrNumber(val) {
+    if (val === undefined || val.trim() === '')
+        return undefined;
+    const n = Number(val);
+    return Number.isFinite(n) ? n : undefined;
+}
+export function coerceNumericLiteral(text) {
+    const trimmed = text.trim();
+    return /^-?\d+(?:\.\d+)?$/.test(trimmed) ? Number(trimmed) : text;
+}
+export function enumToken(val, isMember) {
+    return val !== undefined && isMember(val) ? val : undefined;
+}

package/dist/xml/xml.d.ts

@@ -25,7 +25,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "2.1.0",
+  "version": "3.0.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",