@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/column.js

@@ -1,9 +1,11 @@
 import { assertColumnInBounds, encodeAddress, numberToColumn } from './address.js';
+import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
-export class Column {
+export class Column extends AxisHandle {
     #sheet;
     index;
     constructor(sheet, index) {
+        super();
         assertColumnInBounds(index);
         this.#sheet = sheet;
         this.index = index;
@@ -12,73 +14,82 @@ export class Column {
         return numberToColumn(this.index);
     }
     get properties() {
+        return this.propertiesOf();
+    }
+    propertiesOf() {
         return this.#sheet[INTERNAL].columnPropertiesOf(this.index);
     }
+    ensureProperties() {
+        return this.#sheet[INTERNAL].ensureColumnProperties(this.index);
+    }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropColumnProperties(this.index);
+    }
     get key() {
-        return this.#read('key');
+        return this.read('key');
     }
     set key(key) {
-        this.#write('key', key);
+        this.write('key', key);
     }
     get width() {
-        return this.#read('width');
+        return this.read('width');
     }
     set width(width) {
-        this.#write('width', width);
+        this.write('width', width);
     }
     get hidden() {
-        return this.#read('hidden');
+        return this.read('hidden');
     }
     set hidden(hidden) {
-        this.#write('hidden', hidden);
+        this.write('hidden', hidden);
     }
     get outlineLevel() {
-        return this.#read('outlineLevel');
+        return this.read('outlineLevel');
     }
     set outlineLevel(outlineLevel) {
-        this.#write('outlineLevel', outlineLevel);
+        this.write('outlineLevel', outlineLevel);
     }
     get collapsed() {
-        return this.#read('collapsed');
+        return this.read('collapsed');
     }
     set collapsed(collapsed) {
-        this.#write('collapsed', collapsed);
+        this.write('collapsed', collapsed);
     }
     get fill() {
-        return this.#read('fill');
+        return this.read('fill');
     }
     set fill(fill) {
-        this.#write('fill', fill);
+        this.write('fill', fill);
     }
     get numFmt() {
-        return this.#read('numFmt');
+        return this.read('numFmt');
     }
     set numFmt(numFmt) {
-        this.#write('numFmt', numFmt);
+        this.write('numFmt', numFmt);
     }
     get font() {
-        return this.#read('font');
+        return this.read('font');
     }
     set font(font) {
-        this.#write('font', font);
+        this.write('font', font);
     }
     get border() {
-        return this.#read('border');
+        return this.read('border');
     }
     set border(border) {
-        this.#write('border', border);
+        this.write('border', border);
     }
     get alignment() {
-        return this.#read('alignment');
+        return this.read('alignment');
     }
     set alignment(alignment) {
-        this.#write('alignment', alignment);
+        this.write('alignment', alignment);
     }
     get protection() {
-        return this.#read('protection');
+        return this.read('protection');
     }
     set protection(protection) {
-        this.#write('protection', protection);
+        this.write('protection', protection);
     }
     getCell(row) {
         return this.#sheet.getCell(encodeAddress(this.index, row));
@@ -98,16 +109,4 @@ export class Column {
                 this.getCell(index + 1).value = value;
         });
     }
-    #read(key) {
-        return this.#sheet[INTERNAL].columnPropertiesOf(this.index)?.[key];
-    }
-    #write(key, value) {
-        if (value === undefined) {
-            const properties = this.#sheet[INTERNAL].columnPropertiesOf(this.index);
-            if (properties !== undefined)
-                delete properties[key];
-            return;
-        }
-        this.#sheet[INTERNAL].ensureColumnProperties(this.index)[key] = value;
-    }
 }

package/dist/core/comment-thread.js

@@ -1,9 +1,10 @@
+import { quoted } from '../errors.js';
 const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}?$/i;
 export function commentThreadGuid(value, what) {
     const match = GUID.exec(value.trim());
     if (match === null) {
         throw new SyntaxError(`${what} must be a GUID: Excel writes threaded-comment ids as ` +
-            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got "${value}"`);
+            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got ${quoted(value)}`);
     }
     return `{${match.slice(1).join('-').toUpperCase()}}`;
 }

package/dist/core/conditional-formatting-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type ConditionalFormatting } from './conditional-formatting.ts';
+import type { AxisSplice } from './grid-shift.ts';
 export declare class ConditionalFormattingOverlay {
     #private;
     /**
@@ -14,7 +15,7 @@ export declare class ConditionalFormattingOverlay {
      * Re-anchor every rule set through a row or column splice, so a highlight keeps covering the cells
      * it was written for. A rule set whose every target area fell inside a deleted span goes with them.
      */
-    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
+    shift(splice: AxisSplice): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/conditional-formatting-overlay.js

@@ -9,10 +9,10 @@ export class ConditionalFormattingOverlay {
     get entries() {
         return this.#entries;
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const entries = [];
         for (const entry of this.#entries) {
-            const ref = shiftSqref(entry.ref, axis, start, count, delta);
+            const ref = shiftSqref(entry.ref, splice);
             if (ref !== undefined)
                 entries.push({ ...entry, ref });
         }

package/dist/core/conditional-formatting.d.ts

@@ -1,8 +1,11 @@
-import type { Color, DifferentialStyle } from './style.ts';
+import { type ClonePlan } from './clone.ts';
+import type { AssertNever } from './internal.ts';
+import { type Color } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.ts';
 /** How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim. */
 export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
 /** Narrow a raw `<cfvo type>` token to a known {@link CfValueObjectType}. */
-export declare function isCfValueObjectType(value: string): value is CfValueObjectType;
+export declare const isCfValueObjectType: (value: string) => value is CfValueObjectType;
 /**
  * One anchor of a colour-scale, data-bar, or icon-set scale: a "conditional format value object".
  * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
@@ -22,7 +25,7 @@ export interface CfValueObject {
  */
 export type ConditionalFormattingType = 'expression' | 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'top10' | 'uniqueValues' | 'duplicateValues' | 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith' | 'containsBlanks' | 'notContainsBlanks' | 'containsErrors' | 'notContainsErrors' | 'timePeriod' | 'aboveAverage';
 /** Narrow a raw `<cfRule type>` token to a known {@link ConditionalFormattingType}. */
-export declare function isConditionalFormattingType(value: string): value is ConditionalFormattingType;
+export declare const isConditionalFormattingType: (value: string) => value is ConditionalFormattingType;
 /**
  * How a `cellIs` or text rule compares, as `ST_ConditionalFormattingOperator` enumerates it.
  *
@@ -32,11 +35,11 @@ export declare function isConditionalFormattingType(value: string): value is Con
  */
 export type ConditionalFormattingOperator = 'lessThan' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'greaterThanOrEqual' | 'greaterThan' | 'between' | 'notBetween' | 'containsText' | 'notContains' | 'beginsWith' | 'endsWith';
 /** Narrow a raw `<cfRule operator>` token to a known {@link ConditionalFormattingOperator}. */
-export declare function isConditionalFormattingOperator(value: string): value is ConditionalFormattingOperator;
+export declare const isConditionalFormattingOperator: (value: string) => value is ConditionalFormattingOperator;
 /** The window a `timePeriod` rule matches against, relative to the day the sheet is recalculated. */
 export type CfTimePeriod = 'today' | 'yesterday' | 'tomorrow' | 'last7Days' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisWeek' | 'lastWeek' | 'nextWeek';
 /** Narrow a raw `<cfRule timePeriod>` token to a known {@link CfTimePeriod}. */
-export declare function isCfTimePeriod(value: string): value is CfTimePeriod;
+export declare const isCfTimePeriod: (value: string) => value is CfTimePeriod;
 /**
  * The named icon family an `iconSet` rule draws from, as `ST_IconSetType` enumerates it. The leading
  * digit is the number of icons, which is also how many {@link CfValueObject} anchors the rule needs.
@@ -47,7 +50,7 @@ export declare function isCfTimePeriod(value: string): value is CfTimePeriod;
  */
 export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
 /** Narrow a raw `<iconSet iconSet>` token to a known {@link IconSetType}. */
-export declare function isIconSetType(value: string): value is IconSetType;
+export declare const isIconSetType: (value: string) => value is IconSetType;
 /**
  * A single conditional-formatting rule. `type` is the OOXML cfRule type; the remaining fields carry
  * the operands that type needs and are absent otherwise. A rule the library does not model in depth
@@ -108,3 +111,8 @@ export interface ConditionalFormatting {
 /** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
  * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
 export declare function cloneConditionalFormatting(cf: ConditionalFormatting): ConditionalFormatting;
+declare const RULE_CLONE: ClonePlan<ConditionalFormattingRule>;
+export type EveryRuleFieldIsCloned = AssertNever<Exclude<keyof Required<ConditionalFormattingRule>, keyof typeof RULE_CLONE>>;
+declare const STYLE_CLONE: ClonePlan<DifferentialStyle>;
+export type EveryDifferentialStyleFieldIsCloned = AssertNever<Exclude<keyof Required<DifferentialStyle>, keyof typeof STYLE_CLONE>>;
+export {};

package/dist/core/conditional-formatting.js

@@ -1,15 +1,15 @@
-const CF_VALUE_OBJECT_TYPES = {
+import { tokenSet } from '../token-set.js';
+import { cloneWith } from './clone.js';
+import { cloneBorder, cloneFill, cloneFont } from './style.js';
+export const isCfValueObjectType = tokenSet({
     num: true,
     percent: true,
     max: true,
     min: true,
     percentile: true,
     formula: true,
-};
-export function isCfValueObjectType(value) {
-    return Object.hasOwn(CF_VALUE_OBJECT_TYPES, value);
-}
-const CONDITIONAL_FORMATTING_TYPES = {
+});
+export const isConditionalFormattingType = tokenSet({
     expression: true,
     cellIs: true,
     colorScale: true,
@@ -28,11 +28,8 @@ const CONDITIONAL_FORMATTING_TYPES = {
     notContainsErrors: true,
     timePeriod: true,
     aboveAverage: true,
-};
-export function isConditionalFormattingType(value) {
-    return Object.hasOwn(CONDITIONAL_FORMATTING_TYPES, value);
-}
-const CONDITIONAL_FORMATTING_OPERATORS = {
+});
+export const isConditionalFormattingOperator = tokenSet({
     lessThan: true,
     lessThanOrEqual: true,
     equal: true,
@@ -45,11 +42,8 @@ const CONDITIONAL_FORMATTING_OPERATORS = {
     notContains: true,
     beginsWith: true,
     endsWith: true,
-};
-export function isConditionalFormattingOperator(value) {
-    return Object.hasOwn(CONDITIONAL_FORMATTING_OPERATORS, value);
-}
-const CF_TIME_PERIODS = {
+});
+export const isCfTimePeriod = tokenSet({
     today: true,
     yesterday: true,
     tomorrow: true,
@@ -60,11 +54,8 @@ const CF_TIME_PERIODS = {
     thisWeek: true,
     lastWeek: true,
     nextWeek: true,
-};
-export function isCfTimePeriod(value) {
-    return Object.hasOwn(CF_TIME_PERIODS, value);
-}
-const ICON_SET_TYPES = {
+});
+export const isIconSetType = tokenSet({
     '3Arrows': true,
     '3ArrowsGray': true,
     '3Flags': true,
@@ -82,32 +73,43 @@ const ICON_SET_TYPES = {
     '5ArrowsGray': true,
     '5Rating': true,
     '5Quarters': true,
-};
-export function isIconSetType(value) {
-    return Object.hasOwn(ICON_SET_TYPES, value);
-}
+});
 export function cloneConditionalFormatting(cf) {
     return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
 }
+const RULE_CLONE = {
+    type: 'value',
+    priority: 'value',
+    stopIfTrue: 'value',
+    operator: 'value',
+    formulae: 'values',
+    text: 'value',
+    style: cloneStyle,
+    dxfId: 'value',
+    cfvo: 'records',
+    color: 'record',
+    colors: 'records',
+    gradient: 'value',
+    negativeFillColor: 'record',
+    axisColor: 'record',
+    iconSet: 'value',
+    rank: 'value',
+    percent: 'value',
+    bottom: 'value',
+    aboveAverage: 'value',
+    equalAverage: 'value',
+    stdDev: 'value',
+    timePeriod: 'value',
+};
 function cloneRule(rule) {
-    return {
-        ...rule,
-        ...(rule.formulae !== undefined ? { formulae: [...rule.formulae] } : {}),
-        ...(rule.cfvo !== undefined ? { cfvo: rule.cfvo.map((v) => ({ ...v })) } : {}),
-        ...(rule.color !== undefined ? { color: { ...rule.color } } : {}),
-        ...(rule.negativeFillColor !== undefined
-            ? { negativeFillColor: { ...rule.negativeFillColor } }
-            : {}),
-        ...(rule.axisColor !== undefined ? { axisColor: { ...rule.axisColor } } : {}),
-        ...(rule.colors !== undefined ? { colors: rule.colors.map((c) => ({ ...c })) } : {}),
-        ...(rule.style !== undefined ? { style: cloneStyle(rule.style) } : {}),
-    };
+    return cloneWith(rule, RULE_CLONE);
 }
+const STYLE_CLONE = {
+    font: cloneFont,
+    fill: cloneFill,
+    border: cloneBorder,
+    numFmt: 'value',
+};
 function cloneStyle(style) {
-    return {
-        ...style,
-        ...(style.font !== undefined ? { font: { ...style.font } } : {}),
-        ...(style.fill !== undefined ? { fill: { ...style.fill } } : {}),
-        ...(style.border !== undefined ? { border: { ...style.border } } : {}),
-    };
+    return cloneWith(style, STYLE_CLONE);
 }

package/dist/core/containers.d.ts

@@ -1,2 +1,14 @@
 export declare function overwrite<T extends object>(target: T, source: T): void;
 export declare function replaceContents<T>(array: T[], next: readonly T[]): void;
+/**
+ * Copy one key from `source` onto `target`, leaving `target` untouched when `source` omits it.
+ *
+ * One key at a time is the whole point, and the reason is a limit of the checker rather than a
+ * preference: over a union key the compiler cannot correlate `source[key]`'s type with `target[key]`'s,
+ * so a version taking the union needs a cast, and that cast is the one place a facet could be written
+ * into the wrong slot with nothing to notice. Bound to a single member here, the assignment is checked.
+ *
+ * Generic over the object as well as the key because these two lines had been written out once for a
+ * cell's formatting and once for a cell's content, each under its own paragraph making this point.
+ */
+export declare function copyKeyIfPresent<T extends object, K extends keyof T>(target: T, source: Readonly<T>, key: K): void;

package/dist/core/containers.js

@@ -8,3 +8,8 @@ export function replaceContents(array, next) {
     for (const item of next)
         array.push(item);
 }
+export function copyKeyIfPresent(target, source, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}

package/dist/core/data-validation-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type DataValidation, type DataValidationEntry } from './data-validation.ts';
+import type { AxisSplice } from './grid-shift.ts';
 export declare class DataValidationOverlay {
     #private;
     /**
@@ -33,7 +34,7 @@ export declare class DataValidationOverlay {
      * attached to rather than on whatever moved into their place. A rule whose every target area fell
      * inside a deleted span is dropped with them.
      */
-    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
+    shift(splice: AxisSplice): void;
     /** Drop every validation, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/data-validation-overlay.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { replaceContents } from './containers.js';
 import { cloneDataValidation, } from './data-validation.js';
 import { decodeSqrefRects, shiftSqref } from './merge.js';
@@ -8,7 +8,7 @@ export class DataValidationOverlay {
     add(sqref, rule, options = {}) {
         const rects = decodeSqrefRects(sqref);
         if (rects.length === 0) {
-            throw new AuthoringError(`data validation range "${sqref}" names no cells`);
+            throw new AuthoringError(`data validation range ${quoted(sqref)} names no cells`);
         }
         const stored = cloneDataValidation(rule);
         const entry = { sqref, rule: stored };
@@ -30,11 +30,11 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const entries = [];
         const rects = [];
         for (const entry of this.#entries) {
-            const sqref = shiftSqref(entry.sqref, axis, start, count, delta);
+            const sqref = shiftSqref(entry.sqref, splice);
             if (sqref === undefined)
                 continue;
             entries.push({ ...entry, sqref });

package/dist/core/data-validation.d.ts

@@ -1,18 +1,20 @@
+import { type ClonePlan } from './clone.ts';
+import type { AssertNever } from './internal.ts';
 /** The kind of constraint a validation enforces. `list` is a dropdown; `custom` is an arbitrary
  * boolean formula; `none` constrains nothing and exists only to carry the rule's messages; the rest
  * bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
 export type DataValidationType = 'none' | 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
 /** Narrow a raw `<dataValidation type>` token to a known {@link DataValidationType}. */
-export declare function isDataValidationType(value: string): value is DataValidationType;
+export declare const isDataValidationType: (value: string) => value is DataValidationType;
 /** How a typed validation compares its operand(s). Absent on a `list`/`custom` rule; defaults to
  * `between` on a typed rule (the value Excel omits from the XML). */
 export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
 /** Narrow a raw `<dataValidation operator>` token to a known {@link DataValidationOperator}. */
-export declare function isDataValidationOperator(value: string): value is DataValidationOperator;
+export declare const isDataValidationOperator: (value: string) => value is DataValidationOperator;
 /** How Excel reacts to input that fails the rule. */
 export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
 /** Narrow a raw `<dataValidation errorStyle>` token to a known {@link DataValidationErrorStyle}. */
-export declare function isDataValidationErrorStyle(value: string): value is DataValidationErrorStyle;
+export declare const isDataValidationErrorStyle: (value: string) => value is DataValidationErrorStyle;
 /** One validation rule. `formulae` holds the operand(s), `formula1` then optional `formula2`: a
  * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
  * its verbatim string. */
@@ -42,4 +44,8 @@ export interface DataValidationEntry {
 }
 /** A defensive copy of a rule, so a stored validation never aliases the caller's object (nor its
  * `formulae` array). */
+declare const RULE_CLONE: ClonePlan<DataValidation>;
+/** The proof that {@link RULE_CLONE} names every field of the rule. */
+export type EveryDataValidationFieldIsCloned = AssertNever<Exclude<keyof Required<DataValidation>, keyof typeof RULE_CLONE>>;
 export declare function cloneDataValidation(rule: DataValidation): DataValidation;
+export {};

package/dist/core/data-validation.js

@@ -1,4 +1,6 @@
-const DATA_VALIDATION_TYPES = {
+import { tokenSet } from '../token-set.js';
+import { cloneWith } from './clone.js';
+export const isDataValidationType = tokenSet({
     none: true,
     list: true,
     whole: true,
@@ -7,11 +9,8 @@ const DATA_VALIDATION_TYPES = {
     time: true,
     textLength: true,
     custom: true,
-};
-export function isDataValidationType(value) {
-    return Object.hasOwn(DATA_VALIDATION_TYPES, value);
-}
-const DATA_VALIDATION_OPERATORS = {
+});
+export const isDataValidationOperator = tokenSet({
     between: true,
     notBetween: true,
     equal: true,
@@ -20,21 +19,25 @@ const DATA_VALIDATION_OPERATORS = {
     lessThan: true,
     greaterThanOrEqual: true,
     lessThanOrEqual: true,
-};
-export function isDataValidationOperator(value) {
-    return Object.hasOwn(DATA_VALIDATION_OPERATORS, value);
-}
-const DATA_VALIDATION_ERROR_STYLES = {
+});
+export const isDataValidationErrorStyle = tokenSet({
     stop: true,
     warning: true,
     information: true,
+});
+const RULE_CLONE = {
+    type: 'value',
+    operator: 'value',
+    formulae: 'values',
+    allowBlank: 'value',
+    showInputMessage: 'value',
+    showErrorMessage: 'value',
+    errorStyle: 'value',
+    error: 'value',
+    errorTitle: 'value',
+    prompt: 'value',
+    promptTitle: 'value',
 };
-export function isDataValidationErrorStyle(value) {
-    return Object.hasOwn(DATA_VALIDATION_ERROR_STYLES, value);
-}
 export function cloneDataValidation(rule) {
-    return {
-        ...rule,
-        ...(rule.formulae !== undefined ? { formulae: [...rule.formulae] } : {}),
-    };
+    return cloneWith(rule, RULE_CLONE);
 }

package/dist/core/date-format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Render a `Date` through an Excel number-format code: `yyyy-mm-dd`, `d mmm yy`, `hh:mm:ss`.
+ *
+ * The one vocabulary this library speaks for dates. `Cell.numFmt` holds a code, `DEFAULT_DATE_NUMFMT`
+ * is one, `isDateFormat` classifies one, and the CSV writer's `dateFormat` used to be a moment.js
+ * token set instead -- case-sensitive, with `mm` meaning minutes and the month spelled `MM` -- so
+ * `writeCsv(wb, {dateFormat: cell.numFmt})`, the obvious thing to write, rendered every date cell as
+ * `2024-45-dd` with no throw and no warning. A library with two public date-format properties
+ * speaking different languages has no defensible answer to "which one is this".
+ *
+ * Codes are case-insensitive, as Excel's are. What is *not* covered, deliberately: the elapsed-time
+ * forms (`[h]`, `[mm]`), which measure a duration rather than name a moment, and the locale directive
+ * (`[$-409]`), which is dropped rather than honoured -- month and weekday names render in English.
+ * Both are recorded in ADR 0041.
+ *
+ * @param utc read the date's fields in UTC rather than in the runner's local time. A serial carries
+ *   no timezone, so a `Date` that came from one is UTC wall-clock and this should be `true`; a `Date`
+ *   a caller assigned may mean either.
+ */
+export declare function formatSerialDate(date: Date, code: string, utc: boolean): string;