@devmm/puredocs-excel-formula 1.0.7 → 1.0.9

package/dist/index.d.cts

@@ -152,8 +152,11 @@ declare const enum TokenType {
     SpillReference = 24,
     Exclamation = 25,
     AtSign = 26,
-    ErrorLiteral = 27,
-    EOF = 28
+    LeftBrace = 27,
+    RightBrace = 28,
+    Semicolon = 29,
+    ErrorLiteral = 30,
+    EOF = 31
 }
 interface Token {
     readonly type: TokenType;
@@ -170,7 +173,8 @@ interface Token {
  *   - Error literals (#N/A, #REF!, #VALUE!, etc.)
  *   - Quoted sheet references ('My Sheet'!A1)
  *   - Unquoted sheet references (Sheet1!A1)
- *   - _xlfn. prefix stripping
+ *   - _xlfn. / _xlws. / _xlpm. prefix stripping
+ *   - Array constants ({1,2;3,4})
  *   - Cell references ($A$1, A1, AA123)
  *   - Named ranges
  *   - @ implicit intersection operator
@@ -198,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;
@@ -205,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

@@ -152,8 +152,11 @@ declare const enum TokenType {
     SpillReference = 24,
     Exclamation = 25,
     AtSign = 26,
-    ErrorLiteral = 27,
-    EOF = 28
+    LeftBrace = 27,
+    RightBrace = 28,
+    Semicolon = 29,
+    ErrorLiteral = 30,
+    EOF = 31
 }
 interface Token {
     readonly type: TokenType;
@@ -170,7 +173,8 @@ interface Token {
  *   - Error literals (#N/A, #REF!, #VALUE!, etc.)
  *   - Quoted sheet references ('My Sheet'!A1)
  *   - Unquoted sheet references (Sheet1!A1)
- *   - _xlfn. prefix stripping
+ *   - _xlfn. / _xlws. / _xlpm. prefix stripping
+ *   - Array constants ({1,2;3,4})
  *   - Cell references ($A$1, A1, AA123)
  *   - Named ranges
  *   - @ implicit intersection operator
@@ -198,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;
@@ -205,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.). */