@sheetxl/primitives 0.7.22 → 0.7.23-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/browser/cjs/index.cjs +1 -6
- package/browser/esm/index.mjs +683 -307
- package/node/esm/index.mjs +684 -307
- package/package.json +1 -1
- package/types/index.d.ts +2 -1622
- package/types/src/ErrorPolicy.d.ts +78 -0
- package/types/src/ErrorPolicy.d.ts.map +1 -0
- package/types/src/Flatten.d.ts +34 -0
- package/types/src/Flatten.d.ts.map +1 -0
- package/types/src/FormulaContext.d.ts +227 -0
- package/types/src/FormulaContext.d.ts.map +1 -0
- package/types/src/FormulaError.d.ts +328 -0
- package/types/src/FormulaError.d.ts.map +1 -0
- package/types/src/IFormulaContext.d.ts +533 -0
- package/types/src/IFormulaContext.d.ts.map +1 -0
- package/types/src/IFunction.d.ts +608 -0
- package/types/src/IFunction.d.ts.map +1 -0
- package/types/src/IRange.d.ts +1091 -0
- package/types/src/IRange.d.ts.map +1 -0
- package/types/src/IRangeStats.d.ts +478 -0
- package/types/src/IRangeStats.d.ts.map +1 -0
- package/types/src/IReferenceRange.d.ts +22 -0
- package/types/src/IReferenceRange.d.ts.map +1 -0
- package/types/src/IRichData.d.ts +37 -0
- package/types/src/IRichData.d.ts.map +1 -0
- package/types/src/IRuntime.d.ts +65 -0
- package/types/src/IRuntime.d.ts.map +1 -0
- package/types/src/Lambda.d.ts +17 -0
- package/types/src/Lambda.d.ts.map +1 -0
- package/types/src/LocaleProfile.d.ts +79 -0
- package/types/src/LocaleProfile.d.ts.map +1 -0
- package/types/src/Observable.d.ts +46 -0
- package/types/src/Observable.d.ts.map +1 -0
- package/types/src/Omittable.d.ts +50 -0
- package/types/src/Omittable.d.ts.map +1 -0
- package/types/src/Repeating.d.ts +66 -0
- package/types/src/Repeating.d.ts.map +1 -0
- package/types/src/Scalar.d.ts +67 -0
- package/types/src/Scalar.d.ts.map +1 -0
- package/types/src/ScalarType.d.ts +109 -0
- package/types/src/ScalarType.d.ts.map +1 -0
- package/types/src/WildCard.d.ts +26 -0
- package/types/src/WildCard.d.ts.map +1 -0
- package/types/src/index.d.ts +20 -0
- package/types/src/index.d.ts.map +1 -0
|
@@ -0,0 +1,608 @@
|
|
|
1
|
+
import { Scalar } from './Scalar';
|
|
2
|
+
import { ScalarType } from './ScalarType';
|
|
3
|
+
/**
|
|
4
|
+
* A self-describing, type-safe, executable function.
|
|
5
|
+
*
|
|
6
|
+
* Built-in and user-defined functions share this interface. It pairs the
|
|
7
|
+
* callable entry point (`execute`) with type metadata to guarantee type safety
|
|
8
|
+
* and auto-coerce arguments, plus locale-specific copy for UI display and validation.
|
|
9
|
+
*
|
|
10
|
+
* Formula authors encounter `IFunction` when calling another function by name
|
|
11
|
+
* at evaluation time via `FormulaContext.getFunction`, or when tooling
|
|
12
|
+
* introspects the function registry.
|
|
13
|
+
*
|
|
14
|
+
* @see {@link https://www.sheetxl.com/docs/guides/concepts/udf | UDF authoring guide} for
|
|
15
|
+
* how to create and register functions.
|
|
16
|
+
*/
|
|
17
|
+
export interface IFunction {
|
|
18
|
+
/**
|
|
19
|
+
* Execute the function
|
|
20
|
+
*/
|
|
21
|
+
execute<R = any>(...args: any[]): R;
|
|
22
|
+
/**
|
|
23
|
+
* The name of the function.
|
|
24
|
+
*/
|
|
25
|
+
getName(): string;
|
|
26
|
+
/**
|
|
27
|
+
* Contains type information needed to safely execute the function.
|
|
28
|
+
*/
|
|
29
|
+
getDeclaration(): IFunction.IDeclaration;
|
|
30
|
+
/**
|
|
31
|
+
* Returns user-facing information about the function.
|
|
32
|
+
*/
|
|
33
|
+
getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
|
|
34
|
+
/**
|
|
35
|
+
* Indicates whether the function is a built-in function.
|
|
36
|
+
*/
|
|
37
|
+
isBuiltIn(): boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Returns the execution environment this function belongs to.
|
|
40
|
+
*
|
|
41
|
+
* @remarks
|
|
42
|
+
* SheetXL exposes functions from multiple environments — the formula calculation
|
|
43
|
+
* engine and the macro/scripting runtime — through the same `IFunction` interface.
|
|
44
|
+
* The context identifier distinguishes them and determines which argument types and
|
|
45
|
+
* calling conventions apply. Returns `null` for standard formula functions.
|
|
46
|
+
*/
|
|
47
|
+
getContext(): string | null;
|
|
48
|
+
/**
|
|
49
|
+
* Type guard property. Always `true` on any `IFunction` instance.
|
|
50
|
+
*
|
|
51
|
+
* @remarks
|
|
52
|
+
* Use this to distinguish an `IFunction` from other objects at runtime without
|
|
53
|
+
* relying on `instanceof`, which does not work across module boundaries.
|
|
54
|
+
*/
|
|
55
|
+
get isIFunction(): true;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* {@inheritDoc IFunction}
|
|
59
|
+
*
|
|
60
|
+
* @see
|
|
61
|
+
* ### **Interface**
|
|
62
|
+
*
|
|
63
|
+
* {@link IFunction}
|
|
64
|
+
*/
|
|
65
|
+
export declare namespace IFunction {
|
|
66
|
+
/**
|
|
67
|
+
* Describes the type characteristics of a value used as a function parameter or return value.
|
|
68
|
+
*
|
|
69
|
+
* @remarks
|
|
70
|
+
* If `getScalarType` is `null` and `getRangeType` is `null`, the value is untyped. Not all
|
|
71
|
+
* runtimes will allow this.
|
|
72
|
+
*/
|
|
73
|
+
interface IValueType {
|
|
74
|
+
/**
|
|
75
|
+
* Indicates that the value is a single, scalar cell-compatible value.
|
|
76
|
+
*
|
|
77
|
+
* @remarks
|
|
78
|
+
* This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
|
|
79
|
+
* `'*'` is a scalar of undeclared type — still provably a scalar, unlike untyped.
|
|
80
|
+
* `ScalarType.Null` is permitted only for event handler return types.
|
|
81
|
+
*/
|
|
82
|
+
getScalarType(): ScalarType | '*' | null;
|
|
83
|
+
/**
|
|
84
|
+
* Indicates that the value is a range (multi-cell) structure.
|
|
85
|
+
*
|
|
86
|
+
* - `p`: A `RangeReference`, representing a pointer to sheet coordinates.
|
|
87
|
+
* - `r`: A `Range`, representing the actual values in the range.
|
|
88
|
+
* - `m`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
|
|
89
|
+
*
|
|
90
|
+
* If specified, the function supports multi-cell or structured range inputs.
|
|
91
|
+
*/
|
|
92
|
+
getRangeType(): 'p' | 'r' | 'm' | '*' | null;
|
|
93
|
+
/**
|
|
94
|
+
* Indicates that the value is a LAMBDA (a function value), and what it produces — which is
|
|
95
|
+
* also what the marshalled callable coerces each result to.
|
|
96
|
+
*
|
|
97
|
+
* - `'*'`: any SCALAR — each result coerces to one scalar.
|
|
98
|
+
* - a `ScalarType`: the lambda's declared return.
|
|
99
|
+
* - `'raw'`: a declared `any` return — results pass uncoerced (`REDUCE`'s accumulator).
|
|
100
|
+
* - `null`: not a lambda.
|
|
101
|
+
*
|
|
102
|
+
* @remarks
|
|
103
|
+
* A lambda is neither a value nor a location, so this is the accessor to ask before concluding
|
|
104
|
+
* anything from {@link getScalarType} — which reports `'l'` alongside a lambda for historical
|
|
105
|
+
* reasons, a spelling outside its own declared `ScalarType | '*' | null`.
|
|
106
|
+
*
|
|
107
|
+
* Applies to both parameters (`BYROW`'s `fn`) and the one return that is a lambda (`LAMBDA`).
|
|
108
|
+
*/
|
|
109
|
+
getLambda(): ScalarType | '*' | 'raw' | null;
|
|
110
|
+
/**
|
|
111
|
+
* Defines the number of array signatures after a parameter.
|
|
112
|
+
* - `0`: No array signature. The value is scalar or a single cell.
|
|
113
|
+
* - `1`: Will flatten.
|
|
114
|
+
* - `2`: Nest.
|
|
115
|
+
*/
|
|
116
|
+
getArrayDepth(): number;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Describes the parameter to a function, including its name, type,
|
|
120
|
+
* whether it's required, and if it's a rest parameter.
|
|
121
|
+
*/
|
|
122
|
+
interface IParameterType extends IValueType {
|
|
123
|
+
/**
|
|
124
|
+
* The name of the parameter.
|
|
125
|
+
*/
|
|
126
|
+
getName(): string;
|
|
127
|
+
/**
|
|
128
|
+
* The DECLARED error policy, or `null` when the parameter relies on the default.
|
|
129
|
+
*
|
|
130
|
+
* @remarks
|
|
131
|
+
* `null` is the common case and it is not "no policy": the default is REJECT in every position
|
|
132
|
+
* — scalar, lifted, flattened and range alike — so `null` means reject. There is deliberately
|
|
133
|
+
* no `'reject'` value to declare it with; a `RejectError<T>` marker existed, said exactly what
|
|
134
|
+
* `null` already says, and was removed rather than left as a second spelling.
|
|
135
|
+
*
|
|
136
|
+
* @see {@link ParameterTypeJSON.errors}
|
|
137
|
+
*/
|
|
138
|
+
getErrorPolicy(): 'accept' | 'accept-ref' | null;
|
|
139
|
+
/**
|
|
140
|
+
* Indicates whether the parameter is required.
|
|
141
|
+
*/
|
|
142
|
+
isOptional(): boolean;
|
|
143
|
+
/**
|
|
144
|
+
* The value the parameter's own initializer supplies when the argument is ABSENT, or
|
|
145
|
+
* `undefined` where none can be read.
|
|
146
|
+
*
|
|
147
|
+
* @see {@link ParameterTypeJSON.defaultValue}
|
|
148
|
+
*/
|
|
149
|
+
getDefaultValue(): Scalar | undefined;
|
|
150
|
+
/**
|
|
151
|
+
* The SLOTS of a repeating parameter group, or `null` when this parameter is not one.
|
|
152
|
+
*
|
|
153
|
+
* @remarks
|
|
154
|
+
* A repeating group is one declared parameter whose arguments arrive as a fixed-size cycle
|
|
155
|
+
* repeated N times — `SUMIFS(sum, r1, c1, r2, c2, …)` is a `[criteriaRange, criteria]` group.
|
|
156
|
+
* The returned array IS the cycle, so `getRepeatingTypes()!.length` is the period and argument
|
|
157
|
+
* `i` binds to slot `(i − prefixLength) % period`.
|
|
158
|
+
*
|
|
159
|
+
* This is a NESTED node rather than a flattened list on purpose: a flat list cannot be
|
|
160
|
+
* re-segmented, and every consumer (the site predicate, the arity check, the function wizard)
|
|
161
|
+
* needs the period to bind an argument position to a slot.
|
|
162
|
+
*
|
|
163
|
+
* A period-1 group carries a single slot with the same name as the parameter, which is what
|
|
164
|
+
* makes it display identically to a rest parameter (`array1, array2, …`).
|
|
165
|
+
*
|
|
166
|
+
* Only the LAST slot may be optional, and it means one thing: it may be omitted when there is
|
|
167
|
+
* exactly one repetition (`SORTBY(array, by1)` is legal; `SORTBY(array, by1, o1, by2)` is not).
|
|
168
|
+
*
|
|
169
|
+
* @see {@link Repeating}
|
|
170
|
+
*/
|
|
171
|
+
getRepeatingTypes(): readonly IFunction.IParameterType[] | null;
|
|
172
|
+
/**
|
|
173
|
+
* Indicates whether the parameter is a rest parameter (accepts multiple arguments).
|
|
174
|
+
*
|
|
175
|
+
* @remarks
|
|
176
|
+
* - A rest parameter can only be the last parameter in a function.
|
|
177
|
+
* - If `rest` is `true`, the parameter is also considered optional.
|
|
178
|
+
*
|
|
179
|
+
* A rest parameter is the degenerate repeating group: period 1, no minimum. Prefer
|
|
180
|
+
* {@link getRepeatingTypes} (`Repeating<T>`) when at least one argument is required.
|
|
181
|
+
*/
|
|
182
|
+
isRest(): boolean;
|
|
183
|
+
/**
|
|
184
|
+
* Indicates that the parameter is limited to a list of specific values.
|
|
185
|
+
* If the input value is a `string` it will be passed as a case-insensitive version.
|
|
186
|
+
* If the input value is a `number` it will be passed as a value against the offset.
|
|
187
|
+
*/
|
|
188
|
+
getEnums(): readonly string[];
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Describes the runtime return behavior of a function, including modifiers like
|
|
192
|
+
* async resolution, streaming data, or volatility.
|
|
193
|
+
*
|
|
194
|
+
* @remarks
|
|
195
|
+
* All return type modifiers are mutually exclusive.
|
|
196
|
+
* If none are specified, The value will be returned with no special behavior.
|
|
197
|
+
*/
|
|
198
|
+
interface IReturnType extends IValueType {
|
|
199
|
+
/**
|
|
200
|
+
* Indicates the return value is a Promise or Promise-like (i.e., async).
|
|
201
|
+
* The system will mark the result as pending and re-trigger evaluation once resolved.
|
|
202
|
+
*
|
|
203
|
+
* Can be combined with any scalar, array, or range return type.
|
|
204
|
+
*/
|
|
205
|
+
isAsync(): boolean;
|
|
206
|
+
/**
|
|
207
|
+
* Indicates whether the function produces a continuous stream of output (e.g., real-time data).
|
|
208
|
+
*
|
|
209
|
+
* @defaultValue `false`
|
|
210
|
+
*/
|
|
211
|
+
isStreaming(): boolean;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* The type-system metadata the engine reads to coerce arguments, apply broadcasting,
|
|
215
|
+
* and validate calls before execution. This is separate from {@link IDescriptor},
|
|
216
|
+
* which carries locale-specific user-facing copy.
|
|
217
|
+
*/
|
|
218
|
+
interface IDeclaration {
|
|
219
|
+
/**
|
|
220
|
+
* Named of the actual function in code.
|
|
221
|
+
*
|
|
222
|
+
* @remarks
|
|
223
|
+
* The unique identifier for the function. It has a number of rules:
|
|
224
|
+
* * The only characters allowed are: (A-Z, 0-9, _m .)
|
|
225
|
+
* * Character casing is ignored and will be converted to upper.
|
|
226
|
+
* * At least 2 characters.
|
|
227
|
+
* * Must start with a letter (A-Z).
|
|
228
|
+
* * Must be globally unique.
|
|
229
|
+
* * Must not be a reserved word.
|
|
230
|
+
* * Must not be a built-in function.
|
|
231
|
+
*/
|
|
232
|
+
getName(): string;
|
|
233
|
+
/**
|
|
234
|
+
* An array of `Parameter` objects describing the function's parameters.
|
|
235
|
+
*
|
|
236
|
+
* @remarks
|
|
237
|
+
* If not specified, the function is assumed to be volatile (its output might change even if its inputs haven't).
|
|
238
|
+
*/
|
|
239
|
+
getParameters(): readonly IParameterType[];
|
|
240
|
+
/**
|
|
241
|
+
* Metadata describing the type and dimensionality of the return value.
|
|
242
|
+
*
|
|
243
|
+
* @defaultValue `{ type: 'void' }`
|
|
244
|
+
*/
|
|
245
|
+
getReturnType(): IReturnType;
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* Locale-specific, user-facing metadata: display name, summary, category, and
|
|
249
|
+
* parameter descriptions shown in the formula bar and autocomplete UI.
|
|
250
|
+
* Separate from {@link IDeclaration}, which carries the type-system metadata
|
|
251
|
+
* the engine uses for coercion and broadcasting.
|
|
252
|
+
*/
|
|
253
|
+
interface IDescriptor {
|
|
254
|
+
/**
|
|
255
|
+
* A overwritten name for the function.
|
|
256
|
+
*/
|
|
257
|
+
getName(): string;
|
|
258
|
+
/**
|
|
259
|
+
* The function's name in the user's language (the active spreadsheet-language pack), e.g. `SUMME`
|
|
260
|
+
* for `SUM` in German — Excel's `getXxxLocal()` convention (`getFormulaLocal`/`getNumberFormatLocal`).
|
|
261
|
+
* Falls back to the canonical {@link getName} when the active language does not translate it (English
|
|
262
|
+
* is always accepted). {@link getName} stays the canonical identity; only display uses this.
|
|
263
|
+
*/
|
|
264
|
+
getNameLocal(): string;
|
|
265
|
+
/**
|
|
266
|
+
* A description of the function's purpose and usage.
|
|
267
|
+
*/
|
|
268
|
+
getSummary(): string;
|
|
269
|
+
/**
|
|
270
|
+
* A category or group to which the function belongs.
|
|
271
|
+
*/
|
|
272
|
+
getCategory(): string;
|
|
273
|
+
/**
|
|
274
|
+
* If `true` the function is available but will not be returned in search
|
|
275
|
+
* results unless hidden is specifically requested.
|
|
276
|
+
*
|
|
277
|
+
* @defaultValue 'null'
|
|
278
|
+
*
|
|
279
|
+
* @remarks
|
|
280
|
+
* * If this is a string it can be used to provide a deprecated label.
|
|
281
|
+
* * This is useful for functions that are in beta or deprecated.
|
|
282
|
+
*/
|
|
283
|
+
isDeprecated(): boolean | string;
|
|
284
|
+
/**
|
|
285
|
+
* An array of links associated with the value.
|
|
286
|
+
*/
|
|
287
|
+
getLinks(): readonly [url: string, text?: string][];
|
|
288
|
+
/**
|
|
289
|
+
* Describe each parameter in the function.
|
|
290
|
+
*
|
|
291
|
+
* @remarks
|
|
292
|
+
* Each field is optional — a parameter may declare only a description, only an example, or nothing.
|
|
293
|
+
* The keys are the declaration parameter names (see {@link IParameterType.getName}).
|
|
294
|
+
*/
|
|
295
|
+
getParameters(): Readonly<Record<string, {
|
|
296
|
+
description?: string;
|
|
297
|
+
example?: string;
|
|
298
|
+
defaultValue?: Scalar;
|
|
299
|
+
}>>;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Describes the type characteristics of a function parameter or return value.
|
|
303
|
+
*
|
|
304
|
+
* At least one of `scalar`, `range`, or `context` must be defined.
|
|
305
|
+
*/
|
|
306
|
+
interface ValueTypeJSON {
|
|
307
|
+
/**
|
|
308
|
+
* Indicates that the value is a single, scalar cell-compatible value.
|
|
309
|
+
*
|
|
310
|
+
* @remarks
|
|
311
|
+
* This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
|
|
312
|
+
* `ScalarType.Null` is permitted only for event handler return types.
|
|
313
|
+
*/
|
|
314
|
+
scalar?: ScalarType | string;
|
|
315
|
+
/**
|
|
316
|
+
* Indicates that the value is a range (multi-cell) structure.
|
|
317
|
+
*
|
|
318
|
+
* - `p`: A `RangeReference`, representing a pointer to sheet coordinates.
|
|
319
|
+
* - `r`: A `Range`, representing the actual values in the range.
|
|
320
|
+
* - `m`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
|
|
321
|
+
* - `*`: Any value — a scalar or a range. Declared `any`, and the same `*`-means-any spelling
|
|
322
|
+
* as {@link scalar} and {@link lambda}.
|
|
323
|
+
*
|
|
324
|
+
* If specified, the function supports multi-cell or structured range inputs.
|
|
325
|
+
*
|
|
326
|
+
* @remarks
|
|
327
|
+
* A `*` parameter is handed the whole argument, whatever it is. It is a VALUE position rather
|
|
328
|
+
* than a range one, which matters when another parameter causes the call to broadcast: a `*`
|
|
329
|
+
* parameter follows that broadcast and receives one element per position, where an `r`/`p`
|
|
330
|
+
* parameter would receive the whole range on every call. It never causes a broadcast itself.
|
|
331
|
+
*
|
|
332
|
+
* `IF(logical, valueIfTrue, valueIfFalse)` is the canonical shape — the branches are `*`, so
|
|
333
|
+
* a single condition returns the chosen branch untouched while an array condition selects
|
|
334
|
+
* element by element.
|
|
335
|
+
*/
|
|
336
|
+
range?: 'p' | 'r' | 'm' | '*';
|
|
337
|
+
/**
|
|
338
|
+
* Indicates that the value is a lambda function, and what the lambda RETURNS — which is also
|
|
339
|
+
* what the marshalled callable coerces each result to:
|
|
340
|
+
*
|
|
341
|
+
* - a `ScalarType`: that scalar.
|
|
342
|
+
* - `*`: any SCALAR — each result still coerces to ONE scalar (a 1×1 range/reference unwraps,
|
|
343
|
+
* an error embeds as a value, a larger shape is `#CALC!` for the whole call).
|
|
344
|
+
* - `raw`: a declared `any` return (`Lambda<Args, any>`) — results pass to the body
|
|
345
|
+
* uncoerced. `REDUCE` is the case: its accumulator threads raw, which is what makes an
|
|
346
|
+
* array/reference accumulator legal.
|
|
347
|
+
*
|
|
348
|
+
* If specified, the function supports lambda inputs.
|
|
349
|
+
*/
|
|
350
|
+
lambda?: ScalarType | '*' | 'raw';
|
|
351
|
+
/**
|
|
352
|
+
* The lambda's declared parameter count, from the `Lambda<Args, R>` tuple.
|
|
353
|
+
*
|
|
354
|
+
* Enforced by the marshaller at the call — a callable that cannot take exactly this many
|
|
355
|
+
* arguments is `#VALUE!` for the whole call, before any element runs (an eta-reduced function
|
|
356
|
+
* name defers to its own dispatch). Absent when the declaration leaves arity open
|
|
357
|
+
* (`Lambda<any[], R>`): a lambda slot in a repeating group then requires one parameter per
|
|
358
|
+
* OTHER argument of the call; anywhere else the arity is unchecked.
|
|
359
|
+
*/
|
|
360
|
+
lambdaArity?: number;
|
|
361
|
+
/**
|
|
362
|
+
* Defines the number of array signatures after a parameter.
|
|
363
|
+
* - `0`: No array signature. The value is scalar or a single cell.
|
|
364
|
+
* - `1`: Will flatten.
|
|
365
|
+
* - `2`: Nest.
|
|
366
|
+
* - `3`: Array of arrays of arrays (e.g. for 3D ranges or arrays of tables)
|
|
367
|
+
*
|
|
368
|
+
* @defaultValue `0` if no `range` is defined, otherwise `1`.
|
|
369
|
+
*/
|
|
370
|
+
arrayDepth?: number;
|
|
371
|
+
/**
|
|
372
|
+
* A short description of the value's purpose or expected usage.
|
|
373
|
+
*/
|
|
374
|
+
description?: string;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Describes the parameter to a function, including its name, type,
|
|
378
|
+
* whether it's required, and if it's a rest parameter.
|
|
379
|
+
*/
|
|
380
|
+
interface ParameterTypeJSON extends ValueTypeJSON {
|
|
381
|
+
/**
|
|
382
|
+
* The name of the parameter.
|
|
383
|
+
*/
|
|
384
|
+
name: string;
|
|
385
|
+
/**
|
|
386
|
+
* Indicates whether the parameter is required.
|
|
387
|
+
*
|
|
388
|
+
* @defaultValue true
|
|
389
|
+
*/
|
|
390
|
+
optional?: boolean;
|
|
391
|
+
/**
|
|
392
|
+
* The value the parameter's own initializer supplies when the argument is ABSENT.
|
|
393
|
+
*
|
|
394
|
+
* @remarks
|
|
395
|
+
* Descriptive rather than applied: an absent argument is never pushed, so the initializer
|
|
396
|
+
* supplies the value itself. It is recorded so help text, tooltips and completions can say
|
|
397
|
+
* "defaults to 3" without reading the source.
|
|
398
|
+
*
|
|
399
|
+
* Present for a literal initializer only. One computed from another argument
|
|
400
|
+
* (`numberS2: number = numberS`) has no value to record and leaves this undefined.
|
|
401
|
+
*
|
|
402
|
+
* Concerns the ABSENT position specifically; {@link omittedValue} covers what an argument
|
|
403
|
+
* supplied EMPTY means, which is frequently a different value.
|
|
404
|
+
*/
|
|
405
|
+
defaultValue?: Scalar;
|
|
406
|
+
/**
|
|
407
|
+
* An argument supplied EMPTY (`FIXED(1.5,)`) does not coerce to the parameter's type.
|
|
408
|
+
* Generated from the `Omittable<T>` marker.
|
|
409
|
+
*
|
|
410
|
+
* @remarks
|
|
411
|
+
* Undeclared, an omitted argument reaches the body as `0` / `false` / `""` — the right default
|
|
412
|
+
* for most functions, and what `VLOOKUP(x,r,2,)` means by an exact match. Declared, the
|
|
413
|
+
* argument arrives as {@link omittedValue} where one is given, and otherwise as `undefined`,
|
|
414
|
+
* letting the parameter's own initializer supply it so that an omitted argument means what an
|
|
415
|
+
* absent one means.
|
|
416
|
+
*
|
|
417
|
+
* A blank CELL in the same position is unaffected and continues to coerce: it is a value the
|
|
418
|
+
* caller supplied, where an omitted argument is the caller supplying none.
|
|
419
|
+
*
|
|
420
|
+
* @see {@link Omittable}
|
|
421
|
+
*/
|
|
422
|
+
omittable?: boolean;
|
|
423
|
+
/**
|
|
424
|
+
* What an argument supplied EMPTY means, where that differs from the absent default. Generated
|
|
425
|
+
* from the second type argument of `Omittable<T, V>`.
|
|
426
|
+
*
|
|
427
|
+
* @remarks
|
|
428
|
+
* Left undeclared where the two coincide, which is the common case — the parameter's own
|
|
429
|
+
* initializer then serves both positions. It is declared where a function distinguishes them:
|
|
430
|
+
* `MATCH(3,{2})` is `1` while `MATCH(3,{2},)` is `#N/A`, giving `matchType` the declaration
|
|
431
|
+
* `Omittable<number, 0> = 1`.
|
|
432
|
+
*
|
|
433
|
+
* Implies {@link omittable}. Unlike {@link defaultValue}, which only records what the
|
|
434
|
+
* initializer would supply, this value is applied by the engine.
|
|
435
|
+
*/
|
|
436
|
+
omittedValue?: Scalar;
|
|
437
|
+
/**
|
|
438
|
+
* Indicates whether the parameter is a rest parameter (accepts multiple arguments).
|
|
439
|
+
*
|
|
440
|
+
* @remarks
|
|
441
|
+
* - A rest parameter can only be the last parameter in a function.
|
|
442
|
+
* - If `rest` is `true`, the parameter is also considered optional.
|
|
443
|
+
*/
|
|
444
|
+
rest?: boolean;
|
|
445
|
+
/**
|
|
446
|
+
* The SLOTS of a repeating parameter group, generated from the `Repeating<T>` marker.
|
|
447
|
+
*
|
|
448
|
+
* @remarks
|
|
449
|
+
* Present iff this parameter IS a group; its own `scalar`/`range`/`arrayDepth` are then unset
|
|
450
|
+
* and the slots carry the types. The array length is the group's PERIOD. Cannot be combined
|
|
451
|
+
* with {@link rest}.
|
|
452
|
+
*
|
|
453
|
+
* @see {@link IParameterType.getRepeatingTypes}
|
|
454
|
+
*/
|
|
455
|
+
repeating?: ParameterTypeJSON[];
|
|
456
|
+
/**
|
|
457
|
+
* The DECLARED error policy, generated from the `AcceptError<T>` / `AcceptRefError<T>`
|
|
458
|
+
* parameter markers.
|
|
459
|
+
*
|
|
460
|
+
* - `'accept'`: the body receives `FormulaError` values raw.
|
|
461
|
+
* - `'accept-ref'`: per argument SHAPE — reject for a direct/computed argument, accept for a
|
|
462
|
+
* reference-shaped one. Resolved to one of the two before any coercion runs, so nothing
|
|
463
|
+
* downstream sees this value.
|
|
464
|
+
*
|
|
465
|
+
* OMITTED is the default and the default is REJECT (ErrorPolicy.ts): never call the body — the
|
|
466
|
+
* error propagates with its identity (scalar argument), becomes an error member of the output
|
|
467
|
+
* (lifted member), or short-circuits on the first error in row-major order (range/array
|
|
468
|
+
* member). Only a `FormulaError.Known`-typed parameter receives without a marker, because the
|
|
469
|
+
* type declares it. There is no `'reject'` value: it would say what omitting this says.
|
|
470
|
+
*/
|
|
471
|
+
errors?: 'accept' | 'accept-ref';
|
|
472
|
+
/**
|
|
473
|
+
* Indicates whether the function requires the address of the calling cell as an input.
|
|
474
|
+
* Cannot be combined with `stream`.
|
|
475
|
+
*
|
|
476
|
+
* @defaultValue `false`
|
|
477
|
+
*/
|
|
478
|
+
enums?: string[];
|
|
479
|
+
}
|
|
480
|
+
/**
|
|
481
|
+
* Describes the runtime return behavior of a function, including modifiers like
|
|
482
|
+
* async resolution, streaming data, or volatility.
|
|
483
|
+
*
|
|
484
|
+
* @remarks
|
|
485
|
+
* If none are specified, The value will be returned with no special behavior.
|
|
486
|
+
*/
|
|
487
|
+
interface ReturnTypeJSON extends ValueTypeJSON {
|
|
488
|
+
/**
|
|
489
|
+
* Indicates the return value is a Promise or Promise-like (i.e., async).
|
|
490
|
+
* The system will mark the result as pending and re-trigger evaluation once resolved.
|
|
491
|
+
*
|
|
492
|
+
* Can be combined with any scalar, array, or range return type.
|
|
493
|
+
*/
|
|
494
|
+
async?: boolean;
|
|
495
|
+
/**
|
|
496
|
+
* Indicates whether the function produces a continuous stream of output (e.g., real-time data).
|
|
497
|
+
*
|
|
498
|
+
* @defaultValue `false`
|
|
499
|
+
*/
|
|
500
|
+
stream?: boolean;
|
|
501
|
+
}
|
|
502
|
+
/**
|
|
503
|
+
* Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
|
|
504
|
+
*/
|
|
505
|
+
interface DeclarationJSON {
|
|
506
|
+
/** @inheritdoc IFunction.IDeclaration.getName */
|
|
507
|
+
name: string;
|
|
508
|
+
/** @inheritdoc IFunction.IDeclaration.getReturnType */
|
|
509
|
+
returnType?: ReturnTypeJSON;
|
|
510
|
+
/** @inheritdoc IFunction.IDeclaration.getParameters */
|
|
511
|
+
parameters?: ParameterTypeJSON[];
|
|
512
|
+
/**
|
|
513
|
+
* Describes the execution context required by the function.
|
|
514
|
+
*
|
|
515
|
+
* Contexts fall into two categories:
|
|
516
|
+
*
|
|
517
|
+
* - **Macro contexts**: Used by macro-style functions to access parts of the document or selection:
|
|
518
|
+
* - `'Workbook'`: The entire workbook
|
|
519
|
+
* - `'Sheet'`: A single sheet
|
|
520
|
+
* - `'Range'`: A selected sheet range
|
|
521
|
+
* - `'Ranges'`: Multiple selected ranges
|
|
522
|
+
*
|
|
523
|
+
* - **Calculation context**: Used by formula functions like `OFFSET` or `INDIRECT`
|
|
524
|
+
* that need access to evaluation position or sheet metadata during calculation.
|
|
525
|
+
* This context is available in headless or worker environments.
|
|
526
|
+
*
|
|
527
|
+
* @remarks
|
|
528
|
+
* * If omitted, the function is consider a FormulaFunction.
|
|
529
|
+
* * If a function has a context it will be passed as the first argument to `execute`.
|
|
530
|
+
* * If the context is `IFunction.Calculation` then the function must return a value.
|
|
531
|
+
* * If the context is not `IFunction.Calculation` then the function must return `void` or a cleanup function.
|
|
532
|
+
*/
|
|
533
|
+
context?: string;
|
|
534
|
+
/**
|
|
535
|
+
* Additional metadata about the function's behavior or requirements.
|
|
536
|
+
*/
|
|
537
|
+
behavior?: BehaviorJSON;
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* Contains user information about the function.
|
|
541
|
+
*
|
|
542
|
+
* @remarks
|
|
543
|
+
* This is locale specific.
|
|
544
|
+
*/
|
|
545
|
+
interface DescriptorJSON {
|
|
546
|
+
/**
|
|
547
|
+
* A overwritten name for the function.
|
|
548
|
+
*
|
|
549
|
+
* @defaultValue The name of the function in code.
|
|
550
|
+
*/
|
|
551
|
+
name?: string;
|
|
552
|
+
/**
|
|
553
|
+
* The function name in the user's language (spreadsheet-language pack), e.g. `SUMME`. Snapshot
|
|
554
|
+
* for the language the descriptor was resolved for; absent ⇒ falls back to {@link name}.
|
|
555
|
+
*/
|
|
556
|
+
nameLocal?: string;
|
|
557
|
+
/**
|
|
558
|
+
* A more detailed explanation of the function's purpose and usage.
|
|
559
|
+
*/
|
|
560
|
+
summary?: string;
|
|
561
|
+
/**
|
|
562
|
+
* A category or group to which the function belongs.
|
|
563
|
+
*
|
|
564
|
+
* @defaultValue 'custom'
|
|
565
|
+
*/
|
|
566
|
+
category?: string;
|
|
567
|
+
/**
|
|
568
|
+
* If `true` or has a string value then is usable in calculation but not provided in the ui.
|
|
569
|
+
*
|
|
570
|
+
* @defaultValue 'null'
|
|
571
|
+
*
|
|
572
|
+
* @remarks
|
|
573
|
+
* * If this is a string it can be used to provide a deprecated label.
|
|
574
|
+
* * This is useful for functions that are in beta or deprecated.
|
|
575
|
+
*/
|
|
576
|
+
deprecated?: string | boolean;
|
|
577
|
+
/**
|
|
578
|
+
* An array of links associated with the value.
|
|
579
|
+
*/
|
|
580
|
+
links?: [url: string, text?: string][];
|
|
581
|
+
/**
|
|
582
|
+
* Describe each parameter in the function.
|
|
583
|
+
*/
|
|
584
|
+
parameters?: Record<string, {
|
|
585
|
+
description: string;
|
|
586
|
+
example?: string;
|
|
587
|
+
defaultValue?: Scalar;
|
|
588
|
+
}>;
|
|
589
|
+
}
|
|
590
|
+
/**
|
|
591
|
+
* Contains extended metadata about a function that is not be directly inferable from the code itself.
|
|
592
|
+
*/
|
|
593
|
+
interface BehaviorJSON {
|
|
594
|
+
/**
|
|
595
|
+
* If `true` this function will be called on load unless scripts are disabled.
|
|
596
|
+
*
|
|
597
|
+
* @defaultValue `false`.
|
|
598
|
+
*/
|
|
599
|
+
default?: boolean;
|
|
600
|
+
/**
|
|
601
|
+
* Indicates whether the function's execution can be canceled by the user.
|
|
602
|
+
*
|
|
603
|
+
* @defaultValue false
|
|
604
|
+
*/
|
|
605
|
+
cancelable?: boolean;
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
//# sourceMappingURL=IFunction.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"IFunction.d.ts","sourceRoot":"","sources":["../../../src/IFunction.ts"],"names":[],"mappings":"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"}
|