@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/default-syntax-probe.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Formula-syntax probe slot.
+ *
+ * ## What this is
+ *
+ * `DefinedNames` (in the excel module) needs a way to tell whether a raw
+ * defined-name text like `OFFSET(Sheet1!$A$1,0,0,3,1)` is a parseable
+ * formula or opaque content to preserve verbatim. The only authoritative
+ * answer comes from the formula tokenizer + parser, which ship in the
+ * `@cj-tech-master/excelts/formula` subpath and are an opt-in
+ * dependency.
+ *
+ * This file is a tiny passive registration slot — a single `let` with
+ * a getter/setter pair — carrying **no** formula-engine code. Importing
+ * `DefinedNames` pulls in this slot (~0.5 KB minified) but never drags
+ * in the tokenizer, parser, or evaluator.
+ *
+ * ## Classification semantics
+ *
+ * - **No probe installed** (default): `DefinedNames` classifies any
+ *   non-range, non-wrapper text as **opaque**. The `rawText` is
+ *   preserved so XLSX round-trip bytes are stable; the entry simply
+ *   cannot be evaluated — which is correct, because no formula engine
+ *   is available anyway.
+ *
+ * - **Probe installed** (after `installFormulaEngine()`): `DefinedNames`
+ *   classifies strictly. Parseable text becomes `formula`, unparseable
+ *   text becomes `opaque`.
+ *
+ * ## Why the slot lives in the formula module
+ *
+ * Module dependency direction: `excel` may import from `formula`
+ * (layer 4 → layer 3), but `formula` must not import from `excel`. The
+ * probe slot is a *formula-module concept* (it wraps a formula
+ * tokenizer+parser) that excel consults; keeping it here preserves the
+ * one-way dependency.
+ *
+ * ## Construction-time injection is also supported
+ *
+ * `Workbook` and `DefinedNames` each accept an explicit
+ * `formulaSyntaxProbe` option. That is the preferred API for callers
+ * who want deterministic, per-instance behaviour (e.g. a test that
+ * needs a specific probe without touching process-global state). The
+ * default-probe slot here is the convenience layer for
+ * `installFormulaEngine()` — call it once at startup and every
+ * subsequent `new Workbook()` picks up strict classification
+ * automatically.
+ *
+ * ## Lookup timing
+ *
+ * `DefinedNames` reads the default probe lazily, at the moment `model`
+ * is assigned (i.e. during XLSX parsing). This means the common
+ * sequence
+ *
+ * ```ts
+ * const wb = new Workbook();
+ * installFormulaEngine();            // later
+ * await wb.xlsx.load(buffer);        // sees the installed probe
+ * ```
+ *
+ * works correctly — the probe installed before `load()` is the one
+ * used, regardless of when `Workbook` itself was constructed.
+ */
+export type SyntaxProbe = (text: string) => boolean;
+/**
+ * Install (or clear) the process-wide default syntax probe.
+ *
+ * Called from `installFormulaEngine()` in `./install`. Passing `null`
+ * uninstalls the probe — symmetric with the formula-engine registry and
+ * useful for tests that exercise the "no probe" classification path.
+ */
+export declare function setDefaultSyntaxProbe(probe: SyntaxProbe | null): void;
+/**
+ * Retrieve the currently-installed default probe, or `null` if none is
+ * installed. Consumers (chiefly `DefinedNames`) should treat `null` as
+ * a signal to use conservative (opaque) classification rather than
+ * guessing.
+ */
+export declare function getDefaultSyntaxProbe(): SyntaxProbe | null;

package/dist/browser/modules/formula/default-syntax-probe.js

@@ -0,0 +1,83 @@
+/**
+ * Formula-syntax probe slot.
+ *
+ * ## What this is
+ *
+ * `DefinedNames` (in the excel module) needs a way to tell whether a raw
+ * defined-name text like `OFFSET(Sheet1!$A$1,0,0,3,1)` is a parseable
+ * formula or opaque content to preserve verbatim. The only authoritative
+ * answer comes from the formula tokenizer + parser, which ship in the
+ * `@cj-tech-master/excelts/formula` subpath and are an opt-in
+ * dependency.
+ *
+ * This file is a tiny passive registration slot — a single `let` with
+ * a getter/setter pair — carrying **no** formula-engine code. Importing
+ * `DefinedNames` pulls in this slot (~0.5 KB minified) but never drags
+ * in the tokenizer, parser, or evaluator.
+ *
+ * ## Classification semantics
+ *
+ * - **No probe installed** (default): `DefinedNames` classifies any
+ *   non-range, non-wrapper text as **opaque**. The `rawText` is
+ *   preserved so XLSX round-trip bytes are stable; the entry simply
+ *   cannot be evaluated — which is correct, because no formula engine
+ *   is available anyway.
+ *
+ * - **Probe installed** (after `installFormulaEngine()`): `DefinedNames`
+ *   classifies strictly. Parseable text becomes `formula`, unparseable
+ *   text becomes `opaque`.
+ *
+ * ## Why the slot lives in the formula module
+ *
+ * Module dependency direction: `excel` may import from `formula`
+ * (layer 4 → layer 3), but `formula` must not import from `excel`. The
+ * probe slot is a *formula-module concept* (it wraps a formula
+ * tokenizer+parser) that excel consults; keeping it here preserves the
+ * one-way dependency.
+ *
+ * ## Construction-time injection is also supported
+ *
+ * `Workbook` and `DefinedNames` each accept an explicit
+ * `formulaSyntaxProbe` option. That is the preferred API for callers
+ * who want deterministic, per-instance behaviour (e.g. a test that
+ * needs a specific probe without touching process-global state). The
+ * default-probe slot here is the convenience layer for
+ * `installFormulaEngine()` — call it once at startup and every
+ * subsequent `new Workbook()` picks up strict classification
+ * automatically.
+ *
+ * ## Lookup timing
+ *
+ * `DefinedNames` reads the default probe lazily, at the moment `model`
+ * is assigned (i.e. during XLSX parsing). This means the common
+ * sequence
+ *
+ * ```ts
+ * const wb = new Workbook();
+ * installFormulaEngine();            // later
+ * await wb.xlsx.load(buffer);        // sees the installed probe
+ * ```
+ *
+ * works correctly — the probe installed before `load()` is the one
+ * used, regardless of when `Workbook` itself was constructed.
+ */
+let defaultProbe = null;
+/**
+ * Install (or clear) the process-wide default syntax probe.
+ *
+ * Called from `installFormulaEngine()` in `./install`. Passing `null`
+ * uninstalls the probe — symmetric with the formula-engine registry and
+ * useful for tests that exercise the "no probe" classification path.
+ */
+export function setDefaultSyntaxProbe(probe) {
+    defaultProbe = probe;
+}
+/**
+ * Retrieve the currently-installed default probe, or `null` if none is
+ * installed. Consumers (chiefly `DefinedNames`) should treat `null` as
+ * a signal to use conservative (opaque) classification rather than
+ * guessing.
+ */
+export function getDefaultSyntaxProbe() {
+    return defaultProbe;
+}

package/dist/browser/modules/formula/functions/_date-context.d.ts

@@ -0,0 +1,4 @@
+/** Set the workbook-wide `date1904` mode for the current calculation session. */
+export declare function setDate1904(v: boolean): void;
+/** Read the workbook-wide `date1904` mode. */
+export declare function isDate1904(): boolean;

package/dist/browser/modules/formula/functions/_date-context.js

@@ -0,0 +1,29 @@
+/**
+ * Date context shared between formula functions and the evaluator.
+ *
+ * Native function signatures (`NativeFn = (args: RuntimeValue[]) => RuntimeValue`)
+ * have no access to the evaluation context, so date/time functions cannot
+ * receive the workbook's `date1904` flag through a parameter. Rather than
+ * plumb a new argument through 200+ function signatures, we store the flag
+ * in a module-local variable. The evaluator sets it before evaluating any
+ * formula in a calculation session.
+ *
+ * ## Thread safety
+ *
+ * JavaScript runtimes are single-threaded and a single calculation session
+ * operates on exactly one workbook at a time, so a module-level variable is
+ * safe in practice. If the engine is ever extended to support concurrent
+ * calculations across different workbooks (e.g. via worker threads), each
+ * worker will have its own module instance and remain correctly isolated.
+ * Nested synchronous calls within the same session all share the same
+ * workbook, so the flag remains correct throughout.
+ */
+let currentDate1904 = false;
+/** Set the workbook-wide `date1904` mode for the current calculation session. */
+export function setDate1904(v) {
+    currentDate1904 = v;
+}
+/** Read the workbook-wide `date1904` mode. */
+export function isDate1904() {
+    return currentDate1904;
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Shared helpers for native function implementations.
+ *
+ * Centralizes small utilities that were previously duplicated across multiple
+ * function files (math, statistical, financial, text, date, engineering,
+ * conditional, dynamic-array, database, lookup). None of these change runtime
+ * semantics — they are the canonical extractions of the identical helpers that
+ * appeared in several modules.
+ */
+import type { RuntimeValue, ScalarValue, NumberValue, ErrorValue, ArrayValue } from "../runtime/values.js";
+/**
+ * Return the error value if `v` (as a scalar, extracted via `topLeft`) is an
+ * error; otherwise return `null`. Used by text / date / engineering functions
+ * for the standard "propagate first-arg error" pattern.
+ */
+export declare function checkError(v: RuntimeValue): ErrorValue | null;
+/**
+ * Coerce a single RuntimeValue argument to a number. Applies `topLeft` first
+ * so that a 1×1 (or arbitrary) array yields its top-left scalar before
+ * numeric coercion. Matches the semantics formerly found as `argToNumber` in
+ * `math.ts` and `numArg(args, idx)` in `statistical.ts`.
+ */
+export declare function argToNumber(arg: RuntimeValue): NumberValue | ErrorValue;
+/**
+ * Flatten a list of arguments into a sequence of numeric values (or errors).
+ *
+ * Array arguments contribute only their `Number` and `Error` cells — booleans,
+ * strings, and blanks inside arrays are skipped (Excel range semantics).
+ * Direct scalar arguments are coerced via `toNumberRV`, except for direct
+ * `Blank` scalars which are skipped (Excel aggregate semantics).
+ *
+ * Returns a list of `NumberValue | ErrorValue`. Callers that need raw
+ * `number[]` after an error check should map `.value` themselves.
+ */
+export declare function flattenNumbers(args: RuntimeValue[]): (NumberValue | ErrorValue)[];
+/**
+ * Flatten all cells from the arguments into a flat list of ScalarValue,
+ * preserving every cell (including blanks, errors, booleans, strings).
+ * Direct scalar arguments are projected via `topLeft`.
+ */
+export declare function flattenAll(args: RuntimeValue[]): ScalarValue[];
+/**
+ * Return the first `ErrorValue` in a list of `NumberValue | ErrorValue`,
+ * or `null` if none is present.
+ */
+export declare function firstError(values: readonly (NumberValue | ErrorValue)[]): ErrorValue | null;
+/**
+ * Narrow a RuntimeValue to an ArrayValue, returning `null` if it is not an
+ * array. Used by conditional / database / lookup / dynamic-array families.
+ */
+export declare function asArray(v: RuntimeValue): ArrayValue | null;
+/**
+ * Safe cell accessor for ArrayValue — returns `BLANK` for out-of-bounds (r, c).
+ */
+export declare function getCell(arr: ArrayValue, r: number, c: number): ScalarValue;
+/**
+ * Return `true` if `s` contains an unescaped `*` or `?`. Excel uses `~` as
+ * the escape character, so `~*` and `~?` are literals while `*` and `?` at
+ * any other position are wildcards. `~~` is an escaped tilde.
+ *
+ * Centralised here so every wildcard-consuming function (SEARCH, MATCH,
+ * XLOOKUP, SUMIF/COUNTIF/…) agrees on whether a criterion should trigger
+ * the wildcard code path.
+ */
+export declare function hasUnescapedWildcard(s: string): boolean;
+/**
+ * Convert an Excel wildcard pattern to a JavaScript regex source. Rules:
+ *   `*`     → `.*`
+ *   `?`     → `.`
+ *   `~*`    → literal `*`
+ *   `~?`    → literal `?`
+ *   `~~`    → literal `~`
+ *   `~x`    → literal `x` (any other character after `~` is treated literally,
+ *             matching Excel's tolerant behaviour)
+ *   everything else → regex-escaped literal
+ *
+ * Callers typically wrap the result in `^…$` and use the `i` flag for
+ * case-insensitive matching.
+ */
+export declare function excelWildcardToRegex(s: string): string;
+/**
+ * Strip `~` escape characters from an Excel criteria string so the remaining
+ * text can be used for a literal comparison. `~*` → `*`, `~?` → `?`,
+ * `~~` → `~`, etc. Only used when the caller has already determined that the
+ * pattern contains no unescaped wildcards.
+ */
+export declare function unescapeExcelWildcard(s: string): string;
+/**
+ * Replace every cell marked by the array's `subtotalMask` with BLANK so an
+ * outer SUBTOTAL/AGGREGATE call does not double-count the inner aggregate's
+ * result. Only ArrayValue args carrying a mask are rewritten; scalars and
+ * arrays without masks pass through unchanged.
+ *
+ * Excel behavior: SUBTOTAL and AGGREGATE deliberately skip any cell whose
+ * own formula is itself SUBTOTAL or AGGREGATE — this is how the classic
+ * "totals row inside a filtered range" case works without double-counting.
+ */
+export declare function stripSubtotalMaskedCells(args: RuntimeValue[]): RuntimeValue[];
+/**
+ * Replace every cell in a hidden row with BLANK so aggregate functions
+ * drop them during flattening. Callers: SUBTOTAL's 1xx-variant codes
+ * (101-111) and AGGREGATE with option 5 or 7.
+ *
+ * Only ArrayValue args carrying a hiddenRowMask are rewritten.
+ */
+export declare function stripHiddenRowCells(args: RuntimeValue[]): RuntimeValue[];
+/**
+ * Replace every error cell inside ArrayValue args with BLANK so
+ * aggregate functions simply skip them during flattening. Callers:
+ * AGGREGATE with option 2, 3, 6, or 7.
+ *
+ * Direct scalar error args are left alone — AGGREGATE's caller
+ * already passes them as scalars; our aggregators will surface them
+ * as-is, which matches Excel when a direct literal is an error.
+ *
+ * This is distinct from the standard error-propagation path: arrays
+ * that contain errors normally propagate those errors out of the
+ * aggregate. With option 2/3/6/7, errors inside the *arrays* are
+ * deliberately ignored.
+ */
+export declare function stripErrorCells(args: RuntimeValue[]): RuntimeValue[];