@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/errors.d.ts

@@ -77,3 +77,67 @@ export declare class InternalError extends XlsxError {
     readonly code = "internal";
     constructor(message?: string, options?: ErrorOptions);
 }
+/**
+ * A name as it should appear inside an error message: quoted, and unambiguous whatever it contains.
+ *
+ * Almost every message this library throws names something the caller or the file chose - a sheet, a
+ * table, a defined name, a module stream, a part path - and the tree had grown three ways of setting
+ * that name off from the prose, split by directory rather than by intent: `"..."`, `'...'`, and
+ * `JSON.stringify`. Only the third survives a name that itself contains a quote, which is exactly the
+ * class of name a spreadsheet permits: a sheet called `Q1 "draft"` renders under either literal
+ * spelling as a message whose reader cannot tell where the name ends. It also renders a name
+ * containing a newline or a zero-width character as one that looks identical to a name that does not,
+ * which for a library whose input is untrusted is the difference between a diagnostic and a decoy.
+ *
+ * So: one spelling, and the one that escapes. `JSON.stringify` is the whole implementation - the
+ * point is not the algorithm but that every throw site reaches the same one.
+ *
+ * Not exported from the `/errors` entry: this is how messages are written, not part of the taxonomy
+ * a caller catches.
+ */
+export declare function quoted(name: string): string;
+/**
+ * The one message for "that token is not in the enumeration", owned here because both sides of a
+ * layering boundary throw it.
+ *
+ * `checkedToken` in `src/xml/xml.ts` is the general form, and `core/` may not import a serialisation
+ * to reach it. The response to that constraint had been to transcribe the sentence into
+ * `core/table-style.ts` character for character, which is a copy that no gate can see is a copy. This
+ * module is the one place below both of them, so the template lives here and neither side owns it.
+ */
+export declare function invalidToken(kind: string, value: string): AuthoringError;
+/**
+ * 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. Neither has the formula grammar, which is why the guard is here rather than in the XML
+ * serialiser: the two spellings of a number this library writes -- an attribute's and a formula
+ * literal's -- sit on opposite sides of the `core`/`xml` boundary and refuse the same values.
+ *
+ * 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 assertWritableNumber(value: number): void;
+/** `U+0001`-style spelling of a code point, for an escape body or an error message. */
+export declare function codePointHex(codePoint: number): string;
+/**
+ * The error for a string carrying a character the target format cannot encode, or `undefined` when
+ * it carries none. Naming the code point and its offset is the whole value of the message: these
+ * strings arrive from a database column or a CSV field, not from a literal the author can see.
+ *
+ * Two formats refuse characters for unrelated reasons -- XML 1.0's `Char` production, and UTF-8's
+ * inability to encode a lone surrogate -- and each had grown its own copy of the rendering, which
+ * had already drifted: the CSV one omitted the zero padding, invisibly, because a surrogate is
+ * always four digits and nothing narrower had been added yet. The *patterns* stay beside their
+ * consumers, which is where they are understood; only the spelling and the message skeleton are
+ * shared, which is where they were wrong.
+ *
+ * `pattern` must not carry the `g` flag: a stateful `lastIndex` would make the same string answer
+ * differently on a second call.
+ *
+ * @param why the clause explaining the refusal, appended after the offset.
+ */
+export declare function unrepresentable(text: string, pattern: RegExp, why: string): AuthoringError | undefined;

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { hex } from './hex.js';
 export class XlsxError extends Error {
 }
 export class AuthoringError extends XlsxError {
@@ -13,3 +14,24 @@ export class InternalError extends XlsxError {
         super(message === undefined ? REPORT_NOTICE : `${message}\n\n${REPORT_NOTICE}`, options);
     }
 }
+export function quoted(name) {
+    return JSON.stringify(name);
+}
+export function invalidToken(kind, value) {
+    return new AuthoringError(`invalid ${kind} ${quoted(value)}: not a value the OOXML enumeration allows`);
+}
+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 codePointHex(codePoint) {
+    return hex(codePoint, 4);
+}
+export function unrepresentable(text, pattern, why) {
+    const found = pattern.exec(text);
+    if (found === null)
+        return undefined;
+    const codePoint = text.codePointAt(found.index);
+    return new AuthoringError(`cannot write U+${codePointHex(codePoint)} at offset ${found.index}: ${why}`);
+}

package/dist/hex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `value` in uppercase hexadecimal, zero-padded to at least `digits`.
+ *
+ * Uppercase because five of the six sites this replaced were, because OOXML writes `ARGB` values that
+ * way, and because a hex digit read by a human beside a decimal number is easier to tell apart when
+ * it is not lowercase. A value wider than `digits` is not truncated: padding is a minimum.
+ */
+export declare function hex(value: number, digits: number): string;

package/dist/hex.js

@@ -0,0 +1,3 @@
+export function hex(value, digits) {
+    return value.toString(16).toUpperCase().padStart(digits, '0');
+}

package/dist/io/cell-metadata/metadata.d.ts

@@ -0,0 +1,42 @@
+import type { ErrorCode } from '../../core/value.ts';
+/** The metadata type whose blocks mark a dynamic-array formula. */
+export declare const DYNAMIC_ARRAY_TYPE = "XLDAPR";
+/** The metadata type whose blocks name a rich value. */
+export declare const RICH_VALUE_TYPE = "XLRICHVALUE";
+/** One record of a metadata block: `type` indexes the metadata types from 1, `value` that type's blocks from 0. */
+export interface MetadataRecord {
+    readonly type: number;
+    readonly value: number;
+}
+/** The metadata part, read as far as a cell's `cm` and `vm` can reach into it. */
+export interface WorkbookMetadata {
+    /** Each metadata type's name, in order. */
+    readonly typeNames: readonly string[];
+    /** Whether each dynamic-array block, in order, sets `fDynamic`. */
+    readonly dynamicArrayBlocks: readonly boolean[];
+    /** The rich value each rich-value block names, in order; -1 for a block naming none it can read. */
+    readonly richValueBlocks: readonly number[];
+    /** Each cell-metadata block's records, in order: a `cm` of 1 is the first. */
+    readonly cellBlocks: readonly (readonly MetadataRecord[])[];
+    /** Each value-metadata block's records, in order: a `vm` of 1 is the first. */
+    readonly valueBlocks: readonly (readonly MetadataRecord[])[];
+}
+/** A workbook with no metadata part. */
+export declare const NO_METADATA: WorkbookMetadata;
+/** What a cell's metadata indices resolve to, for the readers of every sheet in the workbook. */
+export interface CellMetadataIndex {
+    /** The `cm` values marking a dynamic-array formula. */
+    readonly dynamicArrayCells: ReadonlySet<number>;
+    /** The error each `vm` names through a rich value, where it names one. */
+    readonly valueErrors: ReadonlyMap<number, ErrorCode>;
+}
+/** The index of a workbook with no metadata part: no cell is a dynamic array, and no value names an error. */
+export declare const NO_CELL_METADATA: CellMetadataIndex;
+/**
+ * Resolve every `cm` and `vm` the metadata part can answer. `richValueErrors` is the error each rich
+ * value holds, by its index in the rich-value part.
+ *
+ * An index resolving to no block, to a block of another type, or to a rich value that is not an error
+ * marks nothing, so a cell carrying it reads as its own `<v>` says.
+ */
+export declare function indexCellMetadata(metadata: WorkbookMetadata, richValueErrors: ReadonlyMap<number, ErrorCode>): CellMetadataIndex;

package/dist/io/cell-metadata/metadata.js

@@ -0,0 +1,35 @@
+export const DYNAMIC_ARRAY_TYPE = 'XLDAPR';
+export const RICH_VALUE_TYPE = 'XLRICHVALUE';
+export const NO_METADATA = {
+    typeNames: [],
+    dynamicArrayBlocks: [],
+    richValueBlocks: [],
+    cellBlocks: [],
+    valueBlocks: [],
+};
+export const NO_CELL_METADATA = {
+    dynamicArrayCells: new Set(),
+    valueErrors: new Map(),
+};
+export function indexCellMetadata(metadata, richValueErrors) {
+    const typeOf = (record) => metadata.typeNames[record.type - 1];
+    const dynamicArrayCells = new Set();
+    metadata.cellBlocks.forEach((records, index) => {
+        const dynamic = records.some((record) => typeOf(record) === DYNAMIC_ARRAY_TYPE && metadata.dynamicArrayBlocks[record.value] === true);
+        if (dynamic)
+            dynamicArrayCells.add(index + 1);
+    });
+    const valueErrors = new Map();
+    metadata.valueBlocks.forEach((records, index) => {
+        for (const record of records) {
+            if (typeOf(record) !== RICH_VALUE_TYPE)
+                continue;
+            const error = richValueErrors.get(metadata.richValueBlocks[record.value] ?? -1);
+            if (error !== undefined) {
+                valueErrors.set(index + 1, error);
+                break;
+            }
+        }
+    });
+    return { dynamicArrayCells, valueErrors };
+}

package/dist/io/cell-metadata/rich-values.d.ts

@@ -0,0 +1,11 @@
+import type { ErrorCode } from '../../core/value.ts';
+/** The structure type of a rich value naming an error. */
+export declare const ERROR_STRUCTURE = "_error";
+/** The `errorType` a rich value names each error with, for the errors Excel stores only this way. */
+export declare const RICH_VALUE_ERROR_TYPES: ReadonlyMap<ErrorCode, number>;
+/**
+ * The error each rich value holds, keyed by its 0-based index in the rich-value part. A value whose
+ * structure is not `_error`, has no `errorType` key, or names an `errorType` Excel was not seen to read
+ * back as one error holds none.
+ */
+export declare function parseRichValueErrors(structuresXml: string, valuesXml: string): ReadonlyMap<number, ErrorCode>;

package/dist/io/cell-metadata/rich-values.js

@@ -0,0 +1,80 @@
+import { numInteger } from '../../xml/xml-attrs.js';
+import { parseXml } from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
+export const ERROR_STRUCTURE = '_error';
+export const RICH_VALUE_ERROR_TYPES = new Map([
+    ['#SPILL!', 8],
+    ['#CONNECT!', 9],
+    ['#BLOCKED!', 10],
+    ['#UNKNOWN!', 11],
+    ['#FIELD!', 12],
+    ['#CALC!', 13],
+]);
+const ERROR_OF_TYPE = new Map([
+    [3, '#REF!'],
+    [4, '#NAME?'],
+    [6, '#N/A'],
+    ...[...RICH_VALUE_ERROR_TYPES].map(([code, type]) => [type, code]),
+]);
+export function parseRichValueErrors(structuresXml, valuesXml) {
+    const errors = new Map();
+    if (structuresXml === '' || valuesXml === '')
+        return errors;
+    const errorTypeKeys = parseErrorTypeKeys(structuresXml);
+    let index = -1;
+    let wanted = -1;
+    let position = -1;
+    let capturing = false;
+    let text = '';
+    parseXml(valuesXml, {
+        onOpen(name, attrs, selfClosing) {
+            const local = localName(name);
+            if (local === 'rv') {
+                index++;
+                position = -1;
+                const structure = numInteger(attrs.s, 0);
+                wanted = structure === undefined ? -1 : (errorTypeKeys[structure] ?? -1);
+            }
+            else if (local === 'v') {
+                position++;
+                capturing = !selfClosing && position === wanted;
+                text = '';
+            }
+        },
+        onText(chunk) {
+            if (capturing)
+                text += chunk;
+        },
+        onClose(name) {
+            if (localName(name) !== 'v' || !capturing)
+                return;
+            capturing = false;
+            const error = ERROR_OF_TYPE.get(numInteger(text.trim(), 0) ?? -1);
+            if (error !== undefined)
+                errors.set(index, error);
+        },
+    });
+    return errors;
+}
+function parseErrorTypeKeys(xml) {
+    const keys = [];
+    let isError = false;
+    let key = -1;
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 's') {
+                isError = attrs.t === ERROR_STRUCTURE;
+                key = -1;
+                keys.push(-1);
+            }
+            else if (local === 'k' && keys.length > 0) {
+                key++;
+                if (isError && attrs.n === 'errorType' && keys[keys.length - 1] === -1) {
+                    keys[keys.length - 1] = key;
+                }
+            }
+        },
+    });
+    return keys;
+}

package/dist/io/csv/delimiter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Refuse a field delimiter the codec cannot honour.
+ *
+ * A `RangeError` rather than an `AuthoringError`: this is a single scalar out of range, which
+ * `src/errors.ts` reserves for the native types on the grounds that they exist for exactly that.
+ *
+ * @throws {RangeError} if the delimiter is not exactly one character, or is a quote, CR or LF.
+ */
+export declare function assertDelimiter(delimiter: string): void;
+/**
+ * Refuse a row delimiter the writer cannot keep apart from the data.
+ *
+ * Only the writer takes one: the reader recognises LF, CRLF and a bare CR, and a record boundary it
+ * cannot see is a choice the caller makes for a consumer other than this codec. What is refused here
+ * is output no consumer can split. An empty delimiter joins every row into one line. One that
+ * contains the field delimiter reads as an extra field at every row boundary, and one that contains a
+ * quote collides with the quoting that is supposed to protect a field from it.
+ *
+ * @throws {RangeError} if the row delimiter is empty, or contains the field delimiter or a quote.
+ */
+export declare function assertRowDelimiter(rowDelimiter: string, delimiter: string): void;

package/dist/io/csv/delimiter.js

@@ -0,0 +1,18 @@
+import { quoted } from '../../errors.js';
+const RESERVED = new Set(['"', '\r', '\n']);
+export function assertDelimiter(delimiter) {
+    if (delimiter.length !== 1) {
+        throw new RangeError(`CSV delimiter must be a single character, got ${quoted(delimiter)}`);
+    }
+    if (RESERVED.has(delimiter)) {
+        throw new RangeError(`CSV delimiter ${quoted(delimiter)} is reserved: a quote opens a quoted field, and CR and LF end a row`);
+    }
+}
+export function assertRowDelimiter(rowDelimiter, delimiter) {
+    if (rowDelimiter === '') {
+        throw new RangeError('CSV row delimiter must not be empty');
+    }
+    if (rowDelimiter.includes(delimiter) || rowDelimiter.includes('"')) {
+        throw new RangeError(`CSV row delimiter ${quoted(rowDelimiter)} must contain neither the field delimiter ${quoted(delimiter)} nor a quote`);
+    }
+}

package/dist/io/csv/errors.d.ts

@@ -0,0 +1,14 @@
+import { XlsxError } from '../../errors.ts';
+/**
+ * Thrown when CSV text parses but cannot become a worksheet: a record with more fields than a sheet
+ * has columns, or more records than it has rows.
+ *
+ * CSV has no malformed markup to reject, since any text splits into fields somehow, so the only way a
+ * file fails is by not fitting the grid. That is still the file's fault rather than the caller's,
+ * which is why it is this error and not the `RangeError` the grid raises for an authored cell out of
+ * bounds.
+ */
+export declare class CsvParseError extends XlsxError {
+    readonly name = "CsvParseError";
+    readonly code = "malformed-input";
+}

package/dist/io/csv/errors.js

@@ -0,0 +1,5 @@
+import { XlsxError } from '../../errors.js';
+export class CsvParseError extends XlsxError {
+    name = 'CsvParseError';
+    code = 'malformed-input';
+}

package/dist/io/csv/read.d.ts

@@ -11,5 +11,10 @@ export interface CsvReadOptions {
     /** Name for the single worksheet produced; defaults to `"Sheet1"`. */
     readonly sheetName?: string;
 }
-/** Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet. */
+/**
+ * Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet.
+ *
+ * @throws {CsvParseError} if a record has more fields than a worksheet has columns, or the data
+ *   records outnumber a worksheet's rows.
+ */
 export declare function readCsv(input: string | Uint8Array, options?: CsvReadOptions): Workbook;

package/dist/io/csv/read.js

@@ -1,11 +1,12 @@
+import { MAX_COLUMN, MAX_ROW } from '../../core/address.js';
 import { Workbook } from '../../core/workbook.js';
+import { assertDelimiter } from './delimiter.js';
+import { CsvParseError } from './errors.js';
 export function readCsv(input, options = {}) {
     const text = stripBom(typeof input === 'string' ? input : new TextDecoder('utf-8', { ignoreBOM: true }).decode(input));
     const delimiter = options.delimiter ?? ',';
-    if (delimiter.length !== 1) {
-        throw new RangeError(`CSV delimiter must be a single character, got ${JSON.stringify(delimiter)}`);
-    }
-    let rows = parseCsvRows(text, delimiter);
+    assertDelimiter(delimiter);
+    let rows = parseCsvRows(text, delimiter, MAX_ROW + (options.headers ? 1 : 0));
     if (options.headers)
         rows = rows.slice(1);
     const coerce = options.map ?? defaultCsvCoerce;
@@ -17,11 +18,28 @@ export function readCsv(input, options = {}) {
 function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
-function parseCsvRows(text, delimiter) {
+function parseCsvRows(text, delimiter, maxRecords) {
     const rows = [];
     let row = [];
     let field = '';
     let inQuotes = false;
+    let atFieldStart = true;
+    const endField = () => {
+        if (row.length === MAX_COLUMN) {
+            throw new CsvParseError(`CSV record ${rows.length + 1} has more than ${MAX_COLUMN} fields, the most columns a worksheet holds`);
+        }
+        row.push(field);
+        field = '';
+        atFieldStart = true;
+    };
+    const endRow = () => {
+        endField();
+        if (rows.length === maxRecords) {
+            throw new CsvParseError(`CSV has more than ${MAX_ROW} data records, the most rows a worksheet holds`);
+        }
+        rows.push(row);
+        row = [];
+    };
     for (let i = 0; i < text.length; i++) {
         const ch = text.charAt(i);
         if (inQuotes) {
@@ -39,37 +57,43 @@ function parseCsvRows(text, delimiter) {
             }
             continue;
         }
-        if (ch === '"') {
+        if (ch === '"' && atFieldStart) {
             inQuotes = true;
+            atFieldStart = false;
         }
         else if (ch === delimiter) {
-            row.push(field);
-            field = '';
+            endField();
         }
         else if (ch === '\n') {
-            row.push(field);
-            rows.push(row);
-            row = [];
-            field = '';
+            endRow();
         }
-        else if (ch !== '\r') {
+        else if (ch === '\r') {
+            if (text[i + 1] !== '\n')
+                endRow();
+        }
+        else {
             field += ch;
+            atFieldStart = false;
         }
     }
-    row.push(field);
     const trailingNewline = text.endsWith('\n') || text.endsWith('\r');
-    if (!(trailingNewline && row.length === 1 && row[0] === ''))
-        rows.push(row);
+    if (!(trailingNewline && row.length === 0 && field === ''))
+        endRow();
     return rows;
 }
 const NUMERIC = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+const MAX_EXACT_SIGNIFICANT_DIGITS = 15;
 function defaultCsvCoerce(field) {
     if (field === '')
         return null;
-    if (NUMERIC.test(field)) {
+    const numeric = NUMERIC.exec(field);
+    if (numeric) {
         const value = Number(field);
-        return Number.isFinite(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER ? value : field;
+        const exact = Number.isFinite(value) &&
+            Math.abs(value) <= Number.MAX_SAFE_INTEGER &&
+            significantDigits(numeric[1] ?? '') <= MAX_EXACT_SIGNIFICANT_DIGITS;
+        return exact ? value : field;
     }
     const iso = ISO_DATE.exec(field);
     if (iso) {
@@ -79,6 +103,9 @@ function defaultCsvCoerce(field) {
     }
     return field;
 }
+function significantDigits(mantissa) {
+    return mantissa.replace('.', '').replace(/^0+/, '').replace(/0+$/, '').length;
+}
 function isoToDate(match) {
     const year = Number(match[1]);
     const month = Number(match[2]);
@@ -86,9 +113,11 @@ function isoToDate(match) {
     const hour = match[4] === undefined ? 0 : Number(match[4]);
     const minute = match[5] === undefined ? 0 : Number(match[5]);
     const second = match[6] === undefined ? 0 : Number(match[6]);
-    if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) {
+    if (hour > 23 || minute > 59 || second > 59)
         return null;
-    }
-    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
-    return Number.isNaN(date.getTime()) ? null : date;
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, 0);
+    const real = date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+    return real ? date : null;
 }

package/dist/io/csv/write.d.ts

@@ -14,12 +14,20 @@ export interface CsvWriteOptions {
     /** Which worksheet to write; defaults to the first. A name matching no sheet throws rather than
      * silently emitting an empty file. */
     readonly sheetName?: string;
-    /** Field separator; defaults to a comma. */
+    /** Field separator; defaults to a comma. A single character other than a quote, CR or LF. */
     readonly delimiter?: string;
-    /** Line separator between rows; defaults to `"\n"`. */
+    /** Line separator between rows; defaults to `"\n"`. Not empty, and containing neither the field
+     * delimiter nor a quote. A field that contains it is quoted. */
     readonly rowDelimiter?: string;
-    /** A token format (e.g. `"MM/DD/YYYY"`) for Date cells; without it a Date renders as a full
-     * ISO-8601 timestamp. */
+    /**
+     * An Excel number-format code (e.g. `"yyyy-mm-dd"`, `"d mmm yy hh:mm"`) for Date cells; without it
+     * a Date renders as a full ISO-8601 timestamp.
+     *
+     * The same vocabulary as {@link Cell.numFmt}, so `writeCsv(wb, {dateFormat: cell.numFmt})` renders
+     * what the cell would show. It used to be a moment.js-style token set, which is case-sensitive and
+     * spells the month `MM` and the minute `mm`: passing this library's own format codes to it produced
+     * `2024-45-dd` with no throw and no warning. See ADR 0041.
+     */
     readonly dateFormat?: string;
     /** Render Date cells in UTC rather than the runner's local time. */
     readonly dateUTC?: boolean;
@@ -32,12 +40,18 @@ export interface CsvWriteOptions {
      * still applied to the returned text. */
     readonly map?: (value: CellValue, index: number) => string;
 }
-/** The logical CSV text of one worksheet: no BOM, no byte encoding. */
+/**
+ * The logical CSV text of one worksheet: no BOM, no byte encoding. Line N holds row N, so an empty
+ * row before the last populated one is an empty line.
+ *
+ * @throws {RangeError} if `delimiter` or `rowDelimiter` is one the output could not be split on.
+ */
 export declare function writeCsvText(workbook: Workbook, options?: CsvWriteOptions): string;
 /**
  * The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default.
  *
  * @throws {AuthoringError} if a field holds an unpaired surrogate and the encoding is UTF-8, which
  * cannot represent one. The alternative is a silent U+FFFD substitution.
+ * @throws {RangeError} on a delimiter {@link writeCsvText} refuses.
  */
 export declare function writeCsv(workbook: Workbook, options?: CsvWriteOptions): Uint8Array;

package/dist/io/csv/write.js

@@ -1,25 +1,33 @@
-import { cellValueToText, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
-import { AuthoringError } from '../../errors.js';
+import { formatSerialDate } from '../../core/date-format.js';
+import { cellValueToText, isArrayFormulaValue, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
+import { AuthoringError, unrepresentable } from '../../errors.js';
+import { assertDelimiter, assertRowDelimiter } from './delimiter.js';
 const UTF8_BOM = Uint8Array.of(0xef, 0xbb, 0xbf);
 export function writeCsvText(workbook, options = {}) {
     const sheet = selectSheet(workbook, options.sheetName);
     const delimiter = options.delimiter ?? ',';
+    assertDelimiter(delimiter);
     const rowDelimiter = options.rowDelimiter ?? '\n';
+    assertRowDelimiter(rowDelimiter, delimiter);
     const lines = [];
-    for (const { cells } of sheet.rows()) {
+    for (const row of sheet.rows()) {
         let width = 0;
         const byColumn = new Map();
-        for (const cell of cells) {
+        for (const cell of row.cells) {
             byColumn.set(cell.col, cell);
             if (cell.col > width)
                 width = cell.col;
         }
+        if (width === 0)
+            continue;
         const fields = [];
         for (let column = 1; column <= width; column++) {
             const value = byColumn.get(column)?.value ?? null;
             const text = options.map ? options.map(value, column - 1) : csvFieldText(value, options);
-            fields.push(quoteField(text, delimiter));
+            fields.push(quoteField(text, delimiter, rowDelimiter));
         }
+        while (lines.length < row.number - 1)
+            lines.push('');
         lines.push(fields.join(delimiter));
     }
     return lines.join(rowDelimiter);
@@ -58,14 +66,11 @@ function encode(text, encoding) {
     return bytes;
 }
 function assertEncodable(text) {
-    const found = LONE_SURROGATE.exec(text);
-    if (found === null)
-        return;
-    const codePoint = text.codePointAt(found.index).toString(16).toUpperCase();
-    throw new AuthoringError(`cannot write U+${codePoint} at offset ${found.index} of the CSV text: it is an unpaired ` +
-        'surrogate, which UTF-8 cannot encode and CSV has no escape for');
+    const error = unrepresentable(text, SURROGATES, 'it is an unpaired surrogate, which UTF-8 cannot encode and CSV has no escape for');
+    if (error !== undefined)
+        throw error;
 }
-const LONE_SURROGATE = /[\u{D800}-\u{DFFF}]/u;
+const SURROGATES = /[\u{D800}-\u{DFFF}]/u;
 function selectSheet(workbook, name) {
     if (name === undefined) {
         const first = workbook.worksheets[0];
@@ -77,44 +82,19 @@ function selectSheet(workbook, name) {
 }
 function csvFieldText(value, options) {
     if (value instanceof Date && options.dateFormat !== undefined) {
-        return formatDate(value, options.dateFormat, options.dateUTC ?? false);
+        return formatSerialDate(value, options.dateFormat, options.dateUTC ?? false);
     }
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+    if (isFormulaValue(value) ||
+        isSharedFormulaValue(value) ||
+        isArrayFormulaValue(value) ||
+        isDataTableFormulaValue(value)) {
         return value.result === undefined ? '' : csvFieldText(value.result, options);
     }
     return cellValueToText(value);
 }
-const DATE_TOKENS = /YYYY|YY|MM|DD|HH|mm|ss|M|D|H|m|s/g;
-function formatDate(date, format, utc) {
-    if (Number.isNaN(date.getTime()))
-        return '';
-    if (format === undefined)
-        return date.toISOString();
-    const year = utc ? date.getUTCFullYear() : date.getFullYear();
-    const month = (utc ? date.getUTCMonth() : date.getMonth()) + 1;
-    const day = utc ? date.getUTCDate() : date.getDate();
-    const hour = utc ? date.getUTCHours() : date.getHours();
-    const minute = utc ? date.getUTCMinutes() : date.getMinutes();
-    const second = utc ? date.getUTCSeconds() : date.getSeconds();
-    const pad = (n) => String(n).padStart(2, '0');
-    const tokens = {
-        YYYY: String(year),
-        YY: pad(year % 100),
-        MM: pad(month),
-        M: String(month),
-        DD: pad(day),
-        D: String(day),
-        HH: pad(hour),
-        H: String(hour),
-        mm: pad(minute),
-        m: String(minute),
-        ss: pad(second),
-        s: String(second),
-    };
-    return format.replace(DATE_TOKENS, (token) => tokens[token] ?? token);
-}
-function quoteField(field, delimiter) {
+function quoteField(field, delimiter, rowDelimiter) {
     if (field.includes(delimiter) ||
+        field.includes(rowDelimiter) ||
         field.includes('"') ||
         field.includes('\n') ||
         field.includes('\r')) {