@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/xml/xml.d.ts

@@ -1,23 +1,45 @@
+/**
+ * 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;
 /**
- * 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.
+ * Escape a cell value: the `_xHHHH_` convention first, then XML's own escapes.
+ *
+ * The order of the two replacements is load-bearing. Once `_xHHHH_` decodes to something, a
+ * value that legitimately reads `_x0041_` would come back as `A`, so the underscore is
+ * escaped first, and only where it begins a sequence that would otherwise decode, leaving
+ * every other underscore alone. Doing that after the character escape would re-escape the
+ * `_x005F_` it had just introduced.
+ *
+ * `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
+ * makes the `_x005F_` step above reversible. Change either and read its comment first.
  */
-export declare function needsSpacePreserve(value: string): boolean;
+export declare function escapeSpreadsheetText(value: string): string;
 /**
  * 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.
+ * whitespace would otherwise be collapsed. Shared by every string-bearing element (a plain
+ * inline string cell, a rich-text run, a pooled string, a note's body) 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,
+ * `=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;
@@ -25,14 +47,56 @@ 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.
+ * 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 &amp; 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 a count an author never set stays out of the element rather than fabricating a default.
+ * 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

@@ -14,18 +14,38 @@ const ATTR_ESCAPES = {
     '\r': '
',
     '\t': '	',
 };
+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');
+}
 export function escapeText(value) {
+    assertRepresentable(value);
     return value.replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
 }
 export function escapeAttr(value) {
+    assertRepresentable(value);
     return value.replace(/[&<>"'\n\r\t]/g, (ch) => ATTR_ESCAPES[ch]);
 }
-export function needsSpacePreserve(value) {
+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))}_`));
+}
+function needsSpacePreserve(value) {
     return value.length > 0 && (value !== value.trim() || /[\n\r\t]/.test(value));
 }
 export function textElement(value) {
     const space = needsSpacePreserve(value) ? ' xml:space="preserve"' : '';
-    return `<t${space}>${escapeText(value)}</t>`;
+    return `<t${space}>${escapeSpreadsheetText(value)}</t>`;
 }
 export function stripFormulaEquals(value) {
     if (typeof value === 'number')
@@ -35,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,23 +1,37 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "1.3.1",
+  "version": "2.1.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
+  "keywords": [
+    "csv",
+    "excel",
+    "ooxml",
+    "spreadsheet",
+    "streaming",
+    "typescript",
+    "workbook",
+    "xlsx"
+  ],
+  "homepage": "https://shbernal.github.io/ts-xlsx/",
+  "bugs": {
+    "url": "https://github.com/shbernal/ts-xlsx/issues"
+  },
   "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",
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -47,71 +61,80 @@
       "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"
     },
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "dist",
-    "skills",
-    "LICENSE",
-    "README.md"
-  ],
   "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",
     "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",
-    "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",
+    "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:fix": "pnpm run lint --fix",
+    "format": "node scripts/format.ts --write",
+    "format:check": "node scripts/format.ts --check",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "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:coverage": "node --test --experimental-test-coverage \"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",
     "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",
+    "validate:ooxml": "ooxml-validate",
     "test:ooxml": "node test/ooxml-validation/run.ts"
   },
-  "keywords": [
-    "xlsx",
-    "ooxml",
-    "excel",
-    "spreadsheet",
-    "csv",
-    "typescript",
-    "workbook",
-    "streaming"
-  ],
   "dependencies": {
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.7",
     "@types/node": "^24.13.3",
+    "charcheck": "^0.3.0",
     "jszip": "^3.10.1",
     "lefthook": "^2.1.10",
-    "typescript": "^7.0.2"
-  }
+    "ooxml-validate": "^0.0.3",
+    "oxfmt": "^0.64.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"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.11.0"
 }