@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/pivot-table.js

@@ -1,5 +1,7 @@
-import { AuthoringError, InternalError } from '../errors.js';
-import { encodeAddress } from './address.js';
+import { AuthoringError, InternalError, quoted } from '../errors.js';
+import { tokenSet } from '../token-set.js';
+import { encodeRect } from './address.js';
+import { INTERNAL } from './internal.js';
 import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
 const PIVOT_METRICS = {
     sum: true,
@@ -14,23 +16,18 @@ const PIVOT_METRICS = {
     var: true,
     varp: true,
 };
-function isPivotMetric(value) {
-    return Object.hasOwn(PIVOT_METRICS, value);
-}
+const isPivotMetric = tokenSet(PIVOT_METRICS);
 export function pivotMetricFromSubtotal(subtotal) {
     if (subtotal === undefined)
         return 'sum';
     return isPivotMetric(subtotal) ? subtotal : 'sum';
 }
-const DECLARABLE_PIVOT_SOURCE_KINDS = {
+export const isDeclarablePivotSourceKind = tokenSet({
     worksheet: true,
     external: true,
     consolidation: true,
     scenario: true,
-};
-export function isDeclarablePivotSourceKind(value) {
-    return Object.hasOwn(DECLARABLE_PIVOT_SOURCE_KINDS, value);
-}
+});
 const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
@@ -44,7 +41,7 @@ export class PivotTable {
     constructor(options) {
         const metric = options.metric ?? 'sum';
         if (!Object.hasOwn(PIVOT_METRICS, metric)) {
-            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
+            throw new AuthoringError(`unsupported pivot metric ${quoted(metric)}: expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
         }
         this.metric = metric;
         const source = options.source;
@@ -53,51 +50,36 @@ export class PivotTable {
         if (columnCount < 1 || lastRow < 2) {
             throw new AuthoringError('a pivot source needs a header row and at least one data row');
         }
-        const fields = [];
-        for (let col = 1; col <= columnCount; col++) {
-            const name = textOf(scalarOf(source.getCell(encodeAddress(col, 1)).value));
-            if (name !== '')
-                fields.push({ name, col });
-        }
-        if (fields.length === 0)
-            throw new AuthoringError('the pivot source header row is empty');
-        const resolve = (role, name) => {
-            const index = fields.findIndex((field) => field.name === name);
-            if (index < 0) {
-                throw new AuthoringError(`pivot ${role} field "${name}" is not a column header in the source sheet`);
-            }
-            return index;
-        };
-        if (options.rows.length === 0)
-            throw new AuthoringError('a pivot table needs at least one row field');
-        if (options.columns.length === 0)
-            throw new AuthoringError('a pivot table needs at least one column field');
-        const [valueName, ...extraValues] = options.values;
-        if (valueName === undefined || extraValues.length > 0) {
-            throw new AuthoringError('a pivot table needs exactly one value field');
-        }
-        this.rowFields = options.rows.map((name) => resolve('row', name));
-        this.columnFields = options.columns.map((name) => resolve('column', name));
-        this.valueField = resolve('value', valueName);
-        const axisFields = new Set([...this.rowFields, ...this.columnFields]);
+        const internals = source[INTERNAL];
+        const valueAt = (row, col) => internals.peekCell(row, col)?.value ?? null;
+        const fields = discoverFields(valueAt, columnCount);
+        const roles = resolveRoles(options, fields);
+        this.rowFields = roles.rowFields;
+        this.columnFields = roles.columnFields;
+        this.valueField = roles.valueField;
+        const axisFields = new Set([...roles.rowFields, ...roles.columnFields]);
         const firstField = fields[0];
-        const lastField = fields[fields.length - 1];
+        const lastField = fields.at(-1);
         if (firstField === undefined || lastField === undefined) {
-            throw new AuthoringError('the pivot source header row is empty');
+            throw new InternalError('pivot field list is empty after discoverFields guaranteed it is not');
         }
         this.sourceSheetName = source.name;
-        this.sourceRef = `${encodeAddress(firstField.col, 1)}:${encodeAddress(lastField.col, lastRow)}`;
+        this.sourceRef = encodeRect({
+            top: 1,
+            left: firstField.col,
+            bottom: lastRow,
+            right: lastField.col,
+        });
         const dataRowCount = lastRow - 1;
         const columnScalars = fields.map((field) => {
             const scalars = [];
-            for (let row = 2; row <= lastRow; row++) {
-                scalars.push(scalarOf(source.getCell(encodeAddress(field.col, row)).value));
-            }
+            for (let row = 2; row <= lastRow; row++)
+                scalars.push(scalarOf(valueAt(row, field.col)));
             return scalars;
         });
         const catalogues = fields.map(() => null);
         this.cacheFields = fields.map((field, fieldIndex) => {
-            const scalars = scalarsForField(columnScalars, fieldIndex);
+            const scalars = columnScalars[fieldIndex] ?? missingColumn(fieldIndex);
             const containsBlank = scalars.some((scalar) => scalar.kind === 'blank');
             if (axisFields.has(fieldIndex)) {
                 const items = [];
@@ -114,15 +96,18 @@ export class PivotTable {
             }
             return { name: field.name, sharedItems: null, numeric: numericSummary(scalars), containsBlank };
         });
+        const byField = fields.map((_field, fieldIndex) => ({
+            scalars: columnScalars[fieldIndex] ?? missingColumn(fieldIndex),
+            catalogue: catalogues[fieldIndex],
+        }));
         const records = [];
         for (let row = 0; row < dataRowCount; row++) {
-            records.push(fields.map((_field, fieldIndex) => {
-                const scalar = scalarsForField(columnScalars, fieldIndex)[row];
+            records.push(byField.map(({ scalars, catalogue }, fieldIndex) => {
+                const scalar = scalars[row];
                 if (scalar === undefined) {
                     throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex}: every column was ` +
                         'scanned for the same dataRowCount above, so this index is always in range');
                 }
-                const catalogue = catalogues[fieldIndex];
                 if (!catalogue)
                     return scalar;
                 const index = catalogue.get(itemKey(scalar));
@@ -142,12 +127,41 @@ export class PivotTable {
         return field.name;
     }
 }
-function scalarsForField(columnScalars, fieldIndex) {
-    const scalars = columnScalars[fieldIndex];
-    if (scalars === undefined) {
-        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
+function discoverFields(valueAt, columnCount) {
+    const fields = [];
+    for (let col = 1; col <= columnCount; col++) {
+        const name = textOf(scalarOf(valueAt(1, col)));
+        if (name !== '')
+            fields.push({ name, col });
+    }
+    if (fields.length === 0)
+        throw new AuthoringError('the pivot source header row is empty');
+    return fields;
+}
+function resolveRoles(options, fields) {
+    const resolve = (role, name) => {
+        const index = fields.findIndex((field) => field.name === name);
+        if (index < 0) {
+            throw new AuthoringError(`pivot ${role} field ${quoted(name)} is not a column header in the source sheet`);
+        }
+        return index;
+    };
+    if (options.rows.length === 0)
+        throw new AuthoringError('a pivot table needs at least one row field');
+    if (options.columns.length === 0)
+        throw new AuthoringError('a pivot table needs at least one column field');
+    const [valueName, ...extraValues] = options.values;
+    if (valueName === undefined || extraValues.length > 0) {
+        throw new AuthoringError('a pivot table needs exactly one value field');
     }
-    return scalars;
+    return {
+        rowFields: options.rows.map((name) => resolve('row', name)),
+        columnFields: options.columns.map((name) => resolve('column', name)),
+        valueField: resolve('value', valueName),
+    };
+}
+function missingColumn(fieldIndex) {
+    throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
 }
 function itemKey(item) {
     switch (item.kind) {

package/dist/core/protection.js

@@ -1,4 +1,4 @@
-import { concat, toBase64 } from '../bytes.js';
+import { concat, toBase64, utf16leBytes } from '../bytes.js';
 import { sha512 } from '../sha512.js';
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
@@ -22,7 +22,7 @@ const DEFAULT_SPIN_COUNT = 100000;
 const SALT_BYTES = 16;
 export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
     const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
-    let hash = sha512(concat([salt, utf16le(password)]));
+    let hash = sha512(concat([salt, utf16leBytes(password)]));
     const spun = new Uint8Array(hash.length + 4);
     const counter = new DataView(spun.buffer, hash.length, 4);
     for (let i = 0; i < spinCount; i++) {
@@ -37,12 +37,3 @@ export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
         spinCount,
     };
 }
-function utf16le(text) {
-    const bytes = new Uint8Array(text.length * 2);
-    for (let i = 0; i < text.length; i++) {
-        const unit = text.charCodeAt(i);
-        bytes[i * 2] = unit & 0xff;
-        bytes[i * 2 + 1] = unit >>> 8;
-    }
-    return bytes;
-}

package/dist/core/range.js

@@ -1,5 +1,7 @@
-import { decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW } from './address.js';
+import { quoted } from '../errors.js';
+import { assertAxisInBounds, decodeRange, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, } from './address.js';
 import { applyCellStyle } from './cell.js';
+import { INTERNAL } from './internal.js';
 import { CELL_STYLE_FACETS, } from './style.js';
 export class Range {
     #sheet;
@@ -8,10 +10,10 @@ export class Range {
     bottom;
     right;
     constructor(sheet, top, left, bottom, right) {
-        checkBound('row', top, MAX_ROW);
-        checkBound('row', bottom, MAX_ROW);
-        checkBound('column', left, MAX_COLUMN);
-        checkBound('column', right, MAX_COLUMN);
+        assertAxisInBounds('row', top);
+        assertAxisInBounds('row', bottom);
+        assertAxisInBounds('column', left);
+        assertAxisInBounds('column', right);
         this.#sheet = sheet;
         this.top = Math.min(top, bottom);
         this.bottom = Math.max(top, bottom);
@@ -22,7 +24,7 @@ export class Range {
         return this.#sheet;
     }
     get address() {
-        return `${encodeAddress(this.left, this.top)}:${encodeAddress(this.right, this.bottom)}`;
+        return encodeRect(this);
     }
     get rowCount() {
         return this.bottom - this.top + 1;
@@ -45,12 +47,8 @@ export class Range {
     }
     get cells() {
         const cells = [];
-        for (let row = this.top; row <= this.bottom; row++) {
-            for (let col = this.left; col <= this.right; col++) {
-                if (this.#sheet.hasCell(row, col))
-                    cells.push(this.#sheet.getCell(encodeAddress(col, row)));
-            }
-        }
+        for (const cell of this.#storedCells())
+            cells.push(cell);
         return cells;
     }
     get style() {
@@ -64,7 +62,7 @@ export class Range {
             applyCellStyle(cell, style);
     }
     clearStyle() {
-        for (const cell of this.cells) {
+        for (const cell of this.#storedCells()) {
             for (const facet of CELL_STYLE_FACETS)
                 setFacet(cell, facet, undefined);
         }
@@ -105,28 +103,42 @@ export class Range {
     set protection(protection) {
         this.#writeFacet('protection', protection);
     }
-    #materialise() {
-        return [...this.addresses()].map((address) => this.#sheet.getCell(address));
+    *#materialise() {
+        const internals = this.#sheet[INTERNAL];
+        for (let row = this.top; row <= this.bottom; row++) {
+            for (let col = this.left; col <= this.right; col++) {
+                yield internals.masterAt(row, col);
+            }
+        }
     }
     #writeFacet(facet, value) {
-        const cells = value === undefined ? this.cells : this.#materialise();
+        const cells = value === undefined ? this.#storedCells() : this.#materialise();
         for (const cell of cells)
             setFacet(cell, facet, value);
     }
+    *#storedCells() {
+        const internals = this.#sheet[INTERNAL];
+        for (let row = this.top; row <= this.bottom; row++) {
+            for (let col = this.left; col <= this.right; col++) {
+                const cell = internals.peekCell(row, col);
+                if (cell !== undefined)
+                    yield cell;
+            }
+        }
+    }
     #collectShared(target, facet) {
         const shared = this.#sharedFacet(facet);
         if (shared !== undefined)
             target[facet] = shared;
     }
     #sharedFacet(facet) {
+        const internals = this.#sheet[INTERNAL];
         let first;
         let firstKey;
         let seen = 0;
         for (let row = this.top; row <= this.bottom; row++) {
             for (let col = this.left; col <= this.right; col++) {
-                const value = this.#sheet.hasCell(row, col)
-                    ? this.#sheet.getCell(encodeAddress(col, row))[facet]
-                    : undefined;
+                const value = internals.peekCell(row, col)?.[facet];
                 const key = facetKey(value);
                 if (seen === 0) {
                     first = value;
@@ -152,24 +164,16 @@ function facetKey(value) {
         ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : 1)))
         : inner);
 }
-function checkBound(axis, value, max) {
-    if (!Number.isInteger(value) || value < 1) {
-        throw new RangeError(`${axis} ${value} is out of bounds: ${axis}s start at 1`);
-    }
-    if (value > max) {
-        throw new RangeError(`${axis} ${value} is out of bounds: the sheet ends at ${max}`);
-    }
-}
 export function rangeFrom(sheet, reference) {
     const { top, left, bottom, right, sheetName, dimensions } = decodeRange(reference);
     if (sheetName !== undefined && sheetName.toLowerCase() !== sheet.name.toLowerCase()) {
-        throw new SyntaxError(`"${reference}" names worksheet "${sheetName}", not "${sheet.name}": a range belongs to the sheet it came from`);
+        throw new SyntaxError(`${quoted(reference)} names worksheet ${quoted(sheetName)}, not ${quoted(sheet.name)}: a range belongs to the sheet it came from`);
     }
     if (top === undefined || bottom === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole columns (${dimensions}): style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
+        throw new SyntaxError(`${quoted(reference)} spans whole columns (${dimensions}): style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
     }
     if (left === undefined || right === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole rows (${dimensions}): style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
+        throw new SyntaxError(`${quoted(reference)} spans whole rows (${dimensions}): style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
     }
     return new Range(sheet, top, left, bottom, right);
 }

package/dist/core/row-input.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { Cell } from './cell.js';
 export function positionalPlacements(values) {
     const placements = [];
@@ -27,5 +27,5 @@ function columnIndexByKey(columns, key) {
         if (properties.key === key)
             return index;
     }
-    throw new AuthoringError(`no column is keyed ${JSON.stringify(key)}: set getColumn(n).key first`);
+    throw new AuthoringError(`no column is keyed ${quoted(key)}: set getColumn(n).key first`);
 }

package/dist/core/row.d.ts

@@ -1,9 +1,10 @@
+import { AxisHandle } from './axis-handle.ts';
 import type { Cell } from './cell.ts';
 import { type AssertNever } from './internal.ts';
 import type { Fill } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { RowProperties, Worksheet } from './worksheet.ts';
-export declare class Row {
+export declare class Row extends AxisHandle<RowProperties> {
     #private;
     /** 1-based row number. Fixed for this handle's lifetime. */
     readonly number: number;
@@ -16,6 +17,9 @@ export declare class Row {
      * formatted, and they create the record on first write.
      */
     get properties(): Readonly<RowProperties> | undefined;
+    protected propertiesOf(): RowProperties | undefined;
+    protected ensureProperties(): RowProperties;
+    protected dropProperties(): void;
     /**
      * Row height in points; `undefined` leaves the sheet default in force.
      *

package/dist/core/row.js

@@ -1,45 +1,56 @@
 import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
+import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
-export class Row {
+export class Row extends AxisHandle {
     #sheet;
     number;
     constructor(sheet, number) {
+        super();
         assertRowInBounds(number);
         this.#sheet = sheet;
         this.number = number;
     }
     get properties() {
+        return this.propertiesOf();
+    }
+    propertiesOf() {
         return this.#sheet[INTERNAL].rowPropertiesOf(this.number);
     }
+    ensureProperties() {
+        return this.#sheet[INTERNAL].ensureRowProperties(this.number);
+    }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropRowProperties(this.number);
+    }
     get height() {
-        return this.#read('height');
+        return this.read('height');
     }
     set height(height) {
-        this.#write('height', height);
+        this.write('height', height);
     }
     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);
     }
     getCell(column) {
         const index = typeof column === 'number' ? column : columnToNumber(column);
@@ -60,16 +71,4 @@ export class Row {
                 this.getCell(index + 1).value = value;
         });
     }
-    #read(key) {
-        return this.#sheet[INTERNAL].rowPropertiesOf(this.number)?.[key];
-    }
-    #write(key, value) {
-        if (value === undefined) {
-            const properties = this.#sheet[INTERNAL].rowPropertiesOf(this.number);
-            if (properties !== undefined)
-                delete properties[key];
-            return;
-        }
-        this.#sheet[INTERNAL].ensureRowProperties(this.number)[key] = value;
-    }
 }