@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/xml/xml-read.js

@@ -1,11 +1,7 @@
 import { XmlParseError } from './errors.js';
+import { NamespaceScope } from './xml-namespaces.js';
 import { localName, markupAt, parseAttributes, tagAt, xmlEvents, } from './xml-scan.js';
-export function elementSubtrees(source, selection) {
-    const fragments = new Map();
-    const attributes = new Map();
-    const finished = new Set();
-    let container;
-    let capture;
+function* rawTags(source) {
     const length = source.length;
     let i = 0;
     while (i < length) {
@@ -18,7 +14,17 @@ export function elementSubtrees(source, selection) {
             continue;
         }
         const tag = tagAt(source, lt);
-        const local = localName(tag.name);
+        i = tag.next;
+        yield { lt, tag, local: localName(tag.name) };
+    }
+}
+export function elementSubtrees(source, selection) {
+    const fragments = new Map();
+    const attributes = new Map();
+    const finished = new Set();
+    let container;
+    let capture;
+    for (const { lt, tag, local } of rawTags(source)) {
         if (tag.close) {
             if (capture !== undefined && local === capture.local) {
                 if (capture.depth > 0)
@@ -36,7 +42,6 @@ export function elementSubtrees(source, selection) {
                     container = undefined;
                 }
             }
-            i = tag.next;
             continue;
         }
         const { selfClosing } = tag;
@@ -66,22 +71,140 @@ export function elementSubtrees(source, selection) {
                 }
             }
         }
-        i = tag.next;
     }
     if (capture !== undefined) {
         throw new XmlParseError(`unterminated <${capture.local}> element`);
     }
     return { fragments, attributes };
 }
+export function elementRange(source, path) {
+    const open = [];
+    let pending;
+    for (const { lt, tag, local } of rawTags(source)) {
+        if (tag.close) {
+            const innermost = open.at(-1);
+            if (innermost !== undefined && innermost.local === local) {
+                if (innermost.depth > 0)
+                    innermost.depth -= 1;
+                else {
+                    open.pop();
+                    if (pending !== undefined && open.length === path.length - 1) {
+                        return { ...pending, end: tag.next, contentEnd: lt };
+                    }
+                }
+            }
+            continue;
+        }
+        if (pending === undefined && local === path[open.length]) {
+            const last = open.length === path.length - 1;
+            if (last) {
+                if (tag.selfClosing) {
+                    return {
+                        start: lt,
+                        end: tag.next,
+                        contentStart: tag.next,
+                        contentEnd: tag.next,
+                        name: tag.name,
+                        attrs: parseAttributes(tag.attrSource),
+                    };
+                }
+                pending = {
+                    start: lt,
+                    contentStart: tag.next,
+                    name: tag.name,
+                    attrs: parseAttributes(tag.attrSource),
+                };
+                open.push({ local, depth: 0 });
+            }
+            else if (!tag.selfClosing) {
+                open.push({ local, depth: 0 });
+            }
+        }
+        else {
+            const innermost = open.at(-1);
+            if (innermost !== undefined && !tag.selfClosing && innermost.local === local) {
+                innermost.depth += 1;
+            }
+        }
+    }
+    if (pending !== undefined) {
+        throw new XmlParseError(`unterminated <${pending.name}> element`);
+    }
+    return undefined;
+}
+const NO_ATTRIBUTES = Object.freeze(Object.create(null));
+export function* tagRanges(source) {
+    for (const { lt, tag } of rawTags(source)) {
+        yield {
+            start: lt,
+            end: tag.next,
+            name: tag.name,
+            attrs: tag.close ? NO_ATTRIBUTES : parseAttributes(tag.attrSource),
+            close: tag.close,
+            selfClosing: tag.selfClosing,
+        };
+    }
+}
+export function* elementRanges(source, local) {
+    let pending;
+    let depth = 0;
+    for (const { lt, tag, local: tagLocal } of rawTags(source)) {
+        if (tagLocal !== local)
+            continue;
+        if (pending !== undefined) {
+            if (tag.close) {
+                if (depth > 0)
+                    depth -= 1;
+                else {
+                    const open = pending;
+                    pending = undefined;
+                    yield { ...open, end: tag.next, contentEnd: lt };
+                }
+            }
+            else if (!tag.selfClosing) {
+                depth += 1;
+            }
+            continue;
+        }
+        if (tag.close)
+            continue;
+        const attrs = parseAttributes(tag.attrSource);
+        if (tag.selfClosing) {
+            yield {
+                start: lt,
+                end: tag.next,
+                contentStart: tag.next,
+                contentEnd: tag.next,
+                name: tag.name,
+                attrs,
+            };
+        }
+        else {
+            pending = { start: lt, contentStart: tag.next, name: tag.name, attrs };
+            depth = 0;
+        }
+    }
+    if (pending !== undefined) {
+        throw new XmlParseError(`unterminated <${pending.name}> element`);
+    }
+}
 export function* openElements(source, ...localNames) {
     const filter = localNames.length > 0 ? new Set(localNames) : undefined;
+    const scope = new NamespaceScope();
     for (const event of xmlEvents(source)) {
+        if (event.kind === 'close') {
+            scope.close();
+            continue;
+        }
         if (event.kind !== 'open')
             continue;
+        scope.open(event.attrs);
         const local = localName(event.name);
-        if (filter !== undefined && !filter.has(local))
-            continue;
-        yield { name: event.name, local, attrs: event.attrs };
+        if (filter === undefined || filter.has(local)) {
+            yield { name: event.name, local, attrs: event.attrs, scope };
+        }
+        if (event.selfClosing)
+            scope.close();
     }
 }
 export function* closeEmptyElements(events, names) {
@@ -103,17 +226,17 @@ export function parseXmlPasses(source, passes) {
     }
     const handlers = passes.map((pass) => pass.handlers);
     parseXml(source, {
-        onOpen(name, attrs, selfClosing) {
+        onOpen(name, attrs, selfClosing, scope) {
             for (const handler of handlers)
-                handler.onOpen(name, attrs, selfClosing);
+                handler.onOpen(name, attrs, selfClosing, scope);
         },
         onText(text) {
             for (const handler of handlers)
                 handler.onText?.(text);
         },
-        onClose(name) {
+        onClose(name, scope) {
             for (const handler of handlers)
-                handler.onClose?.(name);
+                handler.onClose?.(name, scope);
         },
     }, expanded.size > 0 ? { closeEmptyElements: expanded } : undefined);
 }
@@ -121,16 +244,21 @@ export function parseXml(source, handlers, options) {
     const events = options?.closeEmptyElements
         ? closeEmptyElements(xmlEvents(source), options.closeEmptyElements)
         : xmlEvents(source);
+    const scope = new NamespaceScope();
     for (const event of events) {
         switch (event.kind) {
             case 'open':
-                handlers.onOpen(event.name, event.attrs, event.selfClosing);
+                scope.open(event.attrs);
+                handlers.onOpen(event.name, event.attrs, event.selfClosing, scope);
+                if (event.selfClosing)
+                    scope.close();
                 break;
             case 'text':
                 handlers.onText?.(event.text);
                 break;
             case 'close':
-                handlers.onClose?.(event.name);
+                handlers.onClose?.(event.name, scope);
+                scope.close();
                 break;
         }
     }
@@ -161,6 +289,10 @@ export class TextCapture {
         this.#capturing = undefined;
         return this.#text;
     }
+    reset() {
+        this.#capturing = undefined;
+        this.#text = '';
+    }
 }
 export function* capturedText(source, names) {
     const capture = new TextCapture(names);

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

@@ -1,6 +1,13 @@
 export interface XmlAttributes {
     readonly [name: string]: string;
 }
+/**
+ * One parse event from {@link xmlEvents}. The payloads are what the push adapter in `xml-read.ts`
+ * hands a handler triple, unchanged: `text` is already entity-decoded (or verbatim CDATA), and a
+ * `<x/>` yields one `open` with `selfClosing: true` and no matching `close`. The discriminated
+ * `kind` lets a *pull* consumer drive the parse: the shape the streaming reader needs, where a push
+ * callback cannot `yield`.
+ */
 export type XmlEvent = {
     readonly kind: 'open';
     readonly name: string;
@@ -18,28 +25,29 @@ export type XmlEvent = {
  * `&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.
+ *
+ * A reference naming a code point XML 1.0 has no representation for is left verbatim too, on the
+ * same grounds as one naming no code point at all. `&#1;` is not an escape for U+0001, it is another
+ * way of spelling an ill-formed document, and decoding it puts in the model a character the writer
+ * is *guaranteed* to refuse: a hostile file would then read cleanly and fail on the next save with
+ * an `AuthoringError` blaming the caller, several layers from the input that caused it. The bound
+ * comes from `./xml-chars.ts` rather than from the writer's own guard so that this half of the
+ * codec keeps importing none of the serialisation vocabulary.
  */
 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_`.
+ * A tag's attributes: each a name, then `=`, then a value in either quote style. Matching the quotes
+ * is what lets a delimiter-respecting scan find a tag's end even when a value holds a `>` (legal but
+ * rare). Names may carry a namespace prefix (`r:id`, `xml:space`). Anything that is not an attribute,
+ * such as a name nothing assigns or a quote never closed, is skipped rather than refused.
  *
- * 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.
+ * Linear in the source, and that is the point of it being hand-written. The regex it replaced
+ * backtracked over a run of name characters no `=` followed from every position inside the run, so a
+ * single junk token in a tag cost the square of its length: a megabyte of one letter, a kilobyte
+ * zipped, cost minutes inside either reader. Here a dropped token resumes the scan where the token
+ * ended, and a value's closing quote is found with one `indexOf`, so no character is visited more
+ * than a constant number of times.
  */
-export declare function decodeSpreadsheetText(value: string): string;
 export declare function parseAttributes(source: string): XmlAttributes;
 export type Markup = {
     readonly kind: 'comment' | 'pi' | 'declaration';
@@ -81,20 +89,3 @@ export declare function boolStrict(val: string | undefined): boolean;
  * 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

@@ -1,4 +1,5 @@
 import { XmlParseError } from './errors.js';
+import { isRepresentableCodePoint, stripUnrepresentable } from './xml-chars.js';
 const PREDEFINED_ENTITIES = new Map([
     ['amp', '&'],
     ['lt', '<'],
@@ -15,35 +16,79 @@ export function decodeEntities(value) {
             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)
+            if (!isRepresentableCodePoint(codePoint))
                 return match;
-            try {
-                return String.fromCodePoint(codePoint);
-            }
-            catch {
-                return match;
-            }
+            return String.fromCodePoint(codePoint);
         }
         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)));
+function admitText(value) {
+    return stripUnrepresentable(decodeEntities(value));
+}
+const EQUALS = 0x3d;
+const SLASH = 0x2f;
+const GREATER_THAN = 0x3e;
+const DOUBLE_QUOTE = 0x22;
+const SINGLE_QUOTE = 0x27;
+const WIDE_WHITESPACE = /\s/;
+function isScanWhitespace(code) {
+    if (code < 0x80)
+        return code === 0x20 || (code >= 0x09 && code <= 0x0d);
+    return WIDE_WHITESPACE.test(String.fromCharCode(code));
+}
+function skipScanWhitespace(source, from) {
+    let i = from;
+    while (i < source.length && isScanWhitespace(source.charCodeAt(i)))
+        i++;
+    return i;
+}
+function endsName(code) {
+    if (code > GREATER_THAN && code < 0xa0)
+        return false;
+    return isScanWhitespace(code) || code === EQUALS || code === SLASH || code === GREATER_THAN;
 }
-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);
+    const length = source.length;
+    let i = 0;
+    while (i < length) {
+        const nameStart = i;
+        while (i < length && !endsName(source.charCodeAt(i)))
+            i++;
+        if (i === nameStart) {
+            i++;
+            continue;
+        }
+        let cursor = skipScanWhitespace(source, i);
+        if (source.charCodeAt(cursor) !== EQUALS) {
+            i = cursor;
+            continue;
+        }
+        cursor = skipScanWhitespace(source, cursor + 1);
+        const quote = source.charCodeAt(cursor);
+        const close = quote === DOUBLE_QUOTE || quote === SINGLE_QUOTE
+            ? source.indexOf(quote === DOUBLE_QUOTE ? '"' : "'", cursor + 1)
+            : -1;
+        if (close === -1) {
+            i = cursor;
+            continue;
+        }
+        attrs[source.slice(nameStart, i)] = admitText(normalizeAttributeWhitespace(source.slice(cursor + 1, close)));
+        i = close + 1;
     }
     return attrs;
 }
+const ATTRIBUTE_WHITESPACE = /\r\n|[\t\n\r]/g;
+function normalizeAttributeWhitespace(raw) {
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        if (code === 0x09 || code === 0x0a || code === 0x0d) {
+            return raw.replace(ATTRIBUTE_WHITESPACE, ' ');
+        }
+    }
+    return raw;
+}
 function findTagEnd(source, start) {
     let quote = '';
     for (let i = start + 1; i < source.length; i++) {
@@ -123,18 +168,21 @@ export function* xmlEvents(source) {
         if (lt === -1) {
             const chunk = source.slice(i);
             if (chunk.length > 0)
-                yield { kind: 'text', text: decodeEntities(normalizeLineEndings(chunk)) };
+                yield { kind: 'text', text: admitText(normalizeLineEndings(chunk)) };
             return;
         }
         if (lt > i) {
             const chunk = source.slice(i, lt);
             if (chunk.length > 0)
-                yield { kind: 'text', text: decodeEntities(normalizeLineEndings(chunk)) };
+                yield { kind: 'text', text: admitText(normalizeLineEndings(chunk)) };
         }
         const markup = markupAt(source, lt);
         if (markup !== undefined) {
             if (markup.kind === 'cdata') {
-                yield { kind: 'text', text: source.slice(markup.contentStart, markup.contentEnd) };
+                yield {
+                    kind: 'text',
+                    text: stripUnrepresentable(source.slice(markup.contentStart, markup.contentEnd)),
+                };
             }
             i = markup.next;
             continue;
@@ -181,28 +229,3 @@ export function boolTristate(val) {
         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

@@ -1,18 +1,24 @@
-/**
- * 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;
+/**
+ * {@link escapeAttr} for a number format code: the same escapes minus the apostrophe.
+ *
+ * A format code can legitimately contain `"` (a quoted literal like `"$"`), `<` and `&`, and Excel
+ * writes one with bare apostrophes. `'` is not markup-significant inside a double-quoted attribute,
+ * so leaving it keeps a round-tripped code byte-identical to the source; that divergence is the whole
+ * reason this exists.
+ *
+ * It is built by *omitting* one entry from {@link ATTR_ESCAPES} rather than by listing the escapes it
+ * does want, which is how it used to be written, in `io/xlsx/style-elements.ts`. An independently
+ * maintained list does not stay a one-character divergence: that one silently dropped the tab, line
+ * feed and carriage return escapes as well, and XML 1.0 3.3.3 requires a parser to normalise all
+ * three in an attribute value to a space, so Excel read back a format code with a space where the
+ * author wrote a tab. Our own reader preserved the raw character, so a round trip through this
+ * library returned it unchanged and no test here could see the loss.
+ */
+export declare function escapeFormatCode(code: string): string;
 /**
  * Escape a cell value: the `_xHHHH_` convention first, then XML's own escapes.
  *
@@ -25,7 +31,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-scan.ts`, whose single left-to-right pass is what
+ * Reversed by `decodeSpreadsheetText` in `./xml-attrs.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;
@@ -37,12 +43,14 @@ export declare function escapeSpreadsheetText(value: string): string;
  */
 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,
- * whether that is element text or an attribute value.
+ * Re-render an opening tag, `<name …>` or the empty `<name …/>`, from its parsed name and attributes,
+ * for an edit that changes an attribute of an element a part already carries. Attribute order is the
+ * scanner's, which is the source's, so an element whose attributes an edit merges over keeps them
+ * where they were; only the quoting and the entity spelling become this writer's.
  */
-export declare function stripFormulaEquals(value: string | number): string;
+export declare function startTag(name: string, attrs: {
+    readonly [attribute: string]: string | undefined;
+}, selfClosing: boolean): 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
@@ -85,18 +93,43 @@ export declare function checkedToken(value: string, isValid: (candidate: string)
  */
 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.
+ * An integer attribute rendered with a leading space (` name="3"`), or '' when the value is undefined.
+ *
+ * For an `xsd:int` or `xsd:unsignedInt` attribute, whose lexical space has no spelling for a fraction
+ * any more than for a NaN: `priority="1.5"` and `rank="-1"` make a package the schema rejects, so the
+ * value is refused here rather than written. `min` is the floor the attribute's type implies, `0` for
+ * an unsigned one.
+ *
+ * @throws {AuthoringError} when the value is not finite, not a safe integer, or below `min`.
+ */
+export declare function intAttr(name: string, value: number | undefined, min?: number): string;
+/**
+ * A numeric attribute written only when it differs from its schema default, with a leading space, or
+ * '' when the value is undefined or equals `defaultValue`.
+ *
+ * The number is checked before it is compared, because the two answer different questions: whether
+ * the value can be spelled, and whether it is worth spelling. Tested for truthiness instead, `NaN` is
+ * falsy and was omitted as if it were a default of zero, so a gradient fill with `degree: NaN` was
+ * written as an ordinary gradient rather than refused.
+ *
+ * @throws {AuthoringError} when the value is not finite.
+ */
+export declare function nonDefaultNumAttr(name: string, value: number | undefined, defaultValue: number): string;
+/**
+ * Refuse a `Date` OOXML cannot spell, naming the property that carries it.
  *
- * 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.
+ * Two ways a `Date` fails to have a `dcterms:W3CDTF` / `xsd:dateTime` spelling, and neither is
+ * caught by the types. An **Invalid Date** is truthy and is an instance of `Date`, so it passes
+ * every guard short of this one and reaches `toISOString()`, which throws a bare
+ * `RangeError: Invalid time value` -- outside this taxonomy, and naming neither the property nor
+ * the document it was being written into. A year **outside 0000-9999** has no four-digit form, so
+ * `toISOString()` falls back to ISO 8601's expanded `+275760-09-13T…` notation, which is not in
+ * the lexical space of either type; that one does not throw at all, it writes a package Excel
+ * offers to repair.
  *
- * @throws {AuthoringError} naming the value.
+ * @throws {AuthoringError} naming the property.
  */
-export declare function assertWritableNumber(value: number): void;
+export declare function assertWritableDate(date: Date, property: string): 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`.