@shbernal/ts-xlsx 2.0.0 → 3.0.0

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;
@@ -50,11 +50,53 @@ export declare function stripFormulaEquals(value: string | number): string;
  * entirely: the two-state-plus-absent contract every flag writer here shares.
  */
 export declare function boolAttr(name: string, value: boolean | undefined): string;
+/**
+ * A free-string attribute rendered with a leading space (` name="a & b"`), or '' when the value
+ * is undefined. The third of the trio with {@link boolAttr} and {@link numAttr}: the value is prose
+ * the caller chose, so it is escaped rather than checked.
+ *
+ * A token from a closed OOXML enumeration is the other case and goes through {@link checkedToken}
+ * instead. Escaping a bogus token would produce a well-formed document that Excel still rejects,
+ * which hides the mistake in the file rather than raising it at the call.
+ */
+export declare function textAttr(name: string, value: string | undefined): string;
+/**
+ * Refuse a token from a closed OOXML enumeration that the writer would otherwise emit verbatim, and
+ * return it unchanged when it belongs. The public types already forbid an out-of-contract value, so
+ * this fires only for one smuggled past them by an untyped caller, a `JSON.parse`, or a cast.
+ *
+ * The writer must never serialise such a value: it would be schema-invalid OOXML that Excel
+ * sometimes tolerates yet the library's own reader, which narrows every such token through the same
+ * guard, discards on read-back. Refusing at the write boundary keeps the two symmetric, garbage out
+ * refused exactly as garbage in, so a value the writer accepts is always one that round-trips.
+ *
+ * @throws {AuthoringError} naming the value and the enumeration.
+ */
+export declare function checkedToken(value: string, isValid: (candidate: string) => boolean, kind: string): string;
 /**
  * A numeric attribute rendered with a leading space (` name="42"`), or '' when the value is undefined
  * so that a count an author never set stays out of the element rather than fabricating a default.
+ *
+ * The value goes through {@link numberText}, so a non-finite one is refused here rather than written
+ * as `NaN`. Every attribute on this path is `xsd:double` or `xsd:unsignedInt`, neither of which has a
+ * spelling for it, so the alternative is a package Excel reports as damaged.
+ *
+ * @throws {AuthoringError} when the value is not finite.
+ */
+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.
+ *
+ * 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.
+ *
+ * @throws {AuthoringError} naming the value.
  */
-export declare function attr(name: string, value: number | undefined): string;
+export declare function assertWritableNumber(value: number): 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

@@ -55,13 +55,25 @@ export function stripFormulaEquals(value) {
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
 }
-export function attr(name, value) {
-    return value === undefined ? '' : ` ${name}="${value}"`;
+export function textAttr(name, value) {
+    return value === undefined ? '' : ` ${name}="${escapeAttr(value)}"`;
 }
-export function numberText(value) {
-    if (!Number.isFinite(value)) {
-        throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
+export function checkedToken(value, isValid, kind) {
+    if (!isValid(value)) {
+        throw new AuthoringError(`Invalid ${kind} ${JSON.stringify(value)}: not a value the OOXML enumeration allows`);
     }
+    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 numberText(value) {
+    assertWritableNumber(value);
     return String(value);
 }
 export const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "keywords": [
     "csv",
@@ -12,7 +12,7 @@
     "workbook",
     "xlsx"
   ],
-  "homepage": "https://github.com/shbernal/ts-xlsx#readme",
+  "homepage": "https://shbernal.github.io/ts-xlsx/",
   "bugs": {
     "url": "https://github.com/shbernal/ts-xlsx/issues"
   },
@@ -61,6 +61,11 @@
       "types": "./dist/entries/customui.d.ts",
       "default": "./dist/entries/customui.js"
     },
+    "./node": {
+      "types": "./dist/entries/node.d.ts",
+      "browser": "./dist/entries/node-unavailable.js",
+      "default": "./dist/entries/node.js"
+    },
     "./errors": {
       "types": "./dist/entries/errors.d.ts",
       "default": "./dist/entries/errors.js"
@@ -72,18 +77,24 @@
   },
   "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",
+    "site:check": "node www/scripts/check.ts",
+    "samples:check": "node www/scripts/check-samples.ts",
+    "site:dev": "pnpm run site:prepare && vitepress dev www",
+    "site:build": "pnpm run site:prepare && vitepress build www && node www/scripts/check-built-links.ts",
+    "site:preview": "vitepress preview www",
     "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",
+    "browser:check": "node scripts/check-browser-safe.ts",
     "source-text:check": "node scripts/check-source-text.ts",
     "chars:check": "charcheck",
-    "lint": "node node_modules/oxlint/bin/oxlint src scripts test tools charcheck.config.ts --type-aware --deny-warnings --report-unused-disable-directives",
+    "lint": "node node_modules/oxlint/bin/oxlint src scripts test tools www charcheck.config.ts --type-aware --deny-warnings --report-unused-disable-directives",
     "lint:fix": "pnpm run lint --fix",
     "format": "node scripts/format.ts --write",
     "format:check": "node scripts/format.ts --check",
@@ -91,7 +102,9 @@
     "typecheck:src": "tsc --noEmit -p tsconfig.json",
     "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:site": "node --test \"www/**/*.test.ts\"",
     "coverage": "node scripts/coverage.ts",
     "corpus": "node test/corpus/run.ts",
     "corpus:dist": "node test/corpus/run.ts --target dist",
@@ -114,7 +127,10 @@
     "oxfmt": "^0.64.0",
     "oxlint": "^1.80.0",
     "oxlint-tsgolint": "7.0.2001",
-    "typescript": "^7.0.2"
+    "shiki": "^4.4.3",
+    "typescript": "^7.0.2",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.41"
   },
   "engines": {
     "node": ">=24"