@shbernal/ts-xlsx 3.0.0 → 3.2.0

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,10 +46,11 @@ 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 startTag(name, attrs, selfClosing) {
+    let out = `<${name}`;
+    for (const key in attrs)
+        out += ` ${key}="${escapeAttr(attrs[key] ?? '')}"`;
+    return `${out}${selfClosing ? '/>' : '>'}`;
 }
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
@@ -60,17 +60,39 @@ 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 intAttr(name, value, min = -Number.MAX_SAFE_INTEGER) {
+    if (value === undefined)
+        return '';
+    assertWritableNumber(value);
+    if (!Number.isSafeInteger(value) || value < min) {
+        const floor = min === -Number.MAX_SAFE_INTEGER ? '' : ` of at least ${min}`;
+        throw new AuthoringError(`cannot write ${name}="${value}": expected an integer${floor}`);
+    }
+    return ` ${name}="${value}"`;
+}
+export function nonDefaultNumAttr(name, value, defaultValue) {
+    if (value === undefined)
+        return '';
+    const text = numberText(value);
+    return value === defaultValue ? '' : ` ${name}="${text}"`;
+}
+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": "3.0.0",
+  "version": "3.2.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "keywords": [
     "csv",
@@ -90,11 +90,16 @@
     "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",
+    "corpus-blind:check": "node scripts/check-corpus-blind.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",
@@ -103,7 +108,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",
@@ -120,20 +126,20 @@
   },
   "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",
-    "oxlint": "^1.80.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.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"
   },
-  "packageManager": "pnpm@11.11.0"
+  "packageManager": "pnpm@12.3.4"
 }

package/skills/ts-xlsx-upstream/SKILL.md

@@ -5,7 +5,7 @@ description: Report a ts-xlsx (@shbernal/ts-xlsx) bug, gap, or wrong output to i
 
 # Reporting a ts-xlsx problem upstream
 
-You are in a project that *uses* `@shbernal/ts-xlsx`, not the project that builds it.
+You are in a project that _uses_ `@shbernal/ts-xlsx`, not the project that builds it.
 This skill is how a defect you hit here becomes a permanent regression test there.
 
 The library's maintainers turn reports with a minimal reproduction into corpus cases,
@@ -20,12 +20,12 @@ builds its own input.** Everything below is in service of that.
 Catch the error and read `code` — the taxonomy is deliberately coarse and each answer
 means something different about whose bug it is.
 
-| `error.code`          | Whose bug        | Report it?                                                     |
-| --------------------- | ---------------- | -------------------------------------------------------------- |
-| `internal`            | **ts-xlsx**      | Always. The library says so itself in the message.              |
-| `unsupported-format`  | usually the file | Only if the file opens **cleanly in Excel**. Then it's our gap. |
-| `malformed-input`     | usually the file | Same test: clean in Excel but rejected here means it's ours.    |
-| `authoring`           | usually you      | Only if the document it refused is one Excel can express.       |
+| `error.code`         | Whose bug        | Report it?                                                      |
+| -------------------- | ---------------- | --------------------------------------------------------------- |
+| `internal`           | **ts-xlsx**      | Always. The library says so itself in the message.              |
+| `unsupported-format` | usually the file | Only if the file opens **cleanly in Excel**. Then it's our gap. |
+| `malformed-input`    | usually the file | Same test: clean in Excel but rejected here means it's ours.    |
+| `authoring`          | usually you      | Only if the document it refused is one Excel can express.       |
 
 Not every defect throws. These are ours too, and are worth reporting:
 
@@ -34,7 +34,7 @@ Not every defect throws. These are ours too, and are worth reporting:
 - Types that make correct code fail to compile, or admit code that throws at runtime.
 - Documented behaviour that does not match observed behaviour.
 
-If the problem is that ts-xlsx does not *have* a feature, that is still worth filing —
+If the problem is that ts-xlsx does not _have_ a feature, that is still worth filing —
 as a feature request rather than a bug.
 
 ## 2. Collect the facts
@@ -54,7 +54,7 @@ salaries, customer lists, and unreleased numbers. Treat every file in this repo
 confidential unless the user tells you otherwise, and never upload one to a public
 tracker — including "just a screenshot of the sheet".
 
-Instead, write a self-contained script that *constructs* its input and fails:
+Instead, write a self-contained script that _constructs_ its input and fails:
 
 ```ts
 import {Workbook, writeXlsx, readXlsx} from '@shbernal/ts-xlsx';
@@ -72,13 +72,13 @@ Then cut it down: remove rows, styles, sheets, and options one at a time, re-run
 after each cut, until removing anything more makes the failure disappear. What is left
 is the report.
 
-If the failure only reproduces with a *specific file* you cannot share, do not ask for
+If the failure only reproduces with a _specific file_ you cannot share, do not ask for
 permission to share it — file without the file. Say exactly that in the report and describe
 the structural feature you believe is responsible (a shared formula, a pivot cache, an
 inline string, a particular namespace prefix). A maintainer can usually synthesize a file
 from that description; they can never unsee an attachment.
 
-If you need a file attached, build one: reproduce the *structure* you suspect in a workbook
+If you need a file attached, build one: reproduce the _structure_ you suspect in a workbook
 you generate, with invented values. A synthesized file is always safe to attach. A redacted
 one is not yours to judge — redaction fails quietly, and a public tracker is permanent.
 
@@ -105,7 +105,7 @@ file from this project is attached. When you cannot manage a self-contained repr
 the answer is a thinner report — the prose description from step 3 — not a question and not
 an attachment.
 
-`gh` defaults to the *current* repository — which here is the consumer's, not ts-xlsx's.
+`gh` defaults to the _current_ repository — which here is the consumer's, not ts-xlsx's.
 Always pass `--repo shbernal/ts-xlsx` explicitly, or you will file the bug into the wrong
 tracker.
 
@@ -121,31 +121,39 @@ issue forms, so mirror its sections in the body file so both routes land the sam
 
 ````markdown
 ### ts-xlsx version
+
 <x.y.z>
 
 ### Node version
+
 <vXX.Y.Z>
 
 ### Error code and class
-<code> / <ClassName>   (or: no error thrown — wrong output)
+
+<code> / <ClassName> (or: no error thrown — wrong output)
 
 ### What happened
+
 <observed>
 
 ### What should have happened
+
 <expected, and why you believe that — a spec clause, Excel's own behaviour, or the docs>
 
 ### Minimal reproduction
+
 ```ts
 <the script from step 3>
 ```
 
 ### Error output
+
 ```
 <verbatim message and stack>
 ```
 
 ### Attached file
+
 <none / synthesized — describe how it was generated>
 ````
 

package/dist/core/modern-functions.d.ts

@@ -1 +0,0 @@
-export declare const MODERN_FUNCTIONS: ReadonlySet<string>;