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

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/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