@sheetxl/primitives 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/Lazy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Declares a parameter the engine may hand over UNEVALUATED — the argument's subtree is not run
+ * before the call, and it runs only if this call's answer needs it.
+ *
+ * @remarks
+ * An argument that is a bare reference has always been cheap to ignore: it resolves into a
+ * register and a body that never reads it never dereferences it. An argument that is an
+ * EXPRESSION is not — `IF(FALSE,B1+1,1)` evaluates `B1+1` before `IF` runs, so the untaken branch
+ * opens `B1` anyway. That is a correctness difference and not a cost one: a read is what decides
+ * a circular reference and what registers a volatile, so an arm nobody takes can report a cycle
+ * the sheet does not have.
+ *
+ * The marker is what closes it, and it is a CONTRACT rather than an inference. Nothing in
+ * JavaScript intercepts a plain parameter read, so a body holding a deferred value is only safe
+ * while it never touches it — which the declaration has to say out loud:
+ *
+ * ```ts
+ * export function IF(
+ *   logicalTest: boolean,
+ *   valueIfTrue: Lazy<AcceptError<any>>,
+ *   valueIfFalse: Lazy<AcceptError<any>, false>
+ * ): any {
+ *   return logicalTest ? valueIfTrue : valueIfFalse;
+ * }
+ * ```
+ *
+ * The parameter is ALWAYS an {@link ILazy} handle and never a union with the bare value, so the
+ * body has two things it may do with it and the type says which is which:
+ *
+ * - **return it unread**, which is what every branch-selecting function does. The engine
+ *   recognizes its own handle coming back as the call's result and evaluates that subtree then.
+ * - **read it** with {@link ILazy.getValue}, which forces the subtree in place. Synchronous only:
+ *   the engine is mid-formula there and has no way to wait, so an ASYNC subtree at a forced
+ *   handle is an error rather than a wrong answer.
+ *
+ * Only the RESULT positions are marked. A condition, an index and a case value are eager, which
+ * is what keeps `AND(FALSE,A1)` a circular reference: laziness is a property of what the function
+ * READS, not of the syntax around it.
+ *
+ * The engine may DECLINE to defer at any time and hand the body a handle that is already full —
+ * an absent argument, an async subtree, a lift that needs every arm anyway. `getValue()` then
+ * returns the value it was built with. The author cannot tell the two apart and must not try.
+ *
+ * @typeParam T - what the argument evaluates to; the marker is otherwise transparent.
+ * @typeParam V - what an ABSENT argument means, as a literal. It replaces the `= false`
+ *   initializer an ordinary parameter would carry, which cannot typecheck against a handle;
+ *   declaring it makes the parameter optional and the engine supplies the value, so the body
+ *   still sees nothing but a handle.
+ *
+ * @see {@link IFunction.ParameterTypeJSON.lazy}
+ */
+export type Lazy<T, V = never> = ILazy<T | V>;
+/**
+ * The handle a {@link Lazy} parameter receives: an argument's subtree, anchored at the calling
+ * cell, that has either not been evaluated yet or has been evaluated already.
+ *
+ * @remarks
+ * The brand exists for the same reason {@link Lambda}'s does — the value-layer sites (coercion,
+ * the operators, a range's typed read, a cell's final value) RECOGNIZE a handle and refuse it, so
+ * that one can never reach a grid, a spill or a named-formula result. A handle is only ever a
+ * live call's argument.
+ */
+export interface ILazy<T = any> {
+    /** The brand itself — the property every recognizing site reads. */
+    readonly isLazy: true;
+    /**
+     * Evaluates the argument and answers its value, forcing the subtree where the engine deferred
+     * it and answering the value it already has where it declined to.
+     *
+     * Forced at most once: a second call answers the same value.
+     */
+    getValue(): T;
+}
+/** `true` for a deferred-argument handle — see {@link ILazy}. */
+export declare const isLazyValue: (value: unknown) => value is ILazy;
+//# sourceMappingURL=Lazy.d.ts.map

package/types/src/NoFilter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declares that the members reaching a REPEATING scalar parameter are COERCED rather than
+ * filtered — one that cannot be coerced is `#VALUE!` for the whole call.
+ *
+ * The native functions FILTER: `SUM({1,"8",TRUE})` is 1, the text and the boolean skipped, and a
+ * blank cell contributes nothing. Excel's Analysis-ToolPak heritage coerces at the slot instead,
+ * and the difference is visible in both directions:
+ *
+ * | argument | native (`SUM`) | this marker (`GCD`) |
+ * | --- | --- | --- |
+ * | numeric text, `{6,"8",12}` | skipped | parses — `GCD({6,"8",12})` is 2 |
+ * | a boolean, `{6,TRUE,12}` | skipped | `#VALUE!` for the whole call |
+ * | a blank inside a multi-cell range | skipped | reads 0 — `LCM(6,A1:A2)` is 0 |
+ *
+ * A DIRECT argument follows the same rule (`GCD(6,TRUE,12)` is `#VALUE!` where `SUM(6,TRUE,12)`
+ * is 19). A one-cell blank reference and an omitted argument are still skipped either way: they
+ * never became members.
+ *
+ * Only a repeating slot has members to filter, so the marker means nothing on a plain scalar,
+ * range or lambda parameter and the linter refuses it there. It is the repeating counterpart of
+ * {@link NoLift}, which is the same heritage's reading of a NON-repeating scalar slot.
+ *
+ * It may be written over the group or on the slot — `NoFilter<number[]>` and `NoFilter<number>[]`
+ * mean the same thing, as they do for `AcceptError`.
+ *
+ * At the type level it is `T`.
+ *
+ * @example
+ * ```ts
+ * export function GCD(number: NoFilter<number>[]): number { ... }
+ * ```
+ */
+export type NoFilter<T> = T;
+//# sourceMappingURL=NoFilter.d.ts.map

package/types/src/NoLift.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Declares that a SCALAR parameter refuses a multi-cell REFERENCE with `#VALUE!` instead of
+ * broadcasting over it.
+ *
+ * The native functions lift: `ROUND(B1:B3,3)` spills three results. Excel's Analysis-ToolPak
+ * heritage refuses at the slot instead — `EDATE(A1:A3,1)` is `#VALUE!` — and the refusal is per
+ * PARAMETER: `NETWORKDAYS.INTL` refuses a reference at its two date slots and lifts one at its
+ * `weekend` slot. Three qualifications:
+ *
+ * | argument at the slot | answer |
+ * | --- | --- |
+ * | a multi-cell REFERENCE, `A1:A3` | `#VALUE!` — the call never runs |
+ * | an ARRAY, `{3,4,5}` | lifts as usual (`MROUND({3,4,5},5)` spills) |
+ * | a one-cell reference or a value | an ordinary argument |
+ *
+ * Only a scalar slot can lift, so the marker means nothing on a range, list or lambda parameter
+ * and the linter refuses it there. A REPEATING scalar slot is also never this marker's business —
+ * it absorbs a container as members whatever the function's heritage (`GCD(C1:C3)` is 4); its
+ * ATP reading is `NoFilter<T>`.
+ *
+ * At the type level it is `T`.
+ *
+ * @example
+ * ```ts
+ * export function NETWORKDAYS_INTL(
+ *   startDate: NoLift<Scalar>, endDate: NoLift<Scalar>, weekend?: Scalar, holidays?: Flatten<Scalar>
+ * ): number { ... }
+ * ```
+ */
+export type NoLift<T> = T;
+//# sourceMappingURL=NoLift.d.ts.map

package/types/src/Repeating.d.ts

@@ -48,19 +48,39 @@
  * "the final element of the final group may be omitted" rule; that rule would accept a formula
  * Excel refuses. An optional slot anywhere else in the group is a compiler error.
  *
+ * ### The maximum, `Max`
+ *
+ * The second type argument is the largest number of arguments the WHOLE CALL accepts, which is
+ * how Excel states it: one number per NAME, compared against the call's total argument count and
+ * refused at entry (`Excess_function_arguments`), never a count of this parameter's own share.
+ * `SWITCH`'s 254 therefore covers its `expression` and its trailing `default` as well as the
+ * pairs, and `CHOOSEROWS`' covers its `array`.
+ *
+ * It defaults to **255**, which is the ceiling for most names and the highest any name carries.
+ * Declare it only where a name draws the line lower — `XOR`, `IFS`, `SWITCH`, `LAMBDA`, `LET`,
+ * `AGGREGATE`, `SORTBY`, `MAXIFS`, `MINIFS`, `CONCAT`, `TEXTJOIN`, `HSTACK`, `VSTACK`,
+ * `CHOOSEROWS`, `CHOOSECOLS` and every DOTTED
+ * descriptive spelling (`STDEV.S`, `VAR.P`, `MODE.MULT`, …) all stop at 254 where their legacy
+ * twins take 255. It cannot be derived from the shape, so it belongs to the declaration.
+ *
+ * A REST parameter is the one place `Repeating` may be written alongside `...`, and only with an
+ * explicit `Max`: `...rest: Repeating<T, 254>` keeps the rest parameter's own 0-or-more meaning
+ * and adds nothing but the ceiling. A bare `Repeating<T>` on a rest parameter stays an error —
+ * that is the spelling collision the marker exists to avoid.
+ *
  * @example
  * ```ts
  * export function SUMIFS(
- *   sumRange: AcceptError<IRange>,
- *   criteria: Repeating<[criteriaRange: AcceptError<IReferenceRange>, criteria: AcceptError<IRange>]>
+ *   sumRange: IRange,
+ *   criteria: Repeating<[criteriaRange: IReferenceRange, criteria: AcceptError<Scalar>]>
  * ): IRange {
  *   for (const [range, test] of criteria) { ... }
  * }
  *
- * export function HSTACK(array: Repeating<AcceptError<IRange>>): IRange {
+ * export function HSTACK(array: Repeating<IRange, 254>): IRange {
  *   return array.reduce((acc, next) => acc.concat(next, IRange.Axis.Column));
  * }
  * ```
  */
-export type Repeating<T> = T[];
+export type Repeating<T, Max extends number = 255> = T[];
 //# sourceMappingURL=Repeating.d.ts.map

package/types/src/ReportType.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Declares the parameter's type as ADVISORY: the engine delivers it when it can, and hands the
+ * body whatever actually arrived when it cannot, instead of answering `#VALUE!` on the body's
+ * behalf.
+ *
+ * @remarks
+ * Excel has no marshalling contract. A function there is called with the operands as they are and
+ * calls library helpers for whatever it needs — `LARGE` asks for a range's values and gets every
+ * area of a union, `ROWS` never dereferences at all and answers `#REF!` when it sees two areas,
+ * `SUMPRODUCT` demands one rectangle and fails on the same argument. Three answers, no rule: the
+ * body's own access pattern is the whole of it.
+ *
+ * A declared surface cannot express that, and modelling it would mean a marker per behavior. This
+ * is the boundary instead — ONE marker saying "the type is what the caller is told, not a
+ * guarantee to the body". The declared `T` still reaches the function help, the wizard and the
+ * linter, because that IS what the slot means to a user; it just stops being a gate.
+ *
+ * | argument | plain `IRange` | `ReportType<IRange>` |
+ * | --- | --- | --- |
+ * | `A1:A5` | the range | the range |
+ * | `(A1:A5,B1:B2)` — a union | `#VALUE!`, the call never runs | the areas, as `IRange[]` |
+ * | a value, an error | `#VALUE!` / propagates | the value, the error |
+ *
+ * At the type level it is `T` — like {@link AcceptError}, and for the same reason: the marker is a
+ * RULE, not a type. A body that declares it and then assumes `T` will crash on the argument the
+ * marker exists to deliver, so narrow first. {@link IFunctionArguments.getKindAt} is total over
+ * what can arrive and {@link IFunctionArguments.getAreaCountAt} answers the union question the
+ * kind cannot — a plain reference is one area, a union is more.
+ *
+ * Its use is meant to stay countable: a slot earns it with a rule Excel actually shows, never
+ * with a guess.
+ *
+ * @example
+ * ```ts
+ * export function ROWS(array: ReportType<IRange>): Scalar {
+ *   if (FormulaContext.getArgs().getAreaCountAt(0) > 1) return FormulaError.BuiltIn.Ref!;
+ *   return array.getRowCount();
+ * }
+ * ```
+ */
+export type ReportType<T> = T;
+//# sourceMappingURL=ReportType.d.ts.map

package/types/src/Scalar.d.ts

@@ -42,7 +42,7 @@ export declare namespace Scalar {
      * text's shape (decimal places, grouping) survives for format inference.
      *
      * @remarks
-     * Callers apply this to every text→number path and to nothing else — measured
+     * Callers apply this to every text→number path and to nothing else. It is
      * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
      */
     function truncateNumberText(text: string): string;

package/types/src/ValueKind.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The KIND of one value — the total discriminator over {@link IFunctionArguments.RawArg}, and the
+ * vocabulary a RETURN declaration speaks ({@link IFunction.IReturnType.getKind}).
+ *
+ * @remarks
+ * A value's kind and its extent are different axes: `{10}`, `A1` and a bare `10` all reach a
+ * range-typed parameter as a 1x1 container, yet Excel separates them:
+ * `VLOOKUP(10,10,1,TRUE)` is `#N/A` while `VLOOKUP(10,{10},1,TRUE)` is 10, and `TYPE` answers
+ * 1 vs 64. The kind is what the CALLER supplied; the extent is merely its size.
+ *
+ * The scalar kinds ARE {@link ScalarType} values — one vocabulary, so
+ * `getKindAt(i) === ScalarType.Boolean` reads naturally — extended with the four kinds only an
+ * argument can be: a reference, a non-reference array, a callable, and no argument at all. As an
+ * argument kind, {@link ScalarType.Null} means a BLANK value.
+ *
+ * The names and values are ours. The numeric codes Excel's `TYPE` function answers are a
+ * PROJECTION of this kind (see `TYPE`'s implementation), not the kind itself.
+ *
+ * @see {@link IFunctionArguments.getKindAt}
+ */
+export declare const ValueKind: {
+    /** A reference — `A1`, `A1:B3`, or a reference-returning call (`INDEX`, `OFFSET`, `TAKE`). */
+    readonly Reference: "reference";
+    /** An ARRAY that is not a reference — `{1,2}`, or a computed one (`SEQUENCE`, `TRANSPOSE(…)`). */
+    readonly Array: "array";
+    /** A callable — `LAMBDA(…)`, an eta-reduced function name, or a lambda-valued binding. */
+    readonly Lambda: "lambda";
+    /**
+     * OMITTED — nothing at this position: the empty comma of `CUMIPMT(,120,…)`, or a position
+     * past what the caller wrote. A blank CELL is a `Reference` (blankness is the cell's value).
+     * ABSENT-vs-omitted — whether the position exists in the call at all — is not a kind; it is
+     * `index >= getLength()`.
+     */
+    readonly Omitted: "omitted";
+    readonly Number: "number";
+    readonly String: "string";
+    readonly Boolean: "boolean";
+    readonly Error: "error";
+    readonly RichData: "richData";
+    readonly Null: "null";
+};
+export type ValueKind = typeof ValueKind[keyof typeof ValueKind];
+//# sourceMappingURL=ValueKind.d.ts.map

package/types/src/Volatile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Declares that a function's RESULT can change with nothing dirty, so a cell naming it
+ * recalculates on every pass.
+ *
+ * ```ts
+ * export function NOW(): Volatile<number> { ... }
+ * ```
+ *
+ * @see {@link IFunction.ReturnTypeJSON.volatile}
+ */
+export type Volatile<T> = T;
+//# sourceMappingURL=Volatile.d.ts.map

package/types/src/WildCard.d.ts

@@ -10,17 +10,21 @@ export declare const WildCard: {
     /**
      * Compiles Excel wildcard text into a regex.
      *
-     * @param anchor Whether the pattern must match the WHOLE string. Excel matches a whole cell, so
-     * every lookup and criteria caller anchors; `SEARCH`, which looks for a substring, does not.
+     * @param anchor Where the pattern has to line up: `true` for the WHOLE string, `'start'` for a
+     * PREFIX, `false` for anywhere in it. Excel matches a whole cell, so every lookup and criteria
+     * caller anchors; `SEARCH`, which looks for a substring, does not; and a `D` function's criteria
+     * table is the prefix form — `DSUM` with the criterion `appl` takes the row whose value is
+     * `Apple`, where `COUNTIF` with the same criterion takes none.
      *
      * @remarks
-     * `~` escapes the next `*`, `?` or `~`; standing alone it is a literal tilde (`COUNTIF(range,
-     * "a~b")` finds the text `a~b`). One left-to-right pass, because chained replaces cannot express
-     * this: the previous implementation guarded its `*`/`?` rewrites with `([^~]??)`, a lazy OPTIONAL
-     * group that matches empty and so guards nothing, and then unescaped `~([?*])` — which could
-     * never fire, the `*` and `?` having already become `.*` and `.`. Every escape was silently
-     * ignored, so `"~*"` compiled to `~.*`: a literal tilde followed by anything.
+     * `~` escapes the next `*`, `?` or `~`; before anything else it is dropped, not kept —
+     * `SEARCH("~b","abc")` is 2 and `MATCH("a~b",…)` finds the text `ab`. A caller that reaches this
+     * compiler only when the pattern holds a `*` or `?` — which is what COUNTIF and its family do —
+     * therefore still compares `"a~b"` literally, because that criteria never becomes a pattern.
+     *
+     * One left-to-right pass; chained replaces cannot express the escape, since by the time a pass
+     * could unescape `~*` the `*` has already become `.*`.
      */
-    toRegex: (lookupText: string, flags?: any, anchor?: boolean) => RegExp;
+    toRegex: (lookupText: string, flags?: any, anchor?: boolean | "start") => RegExp;
 };
 //# sourceMappingURL=WildCard.d.ts.map

package/types/src/index.d.ts

@@ -1,12 +1,17 @@
 export * from './Scalar';
 export * from './ScalarType';
+export * from './ValueKind';
 export * from './WildCard';
 export * from './Lambda';
 export * from './ErrorPolicy';
 export * from './Repeating';
 export * from './Flatten';
+export * from './NoLift';
+export * from './NoFilter';
+export * from './ReportType';
 export * from './Omittable';
-export * from './Compat';
+export * from './Lazy';
+export * from './Volatile';
 export * from './IRange';
 export * from './IReferenceRange';
 export * from './IRichData';

package/browser/cjs/index.cjs

@@ -1 +0,0 @@
-var e;Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),function(e){e.MAX_TEXT_LENGTH=32767;let t=e.MAX_SIGNIFICANT_DIGITS=15;e.truncateNumberText=function(e){let n=e.length;if(n<=t)return e;let r=0,i=null;for(let a=0;a<n;a++){let n=e.charCodeAt(a);if(n>=48&&n<=57){if(r===0&&n===48)continue;r++,r>t&&((i??=e.split(``))[a]=`0`)}else if((n===69||n===101)&&r>0)break}return i===null?e:i.join(``)}}(e||={});var t,n,r,i,a={Number:`number`,String:`string`,Boolean:`boolean`,Error:`error`,RichData:`richData`,Null:`null`},o={...a,Date:`date`},s=/[.*+?^${}()|[\]\\]/,c=e=>s.test(e)?`\\`+e:e,l={isWildCard:e=>typeof e==`string`&&/[*?]/.test(e),toRegex:(e,t,n=!1)=>{let r=``,i=e.length;for(let t=0;t<i;t++){let n=e[t];if(n===`~`){let n=e[t+1];n===`*`||n===`?`||n===`~`?(r+=c(n),t++):r+=`~`;continue}n===`*`?r+=`.*`:r+=n===`?`?`.`:c(n)}return RegExp(n?`^${r}$`:r,t)}},u={noReferenceLift:`A multi-cell reference at a non-repeating scalar parameter is #VALUE! rather than a broadcast.`,noMemberFilter:`Members of a repeating scalar parameter are coerced rather than filtered; one that cannot be is #VALUE!.`},d={atp:[`noReferenceLift`,`noMemberFilter`]};function f(e){if(!e)return null;let t=e.trim().toLowerCase();for(let e of Object.keys(u))if(e.toLowerCase()===t)return e;return null}(n=t||={}).Axis={Column:`column`,Row:`row`},n.AxisSelection={...t.Axis,Both:`both`},n.Direction={Up:`up`,Down:`down`,Left:`left`,Right:`right`},(r||={}).Aggregate={Count:`count`,NumericalCount:`numericalCount`,Sum:`sum`,Average:`average`,StdDev:`stdDev`,PopulationStdDev:`stdDevP`,Variance:`var`,PopulationVariance:`varP`,Min:`min`,Max:`max`},function(e){let t=e.Code={Parse:0,Null:1,Div0:2,Value:3,Ref:4,Name:5,Num:6,NA:7,GettingData:8,Spill:9,Connect:10,Blocked:11,Unknown:12,Field:13,Calc:14,Busy:16,Python:19,Timeout:20},n=e.Label={Parse:`#PARSE!`,Null:`#NULL!`,Div0:`#DIV/0!`,Value:`#VALUE!`,Ref:`#REF!`,Name:`#NAME?`,Num:`#NUM!`,NA:`#N/A`,GettingData:`#GETTING_DATA`,Spill:`#SPILL!`,Connect:`#CONNECT!`,Blocked:`#BLOCKED!`,Unknown:`#UNKNOWN!`,Field:`#FIELD!`,Calc:`#CALC!`,Busy:`#BUSY!`,Python:`#PYTHON!`,Timeout:`#TIMEOUT!`};class r extends Error{constructor(e,t,n,r){super(n,r),this._label=t,this._code=e,this.details=r}static{this.code=i.Code.Unknown}get isFormulaError(){return!0}getLabel(){return this._label}getCode(){return this._code}equals(e){return!!e&&(this._code===e._code||this._code===e.code)}get[Symbol.toStringTag](){return`[FormulaError]`}toString(){return this._label}}e.Known=r;class a extends r{constructor(e,r){super(t.Parse,n.Parse,e,r)}static{this.code=i.Code.Parse}getDetails(){let e=this.details;return{line:e?.line??1,column:e?.column??1,offset:e?.offset??0,length:e?.length??0}}}e.Parse=a;class o extends r{constructor(e,r){super(t.Null,n.Null,e,r)}static{this.code=i.Code.Null}}e.Null=o;class s extends r{constructor(e,r){super(t.Div0,n.Div0,e,r)}static{this.code=i.Code.Div0}}e.Div0=s;class c extends r{constructor(e,r){super(t.Value,n.Value,e,r)}static{this.code=i.Code.Value}}e.Value=c;class l extends r{constructor(e,r){super(t.Ref,n.Ref,e,r)}static{this.code=i.Code.Ref}}e.Ref=l;class u extends r{constructor(e,r){super(t.Name,n.Name,e,r)}static{this.code=i.Code.Name}}e.Name=u;class d extends r{constructor(e,r){super(t.Num,n.Num,e,r)}static{this.code=i.Code.Num}}e.Num=d;class f extends r{constructor(e,r){super(t.NA,n.NA,e,r)}static{this.code=i.Code.NA}}e.NA=f;class p extends r{constructor(e,r){super(t.GettingData,n.GettingData,e,r)}static{this.code=i.Code.GettingData}}e.GettingData=p;class m extends r{constructor(e,r){super(t.Spill,n.Spill,e,r)}static{this.code=i.Code.Spill}}e.Spill=m;class h extends r{constructor(e,r){super(t.Connect,n.Connect,e,r)}static{this.code=i.Code.Connect}}e.Connect=h;class g extends r{constructor(e,r){super(t.Blocked,n.Blocked,e,r)}static{this.code=i.Code.Blocked}}e.Blocked=g;class _ extends r{constructor(e,r){super(t.Unknown,n.Unknown,e,r)}static{this.code=i.Code.Unknown}}e.Unknown=_;class v extends r{constructor(e,r){super(t.Field,n.Field,e,r)}static{this.code=i.Code.Field}}e.Field=v;class y extends r{constructor(e,r){super(t.Calc,n.Calc,e,r)}static{this.code=i.Code.Calc}}e.Calc=y;class b extends r{constructor(e,r){super(t.Busy,n.Busy,e,r)}static{this.code=i.Code.Busy}}e.Busy=b;class x extends r{constructor(e,r){super(t.Python,n.Python,e,r)}static{this.code=i.Code.Python}}e.Python=x;class S extends r{constructor(e,r){super(t.Timeout,n.Timeout,e,r)}static{this.code=i.Code.Timeout}}e.Timeout=S}(i||={});var p={};p[i.Code.Parse]=i.Parse,p[i.Code.Null]=i.Null,p[i.Code.Div0]=i.Div0,p[i.Code.Value]=i.Value,p[i.Code.Ref]=i.Ref,p[i.Code.Name]=i.Name,p[i.Code.Num]=i.Num,p[i.Code.NA]=i.NA,p[i.Code.GettingData]=i.GettingData,p[i.Code.Spill]=i.Spill,p[i.Code.Connect]=i.Connect,p[i.Code.Blocked]=i.Blocked,p[i.Code.Unknown]=i.Unknown,p[i.Code.Field]=i.Field,p[i.Code.Calc]=i.Calc,p[i.Code.Busy]=i.Busy,p[i.Code.Python]=i.Python,p[i.Code.Timeout]=i.Timeout;var m=new Map,h=new Map,g=new Map,_=new Map,v=Object.keys(p);for(let e=0;e<v.length;e++){let t=p[v[e]],n=new t;g.set(n.getLabel(),t),_.set(n.getCode(),t),m.set(n.getLabel(),n),h.set(n.getCode(),n)}(function(e){let t=e.getBuiltInByCode=e=>h.get(e);e.BuiltIn={Parse:t(i.Code.Parse),Null:t(i.Code.Null),Div0:t(i.Code.Div0),Value:t(i.Code.Value),Ref:t(i.Code.Ref),Name:t(i.Code.Name),Num:t(i.Code.Num),NA:t(i.Code.NA),GettingData:t(i.Code.GettingData),Spill:t(i.Code.Spill),Connect:t(i.Code.Connect),Blocked:t(i.Code.Blocked),Unknown:t(i.Code.Unknown),Field:t(i.Code.Field),Calc:t(i.Code.Calc),Busy:t(i.Code.Busy),Python:t(i.Code.Python),Timeout:t(i.Code.Timeout)},e.newTypedError=(e,t,n)=>{let r;return r=typeof e==`string`?g.get(e):_.get(e),r||=i.Unknown,new r(t,n)},e.getBuiltInByLabel=e=>m.get(e),e.isError=function(e,t){return!!e&&!0===e.isFormulaError&&(t===void 0||e.getCode()===t)}})(i||={});var y=class{createRange(e,t,n){throw new S}getReference(e,t){throw new S}getResizedReference(e,t,n){throw new S}getNumberFormat(e,t){throw new S}fromSerialDate(e,t){throw new S}toSerialDate(e,t){throw new S}getDateParts(e,t){throw new S}getSerialDate(e,t,n,r,i,a,o){throw new S}getNow(){throw new S}getValueAt(e,t,n,r){return null}getEntireCoords(){return C}isValidDate(e,t){return e instanceof Date||Object.prototype.toString.call(e)===`[object Date]`?!isNaN(e.getTime()):!t&&typeof e==`number`&&!(e<0||e>T)}getRow(){return 0}getColumn(){return 0}getFormulaAt(e,t,n){return null}getSpillAt(e,t,n){return null}getSheetIndex(e){return-1}getSheetCount(){return 1}markVolatile(){}formatResults(e){}filterHidden(e,t){return e}filterTotals(e){return e}getFunction(e){return null}getAddress(e,t){throw new S}parseAsSerialDate(e,t){throw new S}parseAsDate(e,t){throw new S}parseAsNumber(e,t){throw new S}createCriteria(e){throw new S}parseAsLiteral(e){let t=e.toUpperCase();return t===`TRUE`||t!==`FALSE`&&i.getBuiltInByLabel(t)}toText(e){return typeof e==`string`?e:e==null?``:typeof e==`boolean`?e?`TRUE`:`FALSE`:e?.isFormulaError?e.getLabel():String(e)}compare(e,t,n){if(e===t)return 0;let r=b(e),i=b(t);return r===i?e<t?-1:+(e>t):r<i?-1:1}getRuntime(){return w}getArgs(){throw new S(x)}},b=e=>{if(e==null)return 0;switch(typeof e){case`number`:return 1;case`string`:return 2;case`boolean`:return 3;default:return 4}},x=`FormulaContext.getArgs() is only valid while a function body is running`,S=class extends Error{constructor(e=`Not implemented in StubbedFormulaContext`){super(e),this.name=`NotImplementedError`}},C=Object.freeze({colStart:0,rowStart:0,colEnd:2**14-1,rowEnd:2**20-1}),w={isDate1904:()=>!1,getLocale:()=>O.tag,getLocaleProfile:()=>O,isR1C1:()=>!1,getNow:()=>0,getLocation:()=>`unknown`,getVersion:()=>`1.0.0`,getOS:()=>`unknown`,getUser:()=>`unidentified`,getDescription:()=>`Stubbed Formula Context`},T=2958465,E=new y,D=class{constructor(){this._scope=E,this._argsFn=null}_setScope(e){this._scope=e??E}_getScope(){return this._scope}_setArgsProvider(e){this._argsFn=e}getNumberFormat(e,t){return this._getScope().getNumberFormat(e,t)}getEntireCoords(){return this._getScope().getEntireCoords()??C}parseAsSerialDate(e,t){return this._getScope().parseAsSerialDate(e,t)}parseAsDate(e,t){return this._getScope().parseAsDate(e,t)}parseAsNumber(e,t){return this._getScope().parseAsNumber(e,t)}createCriteria(e){return this._getScope().createCriteria(e)}parseAsLiteral(e){let t=this._getScope();return t.parseAsLiteral?t.parseAsLiteral(e):E.parseAsLiteral(e)}toText(e){return this._getScope().toText(e)}isValidDate(e,t=!1){return this._getScope().isValidDate(e,t)}fromSerialDate(e,t=!1){return this._getScope().fromSerialDate(e,t)}toSerialDate(e,t=!1){return this._getScope().toSerialDate(e,t)}getDateParts(e,t){return this._getScope().getDateParts(e,t)}getSerialDate(e,t,n,r=0,i=0,a=0,o=0){return this._getScope().getSerialDate(e,t,n,r,i,a,o)}getNow(){return this._getScope().getNow()}createRange(e,t,n){return this._getScope().createRange(e,t,n)}getRow(){return this._getScope().getRow?.()??0}getColumn(){return this._getScope().getColumn?.()??0}getReference(e,t){return this._getScope().getReference(e,t)}getResizedReference(e,t,n){return this._getScope().getResizedReference(e,t,n)}getValueAt(e,t,n){return this._getScope().getValueAt(e,t,n)}getFormulaAt(e,t,n){return this._getScope().getFormulaAt?.(e,t,n)??null}getSpillAt(e,t,n){return this._getScope().getSpillAt?.(e,t,n)??null}getSheetIndex(e){return this._getScope().getSheetIndex?.(e)??-1}getSheetCount(){return this._getScope().getSheetCount?.()??1}markVolatile(){this._getScope().markVolatile?.()}formatResults(e){this._getScope().formatResults?.(e)}filterHidden(e,t){return this._getScope().filterHidden?.(e,t)??e}filterTotals(e){return this._getScope().filterTotals?.(e)??e}getFunction(e){return this._getScope().getFunction?.(e)??null}getAddress(e,t){return this._getScope().getAddress(e,t)}compare(e,t,n){return this._getScope().compare?.(e,t,n)??E.compare(e,t,n)}getRuntime(){return this._getScope().getRuntime()}getArgs(){let e=this._argsFn,t=e?e():null;if(!t)throw new S(x);return t}get[Symbol.toStringTag](){return`[FormulaContext]`}toString(){return this._getScope()?.toString?.()??`{STUB SCOPE}`}},O=Object.freeze({tag:`en-US`,numberingSystem:`latn`,decimal:`.`,group:`,`,grouping:[3],minusSign:`-`,percentSign:`%`,permilleSign:`‰`,currencyCode:`USD`,currencySymbol:`$`,currencyDisplay:`symbol`,currencyPosition:`before`,currencySpacing:`tight`,date:Object.freeze({calendar:`gregory`,short:`M/d/yy`,medium:`MMM d, y`,long:`MMMM d, y`,timeShort:`h:mm a`,timeLong:`h:mm:ss a`,am:`AM`,pm:`PM`,firstDay:0,weekend:[6,0],monthsWide:[`January`,`February`,`March`,`April`,`May`,`June`,`July`,`August`,`September`,`October`,`November`,`December`],monthsAbbr:[`Jan`,`Feb`,`Mar`,`Apr`,`May`,`Jun`,`Jul`,`Aug`,`Sep`,`Oct`,`Nov`,`Dec`],weekdaysWide:[`Sunday`,`Monday`,`Tuesday`,`Wednesday`,`Thursday`,`Friday`,`Saturday`],weekdaysAbbr:[`Sun`,`Mon`,`Tue`,`Wed`,`Thu`,`Fri`,`Sat`],hour12:!0}),listSeparator:`,`,csvDelimiter:`,`,rtl:!1,collator:Object.freeze({sensitivity:`base`,numeric:!0})}),k=new D;exports.CompatAliases=d,exports.CompatFeatures=u,exports.DEFAULT_LOCALE_PROFILE=O,exports.FormulaContext=k,Object.defineProperty(exports,"FormulaError",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"IRange",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"IRangeStats",{enumerable:!0,get:function(){return r}}),exports.InteropScalarType=o,exports.Observable=class{constructor(e){this._subscribeFn=e}subscribe(e,t,n){let r=typeof e==`object`?{next:e.next||(()=>{}),error:e.error||(()=>{}),complete:e.complete||(()=>{}),unsubscribe:()=>{}}:{next:e||(()=>{}),error:t||(()=>{}),complete:n||(()=>{}),unsubscribe:()=>{}},i=this._subscribeFn(r);return r.unsubscribe=()=>{typeof i==`function`&&i()},r}},Object.defineProperty(exports,"Scalar",{enumerable:!0,get:function(){return e}}),exports.ScalarType=a,exports.ScopedFormulaContext=D,exports.StubbedFormulaContext=y,exports.WildCard=l,exports.resolveCompatFeature=f,exports.resolveCompatFeatures=function(e){let t=f(e);if(t)return[t];let n=(e??``).trim().toLowerCase();for(let e of Object.keys(d))if(e.toLowerCase()===n)return d[e];return null};

package/types/src/Compat.d.ts

@@ -1,77 +0,0 @@
-/**
- * The behaviors `@compat` can turn on, and what each one does.
- *
- * @remarks
- * A feature earns a place here only if the BODY cannot do it — the decision happens before the
- * body runs, or instead of running it. Everything a body can decide for itself belongs in the
- * body, where `FormulaContext.getArgs()` and `Omittable` already reach.
- *
- * Function-level until a measurement forces otherwise: `noReferenceLift` is per-function in
- * Excel, and no function is known whose parameters disagree.
- *
- * @see {@link https://www.sheetxl.com/docs/guides/concepts/udf | UDF authoring guide}
- */
-export declare const CompatFeatures: {
-    /**
-     * A multi-cell REFERENCE at a non-repeating scalar parameter is `#VALUE!` rather than a
-     * broadcast.
-     *
-     * Excel's Analysis-ToolPak family answers `CUMIPMT(G1:G2,120,100000,13,24,0)` with `#VALUE!`
-     * where the native `ROUND(B1:B3,3)` spills three results. A multi-cell reference has no way to
-     * become a scalar there, because these functions never intersect. An ARRAY at the same slot
-     * still lifts (`MROUND({3,4,5},5)` spills), so the refusal is about references specifically,
-     * and a REPEATING slot absorbs a container as members either way (`GCD(C1:C3)` is 4) — so this
-     * never applies to one.
-     */
-    readonly noReferenceLift: "A multi-cell reference at a non-repeating scalar parameter is #VALUE! rather than a broadcast.";
-    /**
-     * Members of a REPEATING scalar parameter are coerced rather than filtered: numeric text
-     * parses, a blank inside a multi-cell range reads 0, and a boolean or non-numeric text member
-     * is `#VALUE!` for the whole call.
-     *
-     * The native family FILTERS — `SUM({1,"8",TRUE})` is 1, the text and the boolean skipped, and a
-     * blank cell contributes nothing. Excel's Analysis-ToolPak family coerces instead:
-     * `GCD({6,"8",12})` is 2, `GCD({6,TRUE,12})` is `#VALUE!`, `LCM(6,A1:A2)` over two blank cells
-     * is 0. A direct argument follows the same rule (`GCD(6,TRUE,12)` is `#VALUE!` where
-     * `SUM(6,TRUE,12)` is 19), and a one-cell blank reference or an omitted argument is still
-     * skipped — it never became a member.
-     */
-    readonly noMemberFilter: "Members of a repeating scalar parameter are coerced rather than filtered; one that cannot be is #VALUE!.";
-};
-/**
- * One of the {@link CompatFeatures} names.
- */
-export type CompatFeature = keyof typeof CompatFeatures;
-/**
- * Family aliases: one name an author writes that expands to several {@link CompatFeatures}.
- *
- * @remarks
- * Excel's Analysis-ToolPak heritage is ONE measured rule with two halves that act on disjoint
- * parameter kinds — `noReferenceLift` at a non-repeating scalar slot, `noMemberFilter` at a
- * repeating one — so every function in the family carries the same two bits and `@compat atp`
- * says so in one word. The alias is expanded by the linter; only the atomic features are ever
- * stored, so `@compat atp` and `@compat noReferenceLift noMemberFilter` emit the same declaration.
- * The atomic names stay available for the day a function measures as disagreeing on one half.
- */
-export declare const CompatAliases: Readonly<Record<string, readonly CompatFeature[]>>;
-/**
- * Resolves a `@compat` name — a feature or a family alias — CASE-INSENSITIVELY, to the canonical
- * features it turns on.
- *
- * @param name The name as the author wrote it.
- * @returns The canonical features, or `null` when no feature or alias goes by that name.
- */
-export declare function resolveCompatFeatures(name: string): readonly CompatFeature[] | null;
-/**
- * Resolves a `@compat` feature name, CASE-INSENSITIVELY, to its canonical spelling.
- *
- * @param name The name as the author wrote it.
- * @returns The canonical name, or `null` when no feature goes by it.
- *
- * @remarks
- * Authors write `@compat noReferenceLift`; `@Compat NOREFERENCELIFT` means the same thing. Only
- * the canonical spelling is ever stored, so the declaration a build emits does not depend on how
- * the tag was typed.
- */
-export declare function resolveCompatFeature(name: string): CompatFeature | null;
-//# sourceMappingURL=Compat.d.ts.map