@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/pivot-table.js

@@ -1,7 +1,9 @@
-import { AuthoringError, InternalError } from '../errors.js';
+import { AuthoringError, InternalError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { encodeAddress } from './address.js';
-import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
+import { encodeRect } from './address.js';
+import { spliceFormula } from './formula-references.js';
+import { INTERNAL } from './internal.js';
+import { isArrayFormulaValue, isErrorValue, isFormulaValue, isRichTextValue, isSharedFormulaValue, REF_ERROR, richTextToPlain, } from './value.js';
 const PIVOT_METRICS = {
     sum: true,
     count: true,
@@ -31,7 +33,7 @@ const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
     sourceSheetName;
-    sourceRef;
+    #sourceRef;
     cacheFields;
     records;
     rowFields;
@@ -40,7 +42,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;
@@ -49,52 +51,41 @@ 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 containsBlank = scalars.some((scalar) => scalar.kind === 'blank');
+            const scalars = columnScalars[fieldIndex] ?? missingColumn(fieldIndex);
+            const kinds = {
+                containsString: scalars.some((scalar) => scalar.kind === 'string'),
+                containsBlank: scalars.some((scalar) => scalar.kind === 'blank'),
+                numeric: numericSummary(scalars),
+            };
             if (axisFields.has(fieldIndex)) {
                 const items = [];
                 const catalogue = new Map();
@@ -106,19 +97,22 @@ export class PivotTable {
                     }
                 }
                 catalogues[fieldIndex] = catalogue;
-                return { name: field.name, sharedItems: items, numeric: null, containsBlank };
+                return { name: field.name, sharedItems: items, ...kinds };
             }
-            return { name: field.name, sharedItems: null, numeric: numericSummary(scalars), containsBlank };
+            return { name: field.name, sharedItems: null, ...kinds };
         });
+        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));
@@ -129,6 +123,14 @@ export class PivotTable {
         }
         this.records = records;
     }
+    get sourceRef() {
+        return this.#sourceRef;
+    }
+    [INTERNAL] = {
+        spliceSource: (edit) => {
+            this.#sourceRef = splicePivotSource(this.sourceSheetName, this.#sourceRef, edit);
+        },
+    };
     get valueFieldName() {
         const field = this.cacheFields[this.valueField];
         if (field === undefined) {
@@ -138,12 +140,64 @@ 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 = [];
+    const seen = new Map();
+    for (let col = 1; col <= columnCount; col++) {
+        const name = textOf(scalarOf(valueAt(1, col)));
+        if (name === '')
+            continue;
+        const clash = seen.get(name.toLowerCase());
+        if (clash !== undefined) {
+            throw new AuthoringError(`the pivot source header ${quoted(name)} repeats ${quoted(clash)}: pivot field names must ` +
+                'be unique, ignoring case');
+        }
+        seen.set(name.toLowerCase(), 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 key = name.toLowerCase();
+        const index = fields.findIndex((field) => field.name.toLowerCase() === key);
+        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;
+    const axisRoles = new Map();
+    const resolveAxis = (role, names) => names.map((name) => {
+        const index = resolve(role, name);
+        const earlier = axisRoles.get(index);
+        if (earlier === role) {
+            throw new AuthoringError(`pivot ${role} field ${quoted(name)} is named more than once`);
+        }
+        if (earlier !== undefined) {
+            throw new AuthoringError(`pivot field ${quoted(name)} is named as both a ${earlier} and a ${role} field: a field ` +
+                'sits on one axis');
+        }
+        axisRoles.set(index, role);
+        return index;
+    });
+    return {
+        rowFields: resolveAxis('row', options.rows),
+        columnFields: resolveAxis('column', options.columns),
+        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) {
@@ -161,10 +215,8 @@ function numericSummary(scalars) {
     let allInteger = true;
     let sawNumber = false;
     for (const scalar of scalars) {
-        if (scalar.kind === 'blank')
-            continue;
         if (scalar.kind !== 'number')
-            return null;
+            continue;
         sawNumber = true;
         if (scalar.value < min)
             min = scalar.value;
@@ -195,16 +247,16 @@ function scalarOf(value) {
         return { kind: 'string', value: value.toISOString() };
     if (isRichTextValue(value))
         return { kind: 'string', value: richTextToPlain(value) };
-    if (isHyperlinkValue(value)) {
-        return {
-            kind: 'string',
-            value: typeof value.text === 'string' ? value.text : richTextToPlain(value.text),
-        };
-    }
     if (isErrorValue(value))
         return { kind: 'string', value: value.error };
-    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isArrayFormulaValue(value)) {
         return value.result === undefined ? BLANK : scalarOf(value.result);
     }
     return BLANK;
 }
+export function splicePivotSource(sheet, ref, edit) {
+    if (sheet.toLowerCase() !== edit.sheet.toLowerCase())
+        return ref;
+    const moved = spliceFormula(ref, sheet, edit);
+    return moved === REF_ERROR ? ref : moved;
+}

package/dist/core/protection.d.ts

@@ -1,3 +1,4 @@
+import type { AssertNever } from './internal.ts';
 /**
  * Whether each protected-sheet operation stays available to a user. Every flag is an
  * *allow* flag: `true` keeps the operation permitted, `false` forbids it, and an absent
@@ -46,7 +47,20 @@ export interface SheetProtectionCredential {
 export interface SheetProtection {
     readonly flags: SheetProtectionFlags;
     readonly credential?: SheetProtectionCredential;
+    /**
+     * The legacy 16-bit password hash (`password="CC3D"`) a file protected the sheet with, kept verbatim
+     * so the sheet stays guarded after a save. Pre-2010 Excel, XlsxWriter, openpyxl and LibreOffice write
+     * it instead of the agile credential. It is never derived from a password: `protect` writes only the
+     * agile form, and this hash is weak enough that nobody should want it authored.
+     */
+    readonly legacyPasswordHash?: string;
 }
+/**
+ * Whether a string is a legacy sheet password hash as its schema type (`ST_UnsignedShortHex`) spells
+ * one: exactly four hexadecimal digits. The reader keeps only such a value and the writer refuses
+ * anything else, since the hash is interpolated into an attribute.
+ */
+export declare function isLegacyPasswordHash(value: string): boolean;
 /**
  * The OOXML encoding table for the protection flags: each `<sheetProtection>` attribute paired
  * with whether that operation is *forbidden by default* once a sheet is protected. Both directions
@@ -55,10 +69,58 @@ export interface SheetProtection {
  * and deserialization can never fall out of step. Most editing operations default to forbidden
  * under protection; selecting cells and the object/scenario operations default to permitted.
  */
-export declare const SHEET_PROTECTION_FLAGS: readonly {
-    readonly key: keyof SheetProtectionFlags;
-    readonly defaultForbidden: boolean;
-}[];
+export declare const SHEET_PROTECTION_FLAGS: readonly [{
+    readonly key: 'formatCells';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'formatColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'formatRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertHyperlinks';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'deleteColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'deleteRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'sort';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'autoFilter';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'pivotTables';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'objects';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'scenarios';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'selectLockedCells';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'selectUnlockedCells';
+    readonly defaultForbidden: false;
+}];
+/**
+ * Compile-time proof that {@link SHEET_PROTECTION_FLAGS} covers every {@link SheetProtectionFlags}
+ * operation. The table's doc says the writer and reader can never fall out of step; that holds only
+ * while every flag is in it, and a flag added to the interface alone would be neither written nor read.
+ */
+export type EverySheetProtectionFlagIsDeclared = AssertNever<Exclude<keyof SheetProtectionFlags, (typeof SHEET_PROTECTION_FLAGS)[number]['key']>>;
 /**
  * Derive a fresh {@link SheetProtectionCredential} for a password. Each call generates a new
  * random salt, so protecting two sheets with the same password yields different credentials:

package/dist/core/protection.js

@@ -1,5 +1,9 @@
-import { concat, toBase64 } from '../bytes.js';
+import { concat, toBase64, utf16leBytes } from '../bytes.js';
 import { sha512 } from '../sha512.js';
+const LEGACY_PASSWORD_HASH = /^[0-9A-Fa-f]{4}$/;
+export function isLegacyPasswordHash(value) {
+    return LEGACY_PASSWORD_HASH.test(value);
+}
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
     { key: 'formatColumns', defaultForbidden: true },
@@ -22,7 +26,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 +41,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

@@ -19,6 +19,7 @@ export declare class Row extends AxisHandle<RowProperties> {
     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,4 +1,4 @@
-import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, columnToNumber } from './address.js';
 import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
 export class Row extends AxisHandle {
@@ -19,6 +19,9 @@ export class Row extends AxisHandle {
     ensureProperties() {
         return this.#sheet[INTERNAL].ensureRowProperties(this.number);
     }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropRowProperties(this.number);
+    }
     get height() {
         return this.read('height');
     }
@@ -51,7 +54,8 @@ export class Row extends AxisHandle {
     }
     getCell(column) {
         const index = typeof column === 'number' ? column : columnToNumber(column);
-        return this.#sheet.getCell(encodeAddress(index, this.number));
+        assertColumnInBounds(index);
+        return this.#sheet[INTERNAL].masterAt(this.number, index);
     }
     get cells() {
         return this.#sheet[INTERNAL].rowCells(this.number);

package/dist/core/structured-reference.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A structured reference to one column of a table, spelled as Excel spells it: `Table[Column]` for a
+ * plain name, and `Table[[Column]]` for a name holding a character from Microsoft's special list, with
+ * `[`, `]`, `#`, `'` and `@` escaped by a leading `'`. Interpolating the name bare wrote
+ * `SUBTOTAL(109,T[Price [USD]])`, a formula whose brackets close in the middle of the name.
+ */
+export declare function structuredColumnReference(tableName: string, columnName: string): string;

package/dist/core/structured-reference.js

@@ -0,0 +1,7 @@
+const STRUCTURED_REFERENCE_SPECIAL = /[\t\n\r,:.[\]#'"{}$^&*+=></@\\!()%?`;~_-]/;
+const STRUCTURED_REFERENCE_ESCAPED = /[[\]#'@]/g;
+export function structuredColumnReference(tableName, columnName) {
+    if (!STRUCTURED_REFERENCE_SPECIAL.test(columnName))
+        return `${tableName}[${columnName}]`;
+    return `${tableName}[[${columnName.replace(STRUCTURED_REFERENCE_ESCAPED, "'$&")}]]`;
+}