@devmm/puredocs-excel-formula 1.0.8 → 1.1.0

package/dist/index.d.cts

@@ -202,6 +202,8 @@ interface FunctionDef {
     readonly maxArgs: number;
     readonly isVolatile: boolean;
     readonly handler: FormulaFunction;
+    /** Scalar function: an array argument maps it over the array. See {@link FunctionRegistry.registerElementwise}. */
+    readonly elementwise: boolean;
 }
 declare class FunctionRegistry {
     #private;
@@ -209,6 +211,23 @@ declare class FunctionRegistry {
     static get default(): FunctionRegistry;
     /** Registers a function. Name is normalised to UPPERCASE. */
     register(name: string, handler: FormulaFunction, minArgs?: number, maxArgs?: number, isVolatile?: boolean): void;
+    /**
+     * Registers a **scalar** function — one whose arguments are single values —
+     * and lifts it over arrays automatically.
+     *
+     * `LEFT(A2:A100, 3)` is not a special form in Excel: LEFT takes one string, and
+     * the grid maps it over the range, giving a 99-row array. Without that lifting
+     * the range collapses to one value, so the dynamic array built on top of it —
+     * `FILTER(IFERROR(LEFT(A2:A100,3),""), …)` — filters a 1×1 input and returns
+     * `#CALC!`. Lifting belongs here rather than in each handler: the ~40 scalar
+     * text/math/date functions then get it for free and cannot each get it subtly
+     * wrong.
+     *
+     * Only mark functions that are genuinely per-cell. Anything that *consumes* an
+     * array (SUM, COUNTIF, FILTER, SORT, the lazy branch functions) must keep
+     * `register`, or lifting would map it over the array it is meant to reduce.
+     */
+    registerElementwise(name: string, handler: FormulaFunction, minArgs?: number, maxArgs?: number): void;
     /** Executes a function by name with argument validation. */
     execute(name: string, args: FormulaNode[], ctx: FormulaContext): FormulaValue;
     /** Returns true if the named function is volatile (NOW, RAND, etc.). */

package/dist/index.d.ts

@@ -202,6 +202,8 @@ interface FunctionDef {
     readonly maxArgs: number;
     readonly isVolatile: boolean;
     readonly handler: FormulaFunction;
+    /** Scalar function: an array argument maps it over the array. See {@link FunctionRegistry.registerElementwise}. */
+    readonly elementwise: boolean;
 }
 declare class FunctionRegistry {
     #private;
@@ -209,6 +211,23 @@ declare class FunctionRegistry {
     static get default(): FunctionRegistry;
     /** Registers a function. Name is normalised to UPPERCASE. */
     register(name: string, handler: FormulaFunction, minArgs?: number, maxArgs?: number, isVolatile?: boolean): void;
+    /**
+     * Registers a **scalar** function — one whose arguments are single values —
+     * and lifts it over arrays automatically.
+     *
+     * `LEFT(A2:A100, 3)` is not a special form in Excel: LEFT takes one string, and
+     * the grid maps it over the range, giving a 99-row array. Without that lifting
+     * the range collapses to one value, so the dynamic array built on top of it —
+     * `FILTER(IFERROR(LEFT(A2:A100,3),""), …)` — filters a 1×1 input and returns
+     * `#CALC!`. Lifting belongs here rather than in each handler: the ~40 scalar
+     * text/math/date functions then get it for free and cannot each get it subtly
+     * wrong.
+     *
+     * Only mark functions that are genuinely per-cell. Anything that *consumes* an
+     * array (SUM, COUNTIF, FILTER, SORT, the lazy branch functions) must keep
+     * `register`, or lifting would map it over the array it is meant to reduce.
+     */
+    registerElementwise(name: string, handler: FormulaFunction, minArgs?: number, maxArgs?: number): void;
     /** Executes a function by name with argument validation. */
     execute(name: string, args: FormulaNode[], ctx: FormulaContext): FormulaValue;
     /** Returns true if the named function is volatile (NOW, RAND, etc.). */