@devmm/puredocs-excel-formula 1.1.1 → 1.1.3

package/dist/index.d.cts

@@ -295,6 +295,29 @@ declare namespace FormulaHelper {
     function compileCriteria(criteria: string): CompiledCriteria;
     /** Matches a criteria string (e.g. ">5", "=hello", "*partial*") against a value. */
     function matchesCriteria(value: FormulaValue, criteria: string): boolean;
+    /**
+     * True when a string is an Excel *pattern* rather than a literal — it contains
+     * a wildcard, or a `~` that may be escaping one.
+     *
+     * The tilde counts because `~*` is how Excel spells a literal asterisk: such a
+     * string has no wildcard left after unescaping, but it still has to go through
+     * {@link wildcardToRegex} for the escape to be honoured rather than matched.
+     *
+     * This is the one place that decides "is this a pattern?", shared by the
+     * criteria family (`COUNTIF`, `SUMIF`, …) and the lookup family (`MATCH`,
+     * `VLOOKUP`, `HLOOKUP`) so the two can never disagree about a given criterion.
+     */
+    function hasWildcardSyntax(pattern: string): boolean;
+    /**
+     * Compiles an Excel wildcard pattern into an anchored, case-insensitive RegExp:
+     * `*` is any run of characters, `?` is any one character, and `~` escapes the
+     * next character when that character is `*`, `?` or `~` — a `~` before anything
+     * else is a literal tilde, as in Excel.
+     *
+     * Built character by character rather than by chained `replace` calls, because
+     * a replace pass cannot tell an escaped `~*` from a wildcard.
+     */
+    function wildcardToRegex(pattern: string): RegExp;
 }
 
 /**
@@ -332,7 +355,14 @@ declare class RangeCache {
     get(sheet: string, r0: number, c0: number, r1: number, c1: number): FormulaValue | undefined;
     /** Memoises a rectangle's value. `cells` is its area, for the budget. */
     set(sheet: string, r0: number, c0: number, r1: number, c1: number, value: FormulaValue, cells: number): void;
-    /** Drops every cached rectangle containing the given cell. */
+    /**
+     * Drops every cached rectangle containing the given cell.
+     *
+     * The bucket sets are iterated in place. Removing an element of a `Set` while
+     * iterating it is defined behaviour — the iterator simply does not revisit it —
+     * and copying instead cost one array per write, which at one write per formula
+     * was a real share of a recalculation.
+     */
     invalidateCell(sheet: string, row: number, col: number): void;
     clear(): void;
 }
@@ -442,6 +472,8 @@ declare class FormulaContext {
      * cell. Requires the worksheet to expose getSpillRange; otherwise #REF!.
      */
     resolveSpillRange(anchorRef: string): FormulaValue;
+    /** {@link resolveSpillRange} for an anchor on another sheet ('S'!A1#). */
+    resolveSheetSpillRange(sheetName: string, anchorRef: string): FormulaValue;
     getRangeBounds(startRef: string, endRef: string): {
         startRow: number;
         startCol: number;

package/dist/index.d.ts

@@ -295,6 +295,29 @@ declare namespace FormulaHelper {
     function compileCriteria(criteria: string): CompiledCriteria;
     /** Matches a criteria string (e.g. ">5", "=hello", "*partial*") against a value. */
     function matchesCriteria(value: FormulaValue, criteria: string): boolean;
+    /**
+     * True when a string is an Excel *pattern* rather than a literal — it contains
+     * a wildcard, or a `~` that may be escaping one.
+     *
+     * The tilde counts because `~*` is how Excel spells a literal asterisk: such a
+     * string has no wildcard left after unescaping, but it still has to go through
+     * {@link wildcardToRegex} for the escape to be honoured rather than matched.
+     *
+     * This is the one place that decides "is this a pattern?", shared by the
+     * criteria family (`COUNTIF`, `SUMIF`, …) and the lookup family (`MATCH`,
+     * `VLOOKUP`, `HLOOKUP`) so the two can never disagree about a given criterion.
+     */
+    function hasWildcardSyntax(pattern: string): boolean;
+    /**
+     * Compiles an Excel wildcard pattern into an anchored, case-insensitive RegExp:
+     * `*` is any run of characters, `?` is any one character, and `~` escapes the
+     * next character when that character is `*`, `?` or `~` — a `~` before anything
+     * else is a literal tilde, as in Excel.
+     *
+     * Built character by character rather than by chained `replace` calls, because
+     * a replace pass cannot tell an escaped `~*` from a wildcard.
+     */
+    function wildcardToRegex(pattern: string): RegExp;
 }
 
 /**
@@ -332,7 +355,14 @@ declare class RangeCache {
     get(sheet: string, r0: number, c0: number, r1: number, c1: number): FormulaValue | undefined;
     /** Memoises a rectangle's value. `cells` is its area, for the budget. */
     set(sheet: string, r0: number, c0: number, r1: number, c1: number, value: FormulaValue, cells: number): void;
-    /** Drops every cached rectangle containing the given cell. */
+    /**
+     * Drops every cached rectangle containing the given cell.
+     *
+     * The bucket sets are iterated in place. Removing an element of a `Set` while
+     * iterating it is defined behaviour — the iterator simply does not revisit it —
+     * and copying instead cost one array per write, which at one write per formula
+     * was a real share of a recalculation.
+     */
     invalidateCell(sheet: string, row: number, col: number): void;
     clear(): void;
 }
@@ -442,6 +472,8 @@ declare class FormulaContext {
      * cell. Requires the worksheet to expose getSpillRange; otherwise #REF!.
      */
     resolveSpillRange(anchorRef: string): FormulaValue;
+    /** {@link resolveSpillRange} for an anchor on another sheet ('S'!A1#). */
+    resolveSheetSpillRange(sheetName: string, anchorRef: string): FormulaValue;
     getRangeBounds(startRef: string, endRef: string): {
         startRow: number;
         startCol: number;