@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/types/index.d.ts

@@ -35,6 +35,7 @@ export type { NodeInput } from "./modules/excel/stream/workbook-reader.js";
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
 export type { CellAddress, SheetRange, Origin } from "./modules/excel/utils/address.js";
 export type { SheetToJSONOptions, AddJSONOptions, AddAOAOptions } from "./modules/excel/worksheet.js";
+export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 export { base64ToUint8Array, uint8ArrayToBase64 } from "./utils/utils.base.js";
 export { xmlEncode, xmlDecode } from "./modules/xml/encode.js";

package/dist/types/modules/excel/cell.d.ts

@@ -130,6 +130,24 @@ declare class Cell {
     get comment(): Note | undefined;
     set comment(comment: Note | NoteConfig | undefined);
     get text(): string;
+    /**
+     * The cell's display text — the value formatted the way Excel would render
+     * it, applying the cell's `numFmt`. For a Date cell with `numFmt` `"mm-dd-yy"`,
+     * this returns e.g. `"04-12-19"` rather than the JS `Date.prototype.toString()`
+     * output you'd get from `cell.text`.
+     *
+     * Handles primitive values, dates, and formula results. For rich text,
+     * hyperlinks, errors, and other complex types, falls back to `cell.text`.
+     *
+     * Note: numFmt codes that are locale-dependent in Excel (e.g. built-in
+     * numFmtId 14 renders as `dd.mm.yyyy` under German locale but is stored
+     * as `mm-dd-yy`) are applied literally — excelts does not perform
+     * Excel's locale-based format substitution. If you need a specific date
+     * style across cells regardless of per-cell numFmts, call the exported
+     * {@link getCellDisplayText} helper with a `dateFormat` argument, or use
+     * `worksheet.toJSON({ dateFormat })`.
+     */
+    get displayText(): string;
     get html(): string;
     toString(): string;
     get formula(): string | undefined;

package/dist/types/modules/excel/workbook.browser.d.ts

@@ -603,6 +603,63 @@ declare class Workbook {
      * ```
      */
     calculateFormulas(): void;
+    /**
+     * Per-workbook registry of user-defined functions. The formula engine
+     * consults this map before the built-in 433-function registry, so a
+     * registered name either adds a new function (`MYFN`) or shadows a
+     * built-in (`IRR` → project-specific variant).
+     *
+     * Populated by {@link registerFunction}; read by the formula engine
+     * when the host calls `calculateFormulas()` — see
+     * `@formula/runtime/evaluator.ts::evaluateCall`.
+     */
+    userFunctions?: Map<string, {
+        minArity: number;
+        maxArity: number;
+        invoke: (args: unknown[]) => unknown;
+        volatile?: boolean;
+    }>;
+    /**
+     * Register (or replace) a custom formula function on this workbook.
+     *
+     * The function becomes visible to `calculateFormulas()` on this
+     * workbook only — the built-in registry stays untouched. Names are
+     * case-insensitive (normalised to uppercase) and must not include
+     * the `_XLFN.` prefix — the engine strips that automatically.
+     *
+     * @param name    Function name (case-insensitive).
+     * @param fn      Implementation. Receives already-evaluated RuntimeValue
+     *                arguments; return a RuntimeValue. Wrap failures with
+     *                `rvError("#VALUE!")` rather than throwing — throws are
+     *                caught at the evaluator boundary and surface as
+     *                `#VALUE!` so a buggy custom function doesn't tear
+     *                down the whole calculation pass.
+     * @param options Optional arity bounds. Defaults to `minArity=0`,
+     *                `maxArity=255` (Excel's universal argument cap), so
+     *                simple variadic functions work without extra config.
+     *                Set `volatile: true` when the function should be
+     *                re-evaluated on every calc cycle (analogous to
+     *                built-in `RAND`, `NOW`). Currently reserved for
+     *                future use; the engine recomputes every formula on
+     *                each `calculateFormulas()` call regardless.
+     *
+     * ```ts
+     * import { rvNumber } from "@cj-tech-master/excelts/formula";
+     * workbook.registerFunction("DOUBLE", ([x]) => {
+     *   return rvNumber((x as any).value * 2);
+     * }, { minArity: 1, maxArity: 1 });
+     * ```
+     */
+    registerFunction(name: string, fn: (args: unknown[]) => unknown, options?: {
+        minArity?: number;
+        maxArity?: number;
+        volatile?: boolean;
+    }): void;
+    /**
+     * Remove a user-registered function. No-op when the name isn't
+     * registered; returns `true` when an entry was removed.
+     */
+    unregisterFunction(name: string): boolean;
     clearThemes(): void;
     /**
      * Add Image to Workbook and return the id

package/dist/types/modules/formula/compile/bound-ast.d.ts

@@ -46,7 +46,8 @@ export declare const enum BoundExprKind {
     Array = 12,
     NameExpr = 13,
     Lambda = 14,
-    StructuredRef = 15
+    StructuredRef = 15,
+    UnionRef = 16
 }
 /**
  * A resolved literal value.
@@ -220,7 +221,20 @@ export interface BoundStructuredRef {
     /** Special items (#Headers, #Data, #Totals, #All, #This Row). */
     readonly specials: readonly string[];
 }
-export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef;
+/**
+ * A union of reference-producing sub-expressions — `(A1:B2, D4:E5)`.
+ *
+ * Produced only by parenthesised comma lists, and only used by callers
+ * that explicitly know how to consume a multi-area reference (INDEX's
+ * `area_num`, AREAS, union-operator arithmetic). Evaluating a
+ * UnionRef in any other context surfaces as `#VALUE!` since Excel
+ * forbids arithmetic / coercion on disjoint areas.
+ */
+export interface BoundUnionRef {
+    readonly kind: BoundExprKind.UnionRef;
+    readonly areas: readonly BoundExpr[];
+}
+export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef | BoundUnionRef;
 export declare function boundLiteral(value: number | string | boolean | null, errorCode?: string): BoundLiteral;
 export declare function boundCellRef(sheet: string, row: number, col: number): BoundCellRef;
 export declare function boundAreaRef(sheet: string, top: number, left: number, bottom: number, right: number): BoundAreaRef;

package/dist/types/modules/formula/functions/_shared.d.ts

@@ -33,6 +33,25 @@ export declare function argToNumber(arg: RuntimeValue): NumberValue | ErrorValue
  * `number[]` after an error check should map `.value` themselves.
  */
 export declare function flattenNumbers(args: RuntimeValue[]): (NumberValue | ErrorValue)[];
+/**
+ * Streaming fold over numeric arguments.
+ *
+ * Same selection rules as `flattenNumbers` (array cells contribute only
+ * Number/Error; direct scalar coercion via `toNumberRV`; blanks dropped),
+ * but the caller's `onNumber` callback fires inline — no intermediate
+ * array is allocated. On the first error encountered the scan short-
+ * circuits and returns that error.
+ *
+ * Returns:
+ *   - `null` when iteration finished without encountering an error, or
+ *   - the `ErrorValue` that aborted the scan.
+ *
+ * Prefer this over `flattenNumbers` + `firstError` + manual loop in hot
+ * aggregates (SUM / AVERAGE / MIN / MAX / …). The allocation saved is
+ * one `NumberValue | ErrorValue` array per invocation — meaningful
+ * when the engine sums tens of thousands of cells.
+ */
+export declare function forEachNumber(args: readonly RuntimeValue[], onNumber: (n: number) => void): ErrorValue | null;
 /**
  * Flatten all cells from the arguments into a flat list of ScalarValue,
  * preserving every cell (including blanks, errors, booleans, strings).

package/dist/types/modules/formula/functions/engineering.d.ts

@@ -5,10 +5,10 @@ import type { RuntimeValue } from "../runtime/values.js";
 type NativeFn = (args: RuntimeValue[]) => RuntimeValue;
 export declare const fnBIN2DEC: NativeFn;
 export declare const fnDEC2BIN: NativeFn;
-export declare const fnHEX2DEC: NativeFn;
 export declare const fnDEC2HEX: NativeFn;
-export declare const fnOCT2DEC: NativeFn;
 export declare const fnDEC2OCT: NativeFn;
+export declare const fnHEX2DEC: NativeFn;
+export declare const fnOCT2DEC: NativeFn;
 export declare const fnBIN2HEX: NativeFn;
 export declare const fnBIN2OCT: NativeFn;
 export declare const fnHEX2BIN: NativeFn;

package/dist/types/modules/formula/functions/math.d.ts

@@ -42,7 +42,33 @@ export declare const fnPRODUCT: NativeFn;
 export declare const fnSUMPRODUCT: NativeFn;
 export declare const fnABS: NativeFn;
 export declare const fnCEILING: NativeFn;
+/**
+ * CEILING.MATH(number, [significance], [mode]) — rounds away from zero
+ * by default, or toward zero when `mode` is non-zero AND `number` is
+ * negative. Significance is always interpreted by absolute value.
+ *
+ * Different from CEILING: negative numbers with positive significance
+ * are valid (Excel does NOT require same sign), and there is an extra
+ * `mode` switch that flips the rounding direction for negatives.
+ */
+export declare const fnCEILING_MATH: NativeFn;
+/**
+ * CEILING.PRECISE / ISO.CEILING — always rounds toward +∞ (irrespective
+ * of sign), using the absolute value of significance.
+ */
+export declare const fnCEILING_PRECISE: NativeFn;
 export declare const fnFLOOR: NativeFn;
+/**
+ * FLOOR.MATH(number, [significance], [mode]) — rounds toward zero by
+ * default, or away from zero when `mode` is non-zero AND `number` is
+ * negative. Uses `|significance|` so negative significance never
+ * produces #NUM!.
+ */
+export declare const fnFLOOR_MATH: NativeFn;
+/**
+ * FLOOR.PRECISE — always rounds toward −∞ using `|significance|`.
+ */
+export declare const fnFLOOR_PRECISE: NativeFn;
 export declare const fnINT: NativeFn;
 export declare const fnMOD: NativeFn;
 export declare const fnPOWER: NativeFn;

package/dist/types/modules/formula/materialize/types.d.ts

@@ -159,6 +159,21 @@ export interface WorkbookLike {
     properties?: {
         date1904?: boolean;
     };
+    /**
+     * User-registered custom functions exposed to the formula engine.
+     * Keys are uppercase canonical names; values are arity + invoke
+     * descriptors. When the evaluator encounters a call it consults this
+     * map before the global built-in registry, so users can shadow a
+     * built-in (e.g. replace `IRR` with a domain-specific variant) or
+     * add entirely new names.
+     */
+    userFunctions?: ReadonlyMap<string, {
+        minArity: number;
+        maxArity: number;
+        invoke: (args: unknown[]) => unknown;
+        /** Reserved for future volatile-function wiring. */
+        volatile?: boolean;
+    }>;
 }
 /**
  * Tracks a spill region: the source formula cell and the range of cells it

package/dist/types/modules/formula/runtime/evaluator.d.ts

@@ -8,6 +8,7 @@
 import type { BoundExpr } from "../compile/bound-ast.js";
 import type { CompiledFormula } from "../compile/compiled-formula.js";
 import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { FunctionDescriptor } from "./function-registry.js";
 import type { RuntimeValue } from "./values.js";
 /**
  * Cached formula evaluation result with both scalar and raw forms.
@@ -114,6 +115,13 @@ export interface EvalContext {
     };
     /** Local variable bindings from LET expressions. */
     localBindings?: Map<string, RuntimeValue>;
+    /**
+     * User-registered functions that take precedence over the built-in
+     * registry. Lookup happens in `evaluateCall` — a matching
+     * descriptor here shadows any built-in of the same name. Keys are
+     * canonical uppercase names (prefix-stripped on register).
+     */
+    readonly userFunctions?: ReadonlyMap<string, FunctionDescriptor>;
 }
 /**
  * Evaluate a BoundExpr to produce a RuntimeValue.

package/dist/types/modules/formula/runtime/function-registry.d.ts

@@ -38,6 +38,11 @@ export declare function registerFunction(desc: FunctionDescriptor): void;
  * `_XLFN._XLWS.` prefixed variants by stripping the prefix before lookup
  * (a no-op for plain names, so plain lookups also go through a single
  * Map.get call — avoiding the double-lookup pattern used previously).
+ *
+ * Fast-path: the overwhelming majority of lookups use plain names
+ * (`SUM`, `IF`, `VLOOKUP`, …). Checking the prefix sentinel byte up
+ * front lets those callers skip the `slice`/`startsWith` machinery in
+ * `stripFunctionPrefix` entirely.
  */
 export declare function lookupFunction(name: string): FunctionDescriptor | undefined;
 /**

package/dist/types/modules/formula/runtime/values.d.ts

@@ -156,6 +156,19 @@ export declare function rvString(value: string): StringValue;
 export declare function rvBoolean(value: boolean): BooleanValue;
 export declare function rvError(code: ErrorCode): ErrorValue;
 export declare function rvArray(rows: ScalarValue[][], originRow?: number, originCol?: number, subtotalMask?: readonly (readonly boolean[])[], hiddenRowMask?: readonly boolean[]): ArrayValue;
+/**
+ * Fast-path rectangular ArrayValue constructor.
+ *
+ * Callers that have already produced strictly-rectangular `rows` (every
+ * row is the same length — the length they explicitly `new Array(width)`
+ * allocated) can skip the two-pass width-scan + padding loop in
+ * `rvArray`. Examples: `buildRangeArray`, `broadcastBinaryOp`,
+ * `evaluateArrayLiteral`, `TRANSPOSE` — they all know `width` up front.
+ *
+ * Rows MUST be rectangular; passing ragged data will silently surface as
+ * `undefined` cells downstream.
+ */
+export declare function rvArrayRect(rows: ScalarValue[][], height: number, width: number, originRow?: number, originCol?: number, subtotalMask?: readonly (readonly boolean[])[], hiddenRowMask?: readonly boolean[]): ArrayValue;
 export declare function rvRef(sheet: string, top: number, left: number, bottom: number, right: number): ReferenceValue;
 export declare function rvCellRef(sheet: string, row: number, col: number): ReferenceValue;
 export declare function rvLambda(params: string[], body: BoundExpr, closureBindings?: ReadonlyMap<string, RuntimeValue>): LambdaValue;

package/dist/types/modules/formula/syntax/ast.d.ts

@@ -20,7 +20,8 @@ export declare const enum NodeType {
     ColRangeRef = 13,
     RowRangeRef = 14,
     StructuredRef = 15,
-    Missing = 16
+    Missing = 16,
+    UnionRef = 17
 }
 export interface NumberNode {
     type: NodeType.Number;
@@ -126,4 +127,15 @@ export interface StructuredRefNode {
 export interface MissingNode {
     type: NodeType.Missing;
 }
-export type AstNode = NumberNode | StringNode | BooleanNode | ErrorNode | CellRefNode | RangeRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ArrayNode | PercentNode | NameNode | ColRangeRefNode | RowRangeRefNode | StructuredRefNode | MissingNode;
+/**
+ * A reference union produced by the comma operator inside
+ * parentheses — `(A1:B2, D4:E5)`. Each member is itself a
+ * reference-producing sub-expression. INDEX's `area_num` parameter
+ * selects which element of the union to read.
+ */
+export interface UnionRefNode {
+    type: NodeType.UnionRef;
+    /** The union members, in syntactic order. */
+    areas: AstNode[];
+}
+export type AstNode = NumberNode | StringNode | BooleanNode | ErrorNode | CellRefNode | RangeRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ArrayNode | PercentNode | NameNode | ColRangeRefNode | RowRangeRefNode | StructuredRefNode | MissingNode | UnionRefNode;

package/dist/types/modules/formula/syntax/token-types.d.ts

@@ -148,6 +148,10 @@ export interface IntersectToken {
  * The input may or may not already be uppercased — this helper does not
  * alter case; callers that compare against an uppercase table should
  * uppercase first (or compare case-insensitively).
+ *
+ * Fast path: plain names (99%+ of call sites) start with a letter, so
+ * checking the first code unit before the `startsWith` machinery lets
+ * those lookups skip the allocation.
  */
 export declare function stripFunctionPrefix(name: string): string;
 export type Token = NumberToken | StringToken | BooleanToken | ErrorToken | CellRefToken | RangeToken | SheetRefToken | FunctionToken | OperatorToken | OpenParenToken | CloseParenToken | CommaToken | ColonToken | PercentToken | OpenBraceToken | CloseBraceToken | SemicolonToken | UnaryPrefixToken | NameToken | ColRangeToken | RowRangeToken | StructuredRefToken | AtSignToken | IntersectToken;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "9.3.1",
+  "version": "9.4.0",
   "description": "Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.",
   "keywords": [
     "archive",