-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Expand file tree
/
Copy pathsqlite3-api-prologue.js
More file actions
2240 lines (1978 loc) · 86.5 KB
/
Copy pathsqlite3-api-prologue.js
File metadata and controls
2240 lines (1978 loc) · 86.5 KB
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
/*
2022-05-22
The author disclaims copyright to this source code. In place of a
legal notice, here is a blessing:
* May you do good and not evil.
* May you find forgiveness for yourself and forgive others.
* May you share freely, never taking more than you give.
***********************************************************************
This file is intended to be combined at build-time with other
related code, most notably a header and footer which wraps this
whole file into a single callback which can be run after Emscripten
loads the corresponding WASM module. The sqlite3 JS API has no hard
requirements on Emscripten and does not expose any Emscripten APIs
to clients. It is structured such that its build can be tweaked to
include it in arbitrary WASM environments which can supply the
necessary underlying features (e.g. a POSIX file I/O layer).
Main project home page: https://sqlite.org
Documentation home page: https://sqlite.org/wasm
*/
/**
sqlite3ApiBootstrap() is the only global symbol persistently
exposed by this API. It is intended to be called one time at the
end of the API amalgamation process and passed configuration details
for the current environment.
This function is not intended for client-level use. It is intended
for use in creating bundles configured for specific WASM
environments. That said, the "sqlite3-api.js" intermediary build
file aims to be suitable for dropping in to custom builds, and it
exposes only this function.
This function expects a configuration object, intended to abstract
away details specific to any given WASM environment, primarily so
that it can be used without any direct dependency on
Emscripten. (Note the default values for the config object!) The
config object is only honored the first time this is
called. Subsequent calls ignore the argument and return the same
(configured) object which gets initialized by the first call. This
function will throw if any of the required config options are
missing.
The config object properties include:
- `exports`[^1]: the "exports" object for the current WASM
environment. In an Emscripten-based build, this should be set to
`Module['asm']` (versions <=3.1.43) or `Module['wasmExports']`
(versions >=3.1.44).
- `memory`[^1]: optional WebAssembly.Memory object, defaulting to
`exports.memory`. In Emscripten environments this should be set
to `Module.wasmMemory` if the build uses `-sIMPORTED_MEMORY`, or be
left undefined/falsy to default to `exports.memory` when using
WASM-exported memory.
- `functionTable`[^1]: optional WebAssembly.Table object holding
the indirect function table. If not set then the table is assumed
to be in `exports.__indirect_function_table`.
- `bigIntEnabled`: true if BigInt support is enabled. Defaults to
true if `globalThis.BigInt64Array` is available, else false. Some APIs
will throw exceptions if called without BigInt support, as BigInt
is required for marshalling C-side int64 into and out of JS.
(Sidebar: it is technically possible to add int64 support via
marshalling of int32 pairs, but doing so is unduly invasive.)
- `allocExportName`: the name of the function, in `exports`, of the
`malloc(3)`-compatible routine for the WASM environment. Defaults
to `"sqlite3_malloc"`. Beware that using any allocator other than
sqlite3_malloc() may require care in certain client-side code
regarding which allocator is uses. Notably, sqlite3_deserialize()
and sqlite3_serialize() can only safely use memory from different
allocators under very specific conditions. The canonical builds
of this API guaranty that `sqlite3_malloc()` is the JS-side
allocator implementation.
- `deallocExportName`: the name of the function, in `exports`, of
the `free(3)`-compatible routine for the WASM
environment. Defaults to `"sqlite3_free"`.
- `reallocExportName`: the name of the function, in `exports`, of
the `realloc(3)`-compatible routine for the WASM
environment. Defaults to `"sqlite3_realloc"`.
- `debug`, `log`, `warn`, and `error` may be functions equivalent
to the like-named methods of the global `console` object. By
default, these map directly to their `console` counterparts, but
can be replaced with (e.g.) empty functions to squelch all such
output.
- `wasmfsOpfsDir`[^1]: Specifies the "mount point" of the
OPFS-backed filesystem in WASMFS-capable builds. This is only
used in WASMFS-capable builds of the library (which the canonical
builds do not include).
- `disable` (as of 3.53.0) may be an object with the following
properties:
- `vfs`, an object, may contain a map of VFS names to booleans.
Any mapping to falsy are disabled. The supported names
are: "kvvfs", "opfs", "opfs-sahpool", "opfs-wl".
- Other disabling options may be added in the future.
[^1] = This property may optionally be a function, in which case
this function calls that function to fetch the value,
enabling delayed evaluation.
The returned object is the top-level sqlite3 namespace object.
Client code may optionally assign sqlite3ApiBootstrap.defaultConfig
an object-type value before calling sqlite3ApiBootstrap() (without
arguments) in order to tell that call to use this object as its
default config value. The intention of this is to provide
downstream clients with a reasonably flexible approach for plugging
in an environment-suitable configuration without having to define a
new global-scope symbol.
However, because clients who access this library via an
Emscripten-hosted module will not have an opportunity to call
sqlite3ApiBootstrap() themselves, nor to access it before it is
called, an alternative option for setting the configuration is to
define globalThis.sqlite3ApiConfig to an object. If it is set, it
is used instead of sqlite3ApiBootstrap.defaultConfig if
sqlite3ApiBootstrap() is called without arguments. Setting the
`exports` and `memory` parts require already having loaded the WASM
module, though.
Both sqlite3ApiBootstrap.defaultConfig and
globalThis.sqlite3ApiConfig get deleted by sqlite3ApiBootstrap()
because any changes to them made after that point would have no
useful effect. This function also deletes itself from globalThis
when it's called.
This function returns a Promise to the sqlite3 namespace object,
which resolves after the async pieces of the library init are
complete.
*/
'use strict';
globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
apiConfig = (globalThis.sqlite3ApiConfig || sqlite3ApiBootstrap.defaultConfig)
){
if(sqlite3ApiBootstrap.sqlite3){ /* already initialized */
(sqlite3ApiBootstrap.sqlite3.config || console).warn(
"sqlite3ApiBootstrap() called multiple times.",
"Config and external initializers are ignored on calls after the first."
);
return sqlite3ApiBootstrap.sqlite3;
}
const nu = (...obj)=>Object.assign(Object.create(null),...obj);
const config = nu({
exports: undefined,
memory: undefined,
bigIntEnabled: !!globalThis.BigInt64Array,
debug: console.debug.bind(console),
warn: console.warn.bind(console),
error: console.error.bind(console),
log: console.log.bind(console),
wasmfsOpfsDir: '/opfs',
/**
useStdAlloc is just for testing allocator discrepancies. The
docs guarantee that this is false in the canonical builds. For
99% of purposes it doesn't matter which allocators we use, but
it becomes significant with, e.g., sqlite3_deserialize() and
certain wasm.xWrap.resultAdapter()s.
*/
useStdAlloc: false
}, apiConfig);
Object.assign(config, {
allocExportName: config.useStdAlloc ? 'malloc' : 'sqlite3_malloc',
deallocExportName: config.useStdAlloc ? 'free' : 'sqlite3_free',
reallocExportName: config.useStdAlloc ? 'realloc' : 'sqlite3_realloc'
});
[
// If any of these config options are functions, replace them with
// the result of calling that function. They must not be async.
'exports', 'memory', 'functionTable', 'wasmfsOpfsDir'
].forEach((k)=>{
if('function' === typeof config[k]){
config[k] = config[k]();
}
});
/**
The main sqlite3 binding API gets installed into this object,
mimicking the C API as closely as we can. The numerous members
names with prefixes 'sqlite3_' and 'SQLITE_' behave, insofar as
possible, identically to the C-native counterparts, as documented at:
https://sqlite.org/c3ref/intro.html
A very few exceptions require an additional level of proxy
function or may otherwise require special attention in the WASM
environment, and all such cases are documented somewhere below
in this file or in sqlite3-api-glue.js. capi members which are
not documented are installed as 1-to-1 proxies for their
C-side counterparts.
*/
const capi = nu();
/**
Holds state which are specific to the WASM-related
infrastructure and glue code.
Note that a number of members of this object are injected
dynamically after the api object is fully constructed, so
not all are documented in this file.
*/
const wasm = nu();
/** Internal helper for SQLite3Error ctor. */
const __rcStr = (rc)=>{
return (capi.sqlite3_js_rc_str && capi.sqlite3_js_rc_str(rc))
|| ("Unknown result code #"+rc);
};
/** Internal helper for SQLite3Error ctor. */
const isInt32 = (n)=>
'number'===typeof n
&& n===(n | 0)
&& n<=2147483647 && n>=-2147483648;
/**
An Error subclass specifically for reporting DB-level errors and
enabling clients to unambiguously identify such exceptions.
The C-level APIs never throw, but some of the higher-level
C-style APIs do and the object-oriented APIs use exceptions
exclusively to report errors.
*/
class SQLite3Error extends Error {
/**
Constructs this object with a message depending on its arguments:
If its first argument is an integer, it is assumed to be
an SQLITE_... result code and it is passed to
sqlite3.capi.sqlite3_js_rc_str() to stringify it.
If called with exactly 2 arguments and the 2nd is an object,
that object is treated as the 2nd argument to the parent
constructor.
The exception's message is created by concatenating its
arguments with a space between each, except for the
two-args-with-an-object form and that the first argument will
get coerced to a string, as described above, if it's an
integer.
If passed an integer first argument, the error object's
`resultCode` member will be set to the given integer value,
else it will be set to capi.SQLITE_ERROR.
*/
constructor(...args){
let rc;
if(args.length){
if(isInt32(args[0])){
rc = args[0];
if(1===args.length){
super(__rcStr(args[0]));
}else{
const rcStr = __rcStr(rc);
if('object'===typeof args[1]){
super(rcStr,args[1]);
}else{
args[0] = rcStr+':';
super(args.join(' '));
}
}
}else{
if(2===args.length && 'object'===typeof args[1]){
super(...args);
}else{
super(args.join(' '));
}
}
}
this.resultCode = rc || capi.SQLITE_ERROR;
this.name = 'SQLite3Error';
}
};
/**
Functionally equivalent to the SQLite3Error constructor but may
be used as part of an expression, e.g.:
```
return someFunction(x) || SQLite3Error.toss(...);
```
*/
SQLite3Error.toss = (...args)=>{
throw new SQLite3Error(...args);
};
const toss3 = SQLite3Error.toss;
if(config.wasmfsOpfsDir && !/^\/[^/]+$/.test(config.wasmfsOpfsDir)){
toss3("config.wasmfsOpfsDir must be falsy or in the form '/dir-name'.");
}
/**
Returns true if the given BigInt value is small enough to fit
into an int64 value, else false.
*/
const bigIntFits64 = function f(b){
if(!f._max){
f._max = BigInt("0x7fffffffffffffff");
f._min = ~f._max;
}
return b >= f._min && b <= f._max;
};
/**
Returns true if the given BigInt value is small enough to fit
into an int32, else false.
*/
const bigIntFits32 = (b)=>(b >= (-0x7fffffffn - 1n) && b <= 0x7fffffffn);
/**
Returns true if the given BigInt value is small enough to fit
into a double value without loss of precision, else false.
*/
const bigIntFitsDouble = function f(b){
if(!f._min){
f._min = Number.MIN_SAFE_INTEGER;
f._max = Number.MAX_SAFE_INTEGER;
}
return b >= f._min && b <= f._max;
};
/** Returns v if v appears to be a TypedArray, else false. */
const isTypedArray = (v)=>{
return (v && v.constructor && isInt32(v.constructor.BYTES_PER_ELEMENT)) ? v : false;
};
/**
Returns true if v appears to be one of our bind()-able TypedArray
types: Uint8Array or Int8Array or ArrayBuffer. Support for
TypedArrays with element sizes >1 is a potential TODO just
waiting on a use case to justify them. Until then, their `buffer`
property can be used to pass them as an ArrayBuffer. If it's not
a bindable array type, a falsy value is returned.
*/
const isBindableTypedArray = (v)=>
v && (v instanceof Uint8Array
|| v instanceof Int8Array
|| v instanceof ArrayBuffer);
/**
Returns true if v appears to be one of the TypedArray types
which is legal for holding SQL code (as opposed to binary blobs).
Currently this is the same as isBindableTypedArray() but it
seems likely that we'll eventually want to add Uint32Array
and friends to the isBindableTypedArray() list but not to the
isSQLableTypedArray() list.
*/
const isSQLableTypedArray = (v)=>
v && (v instanceof Uint8Array
|| v instanceof Int8Array
|| v instanceof ArrayBuffer);
/** Returns true if isBindableTypedArray(v) does, else throws with a message
that v is not a supported TypedArray value. */
const affirmBindableTypedArray = (v)=>
isBindableTypedArray(v)
|| toss3("Value is not of a supported TypedArray type.");
/**
If v is-a Array, its join("") result is returned. If
isSQLableTypedArray(v) is true then wasm.typedArrayToString(v) is
returned. If it looks like a WASM pointer, wasm.cstrToJs(v) is
returned. Else v is returned as-is.
Reminder to self: the "return as-is" instead of returning ''+v is
arguably a design mistake but changing it is risky at this point.
*/
const flexibleString = function(v){
if(isSQLableTypedArray(v)){
return wasm.typedArrayToString(
(v instanceof ArrayBuffer) ? new Uint8Array(v) : v,
0, v.length
);
}
else if(Array.isArray(v)) return v.join("");
else if(wasm.isPtr(v)) v = wasm.cstrToJs(v);
return v;
};
/**
An Error subclass specifically for reporting Wasm-level malloc()
failure and enabling clients to unambiguously identify such
exceptions.
*/
class WasmAllocError extends Error {
/**
If called with 2 arguments and the 2nd one is an object, it
behaves like the Error constructor, else it concatenates all
arguments together with a single space between each to
construct an error message string. As a special case, if
called with no arguments then it uses a default error
message.
*/
constructor(...args){
if(2===args.length && 'object'===typeof args[1]){
super(...args);
}else if(args.length){
super(args.join(' '));
}else{
super("Allocation failed.");
}
this.resultCode = capi.SQLITE_NOMEM;
this.name = 'WasmAllocError';
}
};
/**
Functionally equivalent to the WasmAllocError constructor but may
be used as part of an expression, e.g.:
```
return someAllocatingFunction(x) || WasmAllocError.toss(...);
```
*/
WasmAllocError.toss = (...args)=>{
throw new WasmAllocError(...args);
};
Object.assign(capi, {
/**
sqlite3_bind_blob() works exactly like its C counterpart unless
its 3rd argument is one of:
- JS string: the 3rd argument is converted to a C string, the
4th argument is ignored, and the C-string's length is used
in its place.
- Array: converted to a string as defined for "flexible
strings" and then it's treated as a JS string.
- Int8Array or Uint8Array: wasm.allocFromTypedArray() is used to
conver the memory to the WASM heap. If the 4th argument is
0 or greater, it is used as-is, otherwise the array's byteLength
value is used. This is an exception to the C API's undefined
behavior for a negative 4th argument, but results are undefined
if the given 4th argument value is greater than the byteLength
of the input array.
- If it's an ArrayBuffer, it gets wrapped in a Uint8Array and
treated as that type.
In all of those cases, the final argument (destructor) is
ignored and capi.SQLITE_WASM_DEALLOC is assumed.
A 3rd argument of `null` is treated as if it were a WASM pointer
of 0.
If the 3rd argument is neither a WASM pointer nor one of the
above-described types, capi.SQLITE_MISUSE is returned.
The first argument may be either an `sqlite3_stmt*` WASM
pointer or an sqlite3.oo1.Stmt instance.
For consistency with the C API, it requires the same number of
arguments. It returns capi.SQLITE_MISUSE if passed any other
argument count.
*/
sqlite3_bind_blob: undefined/*installed later*/,
/**
sqlite3_bind_text() works exactly like its C counterpart unless
its 3rd argument is one of:
- JS string: the 3rd argument is converted to a C string, the
4th argument is ignored, and the C-string's length is used
in its place.
- Array: converted to a string as defined for "flexible
strings". The 4th argument is ignored and a value of -1
is assumed.
- Int8Array or Uint8Array: is assumed to contain UTF-8 text, is
converted to a string. The 4th argument is ignored, replaced
by the array's byteLength value.
- If it's an ArrayBuffer, it gets wrapped in a Uint8Array and
treated as that type.
In each of those cases, the final argument (text destructor) is
ignored and capi.SQLITE_WASM_DEALLOC is assumed.
A 3rd argument of `null` is treated as if it were a WASM pointer
of 0.
If the 3rd argument is neither a WASM pointer nor one of the
above-described types, capi.SQLITE_MISUSE is returned.
The first argument may be either an `sqlite3_stmt*` WASM
pointer or an sqlite3.oo1.Stmt instance.
For consistency with the C API, it requires the same number of
arguments. It returns capi.SQLITE_MISUSE if passed any other
argument count.
If client code needs to bind partial strings, it needs to
either parcel the string up before passing it in here or it
must pass in a WASM pointer for the 3rd argument and a valid
4th-argument value, taking care not to pass a value which
truncates a multi-byte UTF-8 character. When passing
WASM-format strings, it is important that the final argument be
valid or unexpected content can result, or WASM may crash if
the application reads past the WASM heap bounds.
*/
sqlite3_bind_text: undefined/*installed later*/,
/**
sqlite3_create_function_v2() differs from its native
counterpart only in the following ways:
1) The fourth argument (`eTextRep`) argument must not specify
any encoding other than sqlite3.SQLITE_UTF8. The JS API does not
currently support any other encoding and likely never
will. This function does not replace that argument on its own
because it may contain other flags. As a special case, if
the bottom 4 bits of that argument are 0, SQLITE_UTF8 is
assumed.
2) Any of the four final arguments may be either WASM pointers
(assumed to be function pointers) or JS Functions. In the
latter case, each gets bound to WASM using
sqlite3.capi.wasm.installFunction() and that wrapper is passed
on to the native implementation.
For consistency with the C API, it requires the same number of
arguments. It returns capi.SQLITE_MISUSE if passed any other
argument count.
The semantics of JS functions are:
xFunc: is passed `(pCtx, ...values)`. Its return value becomes
the new SQL function's result.
xStep: is passed `(pCtx, ...values)`. Its return value is
ignored.
xFinal: is passed `(pCtx)`. Its return value becomes the new
aggregate SQL function's result.
xDestroy: is passed `(void*)`. Its return value is ignored. The
pointer passed to it is the one from the 5th argument to
sqlite3_create_function_v2().
Note that:
- `pCtx` in the above descriptions is a `sqlite3_context*`. At
least 99 times out of a hundred, that initial argument will
be irrelevant for JS UDF bindings, but it needs to be there
so that the cases where it _is_ relevant, in particular with
window and aggregate functions, have full access to the
lower-level sqlite3 APIs.
- When wrapping JS functions, the remaining arguments are passd
to them as positional arguments, not as an array of
arguments, because that allows callback definitions to be
more JS-idiomatic than C-like. For example `(pCtx,a,b)=>a+b`
is more intuitive and legible than
`(pCtx,args)=>args[0]+args[1]`. For cases where an array of
arguments would be more convenient, the callbacks simply need
to be declared like `(pCtx,...args)=>{...}`, in which case
`args` will be an array.
- If a JS wrapper throws, it gets translated to
sqlite3_result_error() or sqlite3_result_error_nomem(),
depending on whether the exception is an
sqlite3.WasmAllocError object or not.
- When passing on WASM function pointers, arguments are _not_
converted or reformulated. They are passed on as-is in raw
pointer form using their native C signatures. Only JS
functions passed in to this routine, and thus wrapped by this
routine, get automatic conversions of arguments and result
values. The routines which perform those conversions are
exposed for client-side use as sqlite3_values_to_js(),
sqlite3_result_js(), and sqlite3_result_error_js().
For xFunc(), xStep(), and xFinal():
- 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 may be treated as
doubles or BigInts.
If any JS-side bound functions throw, those exceptions are
intercepted and converted to database-side errors with the
exception of xDestroy(): any exception from it is ignored,
possibly generating a console.error() message. Destructors
must not throw.
Automatically-converted JS-to-WASM functions will be cleaned up
either when (A) this function is called again with the same
name, arity, and encoding, but null/0 values for the functions,
or (B) when pDb is passed to sqlite3_close_v2(). If this factor
is relevant for a given client, they can create WASM-bound JS
functions themselves, hold on to their pointers, and pass the
pointers in to here. Later on, they can free those pointers
(using `wasm.uninstallFunction()` or equivalent).
C reference: https://sqlite.org/c3ref/create_function.html
Maintenance reminder: the ability to add new
WASM-accessible functions to the runtime requires that the
WASM build is compiled with emcc's `-sALLOW_TABLE_GROWTH`
flag.
*/
sqlite3_create_function_v2: (
pDb, funcName, nArg, eTextRep, pApp,
xFunc, xStep, xFinal, xDestroy
)=>{/*installed later*/},
/**
Equivalent to passing the same arguments to
sqlite3_create_function_v2(), with 0 as the final argument.
*/
sqlite3_create_function: (
pDb, funcName, nArg, eTextRep, pApp,
xFunc, xStep, xFinal
)=>{/*installed later*/},
/**
The sqlite3_create_window_function() JS wrapper differs from
its native implementation in the exact same way that
sqlite3_create_function_v2() does. The additional function,
xInverse(), is treated identically to xStep() by the wrapping
layer.
*/
sqlite3_create_window_function: (
pDb, funcName, nArg, eTextRep, pApp,
xStep, xFinal, xValue, xInverse, xDestroy
)=>{/*installed later*/},
/**
The sqlite3_prepare_v3() binding handles two different uses
with differing JS/WASM semantics:
1) sqlite3_prepare_v3(pDb, sqlString, -1, prepFlags, ppStmt , null)
2) sqlite3_prepare_v3(pDb, sqlPointer, sqlByteLen, prepFlags, ppStmt, sqlPointerToPointer)
The SQL length argument (the 3rd argument) must, for usage (1),
always be negative because it must be a byte length and that
value is expensive to calculate from JS (where only the
character length of strings is readily available). It is
retained in this API's interface for code/documentation
compatibility reasons but is currently _always_ ignored. With
usage (2), the 3rd argument is used as-is but is is still
critical that the C-style input string (2nd argument) be
terminated with a 0 byte.
In usage (1), the 2nd argument must be of type string,
Uint8Array, Int8Array, or ArrayBuffer (all of which are assumed
to hold SQL). If it is, this function assumes case (1) and
calls the underyling C function with the equivalent of:
(pDb, sqlAsString, -1, prepFlags, ppStmt, null)
The `pzTail` argument is ignored in this case because its
result is meaningless when a string-type value is passed
through: the string goes through another level of internal
conversion for WASM's sake and the result pointer would refer
to that transient conversion's memory, not the passed-in
string.
If the sql argument is not a string, it must be a _pointer_ to
a NUL-terminated string which was allocated in the WASM memory
(e.g. using capi.wasm.alloc() or equivalent). In that case,
the final argument may be 0/null/undefined or must be a pointer
to which the "tail" of the compiled SQL is written, as
documented for the C-side sqlite3_prepare_v3().
In case (2), the underlying C function is called with the
equivalent of:
(pDb, sqlAsPointer, sqlByteLen, prepFlags, ppStmt, pzTail)
It returns its result and compiled statement as documented in
the C API. Fetching the output pointers (5th and 6th
parameters) requires using `capi.wasm.peek()` (or
equivalent) and the `pzTail` will point to an address relative to
the `sqlAsPointer` value.
If passed an invalid 2nd argument type, this function will
return SQLITE_MISUSE and sqlite3_errmsg() will contain a string
describing the problem.
Side-note: if given an empty string, or one which contains only
comments or an empty SQL expression, 0 is returned but the result
output pointer will be NULL.
*/
sqlite3_prepare_v3: (dbPtr, sql, sqlByteLen, prepFlags,
stmtPtrPtr, strPtrPtr)=>{}/*installed later*/,
/**
Equivalent to calling sqlite3_prapare_v3() with 0 as its 4th argument.
*/
sqlite3_prepare_v2: (dbPtr, sql, sqlByteLen,
stmtPtrPtr,strPtrPtr)=>{}/*installed later*/,
/**
This binding enables the callback argument to be a JavaScript.
If the callback is a function, then for the duration of the
sqlite3_exec() call, it installs a WASM-bound function which
acts as a proxy for the given callback. That proxy will also
perform a conversion of the callback's arguments from
`(char**)` to JS arrays of strings. However, for API
consistency's sake it will still honor the C-level callback
parameter order and will call it like:
`callback(pVoid, colCount, listOfValues, listOfColNames)`
If the callback is not a JS function then this binding performs
no translation of the callback, but the sql argument is still
converted to a WASM string for the call using the
"string:flexible" argument converter.
*/
sqlite3_exec: (pDb, sql, callback, pVoid, pErrMsg)=>{}/*installed later*/,
/**
If passed a single argument which appears to be a byte-oriented
TypedArray (Int8Array or Uint8Array), this function treats that
TypedArray as an output target, fetches `theArray.byteLength`
bytes of randomness, and populates the whole array with it. As
a special case, if the array's length is 0, this function
behaves as if it were passed (0,0). When called this way, it
returns its argument, else it returns the `undefined` value.
If called with any other arguments, they are passed on as-is
to the C API. Results are undefined if passed any incompatible
values.
*/
sqlite3_randomness: (n, outPtr)=>{/*installed later*/},
}/*capi*/);
/**
Various internal-use utilities are added here as needed. They
are bound to an object only so that we have access to them in
the differently-scoped steps of the API bootstrapping
process. At the end of the API setup process, this object gets
removed. These are NOT part of the public API.
*/
const util = {
affirmBindableTypedArray, flexibleString,
bigIntFits32, bigIntFits64, bigIntFitsDouble,
isBindableTypedArray,
isInt32, isSQLableTypedArray, isTypedArray,
isUIThread: ()=>(globalThis.window===globalThis && !!globalThis.document),
// is this true for ESM?: 'undefined'===typeof WorkerGlobalScope
toss: function(...args){throw new Error(args.join(' '))},
toss3,
typedArrayPart: wasm.typedArrayPart,
nu,
assert: function(arg,msg){
if( !arg ){
util.toss("Assertion failed:",msg);
}
},
/**
Given a byte array or ArrayBuffer, this function throws if the
lead bytes of that buffer do not hold a SQLite3 database header,
else it returns without side effects.
Added in 3.44.
*/
affirmDbHeader: function(bytes){
if(bytes instanceof ArrayBuffer) bytes = new Uint8Array(bytes);
const header = "SQLite format 3";
if( header.length > bytes.byteLength ){
toss3("Input does not contain an SQLite3 database header.");
}
for(let i = 0; i < header.length; ++i){
if( header.charCodeAt(i) !== bytes[i] ){
toss3("Input does not contain an SQLite3 database header.");
}
}
},
/**
Given a byte array or ArrayBuffer, this function throws if the
database does not, at a cursory glance, appear to be an SQLite3
database. It only examines the size and header, but further
checks may be added in the future.
Added in 3.44.
*/
affirmIsDb: function(bytes){
if(bytes instanceof ArrayBuffer) bytes = new Uint8Array(bytes);
const n = bytes.byteLength;
if(n<512 || n%512!==0) {
toss3("Byte array size",n,"is invalid for an SQLite3 db.");
}
util.affirmDbHeader(bytes);
}
}/*util*/;
/**
wasm.X properties which are used for configuring the wasm
environment via whwashutil.js. This object gets fleshed out with
a number of WASM-specific utilities, in sqlite3-api-glue.c-pp.js.
*/
Object.assign(wasm, {
/**
The symbols exported by the WASM environment.
*/
exports: config.exports
|| toss3("Missing API config.exports (WASM module exports)."),
/**
When Emscripten compiles with `-sIMPORTED_MEMORY`, it
initializes the heap and imports it into wasm, as opposed to
the other way around. In this case, the memory is not available
via this.exports.memory so the client must pass it in via
config.memory.
*/
memory: config.memory
|| config.exports['memory']
|| toss3("API config object requires a WebAssembly.Memory object",
"in either config.exports.memory (exported)",
"or config.memory (imported)."),
/**
The WASM pointer size. If set then it MUST be one of 4 or 8 and
it MUST correspond to the WASM environment's pointer size. We
figure out the size by calling some un-JS-wrapped WASM function
which returns a pointer-type value. If that value is a BigInt,
it's 64-bit, else it's 32-bit. The pieces which populate
sqlite3.wasm (whwasmutil.js) can figure this out _if_ they can
allocate, but we have a chicken/egg situation there which makes
it illegal for that code to invoke wasm.dealloc() at the time
it would be needed. So we need to configure it ahead of time
(here) instead.
*/
pointerSize: ('number'===typeof config.exports.sqlite3_libversion()) ? 4 : 8,
/**
True if BigInt support was enabled via (e.g.) the
Emscripten -sWASM_BIGINT flag, else false. When
enabled, certain 64-bit sqlite3 APIs are enabled which
are not otherwise enabled due to JS/WASM int64
impedance mismatches.
*/
bigIntEnabled: !!config.bigIntEnabled,
/**
WebAssembly.Table object holding the indirect function call
table. Defaults to exports.__indirect_function_table.
*/
functionTable: config.functionTable,
/**
The API's primary point of access to the WASM-side memory
allocator. Works like sqlite3_malloc() but throws a
WasmAllocError if allocation fails. It is important that any
code which might pass through the sqlite3 C API NOT throw and
must instead return SQLITE_NOMEM (or equivalent, depending on
the context).
Very few cases in the sqlite3 JS APIs can result in
client-defined functions propagating exceptions via the C-style
API. Most notably, this applies to WASM-bound JS functions
which are created directly by clients and passed on _as WASM
function pointers_ to functions such as
sqlite3_create_function_v2(). Such bindings created
transparently by this API will automatically use wrappers which
catch exceptions and convert them to appropriate error codes.
For cases where non-throwing allocation is required, use
this.alloc.impl(), which is the unadulterated WASM-exported
counterpart of this wrapper.
Design note: this function is not named "malloc" primarily
because Emscripten uses that name and we wanted to avoid any
confusion early on in this code's development, when it still
had close ties to Emscripten's glue code.
*/
alloc: undefined/*installed later*/,
/**
Rarely necessary in JS code, this routine works like
sqlite3_realloc(M,N), where M is either NULL or a pointer
obtained from this function or this.alloc() and N is the number
of bytes to reallocate the block to. Returns a pointer to the
reallocated block or 0 if allocation fails.
If M is NULL and N is positive, this behaves like
this.alloc(N). If N is 0, it behaves like this.dealloc().
Results are undefined if N is negative (sqlite3_realloc()
treats that as 0, but if this code is built with a different
allocator it may misbehave with negative values).
Like this.alloc.impl(), this.realloc.impl() is a direct binding
to the underlying realloc() implementation which does not throw
exceptions, instead returning 0 (or 0n) on allocation error.
*/
realloc: undefined/*installed later*/,
/**
The API's primary point of access to the WASM-side memory
deallocator. Works like sqlite3_free().
Design note: this function is not named "free" for the same
reason that this.alloc() is not called this.malloc().
*/
dealloc: undefined/*installed later*/
/* Many more wasm-related APIs get installed later on. */
}/*wasm*/);
/**
wasm.alloc()'s srcTypedArray.byteLength bytes,
populates them with the values from the source
TypedArray, and returns the pointer to that memory. The
returned pointer must eventually be passed to
wasm.dealloc() to clean it up.
The argument may be a Uint8Array, Int8Array, or ArrayBuffer,
and it throws if passed any other type.
As a special case, to avoid further special cases where
this is used, if srcTypedArray.byteLength is 0, it
allocates a single byte and sets it to the value
0. Even in such cases, calls must behave as if the
allocated memory has exactly srcTypedArray.byteLength
bytes.
*/
wasm.allocFromTypedArray = function(srcTypedArray){
if(srcTypedArray instanceof ArrayBuffer){
srcTypedArray = new Uint8Array(srcTypedArray);
}
affirmBindableTypedArray(srcTypedArray);
const pRet = wasm.alloc(srcTypedArray.byteLength || 1);
wasm.heapForSize(srcTypedArray.constructor)
.set(srcTypedArray.byteLength ? srcTypedArray : [0], Number(pRet))
/* Maintenance note: the order of alloc() and heapForSize() calls
is significant: https://sqlite.org/forum/forumpost/05b77273be104532 */;
return pRet;
};
{
// Set up allocators...
const keyAlloc = config.allocExportName,
keyDealloc = config.deallocExportName,
keyRealloc = config.reallocExportName;
for(const key of [keyAlloc, keyDealloc, keyRealloc]){
const f = wasm.exports[key];
if(!(f instanceof Function)) toss3("Missing required exports[",key,"] function.");
}
wasm.alloc = function f(n){
return f.impl(n) || WasmAllocError.toss("Failed to allocate",n," bytes.");
};
wasm.alloc.impl = wasm.exports[keyAlloc];
wasm.realloc = function f(m,n){
const m2 = f.impl(wasm.ptr.coerce(m)/*tag:64bit*/,n);
return n ? (m2 || WasmAllocError.toss("Failed to reallocate",n," bytes.")) : wasm.ptr.null;
};
wasm.realloc.impl = wasm.exports[keyRealloc];
wasm.dealloc = function f(m){
f.impl(wasm.ptr.coerce(m)/*tag:64bit*/)
/* This coerce() is the reason we have to set wasm.pointerSize before
calling WhWasmUtilInstaller(). If we don't, that code will call
into this very early in its init, before wasm.ptr has been set up,
resulting in a null deref here. */;
};
wasm.dealloc.impl = wasm.exports[keyDealloc];
}
/**
Reports info about compile-time options using
sqlite3_compileoption_get() and sqlite3_compileoption_used(). It
has several distinct uses:
If optName is an array then it is expected to be a list of
compilation options and this function returns an object
which maps each such option to true or false, indicating
whether or not the given option was included in this
build. That object is returned.
If optName is an object, its keys are expected to be compilation
options and this function sets each entry to true or false,
indicating whether the compilation option was used or not. That
object is returned.
If passed no arguments then it returns an object mapping
all known compilation options to their compile-time values,
or boolean true if they are defined with no value. This
result, which is relatively expensive to compute, is cached
and returned for future no-argument calls.