@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/style/cell-style-resolution.d.ts

@@ -0,0 +1,25 @@
+import type { XfStyle } from './xf-style.ts';
+/**
+ * The cell → row → column → xf 0 style resolution for one worksheet, fed in the order every reader
+ * already visits a sheet: column formats before any cell refers to them, a row before its own cells.
+ * Columns are 1-based, and a negative style index means "declares no format".
+ */
+export declare class CellStyleResolver {
+    #private;
+    /** Record the format a span of columns gives its cells. */
+    noteColumnSpan(first: number, last: number, styleIndex: number): void;
+    /**
+     * Open a row. Its format reaches its cells only when the row is marked `customFormat`; without that
+     * flag the format describes the row itself and is not inherited.
+     */
+    openRow(styleIndex: number, customFormat: boolean): void;
+    /** Close the row, so a cell outside one never inherits the last row's format. */
+    closeRow(): void;
+    /**
+     * The style a cell resolves to: its own, else its row's, else its column's, else xf 0. `undefined`
+     * only when the index it resolves to names no record in `xfStyles`, a damaged or truncated table.
+     */
+    styleFor(col: number, cellStyleIndex: number, xfStyles: ReadonlyArray<XfStyle>): XfStyle | undefined;
+    /** Whether the cell, its row or its column declares a format, rather than the cell falling to xf 0. */
+    declaresFormat(col: number, cellStyleIndex: number): boolean;
+}

package/dist/io/style/cell-style-resolution.js

@@ -0,0 +1,30 @@
+export class CellStyleResolver {
+    #columnStyle = new Map();
+    #rowStyle = -1;
+    noteColumnSpan(first, last, styleIndex) {
+        if (styleIndex < 0)
+            return;
+        for (let index = first; index <= last; index++)
+            this.#columnStyle.set(index, styleIndex);
+    }
+    openRow(styleIndex, customFormat) {
+        this.#rowStyle = customFormat ? styleIndex : -1;
+    }
+    closeRow() {
+        this.#rowStyle = -1;
+    }
+    styleFor(col, cellStyleIndex, xfStyles) {
+        const index = this.#indexFor(col, cellStyleIndex);
+        return xfStyles[index < 0 ? 0 : index];
+    }
+    declaresFormat(col, cellStyleIndex) {
+        return this.#indexFor(col, cellStyleIndex) >= 0;
+    }
+    #indexFor(col, cellStyleIndex) {
+        if (cellStyleIndex >= 0)
+            return cellStyleIndex;
+        if (this.#rowStyle >= 0)
+            return this.#rowStyle;
+        return this.#columnStyle.get(col) ?? -1;
+    }
+}

package/dist/io/style/xf-style.d.ts

@@ -1,5 +1,6 @@
 import { type Cell } from '../../core/cell.ts';
-import { type Border, type CellStyle, type Fill, type Font, type NamedCellStyle, type TableStyleTable } from '../../core/style.ts';
+import { type Border, type CellStyle, type Fill, type Font, type Protection } from '../../core/style.ts';
+import type { NamedCellStyle, TableStyleTable } from '../../core/workbook-styles.ts';
 /**
  * What an xf resolves to: the {@link CellStyle} facet tuple, plus the two flags an xf carries that
  * are not facets. Absent facets stay undefined, matching the contract that an unset facet is simply
@@ -74,6 +75,27 @@ export declare function numFmtCodeFor(id: number, custom: ReadonlyMap<number, st
  * from, and the two cannot drift on what "applying a style" means.
  */
 export declare function applyXfToCell(cell: Cell, style: XfStyle | undefined): void;
+/**
+ * A cell's protection facets from the two flags either serialisation states, keeping only what
+ * carries information.
+ *
+ * `locked` defaults to TRUE in OOXML, so an explicitly *unlocked* cell is the state worth recording
+ * and a locked one merely restates the default; `hidden` defaults to false, so only a set flag does.
+ * An xf that states neither yields no protection at all rather than an empty object, which is what
+ * keeps the two readings of one workbook identical.
+ *
+ * Here rather than once per codec because that is exactly what it was: `parseProtection` in the XML
+ * reader and `readProtection` in the binary one, two spellings of two default rules, agreeing by
+ * review. The inputs differ (an attribute is tri-state, a bit is not) and the rule does not, so the
+ * codecs keep the parsing and share the rule.
+ *
+ * @param locked the `locked` attribute's tri-state reading, or the bit's boolean; `undefined` where
+ *   the file states nothing.
+ */
+export declare function protectionFrom(flags: {
+    readonly locked?: boolean | undefined;
+    readonly hidden?: boolean | undefined;
+}): Protection | undefined;
 /**
  * A `<cellStyle>` / `BrtStyle` label: the name and builtinId that title one `cellStyleXfs` entry,
  * keyed to that entry's index.

package/dist/io/style/xf-style.js

@@ -69,6 +69,14 @@ export function applyXfToCell(cell, style) {
     if (style.xfId !== undefined)
         cell[NAMED_STYLE_ID] = style.xfId;
 }
+export function protectionFrom(flags) {
+    const out = {};
+    if (flags.locked === false)
+        out.locked = false;
+    if (flags.hidden === true)
+        out.hidden = true;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 export function resolveStyleTable(tables) {
     const { directXfs, namedXfs, labels, fonts } = tables;
     const cellXfs = directXfs.map((xf) => {

package/dist/io/xlsb/formula.d.ts

@@ -34,8 +34,8 @@ export interface FormulaAnchor {
  * @param rgce the token stream.
  * @param rgcb the trailing extra-data block: the array constants, and the cell ranges a precomputed
  *   range token refers to. Its entries are consumed in token order.
- * @returns the formula text, or `undefined` if the stream uses a token this reader does not decode.
- * @throws {XlsbParseError} if a token runs past the end of the stream (a malformed formula).
+ * @returns the formula text, or `undefined` if the stream uses a token this reader does not decode,
+ *   or runs off the end of its own record.
  */
 export declare function decodeFormula(rgce: Uint8Array, rgcb: Uint8Array, scope: FormulaScope): string | undefined;
 /**

package/dist/io/xlsb/formula.js

@@ -1,19 +1,35 @@
-import { MAX_COLUMN, numberToColumn } from '../../core/address.js';
-import { quoteSheetName } from '../../core/formula.js';
+import { MAX_COLUMN, MAX_COLUMN_INDEX, MAX_ROW_INDEX, numberToColumn } from '../../core/address.js';
+import { formulaNumberLiteral, quoteSheetName } from '../../core/formula.js';
+import { REF_ERROR } from '../../core/value.js';
+import { XlsbParseError } from './errors.js';
 import { errorCodeFor, RecordReader } from './primitives.js';
-import { FTAB_USER_DEFINED, fixedArityFor, functionNameFor } from './ptg-functions.js';
+import { builtinFunctionAt, FTAB_USER_DEFINED, functionNameFor } from './ptg-functions.js';
 export function decodeFormula(rgce, rgcb, scope) {
-    const tokens = new RecordReader(rgce);
-    const extra = new RecordReader(rgcb);
+    try {
+        return decodeTokens(rgce, rgcb, scope);
+    }
+    catch (error) {
+        if (error instanceof XlsbParseError)
+            return undefined;
+        throw error;
+    }
+}
+function decodeTokens(rgce, rgcb, scope) {
     const stack = [];
-    const push = (text) => {
-        if (text === undefined)
-            return false;
-        stack.push(text);
-        return true;
+    const decode = {
+        tokens: new RecordReader(rgce),
+        extra: new RecordReader(rgcb),
+        stack,
+        scope,
+        push: (text) => {
+            if (text === undefined || text.length > MAX_DECODED_FORMULA_LENGTH)
+                return false;
+            stack.push(text);
+            return true;
+        },
     };
-    while (!tokens.done) {
-        if (!step(tokens.u8(), tokens, extra, stack, scope, push))
+    while (!decode.tokens.done) {
+        if (!step(decode.tokens.u8(), decode))
             return undefined;
     }
     return stack.length === 1 ? stack[0] : undefined;
@@ -29,7 +45,8 @@ export function formulaAnchor(rgce, rgcb) {
         return undefined;
     return { row, column: extra.u32() };
 }
-function step(ptg, tokens, extra, stack, scope, push) {
+function step(ptg, decode) {
+    const { tokens, stack, push } = decode;
     const binary = BINARY_OPERATORS.get(ptg);
     if (binary !== undefined) {
         const right = stack.pop();
@@ -54,33 +71,33 @@ function step(ptg, tokens, extra, stack, scope, push) {
         case PTG.Str:
             return push(quoteString(tokens.shortString()));
         case PTG.Attr:
-            return attribute(tokens, stack, push);
+            return attribute(decode);
         case PTG.Err:
             return push(errorCodeFor(tokens.u8()));
         case PTG.Bool:
             return push(tokens.u8() !== 0 ? 'TRUE' : 'FALSE');
         case PTG.Int:
-            return push(String(tokens.u16()));
+            return push(numberLiteral(tokens.u16()));
         case PTG.Num:
-            return push(numberText(tokens.f64()));
+            return push(numberLiteral(tokens.f64()));
         default:
-            return ptg >= CLASSED_TOKEN_FLOOR
-                ? operand((ptg & CLASSED_TOKEN_MASK) | CLASSED_TOKEN_FLOOR, tokens, extra, stack, scope, push)
+            return ptg >= CLASSED_TOKEN_FLOOR && ptg <= CLASSED_TOKEN_CEILING
+                ? operand((ptg & CLASSED_TOKEN_MASK) | CLASSED_TOKEN_FLOOR, decode)
                 : false;
     }
 }
-function operand(base, tokens, extra, stack, scope, push) {
+function operand(base, decode) {
+    const { tokens, extra, stack, scope, push } = decode;
     switch (base) {
         case PTG.Array:
             tokens.skip(14);
             return push(arrayConstant(extra));
         case PTG.Func: {
-            const name = functionNameFor(tokens.u16());
-            const arity = name === undefined ? undefined : fixedArityFor(name);
-            return name !== undefined && arity !== undefined && push(call(name, arity, stack));
+            const fn = builtinFunctionAt(tokens.u16());
+            return fn !== undefined && fn[1] !== 'variadic' && push(call(fn[0], fn[1], stack));
         }
         case PTG.FuncVar:
-            return variadicCall(tokens, stack, push);
+            return variadicCall(decode);
         case PTG.Name: {
             return push(scope.names[tokens.u32() - 1]);
         }
@@ -100,16 +117,16 @@ function operand(base, tokens, extra, stack, scope, push) {
         }
         case PTG.RefErr:
             tokens.skip(6);
-            return push(REFERENCE_ERROR);
+            return push(REF_ERROR);
         case PTG.AreaErr:
             tokens.skip(12);
-            return push(REFERENCE_ERROR);
+            return push(REF_ERROR);
         case PTG.RefErr3d:
             tokens.skip(8);
-            return push(REFERENCE_ERROR);
+            return push(REF_ERROR);
         case PTG.AreaErr3d:
             tokens.skip(14);
-            return push(REFERENCE_ERROR);
+            return push(REF_ERROR);
         case PTG.MemArea:
             tokens.skip(6);
             return skipExtraRanges(extra);
@@ -117,7 +134,7 @@ function operand(base, tokens, extra, stack, scope, push) {
             return false;
     }
 }
-function attribute(tokens, stack, push) {
+function attribute({ tokens, stack, push }) {
     const flags = tokens.u8();
     const data = tokens.u16();
     if ((flags & ATTR_CHOOSE) !== 0) {
@@ -128,7 +145,7 @@ function attribute(tokens, stack, push) {
         return push(call('SUM', 1, stack));
     return true;
 }
-function variadicCall(tokens, stack, push) {
+function variadicCall({ tokens, stack, push }) {
     const count = tokens.u8() & FUNCVAR_PARAM_MASK;
     const index = tokens.u16() & FUNCVAR_INDEX_MASK;
     if (index !== FTAB_USER_DEFINED) {
@@ -167,7 +184,7 @@ function arrayConstant(extra) {
 function arrayElement(extra) {
     switch (extra.u8()) {
         case SER_NUM:
-            return numberText(extra.f64());
+            return numberLiteral(extra.f64());
         case SER_STR:
             return quoteString(extra.shortString());
         case SER_BOOL:
@@ -212,7 +229,7 @@ function rangeText(rowFirst, rowLast, packedFirst, packedLast) {
         const last = columnOnly(packedLast);
         return first === undefined || last === undefined ? undefined : `${first}:${last}`;
     }
-    if ((packedFirst & COLUMN_MASK) === 0 && (packedLast & COLUMN_MASK) === MAX_COLUMN - 1) {
+    if ((packedFirst & COLUMN_MASK) === 0 && (packedLast & COLUMN_MASK) === MAX_COLUMN_INDEX) {
         return rowFirst > MAX_ROW_INDEX || rowLast > MAX_ROW_INDEX
             ? undefined
             : `${rowOnly(rowFirst, packedFirst)}:${rowOnly(rowLast, packedLast)}`;
@@ -233,10 +250,9 @@ function rowOnly(row, packedColumn) {
 function quoteString(text) {
     return `"${text.replace(/"/g, '""')}"`;
 }
-function numberText(value) {
-    return String(value).toUpperCase();
+function numberLiteral(value) {
+    return Number.isFinite(value) ? formulaNumberLiteral(value) : undefined;
 }
-const REFERENCE_ERROR = '#REF!';
 const BINARY_OPERATORS = new Map([
     [0x03, '+'],
     [0x04, '-'],
@@ -283,7 +299,9 @@ const PTG = {
     AreaErr3d: 0x3d,
 };
 const CLASSED_TOKEN_FLOOR = 0x20;
+const CLASSED_TOKEN_CEILING = 0x7f;
 const CLASSED_TOKEN_MASK = 0x1f;
+const MAX_DECODED_FORMULA_LENGTH = 4 * 8_192;
 const ATTR_CHOOSE = 0x04;
 const ATTR_SUM = 0x10;
 const FUNCVAR_PARAM_MASK = 0x7f;
@@ -291,7 +309,6 @@ const FUNCVAR_INDEX_MASK = 0x7fff;
 const COLUMN_MASK = 0x3fff;
 const COLUMN_RELATIVE = 0x4000;
 const ROW_RELATIVE = 0x8000;
-const MAX_ROW_INDEX = 1048575;
 const SER_NUM = 0x00;
 const SER_STR = 0x01;
 const SER_BOOL = 0x02;

package/dist/io/xlsb/primitives.js

@@ -1,15 +1,18 @@
+import { decodeUtf16le } from '../../bytes.js';
 import { isErrorCode } from '../../core/value.js';
+import { hex } from '../../hex.js';
 import { XlsbParseError } from './errors.js';
-const CHARS_PER_BATCH = 4096;
 const NULL_STRING_LENGTH = 0xffffffff;
 const rkScratch = new DataView(new ArrayBuffer(8));
 export class RecordReader {
     #data;
-    #view;
+    #cachedView;
     #offset = 0;
     constructor(data) {
         this.#data = data;
-        this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    get #view() {
+        return (this.#cachedView ??= new DataView(this.#data.buffer, this.#data.byteOffset, this.#data.byteLength));
     }
     get remaining() {
         return this.#data.length - this.#offset;
@@ -89,16 +92,7 @@ export class RecordReader {
     }
     #characters(count) {
         const start = this.#take(count * 2);
-        let text = '';
-        let batch = [];
-        for (let index = 0; index < count; index++) {
-            batch.push(this.#view.getUint16(start + index * 2, true));
-            if (batch.length === CHARS_PER_BATCH) {
-                text += String.fromCharCode(...batch);
-                batch = [];
-            }
-        }
-        return batch.length > 0 ? text + String.fromCharCode(...batch) : text;
+        return decodeUtf16le(this.#data.subarray(start, start + count * 2));
     }
     #take(count) {
         if (count > this.remaining) {
@@ -144,5 +138,5 @@ function colorByType(type, index, alpha, red, green, blue) {
     }
 }
 function hexByte(value) {
-    return value.toString(16).toUpperCase().padStart(2, '0');
+    return hex(value, 2);
 }

package/dist/io/xlsb/ptg-functions.d.ts

@@ -1,16 +1,25 @@
 /** The index [MS-XLS] reserves for a call whose name is given by the token stream's first operand. */
 export declare const FTAB_USER_DEFINED = 255;
-/** Look up a built-in function name by its `iftab` index, or `undefined` if the index names none. */
-export declare function functionNameFor(index: number): string | undefined;
 /**
- * How many arguments a fixed-arity function takes, or `undefined` for one whose argument count varies.
+ * One built-in function: the name an `iftab` index means, and how many arguments it takes.
  *
- * A `PtgFunc` token states only *which* function is called, never with how many arguments: it is the
- * token Excel emits precisely because the count is implied by the function. So decoding `ROUND(A1,2)`
- * back from its two operands and one call token is impossible without this: the arity is the only
- * thing that says which operands on the stack belong to the call. (`PtgFuncVar` carries its own count
- * and needs none of this; the two token forms partition the table between them.)
+ * The arity is not decoration. A `PtgFunc` token states only *which* function is called, never with
+ * how many arguments: it is the token Excel emits precisely because the count is implied by the
+ * function. So decoding `ROUND(A1,2)` back from its two operands and one call token is impossible
+ * without it, and `'variadic'` says the call cannot be spelled with that token at all (`PtgFuncVar`
+ * carries its own count; the two token forms partition the table between them). Transcribed from the
+ * parameter grammar each function's [MS-XLS] 2.5.198.17 entry states.
  *
- * Transcribed from the parameter grammar each function's [MS-XLS] 2.5.198.17 entry states.
+ * It used to live in a second table keyed by name, which let an entry exist in one and not the other
+ * with nothing to say so. A function whose arity was never transcribed simply read as variadic, and a
+ * `PtgFunc` citing it then took the wrong run of operands off the stack and produced a different
+ * formula, silently. Recording it beside the name makes "no arity recorded" unrepresentable: the
+ * compiler asks for it once per entry, and `'variadic'` becomes a decision written down rather than
+ * an absence that looks like one.
  */
-export declare function fixedArityFor(name: string): number | undefined;
+export type FunctionEntry = readonly [name: string, arity: number | 'variadic'];
+/** The built-in function an `iftab` index names, or `undefined` if the index names none. */
+export declare function builtinFunctionAt(index: number): FunctionEntry | undefined;
+/** Look up a built-in function name by its `iftab` index, or `undefined` if the index names none. */
+export declare function functionNameFor(index: number): string | undefined;
+export declare const FTAB: readonly (FunctionEntry | undefined)[];