forked from sqlite/sqlite-wasm
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.d.ts
8047 lines (7580 loc) · 276 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** Types of values that can be passed to/retrieved from SQLite. */
declare type SqlValue =
| string
| number
| null
| BigInt
| Uint8Array
| Int8Array
| ArrayBuffer;
/** Internal data types supported by SQLite3. */
declare type SQLiteDataType =
| CAPI['SQLITE_INTEGER']
| CAPI['SQLITE_FLOAT']
| CAPI['SQLITE_TEXT']
| CAPI['SQLITE_BLOB']
| CAPI['SQLITE_NULL'];
/** Specifies parameter bindings. */
declare type BindingSpec =
| readonly SqlValue[]
| { [paramName: string]: SqlValue }
/** Assumed to have binding index `1` */
| SqlValue;
/**
* Certain WASM-bound APIs, where explicitly noted, have additional string-type
* argument conversions colloquially known as "flexible strings." This support
* is generally reserved for arguments which expect SQL strings, as such strings
* are often large and frequently come from external sources, e.g. byte arrays
* loaded from local files, over XHR requests, or using `fetch()`. Functions
* which take filename strings, and simlilar "small" strings, do not use this
* feature.
*/
declare type FlexibleString =
| string
/** WASM C-string pointer, passed on to WASM as-is. */
| WasmPointer
/** Assumed to hold UTF-8 encoded text, converted to `string` */
| Uint8Array
| Int8Array
| ArrayBuffer
/**
* Gets converted to a string using `theArray.join('')` (i.e. concatenated
* as-is, with no space between each entry). Though JS supports multi-line
* string literals with the backtick syntax, it is frequently convenient to
* write out longer SQL constructs as arrays.
*/
| readonly string[];
/**
* Prepared statements are created solely through the {@link Database#prepare}
* method. Calling the constructor directly will trigger an exception.
*
* It is important that statements be finalized in a timely manner, else clients
* risk introducing locking errors later on in their apps.
*
* By and large, clients can avoid statement lifetime issues by using the
* {@link Database#exec} method. For cases when more control or flexibility is
* needed, however, clients will need to {@link Database#prepare} statements and
* then ensure that their lifetimes are properly managed. The simplest way to do
* this is with a `try`/`finally` block, as in this example:
*
* @example
* const stmt = myDb.prepare("...");
* try {
* ... use the stmt object ...
* } finally {
* stmt.finalize();
* }
*/
declare class PreparedStatement {
/** Binds one more values to its bindable parameters. */
bind(binding: BindingSpec): this;
/**
* Binds a value to a bindable parameter.
*
* @param idx The index of the bindable parameter to bind to, **ACHTUNG**:
* 1-based!
*/
bind(idx: number, binding: SqlValue): this;
/**
* Special case of {@link PreparedStatement#bind} which binds the given value
* using the `BLOB` binding mechanism instead of the default selected one for
* the value. Index can be the index number (**ACHTUNG**: 1-based!) or the
* string corresponding to a named parameter.
*/
bindAsBlob(
value: string | null | undefined | Uint8Array | Int8Array | ArrayBuffer,
): this;
bindAsBlob(
idx: number | string,
value: string | null | undefined | Uint8Array | Int8Array | ArrayBuffer,
): this;
/** Clears all bound values. */
clearBindings(): this;
/**
* "Finalizes" this statement. This is a no-op if the statement has already
* been finalized. Returns the value of the underlying `sqlite3_finalize()`
* call (0 on success, non-0 on error) or `undefined` if the statement has
* already been finalized. It does not throw if `sqlite3_finalize()` returns
* non-0 because this function is effectively a destructor and "destructors do
* not throw." This function will throw if it is called while the statement is
* in active use via a {@link Database#exec} callback.
*/
finalize(): number | undefined;
/**
* Fetches the value from the given 0-based column index of the current data
* row, throwing if index is out of range.
*
* Requires that {@link PreparedStatement#step} has just returned a truthy
* value, else an exception is thrown.
*
* By default it will determine the data type of the result automatically. If
* passed a second arugment, it must be one of the enumeration values for
* sqlite3 types, which are defined as members of the sqlite3 namespace:
* `SQLITE_INTEGER`, `SQLITE_FLOAT`, `SQLITE_TEXT`, `SQLITE_BLOB`. Any other
* value, except for `undefined`, will trigger an exception. Passing
* `undefined` is the same as not passing a value. It is legal to, e.g., fetch
* an integer value as a string, in which case sqlite3 will convert the value
* to a string.
*
* If the index is an array, this function behaves a differently: it assigns
* the indexes of the array, from 0 to the number of result columns, to the
* values of the corresponding result column, and returns that array:
*
* const values = stmt.get([]);
*
* This will return an array which contains one entry for each result column
* of the statement's current row..
*
* If the index is a plain object, this function behaves even differentlier:
* it assigns the properties of the object to the values of their
* corresponding result columns:
*
* const values = stmt.get({});
*
* This returns an object with properties named after the columns of the
* result set. Be aware that the ordering of the properties is undefined. If
* their order is important, use the array form instead.
*
* Blobs are returned as `Uint8Array` instances.
*
* Special case handling of 64-bit integers: the `Number` type is used for
* both floating point numbers and integers which are small enough to fit into
* it without loss of precision. If a larger integer is fetched, it is
* returned as a `BigInt` if that support is enabled, else it will throw an
* exception. The range of integers supported by the Number class is defined
* as:
*
* - `Number.MIN_SAFE_INTEGER = -9007199254740991`
* - `Number.MAX_SAFE_INTEGER = 9007199254740991`
*/
get(ndx: number, asType?: SQLiteDataType): SqlValue;
get(ndx: SqlValue[]): SqlValue[];
get(ndx: { [columnName: string]: SqlValue }): {
[columnName: string]: SqlValue;
};
/**
* Equivalent to {@link PreparedStatement#get(ndx)} but coerces the result to a
* `Uint8Array`.
*/
getBlob(ndx: number): Uint8Array | null;
/**
* Returns the result column name of the given index, or throws if index is
* out of bounds or this statement has been finalized. This may be used
* without having run {@link PreparedStatement#step()} first.
*/
getColumnName(ndx: number): string;
/**
* If this statement potentially has result columns, this function returns an
* array of all such names. If passed an array, it is used as the target and
* all names are appended to it. Returns the target array. Throws if this
* statement cannot have result columns. `this.columnCount`, set with the
* statement is prepared, holds the number of columns.
*/
getColumnNames(target?: string[]): string[];
/**
* Equivalent to {@link PreparedStatement#get(ndx)} but coerces the result to a
* number.
*/
getFloat(ndx: number): number | null;
/**
* Equivalent to {@link PreparedStatement#get(ndx)} but coerces the result to
* an integral number.
*/
getInt(ndx: number): number | null;
/**
* Equivalent to {@link PreparedStatement#getString(ndx)} but returns passes
* the result of passing the fetched string string through `JSON.parse()`. If
* JSON parsing throws, that exception is propagated.
*/
getJSON(ndx: number): any;
/**
* If this statement has named bindable parameters and the given name matches
* one, its 1-based bind index is returned. If no match is found, 0 is
* returned. If it has no bindable parameters, the undefined value is
* returned.
*/
getParamIndex(name: string): number | undefined;
/**
* Equivalent to {@link PreparedStatement#get(ndx)} but coerces the result to a
* string.
*/
getString(ndx: number): string | null;
/**
* Resets this statement so that it may be `step()`ed again from the
* beginning. Returns `this`. Throws if this statement has been finalized, if
* it may not legally be reset because it is currently being used from a
* {@link Database#exec} callback, or (as of versions 3.42.1 and 3.43) if the
* underlying call to `sqlite3_reset()` returns non-0.
*
* If passed a truthy argument then {@link PreparedStatement#clearBindings} is
* also called, otherwise any existing bindings, along with any memory
* allocated for them, are retained.
*
* In versions 3.42.0 and earlier, this function did not throw if
* `sqlite3_reset()` returns non-0, but it was discovered that throwing (or
* significant extra client-side code) is necessary in order to avoid certain
* silent failure scenarios
*/
reset(alsoClearBinds?: boolean): this;
/**
* Steps the statement one time. If the result indicates that a row of data is
* available, a truthy value is returned. If no row of data is available, a
* falsy value is returned. Throws on error.
*/
step(): boolean;
/**
* Functions like {@link PreparedStatement#step} except that it calls
* {@link PreparedStatement#finalize} on this statement immediately after
* stepping unless the `step()` throws.
*
* On success, it returns true if the step indicated that a row of data was
* available, else it returns false.
*
* This is intended to simplify use cases such as:
*
* ADb.prepare('INSERT INTO foo(a) VALUES(?)').bind(123).stepFinalize();
*/
stepFinalize(): boolean;
/**
* Functions exactly like {@link PreparedStatement#step} except that...
*
* On success, it calls {@link PreparedStatement#reset} and returns this
* object. On error, it throws and does not call reset().
*
* This is intended to simplify constructs like:
*
* For(...) { stmt.bind(...).stepReset(); }
*
* Note that the {@link PreparedStatement#reset} call makes it illegal to call
* {@link PreparedStatement#get} after the step.
*/
stepReset(): this;
/**
* The number of result columns this statement has, or 0 for statements which
* do not have result columns.
*
* _Minor achtung:_ for all releases > 3.42.0 this is a property interceptor
* which invokes `sqlite3_column_count`, so its use should be avoided in loops
* because of the call overhead. In versions <= 3.42.0 this value is collected
* and cached when the statement is created, but that can lead to misbehavior
* if changes are made to the database schema while this statement is active.
*/
columnCount: number;
/** The number of bindable parameters this statement has. */
parameterCount: number;
/**
* WASM pointer rwhich resolves to the `sqlite3_stmt*` which this object
* wraps. This value may be passed to any WASM-bound functions which accept an
* `sqlite3_stmt*` argument. It resolves to `undefined` after this statement
* is {@link PreparedStatement#finalize}d.
*/
pointer: WasmPointer | undefined;
}
declare type ExecOptions = {
/**
* The SQL to run (unless it's provided as the first argument). The SQL may
* contain any number of statements.
*/
sql?: FlexibleString;
/**
* A single value valid as an argument for {@link PreparedStatement#bind}. This
* is only applied to the first non-empty statement in the SQL which has any
* bindable parameters. (Empty statements are skipped entirely.)
*/
bind?: BindingSpec;
/**
* If set, the SQL of each executed statement is appended to this array before
* the statement is executed (but after it is prepared - we don't have the
* string until after that). Empty SQL statements are elided.
*/
saveSql?: string[];
/**
* A string specifying what this function should return: The default value is
* (usually) `"this"`. The exceptions is if the caller passes neither of
* `callback` nor `returnValue` but does pass an explicit `rowMode` then the
* default returnValue is `"resultRows"`, described below. The options are:
*
* - `"this"` menas that the DB object itself should be returned.
* - `"resultRows"` means to return the value of the `resultRows` option. If
* `resultRows` is not set, this function behaves as if it were set to an
* empty array.
* - `"saveSql"` means to return the value of the `saveSql` option. If `saveSql`
* is not set, this function behaves as if it were set to an empty array.
*/
returnValue?: 'this' | 'resultRows' | 'saveSql';
/**
* A function which gets called for each row of the result set (see `rowMode`,
* below), but only if that statement has any result rows. The callback's
* `this` is the `options` object, noting that this function will synthesize
* one if the caller does not provide one. The second argument passed to the
* callback is always the current {@link PreparedStatement} object, as it's
* needed if the caller wants to fetch the column names or some such (noting
* that they could also be fetched via `this.columnNames`, if the client
* provides the `columnNames` option). If the callback returns a literal
* `false` (as opposed to any other falsy value, e.g. an implicit undefined
* return), any ongoing statement-`step()` iteration stops without an error.
* The return value of the callback is otherwise ignored.
*
* Applies only to the first statement which has a non-zero result column
* count, regardless of whether the statement actually produces any result
* rows.
*
* **ACHTUNG:** the callback **MUST NOT** modify the {@link PreparedStatement}
* object. Calling any of the {@link PreparedStatement#get} variants,
* {@link PreparedStatement#getColumnName}, or similar, is legal, but calling
* {@link PreparedStatement#step} or {@link PreparedStatement#finalize} is not.
* Member methods which are illegal in this context will trigger an exception,
* but clients must also refrain from using any lower-level (C-style) APIs
* which might modify the statement.
*/
callback?: (
row:
| SqlValue[]
| { [columnName: string]: SqlValue }
| PreparedStatement
| SqlValue,
stmt: PreparedStatement,
) => void | false;
/**
* If this is an array, the column names of the result set are stored in this
* array before the `callback` (if any) is triggered (regardless of whether
* the query produces any result rows). If no statement has result columns,
* this value is unchanged.
*
* Applies only to the first statement which has a non-zero result column
* count, regardless of whether the statement actually produces any result
* rows.
*
* **Achtung:** an SQL result may have multiple columns with identical names.
*/
columnNames?: string[];
/**
* If this is an array, it functions similarly to the `callback` option: each
* row of the result set (if any), with the exception that the `rowMode`
* `'stmt'` is not legal. It is legal to use both `resultRows` and callback,
* but `resultRows` is likely much simpler to use for small data sets and can
* be used over a WebWorker-style message interface. `exec()` throws if
* `resultRows` is set and rowMode is `'stmt'`.
*
* Applies only to the first statement which has a non-zero result column
* count, regardless of whether the statement actually produces any result
* rows.
*/
resultRows?: (SqlValue[] | { [columnName: string]: SqlValue } | SqlValue)[];
/**
* Specifies the type of he `callback`'s first argument and the type of the
* `resultRows` array entries.
*/
rowMode?: 'array' | 'object' | 'stmt' | number | string;
};
/**
* Derivate type of ExecOptions to be used as base mixin for method overloads on
* `exec`
*/
declare type ExecBaseOptions = Omit<
ExecOptions,
'callback' | 'resultRows' | 'rowMode' | 'returnValue' | 'sql'
>;
declare type ExecReturnThisOptions = {
returnValue?: 'this';
};
declare type ExecReturnResultRowsOptions = {
returnValue: 'resultRows';
};
declare type ExecReturnSaveSqlOptions = {
returnValue: 'saveSql';
};
declare type ExecRowModeArrayOptions = {
callback?: (row: SqlValue[]) => void | false;
resultRows?: SqlValue[][];
rowMode?: 'array';
};
declare type ExecRowModeObjectOptions = {
callback?: (row: { [columnName: string]: SqlValue }) => void | false;
resultRows?: { [columnName: string]: SqlValue }[];
rowMode: 'object';
};
declare type ExecRowModeStmtOptions = {
callback?: (row: PreparedStatement) => void | false;
resultRows?: undefined;
rowMode: 'stmt';
};
declare type ExecRowModeScalarOptions = {
callback?: (row: SqlValue) => void | false;
resultRows?: SqlValue[];
/**
* For number values: indicates a zero-based column in the result row. Only
* that one single value will be passed on. If string. For string values: A
* string with a minimum length of 2 and leading character of `$` will fetch
* the row as an object, extract that one field, and pass that field's value
* to the `callback`. Note that these keys are case-sensitive so must match
* the case used in the SQL. e.g. `"select a A from t"` with a `rowMode` of
* `'$A'` would work but `'$a'` would not. A reference to a column not in the
* result set will trigger an exception on the first row (as the check is not
* performed until rows are fetched).
*/
rowMode: number | Exclude<string, 'stmt' | 'array' | 'object'>;
};
/** Options for creating a user-defined function that can be called from SQL. */
declare type FunctionOptions = {
/**
* Number of arguments which SQL calls to this function expect or require. The
* default value is `X.length` MINUS 1, where X is either `xFunc` or `xStep`,
* depending on the type of function being created. As a special case, if
* `X.length` is 0, its arity is also 0 instead of -1. A negative arity value
* means that the function is variadic and may accept any number of arguments,
* up to sqlite3's compile-time limits. sqlite3 will enforce the argument
* count if is zero or greater. The callback always receives a pointer to an
* `sqlite3_context` object as its first argument. Any arguments after that
* are from SQL code. The leading context argument does not count towards the
* function's arity. See the docs for `sqlite3_create_function()` for why that
* argument is required in the interface.
*/
arity?: number;
/**
* Corresponds to the `SQLITE_DETERMINISTIC` flag. Setting it means that the
* new function always gives the same output when the input parameters are the
* same. The `abs()` function is deterministic, for example, but
* `randomblob()` is not. Functions must be deterministic in order to be used
* in certain contexts such as with the `WHERE` clause of partial indexes or
* in generated columns. SQLite might also optimize deterministic functions by
* factoring them out of inner loops.
*/
deterministic?: boolean;
/**
* Corresponds to the `SQLITE_DIRECTONLY` flag.
*
* Setting it means that the function may only be invoked from top-level SQL,
* and cannot be used in `VIEW`s or `TRIGGER`s nor in schema structures such
* as `CHECK` constraints, `DEFAULT` clauses, expression indexes, partial
* indexes, or generated columns.
*
* The flag is recommended for any application-defined SQL function that has
* side-effects or that could potentially leak sensitive information. This
* will prevent attacks in which an application is tricked into using a
* database file that has had its schema surreptiously modified to invoke the
* application-defined function in ways that are harmful.
*
* Some people say it is good practice to set the flag on all
* application-defined SQL functions, regardless of whether or not they are
* security sensitive, as doing so prevents those functions from being used
* inside of the database schema, and thus ensures that the database can be
* inspected and modified using generic tools (such as the CLI) that do not
* have access to the application-defined functions.
*/
directOnly?: boolean;
/**
* Corresponds to the `SQLITE_INNOCUOUS` flag.
*
* Setting it means that the function is unlikely to cause problems even if
* misused. An innocuous function should have no side effects and should not
* depend on any values other than its input parameters. The `abs()` function
* is an example of an innocuous function. The `load_extension()` SQL function
* is not innocuous because of its side effects. The flag is similar to
* {@link FunctionOptions#directOnly}, but is not exactly the same. The
* `random()` function is an example of a function that is innocuous but not
* deterministic.
*
* Some heightened security settings (`SQLITE_DBCONFIG_TRUSTED_SCHEMA` and
* `PRAGMA trusted_schema=OFF`) disable the use of SQL functions inside views
* and triggers and in schema structures such as `CHECK` constraints,
* `DEFAULT` clauses, expression indexes, partial indexes, and generated
* columns unless the function is tagged with `SQLITE_INNOCUOUS`. Most
* built-in functions are innocuous. Developers are advised to avoid using the
* `SQLITE_INNOCUOUS` flag for application-defined functions unless the
* function has been carefully audited and found to be free of potentially
* security-adverse side-effects and information-leaks.
*/
innocuous?: boolean;
/** Name of the user-defined function. */
name?: string;
/**
* The options object may optionally have an xDestroy function-type property,
* as per `sqlite3_create_function_v2()`. Its argument will be the
* WASM-pointer-type value of the pApp property, and this function will throw
* if pApp is defined but is not null, undefined, or a numeric (WASM pointer)
* value. i.e. pApp, if set, must be value suitable for use as a WASM pointer
* argument, noting that null or undefined will translate to 0 for that
* purpose.
*/
xDestroy?: (pAppPtr: WasmPointer) => void;
};
declare type ScalarFunctionOptions = FunctionOptions & {
/** Scalar function to be defined. */
xFunc: (ctxPtr: number, ...args: SqlValue[]) => SqlValue;
};
declare type AggregateFunctionOptions = FunctionOptions & {
/**
* 'Step' callback for an aggregate function.
*
* It is invoked to add a row to the current aggregate value. The function
* arguments, if any, corresponding to the row being added are passed to the
* implementation of {@link AggregateFunctionOptions#xStep}.
*/
xStep: (ctxPtr: number, ...rowValues: SqlValue[]) => void;
/**
* 'Final' callback for an aggregate function.
*
* It is invoked to return the current value of the aggregate, and to free any
* resources allocated by earlier calls to
* {@link AggregateFunctionOptions#xStep}.
*/
xFinal: (ctxPtr: number) => SqlValue;
};
declare type WindowFunctionOptions = FunctionOptions & {
/**
* 'Step' callback for a window function.
*
* It is invoked to add a row to the current window. The function arguments,
* if any, corresponding to the row being added are passed to the
* implementation of {@link WindowFunctionOptions#xStep}.
*/
xStep: (ctxPtr: number, ...args: any[]) => void;
/**
* 'Final' callback for a window function.
*
* It is invoked to return the current value of the aggregate (determined by
* the contents of the current window), and to free any resources allocated by
* earlier calls to {@link WindowFunctionOptions#xStep}.
*/
xFinal: (ctxPtr: number) => SqlValue;
/**
* 'Value' callback for a window function. This method is invoked to return
* the current value of the aggregate. Unlike
* {@link WindowFunctionOptions#xFinal}, the implementation should not delete
* any context.
*/
xValue: (ctxPtr: number) => SqlValue;
/**
* 'Inverse' callback for a window function.
*
* It is invoked to remove the oldest presently aggregated result of
* {@link WindowFunctionOptions#xStep} from the current window. The function
* arguments, if any, are those passed to {@link WindowFunctionOptions#xStep}
* for the row being removed.
*/
xInverse: (ctxPtr: number, ...args: any[]) => void;
};
/**
* An instance of an implementing class corresponds to one `sqlite3*` created
* using `sqlite3_open` or equivalent.
*
* @example
* ```typescript
* const db = new sqlite3.DB();
* try {
* db.exec([
* "create table t(a);",
* "insert into t(a) values(10),(20),(30)"
* ]);
* } finally {
* db.close();
* }
* ```;
*/
declare class Database {
/**
* Creates a connection to the given file, optionally creating it if needed.
*
* @param options The options to use when opening the database file.
* @param options.filename The filename to open. Must be resolvable using
* whatever filesystem layer (virtual or otherwise) is set up for the
* default sqlite3 VFS. Note that the special sqlite3 db names `":memory:"`
* and `""` (temporary db) have their normal special meanings here.
* @param options.flags The flags to use when opening the file. It must be a
* string containing a sequence of letters (in any order, but case
* sensitive) specifying the mode:
*
* - `c`: create if it does not exist, else fail if it does not exist. Implies
* the `w` flag.
* - `w`: write. Implies `r`: a db cannot be write-only.
* - `r`: read-only if neither `w` nor `c` are provided, else it is ignored.
* - `t`: enable tracing of SQL executed on this database handle, sending it to
* `console.log()`. To disable it later, call
* `sqlite3.capi.sqlite3_trace_v2(thisDb.pointer, 0, 0, 0)`. If `w` is
* not provided, the db is implicitly read-only, noting that `rc` is
* meaningless. Any other letters are currently ignored. The default is
* `c`. These modes are ignored for the special `":memory:"` and `""`
* names and may be ignored by specific VFSes.
*/
constructor(options?: { filename?: string; flags?: string; vfs?: string }); // ✓
/**
* Creates a connection to the given file, optionally creating it if needed.
*
* @param filename The filename to open. Must be resolvable using whatever
* filesystem layer (virtual or otherwise) is set up for the default sqlite3
* VFS. Note that the special sqlite3 db names `":memory:"` and `""`
* (temporary db) have their normal special meanings here.
* @param flags The flags to use when opening the file. It must be a string
* containing a sequence of letters (in any order, but case sensitive)
* specifying the mode:
*
* - `c`: create if it does not exist, else fail if it does not exist. Implies
* the `w` flag.
* - `w`: write. Implies `r`: a db cannot be write-only.
* - `r`: read-only if neither `w` nor `c` are provided, else it is ignored.
* - `t`: enable tracing of SQL executed on this database handle, sending it to
* `console.log()`. To disable it later, call
* `sqlite3.capi.sqlite3_trace_v2(thisDb.pointer, 0, 0, 0)`. If `w` is
* not provided, the db is implicitly read-only, noting that `rc` is
* meaningless. Any other letters are currently ignored. The default is
* `c`. These modes are ignored for the special `":memory:"` and `""`
* names and may be ignored by specific VFSes.
*/
constructor(filename?: string, flags?: string, vfs?: string); // ✓
/** Filename which was passed to the constructor. */
filename: string; // ✓
/**
* Resolves to the `sqlite3*` which this object wraps. This value may be
* passed to any WASM-bound functions which accept an `sqlite3*` argument. It
* resolves to `undefined` after this object is `close()`d.
*/
pointer?: WasmPointer; // ✓
/** Callbacks called immediately before/after database is closed. */
onclose?: {
before?: (db: Database) => void;
after?: (db: Database) => void;
}; // ✓
/**
* Executes SQL statements and optionally collects query results and/or calls
* a callback for each result row.
*
* _LOTS_ of overloads on this one one, depending on:
*
* - `sql` as parameter or as option
* - `returnValue`:
*
* - `"this"`: default, return database instance, use for fluent calls
* - `"resultRows"`: return values of `resultRows` array (set to empty array if
* not set by user)
* - `"saveSql"`: return values of `saveSql` option (set to empty array if not
* set by user)
* - `resultRows`:
*
* - `"array"`: Array of column values for every result row
* - `"object"`: Object mapping column names to values for every result row
* - `"stmt"`: Only for use with `callback` option, pass
* {@link PreparedStatement} object for every row.
* - `number`: Extract column with (zero-based) index from every result row
* - `string`: Extract column with name from every result row, must have format
* `$<column>`, with `column` having at least two characters.
*
* ⚠️**ACHTUNG**⚠️: The combination of `returnValue: "resultRows"` and
* `rowMode: "stmt"` type checks fine, but will lead to a runtime error. This
* is due to a limitation in TypeScript's type system which does not allow
* restrictions on `string` types.
*/
exec(
sql: FlexibleString,
opts?: (ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnThisOptions) & {
sql?: undefined;
},
): this;
exec(
opts: (ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnThisOptions) & { sql: FlexibleString },
): this;
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnThisOptions & {
sql?: undefined;
},
): this;
exec(
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnThisOptions & {
sql: FlexibleString;
},
): this;
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeStmtOptions &
ExecReturnThisOptions & {
sql?: undefined;
},
): this;
exec(
opts: ExecBaseOptions &
ExecRowModeStmtOptions &
ExecReturnThisOptions & {
sql: FlexibleString;
},
): this;
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnThisOptions & {
sql?: undefined;
},
): this;
exec(
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnThisOptions & {
sql: FlexibleString;
},
): this;
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnResultRowsOptions & {
sql?: undefined;
},
): SqlValue[][];
exec(
opts: ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnResultRowsOptions & {
sql: FlexibleString;
},
): SqlValue[][];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnResultRowsOptions & {
sql?: undefined;
},
): { [columnName: string]: SqlValue }[];
exec(
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnResultRowsOptions & {
sql: FlexibleString;
},
): { [columnName: string]: SqlValue }[];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnResultRowsOptions & {
sql?: undefined;
},
): SqlValue[];
exec(
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnResultRowsOptions & {
sql: FlexibleString;
},
): SqlValue[];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnSaveSqlOptions & {
sql?: undefined;
},
): string[];
exec(
opts: ExecBaseOptions &
ExecRowModeArrayOptions &
ExecReturnSaveSqlOptions & {
sql: FlexibleString;
},
): string[];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnSaveSqlOptions & {
sql?: undefined;
},
): string[];
exec(
opts: ExecBaseOptions &
ExecRowModeObjectOptions &
ExecReturnSaveSqlOptions & {
sql: FlexibleString;
},
): string[];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeStmtOptions &
ExecReturnSaveSqlOptions & {
sql?: undefined;
},
): string[];
exec(
opts: ExecBaseOptions &
ExecRowModeStmtOptions &
ExecReturnSaveSqlOptions & {
sql: FlexibleString;
},
): string[];
exec(
sql: FlexibleString,
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnSaveSqlOptions & {
sql?: undefined;
},
): string[];
exec(
opts: ExecBaseOptions &
ExecRowModeScalarOptions &
ExecReturnSaveSqlOptions & {
sql: FlexibleString;
},
): string[];
/**
* Compiles the given SQL and returns a {@link PreparedStatement}. This is the
* only way to create new {@link PreparedStatement} objects. Throws on error.
*/
prepare(sql: FlexibleString): PreparedStatement;
/** Returns true if the database handle is open, else false. */
isOpen(): boolean;
/** Throws if the given DB has been closed. */
affirmOpen(): this;
/**
* Finalizes all still-open statements which were opened by this object and
* closes this database connection. This is a no-op if the db has already been
* closed. After calling `close()`, {@link pointer} will resolve to
* `undefined`, so that can be used to check whether the db instance is still
* opened.
*
* If {@link onclose.before} is a function then it is called before any
* close-related cleanup. If {@link onclose.after} is a function then it is
* called after the db is closed but before auxiliary state like this.filename
* is cleared.
*
* Both onclose handlers are passed this object as their only argument. If
* this db is not opened, neither of the handlers are called. Any exceptions
* the handlers throw are ignored because "destructors must not throw."
*
* Note that garbage collection of a db handle, if it happens at all, will
* never trigger `close()`, so {@link onclose} handlers are not a reliable way
* to implement close-time cleanup or maintenance of a db.
*/
close(): void; // ✓
/**
* Returns the number of changes, as per `sqlite3_changes()` (if the first
* argument is `false`) or `sqlite3_total_changes()` (if it's `true`). If the
* 2nd argument is `true`, it uses `sqlite3_changes64()` or
* `sqlite3_total_changes64()`, which will trigger an exception if this build
* does not have `BigInt` support enabled.
*/
changes(total?: boolean, sixtyFour?: boolean): number;
/**
* Returns the filename associated with the given database name. Defaults to
* `main`. Throws if this database is `close()`d.
*/
dbFilename(dbName?: string): string | null;
/**
* Returns the name of the given 0-based db number. Defaults to `0`. Throws if
* this database is `close()`d.
*/
dbName(dbIndex?: number): string | null;
/**
* Returns the name of the sqlite_vfs for the given database. Defaults to
* `main`. Throws if this database is `close()`d.
*/
dbVfsName(dbName?: string | number): string | undefined;
/**
* Creates a new scalar, aggregate, or window function which is accessible via
* SQL code.
*
* When called from SQL, arguments to the UDF, and its result, will be
* converted between JS and SQL with as much fidelity as is feasible,
* triggering an exception if a type conversion cannot be determined. Some
* freedom is afforded to numeric conversions due to friction between the JS
* and C worlds: integers which are larger than 32 bits will be treated as
* doubles or `BigInt` values.
*
* UDFs cannot currently be removed from a DB handle after they're added. More
* correctly, they can be removed as documented for
* `sqlite3_create_function_v2()`, but doing so will "leak" the JS-created
* WASM binding of those functions.
*
* The first two call forms can only be used for creating scalar functions.
* Creating an aggregate or window function requires the options-object form,
* as described below.
*/
createFunction(
name: string,
func: (ctxPtr: number, ...values: SqlValue[]) => SqlValue,
): this;
createFunction(
name: string,
func: (ctxPtr: number, ...values: SqlValue[]) => void,
options: FunctionOptions,
): this;
createFunction(
name: string,
options:
| ScalarFunctionOptions
| AggregateFunctionOptions
| WindowFunctionOptions,
): this;
createFunction(
options: (
| ScalarFunctionOptions
| AggregateFunctionOptions
| WindowFunctionOptions
) & { name: string },
): this;
/**
* Prepares the given SQL, `step()`s it one time, and returns an array
* containing the values of the first result row. If it has no results,
* `undefined` is returned. If passed a second argument other than
* `undefined`, it is treated like an argument to