@sheetxl/primitives 0.7.26 → 0.7.28-beta.1

package/types/src/IFunction.d.ts

@@ -0,0 +1,608 @@
+import { Scalar } from './Scalar';
+import { ScalarType } from './ScalarType';
+/**
+ * A self-describing, type-safe, executable function.
+ *
+ * Built-in and user-defined functions share this interface. It pairs the
+ * callable entry point (`execute`) with type metadata to guarantee type safety
+ * and auto-coerce arguments, plus locale-specific copy for UI display and validation.
+ *
+ * Formula authors encounter `IFunction` when calling another function by name
+ * at evaluation time via `FormulaContext.getFunction`, or when tooling
+ * introspects the function registry.
+ *
+ * @see {@link https://www.sheetxl.com/docs/guides/concepts/udf | UDF authoring guide} for
+ * how to create and register functions.
+ */
+export interface IFunction {
+    /**
+     * Execute the function
+     */
+    execute<R = any>(...args: any[]): R;
+    /**
+     * The name of the function.
+     */
+    getName(): string;
+    /**
+     * Contains type information needed to safely execute the function.
+     */
+    getDeclaration(): IFunction.IDeclaration;
+    /**
+     * Returns user-facing information about the function.
+     */
+    getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
+    /**
+     * Indicates whether the function is a built-in function.
+     */
+    isBuiltIn(): boolean;
+    /**
+     * Returns the execution environment this function belongs to.
+     *
+     * @remarks
+     * SheetXL exposes functions from multiple environments — the formula calculation
+     * engine and the macro/scripting runtime — through the same `IFunction` interface.
+     * The context identifier distinguishes them and determines which argument types and
+     * calling conventions apply. Returns `null` for standard formula functions.
+     */
+    getContext(): string | null;
+    /**
+     * Type guard property. Always `true` on any `IFunction` instance.
+     *
+     * @remarks
+     * Use this to distinguish an `IFunction` from other objects at runtime without
+     * relying on `instanceof`, which does not work across module boundaries.
+     */
+    get isIFunction(): true;
+}
+/**
+ * {@inheritDoc IFunction}
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunction}
+ */
+export declare namespace IFunction {
+    /**
+     * Describes the type characteristics of a value used as a function parameter or return value.
+     *
+     * @remarks
+     * If `getScalarType` is `null` and `getRangeType` is `null`, the value is untyped. Not all
+     * runtimes will allow this.
+     */
+    interface IValueType {
+        /**
+         * Indicates that the value is a single, scalar cell-compatible value.
+         *
+         * @remarks
+         * This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
+         * `'*'` is a scalar of undeclared type — still provably a scalar, unlike untyped.
+         * `ScalarType.Null` is permitted only for event handler return types.
+         */
+        getScalarType(): ScalarType | '*' | null;
+        /**
+         * Indicates that the value is a range (multi-cell) structure.
+         *
+         * - `p`: A `RangeReference`, representing a pointer to sheet coordinates.
+         * - `r`: A `Range`, representing the actual values in the range.
+         * - `m`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
+         *
+         * If specified, the function supports multi-cell or structured range inputs.
+         */
+        getRangeType(): 'p' | 'r' | 'm' | '*' | null;
+        /**
+         * Indicates that the value is a LAMBDA (a function value), and what it produces — which is
+         * also what the marshalled callable coerces each result to.
+         *
+         * - `'*'`: any SCALAR — each result coerces to one scalar.
+         * - a `ScalarType`: the lambda's declared return.
+         * - `'raw'`: a declared `any` return — results pass uncoerced (`REDUCE`'s accumulator).
+         * - `null`: not a lambda.
+         *
+         * @remarks
+         * A lambda is neither a value nor a location, so this is the accessor to ask before concluding
+         * anything from {@link getScalarType} — which reports `'l'` alongside a lambda for historical
+         * reasons, a spelling outside its own declared `ScalarType | '*' | null`.
+         *
+         * Applies to both parameters (`BYROW`'s `fn`) and the one return that is a lambda (`LAMBDA`).
+         */
+        getLambda(): ScalarType | '*' | 'raw' | null;
+        /**
+         * Defines the number of array signatures after a parameter.
+         * - `0`: No array signature. The value is scalar or a single cell.
+         * - `1`: Will flatten.
+         * - `2`: Nest.
+         */
+        getArrayDepth(): number;
+    }
+    /**
+     * Describes the parameter to a function, including its name, type,
+     * whether it's required, and if it's a rest parameter.
+     */
+    interface IParameterType extends IValueType {
+        /**
+         * The name of the parameter.
+         */
+        getName(): string;
+        /**
+         * The DECLARED error policy, or `null` when the parameter relies on the default.
+         *
+         * @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.
+         *
+         * @see {@link ParameterTypeJSON.errors}
+         */
+        getErrorPolicy(): 'accept' | 'accept-ref' | null;
+        /**
+         * Indicates whether the parameter is required.
+         */
+        isOptional(): boolean;
+        /**
+         * The value the parameter's own initializer supplies when the argument is ABSENT, or
+         * `undefined` where none can be read.
+         *
+         * @see {@link ParameterTypeJSON.defaultValue}
+         */
+        getDefaultValue(): Scalar | undefined;
+        /**
+         * The SLOTS of a repeating parameter group, or `null` when this parameter is not one.
+         *
+         * @remarks
+         * A repeating group is one declared parameter whose arguments arrive as a fixed-size cycle
+         * repeated N times — `SUMIFS(sum, r1, c1, r2, c2, …)` is a `[criteriaRange, criteria]` group.
+         * The returned array IS the cycle, so `getRepeatingTypes()!.length` is the period and argument
+         * `i` binds to slot `(i − prefixLength) % period`.
+         *
+         * This is a NESTED node rather than a flattened list on purpose: a flat list cannot be
+         * re-segmented, and every consumer (the site predicate, the arity check, the function wizard)
+         * needs the period to bind an argument position to a slot.
+         *
+         * A period-1 group carries a single slot with the same name as the parameter, which is what
+         * makes it display identically to a rest parameter (`array1, array2, …`).
+         *
+         * Only the LAST slot may be optional, and it means one thing: it may be omitted when there is
+         * exactly one repetition (`SORTBY(array, by1)` is legal; `SORTBY(array, by1, o1, by2)` is not).
+         *
+         * @see {@link Repeating}
+         */
+        getRepeatingTypes(): readonly IFunction.IParameterType[] | null;
+        /**
+         * Indicates whether the parameter is a rest parameter (accepts multiple arguments).
+         *
+         * @remarks
+         * - A rest parameter can only be the last parameter in a function.
+         * - If `rest` is `true`, the parameter is also considered optional.
+         *
+         * A rest parameter is the degenerate repeating group: period 1, no minimum. Prefer
+         * {@link getRepeatingTypes} (`Repeating<T>`) when at least one argument is required.
+         */
+        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.
+         */
+        getEnums(): readonly string[];
+    }
+    /**
+     * Describes the runtime return behavior of a function, including modifiers like
+     * async resolution, streaming data, or volatility.
+     *
+     * @remarks
+     * All return type modifiers are mutually exclusive.
+     * If none are specified, The value will be returned with no special behavior.
+     */
+    interface IReturnType extends IValueType {
+        /**
+         * 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.
+         *
+         * Can be combined with any scalar, array, or range return type.
+         */
+        isAsync(): boolean;
+        /**
+         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
+         *
+         * @defaultValue `false`
+         */
+        isStreaming(): boolean;
+    }
+    /**
+     * The type-system metadata the engine reads to coerce arguments, apply broadcasting,
+     * and validate calls before execution. This is separate from {@link IDescriptor},
+     * which carries locale-specific user-facing copy.
+     */
+    interface IDeclaration {
+        /**
+         * Named of the actual function in code.
+         *
+         * @remarks
+         * The unique identifier for the function. It has a number of rules:
+         * * The only characters allowed are: (A-Z, 0-9, _m .)
+         * * Character casing is ignored and will be converted to upper.
+         * * At least 2 characters.
+         * * Must start with a letter (A-Z).
+         * * Must be globally unique.
+         * * Must not be a reserved word.
+         * * Must not be a built-in function.
+         */
+        getName(): string;
+        /**
+         * An array of `Parameter` objects describing the function's parameters.
+         *
+         * @remarks
+         * If not specified, the function is assumed to be volatile (its output might change even if its inputs haven't).
+         */
+        getParameters(): readonly IParameterType[];
+        /**
+         * Metadata describing the type and dimensionality of the return value.
+         *
+         * @defaultValue `{ type: 'void' }`
+         */
+        getReturnType(): IReturnType;
+    }
+    /**
+     * Locale-specific, user-facing metadata: display name, summary, category, and
+     * parameter descriptions shown in the formula bar and autocomplete UI.
+     * Separate from {@link IDeclaration}, which carries the type-system metadata
+     * the engine uses for coercion and broadcasting.
+     */
+    interface IDescriptor {
+        /**
+         * A overwritten name for the function.
+         */
+        getName(): string;
+        /**
+         * The function's name in the user's language (the active spreadsheet-language pack), e.g. `SUMME`
+         * for `SUM` in German — Excel's `getXxxLocal()` convention (`getFormulaLocal`/`getNumberFormatLocal`).
+         * Falls back to the canonical {@link getName} when the active language does not translate it (English
+         * is always accepted). {@link getName} stays the canonical identity; only display uses this.
+         */
+        getNameLocal(): string;
+        /**
+         * A description of the function's purpose and usage.
+         */
+        getSummary(): string;
+        /**
+         * A category or group to which the function belongs.
+         */
+        getCategory(): string;
+        /**
+         * If `true` the function is available but will not be returned in search
+         * results unless hidden is specifically requested.
+         *
+         * @defaultValue 'null'
+         *
+         * @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.
+         */
+        isDeprecated(): boolean | string;
+        /**
+         * An array of links associated with the value.
+         */
+        getLinks(): readonly [url: string, text?: string][];
+        /**
+         * Describe each parameter in the function.
+         *
+         * @remarks
+         * Each field is optional — a parameter may declare only a description, only an example, or nothing.
+         * The keys are the declaration parameter names (see {@link IParameterType.getName}).
+         */
+        getParameters(): Readonly<Record<string, {
+            description?: string;
+            example?: string;
+            defaultValue?: Scalar;
+        }>>;
+    }
+    /**
+     * Describes the type characteristics of a function parameter or return value.
+     *
+     * At least one of `scalar`, `range`, or `context` must be defined.
+     */
+    interface ValueTypeJSON {
+        /**
+         * Indicates that the value is a single, scalar cell-compatible value.
+         *
+         * @remarks
+         * This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
+         * `ScalarType.Null` is permitted only for event handler return types.
+         */
+        scalar?: ScalarType | string;
+        /**
+         * Indicates that the value is a range (multi-cell) structure.
+         *
+         * - `p`: A `RangeReference`, representing a pointer to sheet coordinates.
+         * - `r`: A `Range`, representing the actual values in the range.
+         * - `m`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
+         * - `*`: Any value — a scalar or a range. Declared `any`, and the same `*`-means-any spelling
+         *   as {@link scalar} and {@link lambda}.
+         *
+         * If specified, the function supports multi-cell or structured range inputs.
+         *
+         * @remarks
+         * A `*` parameter is handed the whole argument, whatever it is. It is a VALUE position rather
+         * than a range one, which matters when another parameter causes the call to broadcast: a `*`
+         * parameter follows that broadcast and receives one element per position, where an `r`/`p`
+         * parameter would receive the whole range on every call. It never causes a broadcast itself.
+         *
+         * `IF(logical, valueIfTrue, valueIfFalse)` is the canonical shape — the branches are `*`, so
+         * a single condition returns the chosen branch untouched while an array condition selects
+         * element by element.
+         */
+        range?: 'p' | 'r' | 'm' | '*';
+        /**
+         * Indicates that the value is a lambda function, and what the lambda RETURNS — which is also
+         * what the marshalled callable coerces each result to:
+         *
+         * - a `ScalarType`: that scalar.
+         * - `*`: any SCALAR — each result still coerces to ONE scalar (a 1×1 range/reference unwraps,
+         *   an error embeds as a value, a larger shape is `#CALC!` for the whole call).
+         * - `raw`: a declared `any` return (`Lambda<Args, any>`) — results pass to the body
+         *   uncoerced. `REDUCE` is the case: its accumulator threads raw, which is what makes an
+         *   array/reference accumulator legal.
+         *
+         * If specified, the function supports lambda inputs.
+         */
+        lambda?: ScalarType | '*' | 'raw';
+        /**
+         * The lambda's declared parameter count, from the `Lambda<Args, R>` tuple.
+         *
+         * Enforced by the marshaller at the call — a callable that cannot take exactly this many
+         * arguments is `#VALUE!` for the whole call, before any element runs (an eta-reduced function
+         * name defers to its own dispatch). Absent when the declaration leaves arity open
+         * (`Lambda<any[], R>`): a lambda slot in a repeating group then requires one parameter per
+         * OTHER argument of the call; anywhere else the arity is unchecked.
+         */
+        lambdaArity?: number;
+        /**
+         * Defines the number of array signatures after a parameter.
+         * - `0`: No array signature. The value is scalar or a single cell.
+         * - `1`: Will flatten.
+         * - `2`: Nest.
+         * - `3`: Array of arrays of arrays (e.g. for 3D ranges or arrays of tables)
+         *
+         * @defaultValue `0` if no `range` is defined, otherwise `1`.
+         */
+        arrayDepth?: number;
+        /**
+         * A short description of the value's purpose or expected usage.
+         */
+        description?: string;
+    }
+    /**
+     * Describes the parameter to a function, including its name, type,
+     * whether it's required, and if it's a rest parameter.
+     */
+    interface ParameterTypeJSON extends ValueTypeJSON {
+        /**
+         * The name of the parameter.
+         */
+        name: string;
+        /**
+         * Indicates whether the parameter is required.
+         *
+         * @defaultValue true
+         */
+        optional?: boolean;
+        /**
+         * The value the parameter's own initializer supplies when the argument is ABSENT.
+         *
+         * @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.
+         *
+         * Present for a literal initializer only. One computed from another argument
+         * (`numberS2: number = numberS`) has no value to record and leaves this undefined.
+         *
+         * Concerns the ABSENT position specifically; {@link omittedValue} covers what an argument
+         * supplied EMPTY means, which is frequently a different value.
+         */
+        defaultValue?: Scalar;
+        /**
+         * An argument supplied EMPTY (`FIXED(1.5,)`) does not coerce to the parameter's type.
+         * Generated from the `Omittable<T>` marker.
+         *
+         * @remarks
+         * Undeclared, an omitted argument reaches the body as `0` / `false` / `""` — the right default
+         * for most functions, and what `VLOOKUP(x,r,2,)` means by an exact match. Declared, the
+         * argument arrives as {@link omittedValue} where one is given, and otherwise as `undefined`,
+         * letting the parameter's own initializer supply it so that an omitted argument means what an
+         * absent one means.
+         *
+         * A blank CELL in the same position is unaffected and continues to coerce: it is a value the
+         * caller supplied, where an omitted argument is the caller supplying none.
+         *
+         * @see {@link Omittable}
+         */
+        omittable?: boolean;
+        /**
+         * What an argument supplied EMPTY means, where that differs from the absent default. Generated
+         * from the second type argument of `Omittable<T, V>`.
+         *
+         * @remarks
+         * Left undeclared where the two coincide, which is the common case — the parameter's own
+         * initializer then serves both positions. It is declared where a function distinguishes them:
+         * `MATCH(3,{2})` is `1` while `MATCH(3,{2},)` is `#N/A`, giving `matchType` the declaration
+         * `Omittable<number, 0> = 1`.
+         *
+         * Implies {@link omittable}. Unlike {@link defaultValue}, which only records what the
+         * initializer would supply, this value is applied by the engine.
+         */
+        omittedValue?: Scalar;
+        /**
+         * Indicates whether the parameter is a rest parameter (accepts multiple arguments).
+         *
+         * @remarks
+         * - A rest parameter can only be the last parameter in a function.
+         * - If `rest` is `true`, the parameter is also considered optional.
+         */
+        rest?: boolean;
+        /**
+         * The SLOTS of a repeating parameter group, generated from the `Repeating<T>` marker.
+         *
+         * @remarks
+         * Present iff this parameter IS a group; its own `scalar`/`range`/`arrayDepth` are then unset
+         * and the slots carry the types. The array length is the group's PERIOD. Cannot be combined
+         * with {@link rest}.
+         *
+         * @see {@link IParameterType.getRepeatingTypes}
+         */
+        repeating?: ParameterTypeJSON[];
+        /**
+         * The DECLARED error policy, generated from the `AcceptError<T>` / `AcceptRefError<T>`
+         * parameter markers.
+         *
+         * - `'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.
+         *
+         * 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.
+         */
+        errors?: 'accept' | 'accept-ref';
+        /**
+         * Indicates whether the function requires the address of the calling cell as an input.
+         * Cannot be combined with `stream`.
+         *
+         * @defaultValue `false`
+         */
+        enums?: string[];
+    }
+    /**
+     * Describes the runtime return behavior of a function, including modifiers like
+     * async resolution, streaming data, or volatility.
+     *
+     * @remarks
+     * If none are specified, The value will be returned with no special behavior.
+     */
+    interface ReturnTypeJSON extends ValueTypeJSON {
+        /**
+         * 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.
+         *
+         * Can be combined with any scalar, array, or range return type.
+         */
+        async?: boolean;
+        /**
+         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
+         *
+         * @defaultValue `false`
+         */
+        stream?: boolean;
+    }
+    /**
+     * Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
+     */
+    interface DeclarationJSON {
+        /** @inheritdoc IFunction.IDeclaration.getName */
+        name: string;
+        /** @inheritdoc IFunction.IDeclaration.getReturnType */
+        returnType?: ReturnTypeJSON;
+        /** @inheritdoc IFunction.IDeclaration.getParameters */
+        parameters?: ParameterTypeJSON[];
+        /**
+         * Describes the execution context required by the function.
+         *
+         * Contexts fall into two categories:
+         *
+         * - **Macro contexts**: Used by macro-style functions to access parts of the document or selection:
+         *   - `'Workbook'`: The entire workbook
+         *   - `'Sheet'`: A single sheet
+         *   - `'Range'`: A selected sheet range
+         *   - `'Ranges'`: Multiple selected ranges
+         *
+         * - **Calculation context**: Used by formula functions like `OFFSET` or `INDIRECT`
+         *   that need access to evaluation position or sheet metadata during calculation.
+         *   This context is available in headless or worker environments.
+         *
+         * @remarks
+         * * If omitted, the function is consider a FormulaFunction.
+         * * If a function has a context it will be passed as the first argument to `execute`.
+         * * If the context is `IFunction.Calculation` then the function must return a value.
+         * * If the context is not `IFunction.Calculation` then the function must return `void` or a cleanup function.
+         */
+        context?: string;
+        /**
+        * Additional metadata about the function's behavior or requirements.
+        */
+        behavior?: BehaviorJSON;
+    }
+    /**
+     * Contains user information about the function.
+     *
+     * @remarks
+     * This is locale specific.
+     */
+    interface DescriptorJSON {
+        /**
+         * A overwritten name for the function.
+         *
+         * @defaultValue The name of the function in code.
+         */
+        name?: string;
+        /**
+         * The function name in the user's language (spreadsheet-language pack), e.g. `SUMME`. Snapshot
+         * for the language the descriptor was resolved for; absent ⇒ falls back to {@link name}.
+         */
+        nameLocal?: string;
+        /**
+         * A more detailed explanation of the function's purpose and usage.
+         */
+        summary?: string;
+        /**
+         * A category or group to which the function belongs.
+         *
+         * @defaultValue 'custom'
+         */
+        category?: string;
+        /**
+         * If `true` or has a string value then is usable in calculation but not provided in the ui.
+         *
+         * @defaultValue 'null'
+         *
+         * @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.
+         */
+        deprecated?: string | boolean;
+        /**
+         * An array of links associated with the value.
+         */
+        links?: [url: string, text?: string][];
+        /**
+         * Describe each parameter in the function.
+         */
+        parameters?: Record<string, {
+            description: string;
+            example?: string;
+            defaultValue?: Scalar;
+        }>;
+    }
+    /**
+     * Contains extended metadata about a function that is not be directly inferable from the code itself.
+     */
+    interface BehaviorJSON {
+        /**
+         * If `true` this function will be called on load unless scripts are disabled.
+         *
+         * @defaultValue `false`.
+         */
+        default?: boolean;
+        /**
+         * Indicates whether the function's execution can be canceled by the user.
+         *
+         * @defaultValue false
+         */
+        cancelable?: boolean;
+    }
+}
+//# sourceMappingURL=IFunction.d.ts.map