@sheetxl/primitives 0.7.22 → 0.7.23-beta.2
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
package/types/index.d.ts
CHANGED
|
@@ -1,1622 +1,2 @@
|
|
|
1
|
-
|
|
2
|
-
export
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* An error returned from a formula calculation.
|
|
6
|
-
*
|
|
7
|
-
* Standard Error Codes
|
|
8
|
-
* 0. #PARSE! If the formula contains a syntax error. (Not part of the OOXML spec.)
|
|
9
|
-
* 1. #NULL! Intersection of two ranges that don't intersect.
|
|
10
|
-
* 2. #DIV/0! Division by zero.
|
|
11
|
-
* 3. #VALUE! Wrong type of argument or operand.
|
|
12
|
-
* 4. #REF! Invalid cell reference.
|
|
13
|
-
* 5. #NAME? Unrecognized name (function, named range, etc.).
|
|
14
|
-
* 6. #NUM! Invalid numeric value.
|
|
15
|
-
* 7. #N/A Value not available.
|
|
16
|
-
* # Office 365
|
|
17
|
-
* 8. #GETTING_DATA This is raised for long running calculations that are not yet complete.
|
|
18
|
-
*
|
|
19
|
-
* (Saves as #N/A to disk)
|
|
20
|
-
* 9. #SPILL! Formula's output range is blocked.
|
|
21
|
-
*
|
|
22
|
-
* SpillErrorScalarSubType | "Unknown" | "Collision" | "IndeterminateSize" | "WorksheetEdge" | "OutOfMemoryWhileCalc" | "Table" | "MergedCell"
|
|
23
|
-
* # Office 2023
|
|
24
|
-
* 10. #CONNECT! This occurs when a data type is used that is not currently supported in this version of Excel.
|
|
25
|
-
* 11. #BLOCKED! Indicates that an action or feature is blocked, possibly due to security settings, protected view, or other restrictions. Often related to online features, external links, or macros.
|
|
26
|
-
* 12. #UNKNOWN! May be returned in the case of a protected workbook.
|
|
27
|
-
* 13. #FIELD! Invalid field name for a data type.
|
|
28
|
-
* 14. #CALC! Calculation error (often with LET or LAMBDA or a splitted array).
|
|
29
|
-
* 15.
|
|
30
|
-
* 16. #BUSY! When waiting on an external data source to return data.
|
|
31
|
-
* 17.
|
|
32
|
-
* 18.
|
|
33
|
-
* 19. #PYTHON! The Python interpreter returned the following error: Unexpected failure.
|
|
34
|
-
* 20. #TIMEOUT! Indicates that the operation took too long to complete.
|
|
35
|
-
*/
|
|
36
|
-
export declare namespace FormulaError {
|
|
37
|
-
const Code: {
|
|
38
|
-
readonly Parse: 0;
|
|
39
|
-
readonly Null: 1;
|
|
40
|
-
readonly Div0: 2;
|
|
41
|
-
readonly Value: 3;
|
|
42
|
-
readonly Ref: 4;
|
|
43
|
-
readonly Name: 5;
|
|
44
|
-
readonly Num: 6;
|
|
45
|
-
readonly NA: 7;
|
|
46
|
-
readonly GettingData: 8;
|
|
47
|
-
readonly Spill: 9;
|
|
48
|
-
readonly Connect: 10;
|
|
49
|
-
readonly Blocked: 11;
|
|
50
|
-
readonly Unknown: 12;
|
|
51
|
-
readonly Field: 13;
|
|
52
|
-
readonly Calc: 14;
|
|
53
|
-
readonly Busy: 16;
|
|
54
|
-
readonly Python: 19;
|
|
55
|
-
readonly Timeout: 20;
|
|
56
|
-
};
|
|
57
|
-
const Label: {
|
|
58
|
-
readonly Parse: "#PARSE!";
|
|
59
|
-
readonly Null: "#NULL!";
|
|
60
|
-
readonly Div0: "#DIV/0!";
|
|
61
|
-
readonly Value: "#VALUE!";
|
|
62
|
-
readonly Ref: "#REF!";
|
|
63
|
-
readonly Name: "#NAME?";
|
|
64
|
-
readonly Num: "#NUM!";
|
|
65
|
-
readonly NA: "#N/A";
|
|
66
|
-
readonly GettingData: "#GETTING_DATA";
|
|
67
|
-
readonly Spill: "#SPILL!";
|
|
68
|
-
readonly Connect: "#CONNECT!";
|
|
69
|
-
readonly Blocked: "#BLOCKED!";
|
|
70
|
-
readonly Unknown: "#UNKNOWN!";
|
|
71
|
-
readonly Field: "#FIELD!";
|
|
72
|
-
readonly Calc: "#CALC!";
|
|
73
|
-
readonly Busy: "#BUSY!";
|
|
74
|
-
readonly Python: "#PYTHON!";
|
|
75
|
-
readonly Timeout: "#TIMEOUT!";
|
|
76
|
-
};
|
|
77
|
-
export class Known extends Error {
|
|
78
|
-
protected _label: string;
|
|
79
|
-
protected _code: number;
|
|
80
|
-
protected details: any;
|
|
81
|
-
constructor(code: number, label: string, message?: string, details?: ErrorOptions);
|
|
82
|
-
static code: number;
|
|
83
|
-
get isFormulaError(): true;
|
|
84
|
-
getLabel(): string;
|
|
85
|
-
getCode(): number;
|
|
86
|
-
/**
|
|
87
|
-
* Return true if two errors are same.
|
|
88
|
-
*
|
|
89
|
-
* @param other any object to compare.
|
|
90
|
-
* @returns if two errors are the same type.
|
|
91
|
-
*/
|
|
92
|
-
equals(other: any): boolean;
|
|
93
|
-
get [Symbol.toStringTag](): string;
|
|
94
|
-
toString(): string;
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* #Parse!
|
|
98
|
-
*
|
|
99
|
-
* @remarks
|
|
100
|
-
* Not part of the OOXML spec.
|
|
101
|
-
*/
|
|
102
|
-
export class Parse extends Known {
|
|
103
|
-
constructor(message?: string, details?: ErrorOptions & {
|
|
104
|
-
line?: number;
|
|
105
|
-
column?: number;
|
|
106
|
-
offset?: number;
|
|
107
|
-
length?: number;
|
|
108
|
-
});
|
|
109
|
-
static code: number;
|
|
110
|
-
getDetails(): {
|
|
111
|
-
line: number;
|
|
112
|
-
column: number;
|
|
113
|
-
offset: number;
|
|
114
|
-
length: number;
|
|
115
|
-
};
|
|
116
|
-
}
|
|
117
|
-
/**
|
|
118
|
-
* When a reference is provided that doesn't exist. Usually an invalid range specification.
|
|
119
|
-
* =SUM(G5 G23)
|
|
120
|
-
*/
|
|
121
|
-
export class Null extends Known {
|
|
122
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
123
|
-
static code: number;
|
|
124
|
-
}
|
|
125
|
-
/**
|
|
126
|
-
* Divide by Zero.
|
|
127
|
-
* * ex: The formula or function used is divided by zero.
|
|
128
|
-
*/
|
|
129
|
-
export class Div0 extends Known {
|
|
130
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
131
|
-
static code: number;
|
|
132
|
-
}
|
|
133
|
-
/**
|
|
134
|
-
* Wrong argument in the formula. For example a string was given but a number was
|
|
135
|
-
* * ex: The row index number is too small. Specify a number great than or equal to 1.
|
|
136
|
-
*/
|
|
137
|
-
export class Value extends Known {
|
|
138
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
139
|
-
static code: number;
|
|
140
|
-
}
|
|
141
|
-
/**
|
|
142
|
-
* Reference was remove due to a move or delete of cells.
|
|
143
|
-
* * ex: Moving or deleting cells caused an invalid cell reference, or function is returning reference error.
|
|
144
|
-
*/
|
|
145
|
-
export class Ref extends Known {
|
|
146
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
147
|
-
static code: number;
|
|
148
|
-
}
|
|
149
|
-
/**
|
|
150
|
-
* A formula has references that can not be resolved or may contain parsing errors.
|
|
151
|
-
* * ex: The formula contains unrecognized text.
|
|
152
|
-
*/
|
|
153
|
-
export class Name extends Known {
|
|
154
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
155
|
-
static code: number;
|
|
156
|
-
}
|
|
157
|
-
/**
|
|
158
|
-
* Invalid number.
|
|
159
|
-
*/
|
|
160
|
-
export class Num extends Known {
|
|
161
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
162
|
-
static code: number;
|
|
163
|
-
}
|
|
164
|
-
/**
|
|
165
|
-
* Not available.
|
|
166
|
-
*
|
|
167
|
-
* @remarks
|
|
168
|
-
* Indicates the data needed is not available.
|
|
169
|
-
*/
|
|
170
|
-
export class NA extends Known {
|
|
171
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
172
|
-
static code: number;
|
|
173
|
-
}
|
|
174
|
-
/**
|
|
175
|
-
* Getting Data.
|
|
176
|
-
*/
|
|
177
|
-
export class GettingData extends Known {
|
|
178
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
179
|
-
static code: number;
|
|
180
|
-
}
|
|
181
|
-
/**
|
|
182
|
-
* Spill.
|
|
183
|
-
*/
|
|
184
|
-
export class Spill extends Known {
|
|
185
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
186
|
-
static code: number;
|
|
187
|
-
}
|
|
188
|
-
/**
|
|
189
|
-
* Connect.
|
|
190
|
-
*/
|
|
191
|
-
export class Connect extends Known {
|
|
192
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
193
|
-
static code: number;
|
|
194
|
-
}
|
|
195
|
-
/**
|
|
196
|
-
* Blocked.
|
|
197
|
-
*/
|
|
198
|
-
export class Blocked extends Known {
|
|
199
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
200
|
-
static code: number;
|
|
201
|
-
}
|
|
202
|
-
/**
|
|
203
|
-
* Unknown.
|
|
204
|
-
*/
|
|
205
|
-
export class Unknown extends Known {
|
|
206
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
207
|
-
static code: number;
|
|
208
|
-
}
|
|
209
|
-
/**
|
|
210
|
-
* Field does not exist.
|
|
211
|
-
*
|
|
212
|
-
* @remarks
|
|
213
|
-
* Indicates a field or property being access is not available.
|
|
214
|
-
*/
|
|
215
|
-
export class Field extends Known {
|
|
216
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
217
|
-
static code: number;
|
|
218
|
-
}
|
|
219
|
-
/**
|
|
220
|
-
* Calc.
|
|
221
|
-
*/
|
|
222
|
-
export class Calc extends Known {
|
|
223
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
224
|
-
static code: number;
|
|
225
|
-
}
|
|
226
|
-
/**
|
|
227
|
-
* Busy.
|
|
228
|
-
*/
|
|
229
|
-
export class Busy extends Known {
|
|
230
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
231
|
-
static code: number;
|
|
232
|
-
}
|
|
233
|
-
/**
|
|
234
|
-
* Python.
|
|
235
|
-
*/
|
|
236
|
-
export class Python extends Known {
|
|
237
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
238
|
-
static code: number;
|
|
239
|
-
}
|
|
240
|
-
/**
|
|
241
|
-
* Unknown.
|
|
242
|
-
*/
|
|
243
|
-
export class Timeout extends Known {
|
|
244
|
-
constructor(message?: string, details?: ErrorOptions);
|
|
245
|
-
static code: number;
|
|
246
|
-
}
|
|
247
|
-
}
|
|
248
|
-
|
|
249
|
-
export declare namespace FormulaError {
|
|
250
|
-
const BuiltIn: {
|
|
251
|
-
readonly Parse: Parse;
|
|
252
|
-
readonly Null: Null;
|
|
253
|
-
readonly Div0: Div0;
|
|
254
|
-
readonly Value: Value;
|
|
255
|
-
readonly Ref: Ref;
|
|
256
|
-
readonly Name: Name;
|
|
257
|
-
readonly Num: Num;
|
|
258
|
-
readonly NA: NA;
|
|
259
|
-
readonly GettingData: GettingData;
|
|
260
|
-
readonly Spill: Spill;
|
|
261
|
-
readonly Connect: Connect;
|
|
262
|
-
readonly Blocked: Blocked;
|
|
263
|
-
readonly Unknown: Unknown;
|
|
264
|
-
readonly Field: Field;
|
|
265
|
-
readonly Calc: Calc;
|
|
266
|
-
readonly Busy: Busy;
|
|
267
|
-
readonly Python: Python;
|
|
268
|
-
readonly Timeout: Timeout;
|
|
269
|
-
};
|
|
270
|
-
const getBuiltInByLabel: (label: string) => FormulaError.Known;
|
|
271
|
-
const newTypedError: (label: string | number, message?: string, details?: ErrorOptions) => FormulaError.Known;
|
|
272
|
-
const getBuiltInById: (id: number) => FormulaError.Known;
|
|
273
|
-
}
|
|
274
|
-
|
|
275
|
-
/**
|
|
276
|
-
* Provides the context for formula evaluation functions.
|
|
277
|
-
*/
|
|
278
|
-
export declare interface IFormulaContext {
|
|
279
|
-
/**
|
|
280
|
-
* Return the current location in the sheet.
|
|
281
|
-
*/
|
|
282
|
-
getPosition(): Readonly<IRange.CellCoords>;
|
|
283
|
-
/**
|
|
284
|
-
* Create a range from a materialized 2D array.
|
|
285
|
-
*
|
|
286
|
-
* @param value The value to create a range from. This can be a single value or a 2D array.
|
|
287
|
-
* @param isLiteral If `true`, the range will be treated as a literal value.
|
|
288
|
-
* @returns An IRange representing the value.
|
|
289
|
-
*/
|
|
290
|
-
getRange(value: Scalar | Scalar[][], isLiteral?: boolean): IRange;
|
|
291
|
-
/**
|
|
292
|
-
* Retrieves a value from the sheet.
|
|
293
|
-
*
|
|
294
|
-
* @param row The row where the value is located.
|
|
295
|
-
* @param column The column where the value is located.
|
|
296
|
-
* @returns The value at the specified row and column, or `null` if no value exists.
|
|
297
|
-
*/
|
|
298
|
-
getValueAt(row: number, column: number): Scalar | null;
|
|
299
|
-
/**
|
|
300
|
-
* Returns a spill reference at a location if it exists.
|
|
301
|
-
*
|
|
302
|
-
* @param row The row where the spill starts.
|
|
303
|
-
* @param column The column where the spill starts.
|
|
304
|
-
* @returns An IReferenceRange if a spill exists at the location, otherwise `null`.
|
|
305
|
-
*/
|
|
306
|
-
getSpillAt(row: number, column: number): IReferenceRange | null;
|
|
307
|
-
/**
|
|
308
|
-
* Used for functions that return RangeReferences such as
|
|
309
|
-
* INDIRECT and OFFSET and SUMIF.
|
|
310
|
-
*
|
|
311
|
-
* @param coords The coordinates or a string of the range to get.
|
|
312
|
-
* @param r1c1 If `true`, the coordinates are in R1C1 format.
|
|
313
|
-
* @returns An IReferenceRange representing the range.
|
|
314
|
-
* @throws Error #REF! if unable to parse the range.
|
|
315
|
-
*
|
|
316
|
-
* @remarks
|
|
317
|
-
* * **PERFORMANCE**
|
|
318
|
-
* Calling this method wil create a dynamic dependency on this range if not in the original inputs.
|
|
319
|
-
* * It is recommended to use this sparingly.
|
|
320
|
-
* * If coords is a string it will be parsed but named references are not supported.
|
|
321
|
-
*/
|
|
322
|
-
getReference(coords: Readonly<IRange.Coords> | string, r1c1?: boolean): IReferenceRange<any>;
|
|
323
|
-
/**
|
|
324
|
-
* Returns a formatted value using the number formatting rules.
|
|
325
|
-
*
|
|
326
|
-
* @param formatText The format to apply to the value.
|
|
327
|
-
* @param value The value to format.
|
|
328
|
-
* @returns A formatted string of the value.
|
|
329
|
-
*/
|
|
330
|
-
getNumberFormat(formatText: string, value: Scalar): string | null;
|
|
331
|
-
/**
|
|
332
|
-
* Returns the entire range of the sheet useful for validating range is to large.
|
|
333
|
-
*/
|
|
334
|
-
getEntireCoords(): IRange.Coords;
|
|
335
|
-
/**
|
|
336
|
-
* Returns a formula string or null if no formula exists.
|
|
337
|
-
*
|
|
338
|
-
* @param row The row where the formula is located.
|
|
339
|
-
* @param column The column where the formula is located.
|
|
340
|
-
* @returns The formula string at the specified row and column, or `null` if no formula exists.
|
|
341
|
-
*/
|
|
342
|
-
getFormulaAt(row: number, column: number): string | null;
|
|
343
|
-
/**
|
|
344
|
-
* Returns a formula string or null if no formula exists.
|
|
345
|
-
*
|
|
346
|
-
* @param sheetName The name of the sheet. If not provided the current sheet is used.
|
|
347
|
-
* @returns -1 if the sheet does not exist.
|
|
348
|
-
*/
|
|
349
|
-
getSheetIndex(sheetName?: string): number;
|
|
350
|
-
/**
|
|
351
|
-
* Returns the number of sheets in the workbook.
|
|
352
|
-
*/
|
|
353
|
-
getSheetCount(): number | null;
|
|
354
|
-
/**
|
|
355
|
-
* Calling this will mark the function as volatile.
|
|
356
|
-
*
|
|
357
|
-
* @remarks
|
|
358
|
-
* * Volatile functions will be re-evaluated on the next calculation.
|
|
359
|
-
* * Functions may also be statically marked as volatile in the engine.
|
|
360
|
-
*/
|
|
361
|
-
markVolatile(): void;
|
|
362
|
-
/**
|
|
363
|
-
* Provide a hint to the UI to format the return results.
|
|
364
|
-
*
|
|
365
|
-
* @param numFmt The number format to apply to the results.
|
|
366
|
-
*
|
|
367
|
-
* @remarks
|
|
368
|
-
* * The UI will generally only format results if the user has not already formatted the area.
|
|
369
|
-
* * If a range is returned all values will be formatted with the same format.
|
|
370
|
-
*/
|
|
371
|
-
formatResults(numFmt: string): void;
|
|
372
|
-
/**
|
|
373
|
-
* Returns the address of the current sheet.
|
|
374
|
-
*
|
|
375
|
-
* @param coords The coordinates to get the address for. If not provided the current position is used.
|
|
376
|
-
* @param r1c1 If `true`, the address will be in R1C1 format. Default is `false` (A1 format).
|
|
377
|
-
*/
|
|
378
|
-
getAddress(coords?: Readonly<IRange.FixableCoords | IRange.FixableCellCoords>, r1c1?: boolean): string;
|
|
379
|
-
/**
|
|
380
|
-
* Returns `true` if the value is a valid date.
|
|
381
|
-
*
|
|
382
|
-
* @param value Any value to check.
|
|
383
|
-
*/
|
|
384
|
-
isValidDate(value: any): boolean;
|
|
385
|
-
/**
|
|
386
|
-
* Parsed text as a date and time.
|
|
387
|
-
*
|
|
388
|
-
* @param text The text to parse as a date and time.
|
|
389
|
-
* @param requireDate If `true`, the text must contain a date component.
|
|
390
|
-
* @returns The OADate value or null if the text could not be parsed.
|
|
391
|
-
*/
|
|
392
|
-
parseAsDateTime(text: string, requireDate?: boolean): number | null;
|
|
393
|
-
/**
|
|
394
|
-
* Returns a date from an OADate value. This is used for date calculations.
|
|
395
|
-
*
|
|
396
|
-
* @param oaDate A serialized date as a number.
|
|
397
|
-
*/
|
|
398
|
-
fromOADate(oaDate: number): Date;
|
|
399
|
-
/**
|
|
400
|
-
* Returns an OADate value from a date. This is used for date calculations.
|
|
401
|
-
*
|
|
402
|
-
* @param date A date as a javascript object.
|
|
403
|
-
*/
|
|
404
|
-
toOADate(date: Date): number;
|
|
405
|
-
/**
|
|
406
|
-
* Returns a function.
|
|
407
|
-
*
|
|
408
|
-
* @param name The name of the function.
|
|
409
|
-
*
|
|
410
|
-
* @remarks
|
|
411
|
-
* Case-insensitive
|
|
412
|
-
*/
|
|
413
|
-
getFunction(name: string): IFunction | null;
|
|
414
|
-
/**
|
|
415
|
-
* For introspecting the current runtime.
|
|
416
|
-
*
|
|
417
|
-
* @remarks
|
|
418
|
-
* This is generally used for debugging but the built-in `INFO` function also makes use of this.
|
|
419
|
-
*/
|
|
420
|
-
getRuntime(): IRuntime;
|
|
421
|
-
}
|
|
422
|
-
|
|
423
|
-
/**
|
|
424
|
-
* Provides interfaces for defining and working with functions at runtime, including metadata for
|
|
425
|
-
* function declarations and execution scripts.
|
|
426
|
-
*/
|
|
427
|
-
export declare interface IFunction {
|
|
428
|
-
/**
|
|
429
|
-
* Execute the function
|
|
430
|
-
*/
|
|
431
|
-
execute<T = any>(...args: any[]): T;
|
|
432
|
-
/**
|
|
433
|
-
* The name of the function.
|
|
434
|
-
*/
|
|
435
|
-
getName(): string;
|
|
436
|
-
/**
|
|
437
|
-
* Contains type information needed to safely execute the function.
|
|
438
|
-
*/
|
|
439
|
-
getDeclaration(): IFunction.IDeclaration;
|
|
440
|
-
/**
|
|
441
|
-
* Returns user-facing information about the function.
|
|
442
|
-
*/
|
|
443
|
-
getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
|
|
444
|
-
/**
|
|
445
|
-
* Indicates whether the function is a built-in function.
|
|
446
|
-
*/
|
|
447
|
-
isBuiltIn(): boolean;
|
|
448
|
-
/**
|
|
449
|
-
* Returns the context in which the function is executed.
|
|
450
|
-
*
|
|
451
|
-
* @remarks
|
|
452
|
-
* Not all functions have a context.
|
|
453
|
-
*/
|
|
454
|
-
getContext(): string | null;
|
|
455
|
-
/**
|
|
456
|
-
* For runtime reflection.
|
|
457
|
-
*/
|
|
458
|
-
get isIFunction(): true;
|
|
459
|
-
}
|
|
460
|
-
|
|
461
|
-
/**
|
|
462
|
-
* {@inheritDoc IFunction}
|
|
463
|
-
*
|
|
464
|
-
* @see
|
|
465
|
-
* ### **Interface**
|
|
466
|
-
*
|
|
467
|
-
* {@link IFunction}
|
|
468
|
-
*/
|
|
469
|
-
export declare namespace IFunction {
|
|
470
|
-
/**
|
|
471
|
-
* Describes the type characteristics of a function parameter or return value.
|
|
472
|
-
*
|
|
473
|
-
* At least one of `Scalar`, `IRange`, or `Context` must be defined.
|
|
474
|
-
*/
|
|
475
|
-
export interface IValueType {
|
|
476
|
-
/**
|
|
477
|
-
* Indicates that the value is a single, scalar cell-compatible value.
|
|
478
|
-
*
|
|
479
|
-
* @remarks
|
|
480
|
-
* This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
|
|
481
|
-
* `ScalarType.Null` is permitted only for event handler return types.
|
|
482
|
-
*/
|
|
483
|
-
getScalarType(): ScalarType;
|
|
484
|
-
/**
|
|
485
|
-
* Indicates that the value is a range (multi-cell) structure.
|
|
486
|
-
*
|
|
487
|
-
* - `r`: A `RangeReference`, representing a pointer to sheet coordinates.
|
|
488
|
-
* - `l`: A `RangeLiteral`, representing the actual values in the range.
|
|
489
|
-
* - `a`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
|
|
490
|
-
*
|
|
491
|
-
* If specified, the function supports multi-cell or structured range inputs.
|
|
492
|
-
*/
|
|
493
|
-
getRangeType(): 'r' | 'l' | 'a';
|
|
494
|
-
/**
|
|
495
|
-
* Defines the number of array signatures after a parameter.
|
|
496
|
-
* - `0`: No array signature. The value is scalar or a single cell.
|
|
497
|
-
* - `1`: Will flatten.
|
|
498
|
-
* - `2`: Nest.
|
|
499
|
-
*/
|
|
500
|
-
getArrayDepth(): number;
|
|
501
|
-
}
|
|
502
|
-
/**
|
|
503
|
-
* Describes the parameter to a function, including its name, type,
|
|
504
|
-
* whether it's required, and if it's a rest parameter.
|
|
505
|
-
*/
|
|
506
|
-
export interface IParameterType extends IValueType {
|
|
507
|
-
/**
|
|
508
|
-
* The name of the parameter.
|
|
509
|
-
*/
|
|
510
|
-
getName(): string;
|
|
511
|
-
/**
|
|
512
|
-
* Indicates whether the parameter is required.
|
|
513
|
-
*/
|
|
514
|
-
isOptional(): boolean;
|
|
515
|
-
/**
|
|
516
|
-
* Indicates whether the parameter is a rest parameter (accepts multiple arguments).
|
|
517
|
-
*
|
|
518
|
-
* @remarks
|
|
519
|
-
* - A rest parameter can only be the last parameter in a function.
|
|
520
|
-
* - If `rest` is `true`, the parameter is also considered optional.
|
|
521
|
-
*/
|
|
522
|
-
isRest(): boolean;
|
|
523
|
-
/**
|
|
524
|
-
* Indicates whether the function requires the address of the calling cell as an input.
|
|
525
|
-
* Cannot be combined with `stream`.
|
|
526
|
-
*/
|
|
527
|
-
getEnums(): readonly string[];
|
|
528
|
-
}
|
|
529
|
-
/**
|
|
530
|
-
* Describes the runtime return behavior of a function, including modifiers like
|
|
531
|
-
* async resolution, streaming data, or volatility.
|
|
532
|
-
*
|
|
533
|
-
* @remarks
|
|
534
|
-
* All return type modifiers are mutually exclusive.
|
|
535
|
-
* If none are specified, The value will be returned with no special behavior.
|
|
536
|
-
*/
|
|
537
|
-
export interface IReturnType extends IValueType {
|
|
538
|
-
/**
|
|
539
|
-
* Indicates the return value is a Promise or Promise-like (i.e., async).
|
|
540
|
-
* The system will mark the result as pending and re-trigger evaluation once resolved.
|
|
541
|
-
*
|
|
542
|
-
* Can be combined with any scalar, array, or range return type.
|
|
543
|
-
*/
|
|
544
|
-
isAsync(): boolean;
|
|
545
|
-
/**
|
|
546
|
-
* Indicates whether the function produces a continuous stream of output (e.g., real-time data).
|
|
547
|
-
*
|
|
548
|
-
* @defaultValue `false`
|
|
549
|
-
*/
|
|
550
|
-
isStreaming(): boolean;
|
|
551
|
-
}
|
|
552
|
-
/**
|
|
553
|
-
* Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
|
|
554
|
-
*/
|
|
555
|
-
export interface IDeclaration {
|
|
556
|
-
/**
|
|
557
|
-
* Named of the actual function in code.
|
|
558
|
-
*
|
|
559
|
-
* @remarks
|
|
560
|
-
* The unique identifier for the function. It has a number of rules:
|
|
561
|
-
* * The only characters allowed are: (A-Z, 0-9, _m .)
|
|
562
|
-
* * Character casing is ignored and will be converted to upper.
|
|
563
|
-
* * At least 2 characters.
|
|
564
|
-
* * Must start with a letter (A-Z).
|
|
565
|
-
* * Must be globally unique.
|
|
566
|
-
* * Must not be a reserved word.
|
|
567
|
-
* * Must not be a built-in function.
|
|
568
|
-
*/
|
|
569
|
-
getName(): string;
|
|
570
|
-
/**
|
|
571
|
-
* An array of `Parameter` objects describing the function's parameters.
|
|
572
|
-
*
|
|
573
|
-
* @remarks
|
|
574
|
-
* If not specified, the function is assumed to be volatile (its output might change even if its inputs haven't).
|
|
575
|
-
*/
|
|
576
|
-
getParameters(): readonly IParameterType[];
|
|
577
|
-
/**
|
|
578
|
-
* Metadata describing the type and dimensionality of the return value.
|
|
579
|
-
*
|
|
580
|
-
* @defaultValue `{ type: 'void' }`
|
|
581
|
-
*/
|
|
582
|
-
getReturnType(): IReturnType;
|
|
583
|
-
}
|
|
584
|
-
/**
|
|
585
|
-
* Contains user information about the function.
|
|
586
|
-
*
|
|
587
|
-
* @remarks
|
|
588
|
-
* This is locale specific.
|
|
589
|
-
*/
|
|
590
|
-
export interface IDescriptor {
|
|
591
|
-
/**
|
|
592
|
-
* A overwritten name for the function.
|
|
593
|
-
*/
|
|
594
|
-
getName(): string;
|
|
595
|
-
/**
|
|
596
|
-
* A description of the function's purpose and usage.
|
|
597
|
-
*/
|
|
598
|
-
getSummary(): string;
|
|
599
|
-
/**
|
|
600
|
-
* A category or group to which the function belongs.
|
|
601
|
-
*/
|
|
602
|
-
getCategory(): string;
|
|
603
|
-
/**
|
|
604
|
-
* If `true` the function is available but will not be returned in search
|
|
605
|
-
* results unless hidden is specifically requested.
|
|
606
|
-
* If this is a string it can be used to provide a hidden label.
|
|
607
|
-
*
|
|
608
|
-
* @defaultValue 'null'
|
|
609
|
-
*
|
|
610
|
-
* @remarks
|
|
611
|
-
* This is useful for functions that are unimplemented or deprecated.
|
|
612
|
-
*/
|
|
613
|
-
isHidden(): boolean | string;
|
|
614
|
-
/**
|
|
615
|
-
* An array of links associated with the value.
|
|
616
|
-
*/
|
|
617
|
-
getLinks(): readonly [url: string, text?: string][];
|
|
618
|
-
/**
|
|
619
|
-
* Describe each parameter in the function.
|
|
620
|
-
*/
|
|
621
|
-
getParameters(): Readonly<Record<string, {
|
|
622
|
-
description: string;
|
|
623
|
-
example: string;
|
|
624
|
-
defaultValue?: string;
|
|
625
|
-
}>>;
|
|
626
|
-
}
|
|
627
|
-
/**
|
|
628
|
-
* Describes the type characteristics of a function parameter or return value.
|
|
629
|
-
*
|
|
630
|
-
* At least one of `scalar`, `range`, or `context` must be defined.
|
|
631
|
-
*/
|
|
632
|
-
export interface ValueTypeJSON {
|
|
633
|
-
/**
|
|
634
|
-
* Indicates that the value is a single, scalar cell-compatible value.
|
|
635
|
-
*
|
|
636
|
-
* @remarks
|
|
637
|
-
* This corresponds to a `ScalarType` such as `Number`, `Boolean`, or `String`.
|
|
638
|
-
* `ScalarType.Null` is permitted only for event handler return types.
|
|
639
|
-
*/
|
|
640
|
-
scalar?: ScalarType | string;
|
|
641
|
-
/**
|
|
642
|
-
* Indicates that the value is a range (multi-cell) structure.
|
|
643
|
-
*
|
|
644
|
-
* - `r`: A `RangeReference`, representing a pointer to sheet coordinates.
|
|
645
|
-
* - `l`: A `RangeLiteral`, representing the actual values in the range.
|
|
646
|
-
* - `a`: A materialized array (`Scalar[]` or `Scalar[][]`) that has been extracted from the range.
|
|
647
|
-
*
|
|
648
|
-
* If specified, the function supports multi-cell or structured range inputs.
|
|
649
|
-
*/
|
|
650
|
-
range?: 'r' | 'l' | 'a';
|
|
651
|
-
/**
|
|
652
|
-
* Defines the number of array signatures after a parameter.
|
|
653
|
-
* - `0`: No array signature. The value is scalar or a single cell.
|
|
654
|
-
* - `1`: Will flatten.
|
|
655
|
-
* - `2`: Nest.
|
|
656
|
-
*
|
|
657
|
-
* @defaultValue `0` if no `range` is defined, otherwise `1`.
|
|
658
|
-
*/
|
|
659
|
-
arrayDepth?: number;
|
|
660
|
-
/**
|
|
661
|
-
* A short description of the value's purpose or expected usage.
|
|
662
|
-
*/
|
|
663
|
-
description?: string;
|
|
664
|
-
}
|
|
665
|
-
/**
|
|
666
|
-
* Describes the parameter to a function, including its name, type,
|
|
667
|
-
* whether it's required, and if it's a rest parameter.
|
|
668
|
-
*/
|
|
669
|
-
export interface ParameterTypeJSON extends ValueTypeJSON {
|
|
670
|
-
/**
|
|
671
|
-
* The name of the parameter.
|
|
672
|
-
*/
|
|
673
|
-
name: string;
|
|
674
|
-
/**
|
|
675
|
-
* Indicates whether the parameter is required.
|
|
676
|
-
*
|
|
677
|
-
* @defaultValue true
|
|
678
|
-
*/
|
|
679
|
-
optional?: boolean;
|
|
680
|
-
/**
|
|
681
|
-
* Indicates whether the parameter is a rest parameter (accepts multiple arguments).
|
|
682
|
-
*
|
|
683
|
-
* @remarks
|
|
684
|
-
* - A rest parameter can only be the last parameter in a function.
|
|
685
|
-
* - If `rest` is `true`, the parameter is also considered optional.
|
|
686
|
-
*/
|
|
687
|
-
rest?: boolean;
|
|
688
|
-
/**
|
|
689
|
-
* Indicates whether the function requires the address of the calling cell as an input.
|
|
690
|
-
* Cannot be combined with `stream`.
|
|
691
|
-
*
|
|
692
|
-
* @defaultValue `false`
|
|
693
|
-
*/
|
|
694
|
-
enums?: string[];
|
|
695
|
-
}
|
|
696
|
-
/**
|
|
697
|
-
* Describes the runtime return behavior of a function, including modifiers like
|
|
698
|
-
* async resolution, streaming data, or volatility.
|
|
699
|
-
*
|
|
700
|
-
* @remarks
|
|
701
|
-
* If none are specified, The value will be returned with no special behavior.
|
|
702
|
-
*/
|
|
703
|
-
export interface ReturnTypeJSON extends ValueTypeJSON {
|
|
704
|
-
/**
|
|
705
|
-
* Indicates the return value is a Promise or Promise-like (i.e., async).
|
|
706
|
-
* The system will mark the result as pending and re-trigger evaluation once resolved.
|
|
707
|
-
*
|
|
708
|
-
* Can be combined with any scalar, array, or range return type.
|
|
709
|
-
*/
|
|
710
|
-
async?: boolean;
|
|
711
|
-
/**
|
|
712
|
-
* Indicates whether the function produces a continuous stream of output (e.g., real-time data).
|
|
713
|
-
*
|
|
714
|
-
* @defaultValue `false`
|
|
715
|
-
*/
|
|
716
|
-
stream?: boolean;
|
|
717
|
-
}
|
|
718
|
-
/**
|
|
719
|
-
* Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
|
|
720
|
-
*/
|
|
721
|
-
export interface DeclarationJSON {
|
|
722
|
-
/** @inheritdoc IFunction.IDeclaration.getName */
|
|
723
|
-
name: string;
|
|
724
|
-
/** @inheritdoc IFunction.IDeclaration.getReturnType */
|
|
725
|
-
returnType?: ReturnTypeJSON;
|
|
726
|
-
/** @inheritdoc IFunction.IDeclaration.getParameters */
|
|
727
|
-
parameters?: ParameterTypeJSON[];
|
|
728
|
-
/**
|
|
729
|
-
* Describes the execution context required by the function.
|
|
730
|
-
*
|
|
731
|
-
* Contexts fall into two categories:
|
|
732
|
-
*
|
|
733
|
-
* - **Macro contexts**: Used by macro-style functions to access parts of the document or selection:
|
|
734
|
-
* - `'Workbook'`: The entire workbook
|
|
735
|
-
* - `'Sheet'`: A single sheet
|
|
736
|
-
* - `'Range'`: A selected sheet range
|
|
737
|
-
* - `'Ranges'`: Multiple selected ranges
|
|
738
|
-
*
|
|
739
|
-
* - **Calculation context**: Used by formula functions like `OFFSET` or `INDIRECT`
|
|
740
|
-
* that need access to evaluation position or sheet metadata during calculation.
|
|
741
|
-
* This context is available in headless or worker environments.
|
|
742
|
-
*
|
|
743
|
-
* @remarks
|
|
744
|
-
* * If omitted, the function is consider a FormulaFunction.
|
|
745
|
-
* * If a function has a context it will be passed as the first argument to `execute`.
|
|
746
|
-
* * If the context is `IFunction.Calculation` then the function must return a value.
|
|
747
|
-
* * If the context is not `IFunction.Calculation` then the function must return `void` or a cleanup function.
|
|
748
|
-
*/
|
|
749
|
-
context?: string;
|
|
750
|
-
/**
|
|
751
|
-
* Additional metadata about the function's behavior or requirements.
|
|
752
|
-
*/
|
|
753
|
-
behavior?: BehaviorJSON;
|
|
754
|
-
}
|
|
755
|
-
/**
|
|
756
|
-
* Contains user information about the function.
|
|
757
|
-
*
|
|
758
|
-
* @remarks
|
|
759
|
-
* This is locale specific.
|
|
760
|
-
*/
|
|
761
|
-
export interface DescriptorJSON {
|
|
762
|
-
/**
|
|
763
|
-
* A overwritten name for the function.
|
|
764
|
-
*
|
|
765
|
-
* @defaultValue The name of the function in code.
|
|
766
|
-
*/
|
|
767
|
-
name?: string;
|
|
768
|
-
/**
|
|
769
|
-
* A more detailed explanation of the function's purpose and usage.
|
|
770
|
-
*/
|
|
771
|
-
summary?: string;
|
|
772
|
-
/**
|
|
773
|
-
* A category or group to which the function belongs.
|
|
774
|
-
*
|
|
775
|
-
* @defaultValue 'custom'
|
|
776
|
-
*/
|
|
777
|
-
category?: string;
|
|
778
|
-
/**
|
|
779
|
-
* If `true` is usable in calculation but not provided in the ui.
|
|
780
|
-
* If this is a string it can be used to provide a hidden label.
|
|
781
|
-
*
|
|
782
|
-
* @defaultValue 'null'
|
|
783
|
-
*
|
|
784
|
-
* @remarks
|
|
785
|
-
* This is useful for functions that are unimplemented or deprecated.
|
|
786
|
-
*/
|
|
787
|
-
hidden?: string | boolean;
|
|
788
|
-
/**
|
|
789
|
-
* An array of links associated with the value.
|
|
790
|
-
*/
|
|
791
|
-
links?: [url: string, text?: string][];
|
|
792
|
-
/**
|
|
793
|
-
* Describe each parameter in the function.
|
|
794
|
-
*/
|
|
795
|
-
parameters?: Record<string, {
|
|
796
|
-
description: string;
|
|
797
|
-
example?: string;
|
|
798
|
-
defaultValue?: Scalar;
|
|
799
|
-
}>;
|
|
800
|
-
}
|
|
801
|
-
/**
|
|
802
|
-
* Contains extended metadata about a function that is not be directly inferable from the code itself.
|
|
803
|
-
*/
|
|
804
|
-
export interface BehaviorJSON {
|
|
805
|
-
/**
|
|
806
|
-
* If `true` this function will be called on load unless scripts are disabled.
|
|
807
|
-
*
|
|
808
|
-
* @defaultValue `false`.
|
|
809
|
-
*/
|
|
810
|
-
default?: boolean;
|
|
811
|
-
cancelable?: boolean;
|
|
812
|
-
}
|
|
813
|
-
}
|
|
814
|
-
|
|
815
|
-
/**
|
|
816
|
-
* A two-dimensional ranges of values that use array programming styles similar to NumPy's
|
|
817
|
-
* ndarray, but expanded for use in a spreadsheet environment.
|
|
818
|
-
*
|
|
819
|
-
* * Provides methods for accessing dimensions, iterating over elements, and performing basic matrix operations.
|
|
820
|
-
*/
|
|
821
|
-
export declare interface IRange<T extends Scalar = Scalar> {
|
|
822
|
-
/**
|
|
823
|
-
* Applies a callback function to elements from this range and another range or a scalar, using NumPy-style broadcasting.
|
|
824
|
-
*
|
|
825
|
-
* **Broadcasting Rules:**
|
|
826
|
-
* - If `other` is a scalar, it is broadcasted to match the shape of this range.
|
|
827
|
-
* - If `other` is a range, both ranges must have the same length.
|
|
828
|
-
*
|
|
829
|
-
* @param other The other range or scalar to broadcast with.
|
|
830
|
-
* @param callbackFn The function to apply to corresponding elements.
|
|
831
|
-
* @param options {@link IRange.BroadcastOptions}
|
|
832
|
-
*
|
|
833
|
-
* @returns A new range with the broadcasted results.
|
|
834
|
-
* @throws {Error} If the ranges have different length when broadcasting two ranges.
|
|
835
|
-
*/
|
|
836
|
-
broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
|
|
837
|
-
/**
|
|
838
|
-
* Returns a range of 0x0.
|
|
839
|
-
*/
|
|
840
|
-
empty(): this;
|
|
841
|
-
/**
|
|
842
|
-
* Returns an iterator that allows you to iterate over the individual entries within the range,
|
|
843
|
-
* yielding pairs of `IRange.CellCoords` and `Scalar`.
|
|
844
|
-
*
|
|
845
|
-
* @param options {@link IRange.IteratorOptions}
|
|
846
|
-
* @returns An iterator that yields a IRange.Entry for each value within the range.
|
|
847
|
-
*/
|
|
848
|
-
entries<TS extends Scalar = T>(options?: IRange.IteratorOptions): IterableIterator<IRange.Entry<TS>>;
|
|
849
|
-
/**
|
|
850
|
-
* Tests whether all elements in the range pass the test implemented by the provided function.
|
|
851
|
-
*
|
|
852
|
-
* @param callbackFn The function to test each element.
|
|
853
|
-
* @param options {@link IRange.IteratorOptions}
|
|
854
|
-
* @returns `true` if all elements pass the test, otherwise `false`.
|
|
855
|
-
*/
|
|
856
|
-
every<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): boolean;
|
|
857
|
-
/**
|
|
858
|
-
* Iterates over the cells within the range, applying the provided callback function to each cell.
|
|
859
|
-
*
|
|
860
|
-
* This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges,
|
|
861
|
-
* as it:
|
|
862
|
-
* 1. Skips empty values by default.
|
|
863
|
-
* 2. Avoids creating large arrays.
|
|
864
|
-
* 3. Allows for early termination.
|
|
865
|
-
*
|
|
866
|
-
* @param callbackFn A function that will be called for each non-empty cell in the range. The callback receives:
|
|
867
|
-
* - `value`: The `Scalar` at the current cell.
|
|
868
|
-
* - `coords`: A `IRange.CellCoords`.
|
|
869
|
-
* - The callback can return `{ break: T }` to stop the iteration early.
|
|
870
|
-
* @param options {@link IRange.IteratorOptions}
|
|
871
|
-
* @template T The Scalar type.
|
|
872
|
-
* @template B The callback return type.
|
|
873
|
-
* @returns The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, `void`.
|
|
874
|
-
*/
|
|
875
|
-
forEach<TS extends Scalar = T, B = any>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => {
|
|
876
|
-
break: B;
|
|
877
|
-
} | void, options?: IRange.IteratorOptions): B | void;
|
|
878
|
-
/**
|
|
879
|
-
* Fill the entire range with a single value.
|
|
880
|
-
*
|
|
881
|
-
* @param value The value to fill.
|
|
882
|
-
* @param coords If provided will fill from the coordinates to this area.
|
|
883
|
-
*/
|
|
884
|
-
fill(value: Scalar, coords?: Partial<IRange.Coords>): this;
|
|
885
|
-
/**
|
|
886
|
-
* Returns a new range with all values set to a specific value.
|
|
887
|
-
*
|
|
888
|
-
* @param value The value to fill
|
|
889
|
-
* @param minWidth A fixed width for the range. DefaultValue `original width`.
|
|
890
|
-
* @param minHeight A fixed height for the range. DefaultValue `original height`.
|
|
891
|
-
*/
|
|
892
|
-
fillEmpty(value: Scalar, minWidth?: number, minHeight?: number): this;
|
|
893
|
-
/**
|
|
894
|
-
* Creates a new range with elements that pass the test implemented by the provided function.
|
|
895
|
-
*
|
|
896
|
-
* @param callbackFn The function to test each element.
|
|
897
|
-
* @param options {@link IRange.IteratorOptions}
|
|
898
|
-
* @returns A new range containing only the elements that pass the test.
|
|
899
|
-
*/
|
|
900
|
-
filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): this;
|
|
901
|
-
/**
|
|
902
|
-
* Returns the values as an array of values.
|
|
903
|
-
*
|
|
904
|
-
* @param options {@link IRange.IteratorOptions}
|
|
905
|
-
*/
|
|
906
|
-
flatten(options?: IRange.IteratorOptions): Scalar[];
|
|
907
|
-
/**
|
|
908
|
-
* Returns the values as a materialized 2D array.
|
|
909
|
-
*
|
|
910
|
-
* @param options {@link IRange.GetValuesOptions}
|
|
911
|
-
*
|
|
912
|
-
* @remarks
|
|
913
|
-
* This is useful if a libraries or functions require a 2D array but can be very expensive
|
|
914
|
-
* for large ranges.
|
|
915
|
-
*/
|
|
916
|
-
getValues<TS extends Scalar = T>(options?: IRange.GetValuesOptions): TS[][];
|
|
917
|
-
/**
|
|
918
|
-
* Returns a scalar value at a specific row and column index.
|
|
919
|
-
*
|
|
920
|
-
* @param rowIndex The row index of the value to retrieve.
|
|
921
|
-
* @param colIndex The column index of the value to retrieve.
|
|
922
|
-
* @param options {@link IRange.GetValuesOptions}
|
|
923
|
-
*
|
|
924
|
-
* Returns a value at a specific row and column index.
|
|
925
|
-
*/
|
|
926
|
-
getValueAt<TS extends Scalar = T>(rowIndex: number, colIndex: number, options?: IRange.ValueOptions): TS;
|
|
927
|
-
/**
|
|
928
|
-
* Returns the width of the range.
|
|
929
|
-
*/
|
|
930
|
-
getWidth(): number;
|
|
931
|
-
/**
|
|
932
|
-
* Returns the height of the range.
|
|
933
|
-
*/
|
|
934
|
-
getHeight(): number;
|
|
935
|
-
/**
|
|
936
|
-
* Indicates if the range has a type.
|
|
937
|
-
*/
|
|
938
|
-
getScalarType(): ScalarType | null;
|
|
939
|
-
/**
|
|
940
|
-
* Intersects two ranges and applies a callback function to elements.
|
|
941
|
-
*
|
|
942
|
-
* @param other The other range.
|
|
943
|
-
* @returns A new range with the intersected results or `null` if the ranges do not intersect.
|
|
944
|
-
*/
|
|
945
|
-
intersect<TS extends Scalar = T>(other: IRange, callbackFn?: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.IteratorOptions): this;
|
|
946
|
-
/**
|
|
947
|
-
* Returns `true` if the range is a literal range from a parameter.
|
|
948
|
-
*/
|
|
949
|
-
isLiteral(): boolean;
|
|
950
|
-
/**
|
|
951
|
-
* Applies a transformation function to each value, returning a new `IRange`.
|
|
952
|
-
*
|
|
953
|
-
* @param callbackFn A function applied to each non-empty cell
|
|
954
|
-
* @param options {@link IRange.IteratorOptions}
|
|
955
|
-
*/
|
|
956
|
-
map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.IteratorOptions): this;
|
|
957
|
-
/**
|
|
958
|
-
* Iterate values.
|
|
959
|
-
*
|
|
960
|
-
* @param options {@link IRange.IteratorOptions}
|
|
961
|
-
*/
|
|
962
|
-
values<TS extends Scalar = T>(options?: IRange.IteratorOptions): IterableIterator<TS>;
|
|
963
|
-
/**
|
|
964
|
-
* Applies a function against an accumulator and each element of the range (from left to right) to reduce it to a single value.
|
|
965
|
-
*
|
|
966
|
-
* @template U The type of the accumulator.
|
|
967
|
-
* @param callbackFn The function to execute on each element.
|
|
968
|
-
* @param initialValue The initial value of the accumulator.
|
|
969
|
-
* @param options {@link IRange.IteratorOptions}
|
|
970
|
-
* @returns The reduced value.
|
|
971
|
-
*/
|
|
972
|
-
reduce<TS extends Scalar = T>(callbackFn: (accumulator: TS, value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, initialValue: TS, options?: IRange.IteratorOptions): TS;
|
|
973
|
-
/**
|
|
974
|
-
* Replaces values in the range with values from another range.
|
|
975
|
-
*
|
|
976
|
-
* @param other The other range or a 2d array.
|
|
977
|
-
* @param coords The starting coordinates for the replacement. Default Value {0 ,0}
|
|
978
|
-
*/
|
|
979
|
-
replace<TS extends Scalar = T>(other: IRange | TS[][], coords?: IRange.CellCoords): this;
|
|
980
|
-
/**
|
|
981
|
-
* Returns a new range either trimmed or expanded to fix the new width/height.
|
|
982
|
-
*/
|
|
983
|
-
resize(width: number, height: number, fillValue?: Scalar): this;
|
|
984
|
-
/**
|
|
985
|
-
* Returns a sliced subrange of the current range.
|
|
986
|
-
*
|
|
987
|
-
* @param coords A partial range definition ({ rowStart, rowEnd, colStart, colEnd }).
|
|
988
|
-
* @returns A new `IRange` representing the sliced section.
|
|
989
|
-
*
|
|
990
|
-
* @remarks
|
|
991
|
-
* If any coordinate is omitted, it defaults to the full extent of the range.
|
|
992
|
-
*/
|
|
993
|
-
slice(coords: Partial<IRange.Coords>): this;
|
|
994
|
-
/**
|
|
995
|
-
* Tests whether at least one element in the range passes the test implemented by the provided function.
|
|
996
|
-
*
|
|
997
|
-
* @param callbackFn The function to test each element.
|
|
998
|
-
* @param options {@link IRange.IteratorOptions}
|
|
999
|
-
* @returns `true` if at least one element passes the test, otherwise `false`.
|
|
1000
|
-
*/
|
|
1001
|
-
some<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): boolean;
|
|
1002
|
-
/**
|
|
1003
|
-
* Creates a `IncrementalUpdater` for efficiently updating sparsely populated cells in a streaming low memory way.
|
|
1004
|
-
*
|
|
1005
|
-
* @param options {@link IRange.StartUpdateOptions}
|
|
1006
|
-
*
|
|
1007
|
-
* @remarks
|
|
1008
|
-
* - **Ordering:** By default updates must be added in either row-major or column-major order, as specified
|
|
1009
|
-
* by the `orientation` parameter, with major/minor coordinates increasing monotonically. Unless
|
|
1010
|
-
* `allowUnorderedWrites` is set to `true out of order updates will result in an error.
|
|
1011
|
-
|
|
1012
|
-
* - **Performance:** Setting `orientation` to `IRange.Orientation.Column` is generally faster as it aligns with the internal data representation.
|
|
1013
|
-
* - **Performance:** Setting `allowUnorderedWrites` adds a nominal performance overhead for all updates and will do a full apply when an
|
|
1014
|
-
* out of order update is detected.
|
|
1015
|
-
* The default `IRange.Orientation.Row` is provided for compatibility with common spreadsheet APIs.
|
|
1016
|
-
* - **Validation:** Data validation (e.g., for protected cells or boundaries) is performed when the `apply` method is called.
|
|
1017
|
-
* - **Transactions:**
|
|
1018
|
-
* - Adding values to the `IncrementalUpdater` only builds a temporary representation of the updates.
|
|
1019
|
-
* No actual changes are made to the sheet until `apply` is called.
|
|
1020
|
-
* - This allows for safe batching of updates within a single transaction using `doBatch`.
|
|
1021
|
-
|
|
1022
|
-
* @example
|
|
1023
|
-
```typescript startIncrementalUpdates
|
|
1024
|
-
const updates = range.startIncrementalUpdates()
|
|
1025
|
-
.pushAt(1, 0, 2)
|
|
1026
|
-
.pushAt(1, 0, 567)
|
|
1027
|
-
.pushAt(1, 0, 3)
|
|
1028
|
-
.pushAt(1, 0, 123)
|
|
1029
|
-
.pushAt(1, 0, 1)
|
|
1030
|
-
.apply();
|
|
1031
|
-
});
|
|
1032
|
-
```
|
|
1033
|
-
*/
|
|
1034
|
-
startIncrementalUpdates<TS extends Scalar = T>(options?: IRange.StartUpdateOptions): IRange.IncrementalUpdater<TS>;
|
|
1035
|
-
/**
|
|
1036
|
-
* Returns a string representation of the range.
|
|
1037
|
-
*/
|
|
1038
|
-
toString(): string;
|
|
1039
|
-
/**
|
|
1040
|
-
* Change the type of default range coercion for the values in the range.
|
|
1041
|
-
*
|
|
1042
|
-
* @param type The new scalar type.
|
|
1043
|
-
*/
|
|
1044
|
-
toType(type: ScalarType): this;
|
|
1045
|
-
/**
|
|
1046
|
-
* Returns the range transposed.
|
|
1047
|
-
*/
|
|
1048
|
-
transpose(): this;
|
|
1049
|
-
/**
|
|
1050
|
-
* Returns an iterator that allows you to iterate over the individual values within the range.
|
|
1051
|
-
*
|
|
1052
|
-
* @remarks
|
|
1053
|
-
* For more advanced iteration, use {@link IRange.entries} or {@link IRange.forEach}.
|
|
1054
|
-
*/
|
|
1055
|
-
[Symbol.iterator](): IterableIterator<Scalar>;
|
|
1056
|
-
/**
|
|
1057
|
-
* Returns the size of the range this is the width * height.
|
|
1058
|
-
*/
|
|
1059
|
-
get size(): number;
|
|
1060
|
-
get isIRange(): true;
|
|
1061
|
-
}
|
|
1062
|
-
|
|
1063
|
-
/**
|
|
1064
|
-
* {@inheritDoc IRange}
|
|
1065
|
-
*
|
|
1066
|
-
* @see
|
|
1067
|
-
* ### **Interface**
|
|
1068
|
-
*
|
|
1069
|
-
* {@link IRange}
|
|
1070
|
-
*/
|
|
1071
|
-
export declare namespace IRange {
|
|
1072
|
-
export interface IteratorOptions extends IRange.ValueOptions {
|
|
1073
|
-
/**
|
|
1074
|
-
* The direction of the iteration.
|
|
1075
|
-
*
|
|
1076
|
-
* @defaultValue `IRange.Orientation.Column`
|
|
1077
|
-
*/
|
|
1078
|
-
orientation?: IRange.Orientation;
|
|
1079
|
-
/**
|
|
1080
|
-
* The direction of the iteration.
|
|
1081
|
-
*
|
|
1082
|
-
* @defaultValue `IRange.Orientation.Row`
|
|
1083
|
-
*/
|
|
1084
|
-
bounds?: Partial<IRange.Coords>;
|
|
1085
|
-
/**
|
|
1086
|
-
* Iterate in reverse order.
|
|
1087
|
-
*
|
|
1088
|
-
* @defaultValue `false`
|
|
1089
|
-
*/
|
|
1090
|
-
reverse?: boolean;
|
|
1091
|
-
/**
|
|
1092
|
-
* If true will visit empty cells.
|
|
1093
|
-
* This is a potentially huge performance improvement if set to false.
|
|
1094
|
-
*
|
|
1095
|
-
* @defaultValue `false`
|
|
1096
|
-
*
|
|
1097
|
-
* @remarks
|
|
1098
|
-
* If includeEmpty is `true` this will always return rectangular results.
|
|
1099
|
-
* If bounds are provided it will provide empty spaces before and after.
|
|
1100
|
-
* If passing a large bound care must be taken.
|
|
1101
|
-
*/
|
|
1102
|
-
includeEmpty?: boolean;
|
|
1103
|
-
/**
|
|
1104
|
-
* Useful for callback functions that want a this.
|
|
1105
|
-
*/
|
|
1106
|
-
thisArg?: any;
|
|
1107
|
-
}
|
|
1108
|
-
export interface ValueOptions {
|
|
1109
|
-
/**
|
|
1110
|
-
* Specifies the type of value desired.
|
|
1111
|
-
*
|
|
1112
|
-
* @remarks
|
|
1113
|
-
* Once set the values will attempt to coerce to the type requested.
|
|
1114
|
-
* Various operations will be affected by this setting.
|
|
1115
|
-
*/
|
|
1116
|
-
type?: ScalarType;
|
|
1117
|
-
/**
|
|
1118
|
-
* If type is set and this is true values that don't match will attempt to be
|
|
1119
|
-
* coerced to the type value. If coerce fails the value will be ignored or
|
|
1120
|
-
* a `FormulaError.Value` will be returned depending on the `includeMistyped` setting.
|
|
1121
|
-
*
|
|
1122
|
-
* @default `depends` Ranges that are created from literal scalars will coerce by default.
|
|
1123
|
-
* @remarks
|
|
1124
|
-
* If type is not set this has no effect.
|
|
1125
|
-
*/
|
|
1126
|
-
coerce?: boolean;
|
|
1127
|
-
/**
|
|
1128
|
-
* If `true` values that do not match the `type` will be ignored.
|
|
1129
|
-
* @default `depends` Ranges that are created from literal arrays will be ignored by default.
|
|
1130
|
-
*
|
|
1131
|
-
* @remarks
|
|
1132
|
-
* If type is not set this has no effect.
|
|
1133
|
-
*/
|
|
1134
|
-
includeMistyped?: boolean;
|
|
1135
|
-
/**
|
|
1136
|
-
* Flag for including boolean values in coerce.
|
|
1137
|
-
*
|
|
1138
|
-
* @default `depends` Ranges that are created from literal scalars will include boolean by default.
|
|
1139
|
-
*/
|
|
1140
|
-
includeBoolean?: boolean;
|
|
1141
|
-
}
|
|
1142
|
-
export interface GetValuesOptions extends ValueOptions {
|
|
1143
|
-
/**
|
|
1144
|
-
* The maximum width of the array.
|
|
1145
|
-
*/
|
|
1146
|
-
maxWidth?: number;
|
|
1147
|
-
/**
|
|
1148
|
-
* The maximum width of the array.
|
|
1149
|
-
*/
|
|
1150
|
-
maxHeight?: number;
|
|
1151
|
-
/**
|
|
1152
|
-
* If true will include trailing empties.
|
|
1153
|
-
*/
|
|
1154
|
-
trailingEmpties?: boolean;
|
|
1155
|
-
/**
|
|
1156
|
-
* Allow for this to be set. DefaultValue `IRange.Orientation.Row`
|
|
1157
|
-
*/
|
|
1158
|
-
orientation?: IRange.Orientation;
|
|
1159
|
-
/**
|
|
1160
|
-
* If provided then before return the callback will be visited for each cell.
|
|
1161
|
-
*/
|
|
1162
|
-
onValue?: (value: Scalar, row: number, column: number, range: IRange) => Scalar;
|
|
1163
|
-
}
|
|
1164
|
-
export interface BroadcastOptions extends ValueOptions {
|
|
1165
|
-
/**
|
|
1166
|
-
* Controls how misaligned ranges are handled during broadcasting.
|
|
1167
|
-
*
|
|
1168
|
-
* - By default, `broadcast()` follows strict alignment rules like NumPy and will
|
|
1169
|
-
* throw an error if the input ranges cannot be broadcasted together.
|
|
1170
|
-
* - When `mismatchFill` is provided, `broadcast()` will instead mimic Excel behavior:
|
|
1171
|
-
* - It finds the **largest valid intersection** of the ranges.
|
|
1172
|
-
* - It expands the result to the **union of both range sizes**.
|
|
1173
|
-
* - Any cells that do not have valid corresponding values from the inputs
|
|
1174
|
-
* will be filled with `mismatchFill` instead of causing an error.
|
|
1175
|
-
*
|
|
1176
|
-
* @example
|
|
1177
|
-
* // Throws an error if A and B are not naturally broadcast-compatible
|
|
1178
|
-
* const result = A.broadcast(B, (a, b) => a + b);
|
|
1179
|
-
*
|
|
1180
|
-
* @example
|
|
1181
|
-
* // Expands to union size and fills gaps with "#N/A" instead of erroring
|
|
1182
|
-
* const result = A.broadcast(B, (a, b) => a + b, { mismatchFill: "#N/A" });
|
|
1183
|
-
*/
|
|
1184
|
-
mismatchFill?: Scalar;
|
|
1185
|
-
/**
|
|
1186
|
-
* If used this is will coerce the other.
|
|
1187
|
-
*/
|
|
1188
|
-
otherType?: ScalarType;
|
|
1189
|
-
}
|
|
1190
|
-
/**
|
|
1191
|
-
* Entry for a Range iterator or visiting.
|
|
1192
|
-
*/
|
|
1193
|
-
export interface Entry<T extends Scalar = Scalar> {
|
|
1194
|
-
value: T;
|
|
1195
|
-
coords: CellCoords;
|
|
1196
|
-
}
|
|
1197
|
-
export interface StartUpdateOptions {
|
|
1198
|
-
/**
|
|
1199
|
-
* The direction of the write.
|
|
1200
|
-
*
|
|
1201
|
-
* @defaultValue `IRange.Orientation.Row`
|
|
1202
|
-
*/
|
|
1203
|
-
orientation?: IRange.Orientation;
|
|
1204
|
-
}
|
|
1205
|
-
/**
|
|
1206
|
-
* A Results builder for creating new Ranges.
|
|
1207
|
-
* A builder maintains an ordered structure where major and minor values must always
|
|
1208
|
-
* increase, otherwise an error will be thrown.
|
|
1209
|
-
*
|
|
1210
|
-
* @template T The type of values stored within the tuples.
|
|
1211
|
-
*/
|
|
1212
|
-
export interface IncrementalUpdater<T extends Scalar> {
|
|
1213
|
-
/**
|
|
1214
|
-
* Adds a single value associated with a specific major and minor index.
|
|
1215
|
-
*
|
|
1216
|
-
* @param row The row index.
|
|
1217
|
-
* @param col The column index.
|
|
1218
|
-
* @param value The value to be added.
|
|
1219
|
-
* @throws `Error` If the point is out of order compared to previously added points
|
|
1220
|
-
* (within the same row).
|
|
1221
|
-
*
|
|
1222
|
-
* @remarks
|
|
1223
|
-
* If the value is an Array, it will be treated as a discrete value. If you want to set
|
|
1224
|
-
* multiple values along the minor axis, then use {@link pushMultipleAt}.
|
|
1225
|
-
*/
|
|
1226
|
-
pushAt(row: number, col: number, value: T): this;
|
|
1227
|
-
/**
|
|
1228
|
-
* Adds multiple values associated with a specific row and column index.
|
|
1229
|
-
*
|
|
1230
|
-
* @param row The row index.
|
|
1231
|
-
* @param col The column index.
|
|
1232
|
-
* @param value An array of values to be added.
|
|
1233
|
-
* @throws `Error` If the point is out of order compared to previously added points
|
|
1234
|
-
* (within the same row).
|
|
1235
|
-
*/
|
|
1236
|
-
pushMultipleAt(row: number, col: number, value: T[]): this;
|
|
1237
|
-
/**
|
|
1238
|
-
* Apply the updates
|
|
1239
|
-
*/
|
|
1240
|
-
apply(): IRange;
|
|
1241
|
-
}
|
|
1242
|
-
/**
|
|
1243
|
-
* Specifies a single direction for the range.
|
|
1244
|
-
*/
|
|
1245
|
-
const Orientation: {
|
|
1246
|
-
readonly Column: "column";
|
|
1247
|
-
readonly Row: "row";
|
|
1248
|
-
};
|
|
1249
|
-
export type Orientation = typeof Orientation[keyof typeof Orientation];
|
|
1250
|
-
/**
|
|
1251
|
-
* Allows for either direction or both. (But not none).
|
|
1252
|
-
*/
|
|
1253
|
-
const Orientations: {
|
|
1254
|
-
readonly Both: "both";
|
|
1255
|
-
readonly Column: "column";
|
|
1256
|
-
readonly Row: "row";
|
|
1257
|
-
};
|
|
1258
|
-
export type Orientations = typeof Orientations[keyof typeof Orientations];
|
|
1259
|
-
/**
|
|
1260
|
-
* Indicates a direction for a range along an axis.
|
|
1261
|
-
*
|
|
1262
|
-
* @remarks
|
|
1263
|
-
* Used during fill, shift, etc.
|
|
1264
|
-
*/
|
|
1265
|
-
const Direction: {
|
|
1266
|
-
readonly Up: "up";
|
|
1267
|
-
readonly Down: "down";
|
|
1268
|
-
readonly Left: "left";
|
|
1269
|
-
readonly Right: "right";
|
|
1270
|
-
};
|
|
1271
|
-
export type Direction = typeof Direction[keyof typeof Direction];
|
|
1272
|
-
/**
|
|
1273
|
-
* The coordinates of a cell range in a 2D space.
|
|
1274
|
-
* The rowStart and colStart must be less than or equal to rowEnd and colEnd respectively.
|
|
1275
|
-
* If all of the values are the same this represents a single cell.
|
|
1276
|
-
*/
|
|
1277
|
-
export interface Coords {
|
|
1278
|
-
/**
|
|
1279
|
-
* Left column
|
|
1280
|
-
*/
|
|
1281
|
-
colStart: number;
|
|
1282
|
-
/**
|
|
1283
|
-
* Top row
|
|
1284
|
-
*/
|
|
1285
|
-
rowStart: number;
|
|
1286
|
-
/**
|
|
1287
|
-
* Right column
|
|
1288
|
-
*/
|
|
1289
|
-
colEnd: number;
|
|
1290
|
-
/**
|
|
1291
|
-
* Bottom row
|
|
1292
|
-
*/
|
|
1293
|
-
rowEnd: number;
|
|
1294
|
-
sheetName?: string;
|
|
1295
|
-
}
|
|
1296
|
-
/**
|
|
1297
|
-
* Adds `fixed flags` to `IRange.Coords`.
|
|
1298
|
-
*/
|
|
1299
|
-
export interface FixableCoords extends Coords {
|
|
1300
|
-
/**
|
|
1301
|
-
* If `true` then the colStart is fixed.
|
|
1302
|
-
*
|
|
1303
|
-
* @defaultValue false
|
|
1304
|
-
*/
|
|
1305
|
-
$colStart?: boolean;
|
|
1306
|
-
/**
|
|
1307
|
-
* If `true` then the rowStart is fixed.
|
|
1308
|
-
*
|
|
1309
|
-
* @defaultValue false
|
|
1310
|
-
*/
|
|
1311
|
-
$rowStart?: boolean;
|
|
1312
|
-
/**
|
|
1313
|
-
* If `true` then the colEnd is fixed.
|
|
1314
|
-
*
|
|
1315
|
-
* @defaultValue false
|
|
1316
|
-
*/
|
|
1317
|
-
$colEnd?: boolean;
|
|
1318
|
-
/**
|
|
1319
|
-
* If `true` then the rowEnd is fixed.
|
|
1320
|
-
*
|
|
1321
|
-
* @defaultValue false
|
|
1322
|
-
*/
|
|
1323
|
-
$rowEnd?: boolean;
|
|
1324
|
-
}
|
|
1325
|
-
/**
|
|
1326
|
-
* The coordinates of a single cell in a 2D space.
|
|
1327
|
-
*/
|
|
1328
|
-
export interface CellCoords {
|
|
1329
|
-
/**
|
|
1330
|
-
* The column index of the cell.
|
|
1331
|
-
*/
|
|
1332
|
-
colIndex: number;
|
|
1333
|
-
/**
|
|
1334
|
-
* The row index of the cell.
|
|
1335
|
-
*/
|
|
1336
|
-
rowIndex: number;
|
|
1337
|
-
sheetName?: string;
|
|
1338
|
-
}
|
|
1339
|
-
/**
|
|
1340
|
-
* Adds fixable flag to `IRange.CellCoords`.
|
|
1341
|
-
*/
|
|
1342
|
-
export interface FixableCellCoords extends CellCoords {
|
|
1343
|
-
/**
|
|
1344
|
-
* If `true`, the column is fixed.
|
|
1345
|
-
*/
|
|
1346
|
-
$colIndex?: boolean;
|
|
1347
|
-
/**
|
|
1348
|
-
* If `true`, the row is fixed.
|
|
1349
|
-
*/
|
|
1350
|
-
$rowIndex?: boolean;
|
|
1351
|
-
}
|
|
1352
|
-
/**
|
|
1353
|
-
* A reference precedent can be Either a `IRange.FixableCoords`, a `FormulaError.Known` or a named range `string`.
|
|
1354
|
-
*/
|
|
1355
|
-
export type StaticReference = IRange.FixableCoords | FormulaError.Known | string;
|
|
1356
|
-
}
|
|
1357
|
-
|
|
1358
|
-
/**
|
|
1359
|
-
* A range that belongs to a container; usually a sheet.
|
|
1360
|
-
*/
|
|
1361
|
-
export declare interface IReferenceRange<T extends Scalar = Scalar> extends IRange<T> {
|
|
1362
|
-
/**
|
|
1363
|
-
* Adds coordinates to a range reference.
|
|
1364
|
-
*/
|
|
1365
|
-
getCoords(): IRange.Coords;
|
|
1366
|
-
/**
|
|
1367
|
-
* For runtime type checking.
|
|
1368
|
-
*/
|
|
1369
|
-
get isIReferenceRange(): true;
|
|
1370
|
-
}
|
|
1371
|
-
|
|
1372
|
-
/**
|
|
1373
|
-
* A complex object type. This allows for more complex data types to be stored in a cell.
|
|
1374
|
-
*/
|
|
1375
|
-
export declare interface IRichData {
|
|
1376
|
-
/**
|
|
1377
|
-
* Reference to either a known typename or a JSON Type Definition.
|
|
1378
|
-
* * {@link https://jsontypedef.com/}
|
|
1379
|
-
*/
|
|
1380
|
-
readonly type: string;
|
|
1381
|
-
toJSON(): IRichData.JSON;
|
|
1382
|
-
fromJSON(): any;
|
|
1383
|
-
}
|
|
1384
|
-
|
|
1385
|
-
export declare namespace IRichData {
|
|
1386
|
-
export interface JSON {
|
|
1387
|
-
type: string;
|
|
1388
|
-
data: any;
|
|
1389
|
-
}
|
|
1390
|
-
}
|
|
1391
|
-
|
|
1392
|
-
/**
|
|
1393
|
-
* Provides details about the system level runtime environment.
|
|
1394
|
-
*/
|
|
1395
|
-
export declare interface IRuntime {
|
|
1396
|
-
/**
|
|
1397
|
-
* Returns true if the date calculation is using the 1904 date system.
|
|
1398
|
-
*/
|
|
1399
|
-
isDate1904(): boolean;
|
|
1400
|
-
/**
|
|
1401
|
-
* Returns the currency symbol for currency values.
|
|
1402
|
-
*/
|
|
1403
|
-
getCurrencySymbol(): string;
|
|
1404
|
-
/**
|
|
1405
|
-
* Returns the decimal separator for number values.
|
|
1406
|
-
*/
|
|
1407
|
-
getNumberDecimalSeparator(): string;
|
|
1408
|
-
/**
|
|
1409
|
-
* Returns the group separator for number values.
|
|
1410
|
-
*/
|
|
1411
|
-
getNumberGroupSeparator(): string;
|
|
1412
|
-
/**
|
|
1413
|
-
* The location of the runtime, e.g. "browser", "node", etc.
|
|
1414
|
-
*/
|
|
1415
|
-
getLocation(): string;
|
|
1416
|
-
/**
|
|
1417
|
-
* Returns a description of the runtime environment.
|
|
1418
|
-
*/
|
|
1419
|
-
getDescription(): string;
|
|
1420
|
-
/**
|
|
1421
|
-
* The version of the runtime, e.g. "1.0.0".
|
|
1422
|
-
*/
|
|
1423
|
-
getVersion(): string;
|
|
1424
|
-
/**
|
|
1425
|
-
* Returns the OS string of the runtime.
|
|
1426
|
-
*/
|
|
1427
|
-
getOS(): string;
|
|
1428
|
-
/**
|
|
1429
|
-
* Returns the current user or `null` if no user information is provided.
|
|
1430
|
-
*/
|
|
1431
|
-
getUser(): string | null;
|
|
1432
|
-
}
|
|
1433
|
-
|
|
1434
|
-
/**
|
|
1435
|
-
* Represents a cell value in JavaScript, including `Date` for convenience.
|
|
1436
|
-
*
|
|
1437
|
-
* @remarks
|
|
1438
|
-
* This type extends `Scalar` by allowing `Date` values. While `Date` is not natively
|
|
1439
|
-
* stored in the cell, it can be passed as a convenience, and it will be internally
|
|
1440
|
-
* converted to a numeric representation.
|
|
1441
|
-
*/
|
|
1442
|
-
export declare type JSScalar = Scalar | Date;
|
|
1443
|
-
|
|
1444
|
-
/**
|
|
1445
|
-
* Represents an update to a cell's value in JavaScript, allowing `Date` and `null`.
|
|
1446
|
-
*
|
|
1447
|
-
* @remarks
|
|
1448
|
-
* This type allows for updating a cell's value, including `Date` for convenience.
|
|
1449
|
-
* As with `ScalarUpdate`, `null` can be used to clear the cell's value.
|
|
1450
|
-
*/
|
|
1451
|
-
export declare type JSScalarUpdate = JSScalar | null | undefined;
|
|
1452
|
-
|
|
1453
|
-
/**
|
|
1454
|
-
* An object interface that defines a set of callback functions a user can use to get
|
|
1455
|
-
* notified of any set of {@link Observable}.
|
|
1456
|
-
*
|
|
1457
|
-
* @see {@link https://rxjs.dev/api/index/class/Observable | Observable}
|
|
1458
|
-
*/
|
|
1459
|
-
export declare class Observable<T = any> {
|
|
1460
|
-
protected _subscribeFn: (subscriber: Subscriber<T>) => () => void;
|
|
1461
|
-
constructor(subscribeFn: (subscriber: Subscriber<T>) => () => void);
|
|
1462
|
-
subscribe(next: any, error: (err: any) => void, complete: () => void): {
|
|
1463
|
-
next: any;
|
|
1464
|
-
error: any;
|
|
1465
|
-
complete: any;
|
|
1466
|
-
unsubscribe: () => void;
|
|
1467
|
-
};
|
|
1468
|
-
}
|
|
1469
|
-
|
|
1470
|
-
/**
|
|
1471
|
-
* Represents a scalar value.
|
|
1472
|
-
*
|
|
1473
|
-
* @remarks
|
|
1474
|
-
* This type does not include dates, as spreadsheet date are serialized numbers.
|
|
1475
|
-
*
|
|
1476
|
-
* @see {@link JSScalar} for a version that includes dates.
|
|
1477
|
-
*/
|
|
1478
|
-
export declare type Scalar = number | boolean | string | FormulaError.Known | IRichData;
|
|
1479
|
-
|
|
1480
|
-
/**
|
|
1481
|
-
* Represents the type of a Scalar.
|
|
1482
|
-
*
|
|
1483
|
-
* @remarks
|
|
1484
|
-
* `ScalarType` is used to indicate the kind of data contained in the cell, such as a number,
|
|
1485
|
-
* string, boolean, or rich data object.
|
|
1486
|
-
*
|
|
1487
|
-
* For example, dates are represented as (serial) numbers, and rich text
|
|
1488
|
-
* or complex data is stored as `RichData`.
|
|
1489
|
-
*/
|
|
1490
|
-
export declare const ScalarType: {
|
|
1491
|
-
/**
|
|
1492
|
-
* A numeric value.
|
|
1493
|
-
*
|
|
1494
|
-
* @remarks
|
|
1495
|
-
* Dates are expressed as formatted numbers within cells. They are internally stored as
|
|
1496
|
-
* serial numbers and can be formatted to display as dates.
|
|
1497
|
-
*/
|
|
1498
|
-
readonly Number: "n";
|
|
1499
|
-
/**
|
|
1500
|
-
* A string value.
|
|
1501
|
-
*/
|
|
1502
|
-
readonly String: "s";
|
|
1503
|
-
/**
|
|
1504
|
-
* A boolean value (`true` or `false`).
|
|
1505
|
-
*/
|
|
1506
|
-
readonly Boolean: "b";
|
|
1507
|
-
/**
|
|
1508
|
-
* A cell that contains an error value.
|
|
1509
|
-
*
|
|
1510
|
-
* @remarks
|
|
1511
|
-
* Error cells represent cells where an error occurred during formula evaluation or data processing.
|
|
1512
|
-
*/
|
|
1513
|
-
readonly Error: "e";
|
|
1514
|
-
/**
|
|
1515
|
-
* A complex data type that is represented as a JSON object.
|
|
1516
|
-
*
|
|
1517
|
-
* @remarks
|
|
1518
|
-
* Rich data may include structured or complex data that goes beyond simple strings, numbers,
|
|
1519
|
-
* or booleans. Useful for use cases where a cell holds data like rich text or embedded objects.
|
|
1520
|
-
*/
|
|
1521
|
-
readonly RichData: "r";
|
|
1522
|
-
/**
|
|
1523
|
-
* Represents a cell that contains no value (null).
|
|
1524
|
-
*
|
|
1525
|
-
* @remarks
|
|
1526
|
-
* Cells with `null` values may still contain formatting or other cell metadata.
|
|
1527
|
-
*/
|
|
1528
|
-
readonly Null: "z";
|
|
1529
|
-
};
|
|
1530
|
-
|
|
1531
|
-
export declare type ScalarType = typeof ScalarType[keyof typeof ScalarType];
|
|
1532
|
-
|
|
1533
|
-
/**
|
|
1534
|
-
* Represents an update to a cell's value, allowing `null` to clear the cell.
|
|
1535
|
-
*
|
|
1536
|
-
* @remarks
|
|
1537
|
-
* This type is used to update a cell's value. Passing `null` will clear the cell's content.
|
|
1538
|
-
* The value must conform to the native types allowed in a cell (`Scalar`).
|
|
1539
|
-
*/
|
|
1540
|
-
export declare type ScalarUpdate = Scalar | null | undefined;
|
|
1541
|
-
|
|
1542
|
-
/**
|
|
1543
|
-
* Default implementation of the IFormulaContext interface.
|
|
1544
|
-
*
|
|
1545
|
-
* @see IFormulaContext
|
|
1546
|
-
*
|
|
1547
|
-
* @remarks
|
|
1548
|
-
* This is a stubbed implementation of the IFormulaContext interface.
|
|
1549
|
-
* Runtime engines should provide a complete implementation.
|
|
1550
|
-
*/
|
|
1551
|
-
export declare class StubbedFormulaContext implements IFormulaContext {
|
|
1552
|
-
/** @inheritdoc IFormulaContext.getRange */
|
|
1553
|
-
getRange(value: Scalar | Scalar[][]): IRange;
|
|
1554
|
-
/** @inheritdoc IFormulaContext.getReference */
|
|
1555
|
-
getReference(coords: Readonly<IRange.Coords>, r1c1?: boolean): IReferenceRange;
|
|
1556
|
-
/** @inheritdoc IFormulaContext.getNumberFormat */
|
|
1557
|
-
getNumberFormat(formatText: string, value: Scalar): string;
|
|
1558
|
-
/** @inheritdoc IFormulaContext.fromOADate */
|
|
1559
|
-
fromOADate(oaDate: number): Date;
|
|
1560
|
-
/** @inheritdoc IFormulaContext.toOADate */
|
|
1561
|
-
toOADate(date: Date): number;
|
|
1562
|
-
/** @inheritdoc IFormulaContext.getValueAt */
|
|
1563
|
-
getValueAt(row: number, column: number): Scalar | null;
|
|
1564
|
-
/** @inheritdoc IFormulaContext.getEntireCoords */
|
|
1565
|
-
getEntireCoords(): IRange.Coords;
|
|
1566
|
-
/** @inheritdoc IFormulaContext.isValidDate */
|
|
1567
|
-
isValidDate(value: any): boolean;
|
|
1568
|
-
/** @inheritdoc IFormulaContext.getPosition */
|
|
1569
|
-
getPosition(): Readonly<IRange.CellCoords>;
|
|
1570
|
-
/** @inheritdoc IFormulaContext.getFormulaAt */
|
|
1571
|
-
getFormulaAt(row: number, column: number): string | null;
|
|
1572
|
-
/** @inheritdoc IFormulaContext.getSpillAt */
|
|
1573
|
-
getSpillAt(row: number, column: number): IReferenceRange | null;
|
|
1574
|
-
/** @inheritdoc IFormulaContext.getSheetIndex */
|
|
1575
|
-
getSheetIndex(sheetName?: string): number;
|
|
1576
|
-
/** @inheritdoc IFormulaContext.getSheetCount */
|
|
1577
|
-
getSheetCount(): number | null;
|
|
1578
|
-
/** @inheritdoc IFormulaContext.markVolatile */
|
|
1579
|
-
markVolatile(): void;
|
|
1580
|
-
/** @inheritdoc IFormulaContext.formatResults */
|
|
1581
|
-
formatResults(numFmt: string): void;
|
|
1582
|
-
/** @inheritdoc IFormulaContext.getFunction */
|
|
1583
|
-
getFunction(name: string): IFunction;
|
|
1584
|
-
/** @inheritdoc IFormulaContext.getAddress */
|
|
1585
|
-
getAddress(coords?: Readonly<IRange.FixableCoords | IRange.FixableCellCoords>, r1c1?: boolean): string;
|
|
1586
|
-
/** @inheritdoc IFormulaContext.parseAsDateTime */
|
|
1587
|
-
parseAsDateTime(text: string, requireDate?: boolean): number | null;
|
|
1588
|
-
/** @inheritdoc IFormulaContext.getRuntime */
|
|
1589
|
-
getRuntime(): IRuntime;
|
|
1590
|
-
}
|
|
1591
|
-
|
|
1592
|
-
/**
|
|
1593
|
-
* An object interface that defines a set of callback functions a user can use to get
|
|
1594
|
-
* notified of any set of {@link Observable}.
|
|
1595
|
-
*/
|
|
1596
|
-
export declare interface Subscriber<T> {
|
|
1597
|
-
/**
|
|
1598
|
-
* A callback function that gets called by the producer during the subscription when
|
|
1599
|
-
* the producer "has" the `value`. It won't be called if `error` or `complete` callback
|
|
1600
|
-
* functions have been called, nor after the consumer has unsubscribed.
|
|
1601
|
-
*/
|
|
1602
|
-
next: (value: T) => void;
|
|
1603
|
-
/**
|
|
1604
|
-
* A callback function that gets called by the producer if and when it encountered a
|
|
1605
|
-
* problem of any kind. The errored value will be provided through the `err` parameter.
|
|
1606
|
-
* This callback can't be called more than one time, it can't be called if the
|
|
1607
|
-
* `complete` callback function have been called previously, nor it can't be called if
|
|
1608
|
-
* the consumer has unsubscribed.
|
|
1609
|
-
*/
|
|
1610
|
-
error: (err: any) => void;
|
|
1611
|
-
/**
|
|
1612
|
-
* A callback function that gets called by the producer if and when it has no more
|
|
1613
|
-
* values to provide (by calling `next` callback function). This means that no error
|
|
1614
|
-
* has happened. This callback can't be called more than one time, it can't be called
|
|
1615
|
-
* if the `error` callback function have been called previously, nor it can't be called
|
|
1616
|
-
* if the consumer has unsubscribed.
|
|
1617
|
-
*/
|
|
1618
|
-
complete: () => void;
|
|
1619
|
-
unsubscribe: () => void;
|
|
1620
|
-
}
|
|
1621
|
-
|
|
1622
|
-
export { }
|
|
1
|
+
export * from './src/index'
|
|
2
|
+
export {}
|