@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsb/ptg-functions.js

@@ -0,0 +1,659 @@
+// The `Ftab` built-in function table ([MS-XLS] 2.5.198.17, shared verbatim by BIFF12): the index a
+// `PtgFunc`/`PtgFuncVar` token carries, mapped to the function name that index means.
+//
+// A binary formula names no function — it cites one by number — so this table is the whole difference
+// between `SUM(A1:A5)` and an unreadable stream. It is transcribed from the normative table rather
+// than assembled from Excel's UI, which matters at both ends: the low indices include the XLM macro
+// functions (`GOTO`, `ADD.BAR`, …) that no modern sheet uses but a legacy file may still carry, and
+// the table simply stops at `RTD`. Everything Microsoft added after that — the whole modern library,
+// `TEXTJOIN` through `LAMBDA` — is *not* here and never will be: a post-2007 function is called
+// through index 255 ("user defined") with an `_xlfn.`-prefixed name as its first operand, which is
+// the same indirection the XML form spells out in the function name itself.
+//
+// The four gaps (0x00CA–CB, 0x00D9–DA, 0x00F9–FA, 0x014D) are gaps in the specification: those
+// indices name no function, so a formula citing one is not decodable rather than decodable as
+// something adjacent.
+/** The index [MS-XLS] reserves for a call whose name is given by the token stream's first operand. */
+export const FTAB_USER_DEFINED = 0x00ff;
+/** Look up a built-in function name by its `iftab` index, or `undefined` if the index names none. */
+export function functionNameFor(index) {
+    return FTAB[index];
+}
+/**
+ * How many arguments a fixed-arity function takes, or `undefined` for one whose argument count varies.
+ *
+ * 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.)
+ *
+ * Transcribed from the parameter grammar each function's [MS-XLS] 2.5.198.17 entry states.
+ */
+export function fixedArityFor(name) {
+    return FIXED_ARITY.get(name);
+}
+// Keyed by name rather than index: an arity belongs to the function, and a name is checkable at a
+// glance where a hex index is not.
+const FIXED_ARITY = new Map(Object.entries({
+    // "This function takes no parameters."
+    NA: 0,
+    PI: 0,
+    TRUE: 0,
+    FALSE: 0,
+    RAND: 0,
+    NOW: 0,
+    TODAY: 0,
+    STEP: 0,
+    CALLER: 0,
+    'ACTIVE.CELL': 0,
+    SELECTION: 0,
+    BREAK: 0,
+    NEXT: 0,
+    ELSE: 0,
+    'END.IF': 0,
+    'LAST.ERROR': 0,
+    GROUP: 0,
+    ABS: 1,
+    ACOS: 1,
+    ACOSH: 1,
+    AREAS: 1,
+    ASC: 1,
+    ASIN: 1,
+    ASINH: 1,
+    ATAN: 1,
+    ATANH: 1,
+    BAHTTEXT: 1,
+    CHAR: 1,
+    CLEAN: 1,
+    CODE: 1,
+    COLUMNS: 1,
+    COS: 1,
+    COSH: 1,
+    COUNTBLANK: 1,
+    DATESTRING: 1,
+    DATEVALUE: 1,
+    DAY: 1,
+    DBCS: 1,
+    'DELETE.BAR': 1,
+    'DELETE.TOOLBAR': 1,
+    DEGREES: 1,
+    DEREF: 1,
+    'DIALOG.BOX': 1,
+    'ELSE.IF': 1,
+    'ERROR.TYPE': 1,
+    EVALUATE: 1,
+    EVEN: 1,
+    EXP: 1,
+    FACT: 1,
+    FCLOSE: 1,
+    FISHER: 1,
+    FISHERINV: 1,
+    FREADLN: 1,
+    FSIZE: 1,
+    GAMMALN: 1,
+    'GET.FORMULA': 1,
+    'GET.WORKSPACE': 1,
+    GOTO: 1,
+    HOUR: 1,
+    INFO: 1,
+    INT: 1,
+    ISBLANK: 1,
+    ISERR: 1,
+    ISERROR: 1,
+    ISLOGICAL: 1,
+    ISNA: 1,
+    ISNONTEXT: 1,
+    ISNUMBER: 1,
+    ISREF: 1,
+    ISTEXT: 1,
+    ISTHAIDIGIT: 1,
+    LEN: 1,
+    LENB: 1,
+    LN: 1,
+    LOG10: 1,
+    LOWER: 1,
+    MDETERM: 1,
+    MINUTE: 1,
+    MINVERSE: 1,
+    MONTH: 1,
+    N: 1,
+    NORMSDIST: 1,
+    NORMSINV: 1,
+    NOT: 1,
+    ODD: 1,
+    'OPTIONS.LISTS.GET': 1,
+    PHONETIC: 1,
+    PROPER: 1,
+    RADIANS: 1,
+    'RESET.TOOLBAR': 1,
+    ROUNDBAHTDOWN: 1,
+    ROUNDBAHTUP: 1,
+    ROWS: 1,
+    SECOND: 1,
+    SIGN: 1,
+    SIN: 1,
+    SINH: 1,
+    SQRT: 1,
+    T: 1,
+    TAN: 1,
+    TANH: 1,
+    TERMINATE: 1,
+    THAIDAYOFWEEK: 1,
+    THAIDIGIT: 1,
+    THAIMONTHOFYEAR: 1,
+    THAINUMSOUND: 1,
+    THAINUMSTRING: 1,
+    THAISTRINGLENGTH: 1,
+    THAIYEAR: 1,
+    TIMEVALUE: 1,
+    TRANSPOSE: 1,
+    TRIM: 1,
+    TYPE: 1,
+    UNREGISTER: 1,
+    UPPER: 1,
+    VALUE: 1,
+    WHILE: 1,
+    YEAR: 1,
+    ABSREF: 2,
+    ATAN2: 2,
+    CEILING: 2,
+    CHIDIST: 2,
+    CHIINV: 2,
+    CHITEST: 2,
+    COMBIN: 2,
+    CORREL: 2,
+    COUNTIF: 2,
+    COVAR: 2,
+    EXACT: 2,
+    FLOOR: 2,
+    FREAD: 2,
+    FREQUENCY: 2,
+    FTEST: 2,
+    FWRITE: 2,
+    FWRITELN: 2,
+    INITIATE: 2,
+    INTERCEPT: 2,
+    LARGE: 2,
+    MMULT: 2,
+    MOD: 2,
+    NUMBERSTRING: 2,
+    PEARSON: 2,
+    PERCENTILE: 2,
+    PERMUT: 2,
+    POWER: 2,
+    QUARTILE: 2,
+    RELREF: 2,
+    REPT: 2,
+    REQUEST: 2,
+    ROUND: 2,
+    ROUNDDOWN: 2,
+    ROUNDUP: 2,
+    RSQ: 2,
+    'SET.VALUE': 2,
+    SLOPE: 2,
+    SMALL: 2,
+    STEYX: 2,
+    SUMX2MY2: 2,
+    SUMX2PY2: 2,
+    SUMXMY2: 2,
+    TEXT: 2,
+    TINV: 2,
+    TRIMMEAN: 2,
+    EXECUTE: 2,
+    CONFIDENCE: 3,
+    CRITBINOM: 3,
+    DATE: 3,
+    DATEDIF: 3,
+    DAVERAGE: 3,
+    DCOUNT: 3,
+    DCOUNTA: 3,
+    DGET: 3,
+    DMAX: 3,
+    DMIN: 3,
+    DPRODUCT: 3,
+    DSTDEV: 3,
+    DSTDEVP: 3,
+    DSUM: 3,
+    DVAR: 3,
+    DVARP: 3,
+    'ENABLE.TOOL': 3,
+    EXPONDIST: 3,
+    FDIST: 3,
+    FINV: 3,
+    FORECAST: 3,
+    GAMMAINV: 3,
+    LOGINV: 3,
+    LOGNORMDIST: 3,
+    MID: 3,
+    MIDB: 3,
+    MIRR: 3,
+    NEGBINOMDIST: 3,
+    NORMINV: 3,
+    POISSON: 3,
+    POKE: 3,
+    'PRESS.TOOL': 3,
+    SLN: 3,
+    STANDARDIZE: 3,
+    TDIST: 3,
+    TIME: 3,
+    BINOMDIST: 4,
+    GAMMADIST: 4,
+    HYPGEOMDIST: 4,
+    ISPMT: 4,
+    NORMDIST: 4,
+    REPLACE: 4,
+    REPLACEB: 4,
+    SYD: 4,
+    TTEST: 4,
+    WEIBULL: 4,
+}));
+// The table as contiguous runs, each `[first index, names in order]`. Written this way so the four
+// specification gaps are visible as run boundaries instead of hiding as miscounted array entries.
+const RUNS = [
+    [
+        0x0000,
+        [
+            'COUNT',
+            'IF',
+            'ISNA',
+            'ISERROR',
+            'SUM',
+            'AVERAGE',
+            'MIN',
+            'MAX',
+            'ROW',
+            'COLUMN',
+            'NA',
+            'NPV',
+            'STDEV',
+            'DOLLAR',
+            'FIXED',
+            'SIN',
+            'COS',
+            'TAN',
+            'ATAN',
+            'PI',
+            'SQRT',
+            'EXP',
+            'LN',
+            'LOG10',
+            'ABS',
+            'INT',
+            'SIGN',
+            'ROUND',
+            'LOOKUP',
+            'INDEX',
+            'REPT',
+            'MID',
+            'LEN',
+            'VALUE',
+            'TRUE',
+            'FALSE',
+            'AND',
+            'OR',
+            'NOT',
+            'MOD',
+            'DCOUNT',
+            'DSUM',
+            'DAVERAGE',
+            'DMIN',
+            'DMAX',
+            'DSTDEV',
+            'VAR',
+            'DVAR',
+            'TEXT',
+            'LINEST',
+            'TREND',
+            'LOGEST',
+            'GROWTH',
+            'GOTO',
+            'HALT',
+            'RETURN',
+            'PV',
+            'FV',
+            'NPER',
+            'PMT',
+            'RATE',
+            'MIRR',
+            'IRR',
+            'RAND',
+            'MATCH',
+            'DATE',
+            'TIME',
+            'DAY',
+            'MONTH',
+            'YEAR',
+            'WEEKDAY',
+            'HOUR',
+            'MINUTE',
+            'SECOND',
+            'NOW',
+            'AREAS',
+            'ROWS',
+            'COLUMNS',
+            'OFFSET',
+            'ABSREF',
+            'RELREF',
+            'ARGUMENT',
+            'SEARCH',
+            'TRANSPOSE',
+            'ERROR',
+            'STEP',
+            'TYPE',
+            'ECHO',
+            'SET.NAME',
+            'CALLER',
+            'DEREF',
+            'WINDOWS',
+            'SERIES',
+            'DOCUMENTS',
+            'ACTIVE.CELL',
+            'SELECTION',
+            'RESULT',
+            'ATAN2',
+            'ASIN',
+            'ACOS',
+            'CHOOSE',
+            'HLOOKUP',
+            'VLOOKUP',
+            'LINKS',
+            'INPUT',
+            'ISREF',
+            'GET.FORMULA',
+            'GET.NAME',
+            'SET.VALUE',
+            'LOG',
+            'EXEC',
+            'CHAR',
+            'LOWER',
+            'UPPER',
+            'PROPER',
+            'LEFT',
+            'RIGHT',
+            'EXACT',
+            'TRIM',
+            'REPLACE',
+            'SUBSTITUTE',
+            'CODE',
+            'NAMES',
+            'DIRECTORY',
+            'FIND',
+            'CELL',
+            'ISERR',
+            'ISTEXT',
+            'ISNUMBER',
+            'ISBLANK',
+            'T',
+            'N',
+            'FOPEN',
+            'FCLOSE',
+            'FSIZE',
+            'FREADLN',
+            'FREAD',
+            'FWRITELN',
+            'FWRITE',
+            'FPOS',
+            'DATEVALUE',
+            'TIMEVALUE',
+            'SLN',
+            'SYD',
+            'DDB',
+            'GET.DEF',
+            'REFTEXT',
+            'TEXTREF',
+            'INDIRECT',
+            'REGISTER',
+            'CALL',
+            'ADD.BAR',
+            'ADD.MENU',
+            'ADD.COMMAND',
+            'ENABLE.COMMAND',
+            'CHECK.COMMAND',
+            'RENAME.COMMAND',
+            'SHOW.BAR',
+            'DELETE.MENU',
+            'DELETE.COMMAND',
+            'GET.CHART.ITEM',
+            'DIALOG.BOX',
+            'CLEAN',
+            'MDETERM',
+            'MINVERSE',
+            'MMULT',
+            'FILES',
+            'IPMT',
+            'PPMT',
+            'COUNTA',
+            'CANCEL.KEY',
+            'FOR',
+            'WHILE',
+            'BREAK',
+            'NEXT',
+            'INITIATE',
+            'REQUEST',
+            'POKE',
+            'EXECUTE',
+            'TERMINATE',
+            'RESTART',
+            'HELP',
+            'GET.BAR',
+            'PRODUCT',
+            'FACT',
+            'GET.CELL',
+            'GET.WORKSPACE',
+            'GET.WINDOW',
+            'GET.DOCUMENT',
+            'DPRODUCT',
+            'ISNONTEXT',
+            'GET.NOTE',
+            'NOTE',
+            'STDEVP',
+            'VARP',
+            'DSTDEVP',
+            'DVARP',
+            'TRUNC',
+            'ISLOGICAL',
+            'DCOUNTA',
+            'DELETE.BAR',
+            'UNREGISTER',
+        ],
+    ],
+    [
+        0x00cc,
+        [
+            'USDOLLAR',
+            'FINDB',
+            'SEARCHB',
+            'REPLACEB',
+            'LEFTB',
+            'RIGHTB',
+            'MIDB',
+            'LENB',
+            'ROUNDUP',
+            'ROUNDDOWN',
+            'ASC',
+            'DBCS',
+            'RANK',
+        ],
+    ],
+    [
+        0x00db,
+        [
+            'ADDRESS',
+            'DAYS360',
+            'TODAY',
+            'VDB',
+            'ELSE',
+            'ELSE.IF',
+            'END.IF',
+            'FOR.CELL',
+            'MEDIAN',
+            'SUMPRODUCT',
+            'SINH',
+            'COSH',
+            'TANH',
+            'ASINH',
+            'ACOSH',
+            'ATANH',
+            'DGET',
+            'CREATE.OBJECT',
+            'VOLATILE',
+            'LAST.ERROR',
+            'CUSTOM.UNDO',
+            'CUSTOM.REPEAT',
+            'FORMULA.CONVERT',
+            'GET.LINK.INFO',
+            'TEXT.BOX',
+            'INFO',
+            'GROUP',
+            'GET.OBJECT',
+            'DB',
+            'PAUSE',
+        ],
+    ],
+    [
+        0x00fb,
+        [
+            'RESUME',
+            'FREQUENCY',
+            'ADD.TOOLBAR',
+            'DELETE.TOOLBAR',
+            'User Defined Function',
+            'RESET.TOOLBAR',
+            'EVALUATE',
+            'GET.TOOLBAR',
+            'GET.TOOL',
+            'SPELLING.CHECK',
+            'ERROR.TYPE',
+            'APP.TITLE',
+            'WINDOW.TITLE',
+            'SAVE.TOOLBAR',
+            'ENABLE.TOOL',
+            'PRESS.TOOL',
+            'REGISTER.ID',
+            'GET.WORKBOOK',
+            'AVEDEV',
+            'BETADIST',
+            'GAMMALN',
+            'BETAINV',
+            'BINOMDIST',
+            'CHIDIST',
+            'CHIINV',
+            'COMBIN',
+            'CONFIDENCE',
+            'CRITBINOM',
+            'EVEN',
+            'EXPONDIST',
+            'FDIST',
+            'FINV',
+            'FISHER',
+            'FISHERINV',
+            'FLOOR',
+            'GAMMADIST',
+            'GAMMAINV',
+            'CEILING',
+            'HYPGEOMDIST',
+            'LOGNORMDIST',
+            'LOGINV',
+            'NEGBINOMDIST',
+            'NORMDIST',
+            'NORMSDIST',
+            'NORMINV',
+            'NORMSINV',
+            'STANDARDIZE',
+            'ODD',
+            'PERMUT',
+            'POISSON',
+            'TDIST',
+            'WEIBULL',
+            'SUMXMY2',
+            'SUMX2MY2',
+            'SUMX2PY2',
+            'CHITEST',
+            'CORREL',
+            'COVAR',
+            'FORECAST',
+            'FTEST',
+            'INTERCEPT',
+            'PEARSON',
+            'RSQ',
+            'STEYX',
+            'SLOPE',
+            'TTEST',
+            'PROB',
+            'DEVSQ',
+            'GEOMEAN',
+            'HARMEAN',
+            'SUMSQ',
+            'KURT',
+            'SKEW',
+            'ZTEST',
+            'LARGE',
+            'SMALL',
+            'QUARTILE',
+            'PERCENTILE',
+            'PERCENTRANK',
+            'MODE',
+            'TRIMMEAN',
+            'TINV',
+        ],
+    ],
+    [
+        0x014e,
+        [
+            'MOVIE.COMMAND',
+            'GET.MOVIE',
+            'CONCATENATE',
+            'POWER',
+            'PIVOT.ADD.DATA',
+            'GET.PIVOT.TABLE',
+            'GET.PIVOT.FIELD',
+            'GET.PIVOT.ITEM',
+            'RADIANS',
+            'DEGREES',
+            'SUBTOTAL',
+            'SUMIF',
+            'COUNTIF',
+            'COUNTBLANK',
+            'SCENARIO.GET',
+            'OPTIONS.LISTS.GET',
+            'ISPMT',
+            'DATEDIF',
+            'DATESTRING',
+            'NUMBERSTRING',
+            'ROMAN',
+            'OPEN.DIALOG',
+            'SAVE.DIALOG',
+            'VIEW.GET',
+            'GETPIVOTDATA',
+            'HYPERLINK',
+            'PHONETIC',
+            'AVERAGEA',
+            'MAXA',
+            'MINA',
+            'STDEVPA',
+            'VARPA',
+            'STDEVA',
+            'VARA',
+            'BAHTTEXT',
+            'THAIDAYOFWEEK',
+            'THAIDIGIT',
+            'THAIMONTHOFYEAR',
+            'THAINUMSOUND',
+            'THAINUMSTRING',
+            'THAISTRINGLENGTH',
+            'ISTHAIDIGIT',
+            'ROUNDBAHTDOWN',
+            'ROUNDBAHTUP',
+            'THAIYEAR',
+            'RTD',
+        ],
+    ],
+];
+// Indexed by `iftab`; a hole is an index the specification does not define.
+const FTAB = RUNS.reduce((table, [start, names]) => {
+    names.forEach((name, offset) => {
+        table[start + offset] = name;
+    });
+    return table;
+}, []);

package/dist/io/xlsb/read-shared-strings.d.ts

@@ -0,0 +1,2 @@
+/** Parse `xl/sharedStrings.bin` into the pool, in index order. An absent part is an empty pool. */
+export declare function parseSharedStrings(part: Uint8Array | undefined): string[];

package/dist/io/xlsb/read-shared-strings.js

@@ -0,0 +1,22 @@
+// The BIFF12 shared-string table: `xl/sharedStrings.bin` in, the pool a `BrtCellIsst` cell indexes.
+//
+// The binary table is a flat run of `BrtSSTItem` records between a Begin/End pair, each holding one
+// `RichStr`. Only the text is taken: a pooled string's per-run formatting is not modelled in this cut,
+// so the runs are left unread rather than half-decoded (see `primitives.ts`). Reading stops at the
+// closing record, so trailing future-record blocks are never framed.
+import { RecordReader } from "./primitives.js";
+import { readRecords } from "./record-stream.js";
+import { BRT } from "./record-types.js";
+/** Parse `xl/sharedStrings.bin` into the pool, in index order. An absent part is an empty pool. */
+export function parseSharedStrings(part) {
+    if (part === undefined)
+        return [];
+    const strings = [];
+    for (const record of readRecords(part)) {
+        if (record.type === BRT.SSTItem)
+            strings.push(new RecordReader(record.data).richString());
+        else if (record.type === BRT.EndSst)
+            break;
+    }
+    return strings;
+}

package/dist/io/xlsb/read-styles.d.ts

@@ -0,0 +1,4 @@
+import { type StyleTable, type XfStyle } from '../style/xf-style.ts';
+/** Parse `xl/styles.bin` into the flat cell-format table a worksheet's style indices resolve against. */
+export declare function parseStyleTable(part: Uint8Array | undefined): StyleTable;
+export type { StyleTable, XfStyle };