@shbernal/ts-xlsx 1.2.0 → 2.0.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,12 +47,12 @@ 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 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.
  */
 export declare function attr(name: string, value: number | undefined): string;
 /**

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')
@@ -40,7 +60,7 @@ export function attr(name, value) {
 }
 export function numberText(value) {
     if (!Number.isFinite(value)) {
-        throw new AuthoringError(`cannot write a non-finite number (${value}) — it has no OOXML representation`);
+        throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
     }
     return String(value);
 }

package/package.json

@@ -1,23 +1,37 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
+  "keywords": [
+    "csv",
+    "excel",
+    "ooxml",
+    "spreadsheet",
+    "streaming",
+    "typescript",
+    "workbook",
+    "xlsx"
+  ],
+  "homepage": "https://github.com/shbernal/ts-xlsx#readme",
+  "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",
@@ -53,17 +67,9 @@
     },
     "./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})\"",
@@ -76,42 +82,42 @@
     "layering:check": "node scripts/check-layering.ts",
     "entries:check": "node scripts/check-entries.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 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",
     "test:src": "node --test \"src/**/*.test.ts\"",
-    "test:coverage": "node --test --experimental-test-coverage \"src/**/*.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",
+    "ooxml-validate": "^0.0.3",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "7.0.2001",
     "typescript": "^7.0.2"
-  }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.11.0"
 }