@sheetxl/primitives 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/IFunction.d.ts

@@ -1,5 +1,6 @@
 import { Scalar } from './Scalar';
 import { ScalarType } from './ScalarType';
+import { ValueKind } from './ValueKind';
 /**
  * A self-describing, type-safe, executable function.
  *
@@ -35,6 +36,22 @@ export interface IFunction {
      * Indicates whether the function is a built-in function.
      */
     isBuiltIn(): boolean;
+    /**
+     * Indicates whether the function is a `LAMBDA` rather than a built-in or registered function.
+     *
+     * @remarks
+     * Two kinds of function answer `true`:
+     *
+     * - **A defined name whose body is `LAMBDA(…)`.** It is reachable by name like any other
+     *   function, so signature help and function lookups can describe it: its parameters are the
+     *   lambda's, and its summary is the name's comment, or the name's formula when it has no
+     *   comment. A formula calls it through the NAME, never through {@link execute}, which answers
+     *   `#CALC!`.
+     * - **A `LAMBDA` passed as a value** and received by
+     *   {@link IFunctionArguments.getFunctionsAt}. It has no name ({@link getName} is `''`), its
+     *   parameters are the lambda's, and {@link execute} applies it.
+     */
+    isLambda(): boolean;
     /**
      * Returns the execution environment this function belongs to.
      *
@@ -125,17 +142,47 @@ export declare namespace IFunction {
          */
         getName(): string;
         /**
-         * The DECLARED error policy, or `null` when the parameter relies on the default.
+         * True when a BARE error at this parameter — an error instead of a value or a range, `NA()`,
+         * `#NAME?`, a union where one rectangle is needed — is delivered to the body RAW rather than
+         * propagated: the `AcceptError<T>` marker. A rule, not a type — the engine's auto-reject is
+         * off at this slot, and the body narrows with `FormulaError.isError` if it cares.
          *
          * @remarks
-         * `null` is the common case and it is not "no policy": the default is REJECT in every position
-         * — scalar, lifted, flattened and range alike — so `null` means reject. There is deliberately
-         * no `'reject'` value to declare it with; a `RejectError<T>` marker existed, said exactly what
-         * `null` already says, and was removed rather than left as a second spelling.
+         * The default, and the common case, is that the error propagates with its identity and the
+         * body never runs. The marker never looks INSIDE a container: an error member of a range
+         * reaches the body either way and is the body's to judge (`IRange.firstError`).
+         *
+         * @see {@link ParameterTypeJSON.acceptError}
+         */
+        isAcceptError(): boolean;
+        /**
+         * True when a multi-cell REFERENCE at this scalar parameter is `#VALUE!` rather than a
+         * broadcast — the `NoLift<T>` marker.
+         *
+         * @see {@link ParameterTypeJSON.noLift}
+         */
+        isNoLift(): boolean;
+        /**
+         * True when the members reaching this repeating scalar parameter are coerced rather than
+         * filtered — the `NoFilter<T>` marker.
+         *
+         * @see {@link ParameterTypeJSON.noFilter}
+         */
+        isNoFilter(): boolean;
+        /**
+         * True when the argument at this parameter may reach the body UNEVALUATED, as an `ILazy`
+         * handle — the `Lazy<T>` marker.
          *
-         * @see {@link ParameterTypeJSON.errors}
+         * @see {@link ParameterTypeJSON.lazy}
          */
-        getErrorPolicy(): 'accept' | 'accept-ref' | null;
+        isLazy(): boolean;
+        /**
+         * True when the parameter takes EITHER a value or a range, decided per argument by its kind —
+         * an `IRange | Scalar` union.
+         *
+         * @see {@link ParameterTypeJSON.valueOrRange}
+         */
+        isValueOrRange(): boolean;
         /**
          * Indicates whether the parameter is required.
          */
@@ -181,11 +228,60 @@ export declare namespace IFunction {
          */
         isRest(): boolean;
         /**
-         * Indicates that the parameter is limited to a list of specific values.
-         * If the input value is a `string` it will be passed as a case-insensitive version.
-         * If the input value is a `number` it will be passed as a value against the offset.
+         * The enum the parameter is limited to, or `null` when it takes any value of its type.
+         *
+         * @remarks
+         * Declared by typing the parameter as a TypeScript `enum`, as an alias paired with a same-name
+         * `as const` object, or as a union of number or string literals (`0 | 1`).
+         *
+         * @see {@link IEnum}
          */
-        getEnums(): readonly string[];
+        getEnum(): IFunction.IEnum | null;
+    }
+    /**
+     * One member of an {@link IEnum}.
+     */
+    interface IEnumMember {
+        /**
+         * The declared member name (`End`). For a union of bare literals, which names nothing, this is
+         * the value as text.
+         */
+        getName(): string;
+        /**
+         * The value a formula passes. Typed, and never localized.
+         */
+        getValue(): number | string;
+        /**
+         * Whether the member is declared but not offered, from the member's `@deprecated` tag.
+         *
+         * @remarks
+         * A deprecated member stays in the set, so a formula that passes it is not refused and the
+         * function decides what it answers. It is left out of the argument dropdown and the values
+         * a warning lists. A string is the tag's label (`Excel desktop only`).
+         */
+        isDeprecated(): boolean | string;
+    }
+    /**
+     * A closed set of values a parameter accepts.
+     *
+     * @remarks
+     * All members are numbers or all are strings; the two never mix. The set is free-form: it does
+     * not have to be contiguous or start at zero (`-1 | 0 | 1`).
+     */
+    interface IEnum {
+        /**
+         * The declared type name (`PaymentType`), unique within the module that declares it. For a
+         * union of bare literals it is the values joined by `|`.
+         */
+        getId(): string;
+        /**
+         * Whether the members are numbers or strings.
+         */
+        getScalarType(): typeof ScalarType.Number | typeof ScalarType.String;
+        /**
+         * The members, in declaration order.
+         */
+        getMembers(): readonly IFunction.IEnumMember[];
     }
     /**
      * Describes the runtime return behavior of a function, including modifiers like
@@ -196,6 +292,14 @@ export declare namespace IFunction {
      * If none are specified, The value will be returned with no special behavior.
      */
     interface IReturnType extends IValueType {
+        /**
+         * The declared {@link ValueKind} of the result — the declared override where one exists, else
+         * the kind the type spellings imply — or `null` when the result's kind follows the value
+         * itself (`'*'`, an untyped return).
+         *
+         * @see {@link ReturnTypeJSON.kind}
+         */
+        getKind(): ValueKind | null;
         /**
          * Indicates the return value is a Promise or Promise-like (i.e., async).
          * The system will mark the result as pending and re-trigger evaluation once resolved.
@@ -209,6 +313,17 @@ export declare namespace IFunction {
          * @defaultValue `false`
          */
         isStreaming(): boolean;
+        /**
+         * True when the result can change with nothing dirty, so a cell naming this function
+         * recalculates on every pass — the `Volatile<T>` marker.
+         *
+         * @remarks
+         * STATIC, and read from the formula text at compile time: it is true of the call whether or
+         * not the call runs, which is what a lazy argument (and Excel) requires.
+         *
+         * @see {@link ReturnTypeJSON.volatile}
+         */
+        isVolatile(): boolean;
     }
     /**
      * The type-system metadata the engine reads to coerce arguments, apply broadcasting,
@@ -237,12 +352,32 @@ export declare namespace IFunction {
          * If not specified, the function is assumed to be volatile (its output might change even if its inputs haven't).
          */
         getParameters(): readonly IParameterType[];
+        /**
+         * The largest number of arguments a call to this function may carry.
+         *
+         * @remarks
+         * Only meaningful for a VARIADIC function; a fixed parameter list is already its own maximum.
+         * The number is the whole CALL's argument count, prefix and optional suffix included, and it
+         * is refused where Excel refuses it — at entry, before evaluation.
+         *
+         * @see {@link Repeating}
+         */
+        getMaxArguments(): number;
         /**
          * Metadata describing the type and dimensionality of the return value.
          *
          * @defaultValue `{ type: 'void' }`
          */
         getReturnType(): IReturnType;
+        /**
+         * Whether the function is left out of function lists, from its `@hidden` or `@deprecated` tag.
+         *
+         * @remarks
+         * A hidden function is still callable from a formula and still found by name. Listing calls
+         * leave it out unless asked to include it. {@link IDescriptor.isDeprecated} carries the tag's
+         * label, if it has one.
+         */
+        isHidden(): boolean;
     }
     /**
      * Locale-specific, user-facing metadata: display name, summary, category, and
@@ -252,7 +387,11 @@ export declare namespace IFunction {
      */
     interface IDescriptor {
         /**
-         * A overwritten name for the function.
+         * The canonical name of the function, matching {@link IDeclaration.getName}.
+         *
+         * @remarks
+         * A descriptor may override the name; when it does not, this is the name of the function
+         * in code. Use {@link getNameLocal} for display.
          */
         getName(): string;
         /**
@@ -271,14 +410,11 @@ export declare namespace IFunction {
          */
         getCategory(): string;
         /**
-         * If `true` the function is available but will not be returned in search
-         * results unless hidden is specifically requested.
-         *
-         * @defaultValue 'null'
+         * The label of the function's `@hidden` or `@deprecated` tag (`Unimplemented`), `true` for a tag
+         * with no label, or `false`.
          *
          * @remarks
-         * * If this is a string it can be used to provide a deprecated label.
-         * * This is useful for functions that are in beta or deprecated.
+         * Whether the function is listed is {@link IDeclaration.isHidden}; this is the text to show for it.
          */
         isDeprecated(): boolean | string;
         /**
@@ -297,6 +433,31 @@ export declare namespace IFunction {
             example?: string;
             defaultValue?: Scalar;
         }>>;
+        /**
+         * Describe each enum the function's parameters are limited to.
+         *
+         * @remarks
+         * The keys are enum ids (see {@link IEnum.getId}), and within one the member names (see
+         * {@link IEnumMember.getName}). Every enum a parameter declares has an entry and every member
+         * has one within it, so a caller can read a label without checking: `nameLocal` falls back to
+         * the declared name. Values are never localized — they are on the declaration.
+         */
+        getEnums(): Readonly<Record<string, IFunction.IEnumDescription>>;
+    }
+    /**
+     * The copy for one enum: what it is, and what each member means.
+     */
+    interface IEnumDescription {
+        /** The enum's name in the user's language, or its declared name. */
+        readonly nameLocal: string;
+        /** What the enum controls. */
+        readonly summary?: string;
+        /** By member name. */
+        readonly members: Readonly<Record<string, {
+            /** The member's name in the user's language, or its declared name. */
+            readonly nameLocal: string;
+            readonly description?: string;
+        }>>;
     }
     /**
      * Describes the type characteristics of a function parameter or return value.
@@ -394,7 +555,8 @@ export declare namespace IFunction {
          * @remarks
          * Descriptive rather than applied: an absent argument is never pushed, so the initializer
          * supplies the value itself. It is recorded so help text, tooltips and completions can say
-         * "defaults to 3" without reading the source.
+         * "defaults to 3" without reading the source. The exception is a {@link lazy} slot, which has
+         * no initializer to run — `Lazy<T, V>` declares the default here and the engine applies it.
          *
          * Present for a literal initializer only. One computed from another argument
          * (`numberS2: number = numberS`) has no value to record and leaves this undefined.
@@ -454,28 +616,126 @@ export declare namespace IFunction {
          */
         repeating?: ParameterTypeJSON[];
         /**
-         * The DECLARED error policy, generated from the `AcceptError<T>` / `AcceptRefError<T>`
-         * parameter markers.
+         * A BARE error at this parameter — an error instead of a value or a range — is delivered to
+         * the body RAW rather than propagated: the engine's auto-reject is off at this slot, and the
+         * body narrows if it cares. Generated from the `AcceptError<T>` marker. A failed COERCION to
+         * the declared type is delivered the same way, as the `#VALUE!` it would have raised, so a
+         * body that rethrows what it receives answers exactly as the engine would have — and one that
+         * reads its arguments in its own order can (`IFS(TRUE,1,"x",2)` is 1: the pair is never
+         * reached).
+         *
+         * @remarks
+         * OMITTED is the default (ErrorPolicy.ts): the error propagates with its identity (a scalar
+         * argument), becomes an error member of the output (a lifted member), or short-circuits on the
+         * first error in argument order (a flattened list) — the body never runs. A
+         * `FormulaError.Known`-typed parameter receives without the marker, because the type declares
+         * it. On a TYPED range (`IRange<number>`) the marker also lets error members ride through the
+         * typed read raw — COUNT's profile. Errors INSIDE a range are otherwise never the marker's
+         * business: a valid range is handed over whole.
+         */
+        acceptError?: boolean;
+        /**
+         * The argument's subtree may be handed over UNEVALUATED, as an `ILazy` handle the body either
+         * returns unread or forces with `getValue()`. Generated from the `Lazy<T>` marker.
          *
-         * - `'accept'`: the body receives `FormulaError` values raw.
-         * - `'accept-ref'`: per argument SHAPE — reject for a direct/computed argument, accept for a
-         *   reference-shaped one. Resolved to one of the two before any coercion runs, so nothing
-         *   downstream sees this value.
+         * @remarks
+         * A declaration, not a request: the engine defers where it can and DECLINES where it cannot
+         * (an absent argument, an async subtree, a lift that needs every arm), handing over a handle
+         * that is already full. Either way the body sees a handle and nothing else, which is why the
+         * marker is a contract rather than something inferred from what the body happens to read.
+         *
+         * Only a RESULT position carries it — `IF`'s branches, `CHOOSE`'s arms, `IFERROR`'s fallback.
+         * A condition, an index or a case value is eager, so `AND(FALSE,A1)` still reads `A1` and is
+         * still a circular reference.
+         *
+         * {@link defaultValue} is APPLIED at a lazy slot rather than merely recorded: the parameter
+         * cannot carry an initializer of its own (`= false` does not typecheck against a handle), so
+         * `Lazy<T, V>` declares it and the engine supplies it for an absent argument.
          *
-         * OMITTED is the default and the default is REJECT (ErrorPolicy.ts): never call the body — the
-         * error propagates with its identity (scalar argument), becomes an error member of the output
-         * (lifted member), or short-circuits on the first error in row-major order (range/array
-         * member). Only a `FormulaError.Known`-typed parameter receives without a marker, because the
-         * type declares it. There is no `'reject'` value: it would say what omitting this says.
+         * @see {@link Lazy}
          */
-        errors?: 'accept' | 'accept-ref';
+        lazy?: boolean;
         /**
-         * Indicates whether the function requires the address of the calling cell as an input.
-         * Cannot be combined with `stream`.
+         * A multi-cell REFERENCE at this scalar parameter is `#VALUE!` rather than a broadcast.
+         * Generated from the `NoLift<T>` marker.
          *
-         * @defaultValue `false`
+         * @remarks
+         * Per parameter, because Excel is: `NETWORKDAYS.INTL` refuses a reference at its date slots
+         * and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
+         * ordinary argument, and a repeating slot absorbs a container as members, so the marker only
+         * ever applies to a non-repeating scalar parameter.
+         */
+        noLift?: boolean;
+        /**
+         * The members reaching this repeating scalar parameter are COERCED rather than filtered, and
+         * one that cannot be coerced is `#VALUE!` for the whole call. Generated from the `NoFilter<T>`
+         * marker.
+         *
+         * @remarks
+         * Numeric text parses, a blank inside a multi-cell range reads 0, and a boolean or
+         * non-numeric text member refuses — Excel's Analysis-ToolPak reading of a repeating slot,
+         * where the native family skips all three (`GCD({6,"8",12})` is 2 where `SUM` would answer
+         * over 6 and 12 alone). Only a repeating slot has members, so the marker applies nowhere
+         * else; a non-repeating scalar's counterpart is {@link noLift}.
          */
-        enums?: string[];
+        noFilter?: boolean;
+        /**
+         * The declared type is ADVISORY: the engine delivers it when it can and hands the body the
+         * raw argument when it cannot, instead of answering `#VALUE!` at the slot. Generated from the
+         * `ReportType<T>` marker.
+         *
+         * @remarks
+         * The type still reaches the function help, the wizard and the linter — it is what the slot
+         * means to a caller. It stops being a gate, so the BODY owns every answer the engine would
+         * otherwise have given: a union reaches it as `IRange[]`, a value or an error reaches it as
+         * itself. See {@link IFunctionArguments.getKindAt} and
+         * {@link IFunctionArguments.getAreaCountAt} for the discriminators.
+         */
+        reportType?: boolean;
+        /**
+         * The parameter takes EITHER a value or a range — declared as a two-member union of a bare
+         * range type and a scalar type (`IRange | Scalar`, `IReferenceRange | number`) — and the
+         * marshaller picks the arm by the ARGUMENT's kind: a value, a bare error or a one-cell
+         * reference is the scalar arm (dereferenced, coerced to {@link scalar}, its fault raised in
+         * argument order like any scalar slot's); a multi-cell reference, an array or a reference
+         * union is the range arm, handed over whole. The slot never lifts.
+         *
+         * @remarks
+         * Excel reads a one-cell argument at some array slots as THE ARGUMENT rather than as a
+         * one-cell container: `SORT(<#N/A cell>,1,1,<#DIV/0! cell>)` is `#N/A` where
+         * `TAKE(<#N/A cell>,<#DIV/0! cell>)` is `#DIV/0!`. The engine's default
+         * for a range slot is TAKE's; this flag is SORT's. {@link scalar} and {@link range} each carry
+         * their arm, a pair that without this flag reads as a TYPED range (`IRange<number>`).
+         */
+        valueOrRange?: boolean;
+        /**
+         * The closed set of values the parameter accepts. Generated from a parameter typed as a
+         * TypeScript `enum`, as an alias paired with a same-name `as const` object, or as a union of
+         * number or string literals. {@link scalar} carries the members' type.
+         *
+         * @remarks
+         * Parameters that share a declared enum share one `EnumJSON`, by {@link EnumJSON.id}.
+         */
+        enum?: EnumJSON;
+    }
+    /**
+     * The JSON form of an {@link IEnum}.
+     */
+    interface EnumJSON {
+        /**
+         * The declared type name, unique within the declaring module. A union of bare literals has no
+         * name, so its id is the values joined by `|`.
+         */
+        id: string;
+        /**
+         * Whether the members are numbers or strings. The two never mix.
+         */
+        type: typeof ScalarType.Number | typeof ScalarType.String;
+        /**
+         * The members, in declaration order. A union of bare literals names nothing, so each name is
+         * the value as text.
+         */
+        members: [name: string, value: number | string, deprecated?: string | true][];
     }
     /**
      * Describes the runtime return behavior of a function, including modifiers like
@@ -485,6 +745,24 @@ export declare namespace IFunction {
      * If none are specified, The value will be returned with no special behavior.
      */
     interface ReturnTypeJSON extends ValueTypeJSON {
+        /**
+         * The declared {@link ValueKind} of the result, where the inherited type spellings cannot say
+         * it. Generated from the `@returnKind` marker.
+         *
+         * @remarks
+         * A return type is a pair — is the call a REFERENCE, and what is its value kind. Both halves
+         * usually derive from the type spellings: {@link ValueTypeJSON.range} `'p'` (an
+         * `IReferenceRange` return, which a function whose value paths are casts may also use —
+         * `XLOOKUP`, `TAKE`) is `Reference`; `'r'`/`'m'` is `Array`; a concrete
+         * {@link ValueTypeJSON.scalar} is that scalar kind; `'*'` or an untyped return follows the
+         * value itself. This field overrides the derivation for the one spelling that loses it — a
+         * union like `number[] | number[][]` (`ROW`) collapses to `'*'`, yet the function's one-cell
+         * answer is a SCALAR (`TYPE(ROW(A1))` is 1 where `TYPE(TRANSPOSE({5}))` is 64).
+         *
+         * The engine applies the kind at the call exit: a one-cell range result whose declared kind
+         * is a scalar is its member value downstream.
+         */
+        kind?: ValueKind;
         /**
          * Indicates the return value is a Promise or Promise-like (i.e., async).
          * The system will mark the result as pending and re-trigger evaluation once resolved.
@@ -498,6 +776,20 @@ export declare namespace IFunction {
          * @defaultValue `false`
          */
         stream?: boolean;
+        /**
+         * The result can change with nothing dirty — a cell naming this function recalculates on
+         * every pass. Generated from the `Volatile<T>` marker.
+         *
+         * @remarks
+         * Collected at COMPILE time from the formula text (`CompiledFormula.hasVolatile`), because
+         * that is where Excel decides it: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
+         * no branch selects the arm, and with lazy arguments the call never happens for the engine to
+         * observe. Sits beside {@link async} and {@link stream} because all three are about WHEN a
+         * result arrives rather than what it is.
+         *
+         * @see {@link Volatile}
+         */
+        volatile?: boolean;
     }
     /**
      * Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
@@ -509,6 +801,20 @@ export declare namespace IFunction {
         returnType?: ReturnTypeJSON;
         /** @inheritdoc IFunction.IDeclaration.getParameters */
         parameters?: ParameterTypeJSON[];
+        /**
+         * The largest number of arguments a call may carry, from `Repeating<T, Max>` on the variadic
+         * parameter. Omitted at the default of 255.
+         *
+         * @remarks
+         * Excel keeps one such number per NAME and compares it against the whole call's argument
+         * count in its front end, so a call past it is refused AT ENTRY rather than answered — which
+         * is why the cap lives on the declaration and not in a body. It is not derivable from the
+         * shape: `STDEV` takes 255 arguments and `STDEV.S`, the same function under its dotted name,
+         * takes 254.
+         *
+         * @defaultValue 255
+         */
+        maxArguments?: number;
         /**
          * Describes the execution context required by the function.
          *
@@ -531,6 +837,14 @@ export declare namespace IFunction {
          * * If the context is not `IFunction.Calculation` then the function must return `void` or a cleanup function.
          */
         context?: string;
+        /**
+         * Leave the function out of function lists.
+         *
+         * @defaultValue `false`
+         *
+         * @see {@link IDeclaration.isHidden}
+         */
+        hidden?: boolean;
         /**
         * Additional metadata about the function's behavior or requirements.
         */
@@ -565,13 +879,12 @@ export declare namespace IFunction {
          */
         category?: string;
         /**
-         * If `true` or has a string value then is usable in calculation but not provided in the ui.
+         * The label of a `@hidden` or `@deprecated` tag, or `true` for a tag with no label.
          *
-         * @defaultValue 'null'
+         * @defaultValue `false`
          *
          * @remarks
-         * * If this is a string it can be used to provide a deprecated label.
-         * * This is useful for functions that are in beta or deprecated.
+         * Display text only. Whether the function is listed is {@link DeclarationJSON.hidden}.
          */
         deprecated?: string | boolean;
         /**
@@ -586,6 +899,22 @@ export declare namespace IFunction {
             example?: string;
             defaultValue?: Scalar;
         }>;
+        /**
+         * Describe each enum the function's parameters are limited to, by enum id.
+         */
+        enums?: Record<string, EnumDescriptorJSON>;
+    }
+    /**
+     * The JSON form of an {@link IEnumDescription}. Every field is optional: an enum with no doc
+     * comments has nothing to say, and a language pack may translate any part of one.
+     */
+    interface EnumDescriptorJSON {
+        nameLocal?: string;
+        summary?: string;
+        members?: Record<string, {
+            nameLocal?: string;
+            description?: string;
+        }>;
     }
     /**
      * Contains extended metadata about a function that is not be directly inferable from the code itself.