2028 lines
78 KiB
JavaScript
2028 lines
78 KiB
JavaScript
/*
|
|
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 an Emscripten Module.postRun() handler. 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, passed configuration details
|
|
for the current environment, and then optionally be removed from
|
|
the global object using `delete globalThis.sqlite3ApiBootstrap`.
|
|
|
|
This function is not intended for client-level use. It is intended
|
|
for use in creating bundles configured for specific WASM
|
|
environments.
|
|
|
|
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']`.
|
|
|
|
- `memory`[^1]: optional WebAssembly.Memory object, defaulting to
|
|
`exports.memory`. In Emscripten environments this should be set
|
|
to `Module.wasmMemory` if the build uses `-sIMPORT_MEMORY`, or be
|
|
left undefined/falsy to default to `exports.memory` when using
|
|
WASM-exported memory.
|
|
|
|
- `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]: As of 2022-12-17, this feature does not
|
|
currently work due to incompatible Emscripten-side changes made
|
|
in the WASMFS+OPFS combination. This option is currently ignored.
|
|
|
|
[^1] = This property may optionally be a function, in which case this
|
|
function re-assigns calls that function to fetch the value,
|
|
enabling delayed evaluation.
|
|
|
|
The returned object is the top-level sqlite3 namespace object.
|
|
|
|
*/
|
|
'use strict';
|
|
globalThis.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
|
|
apiConfig = (globalThis.sqlite3ApiConfig || sqlite3ApiBootstrap.defaultConfig)
|
|
){
|
|
if(sqlite3ApiBootstrap.sqlite3){ /* already initalized */
|
|
console.warn("sqlite3ApiBootstrap() called multiple times.",
|
|
"Config and external initializers are ignored on calls after the first.");
|
|
return sqlite3ApiBootstrap.sqlite3;
|
|
}
|
|
const config = Object.assign(Object.create(null),{
|
|
exports: undefined,
|
|
memory: undefined,
|
|
bigIntEnabled: (()=>{
|
|
if('undefined'!==typeof Module){
|
|
/* Emscripten module will contain HEAPU64 when built with
|
|
-sWASM_BIGINT=1, else it will not. */
|
|
return !!Module.HEAPU64;
|
|
}
|
|
return !!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 an allocator discrepancy. 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'
|
|
}, config);
|
|
|
|
[
|
|
// If any of these config options are functions, replace them with
|
|
// the result of calling that function...
|
|
'exports', 'memory', 'wasmfsOpfsDir'
|
|
].forEach((k)=>{
|
|
if('function' === typeof config[k]){
|
|
config[k] = config[k]();
|
|
}
|
|
});
|
|
config.wasmOpfsDir =
|
|
/* 2022-12-17: WASMFS+OPFS can no longer be activated from the
|
|
main thread (aborts via a failed assert() if it's attempted),
|
|
which eliminates any(?) benefit to supporting it. */ false;
|
|
|
|
/**
|
|
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://www.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 = Object.create(null);
|
|
/**
|
|
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 = Object.create(null);
|
|
|
|
/** 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 __isInt = (n)=>'number'===typeof n && n===(n | 0);
|
|
|
|
/**
|
|
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-objec 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(__isInt(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 n is a 32-bit (signed) integer, else
|
|
false. This is used for determining when we need to switch to
|
|
double-type DB operations for integer values in order to keep
|
|
more precision.
|
|
*/
|
|
const isInt32 = (n)=>{
|
|
return ('bigint'!==typeof n /*TypeError: can't convert BigInt to number*/)
|
|
&& !!(n===(n|0) && n<=2147483647 && n>=-2147483648);
|
|
};
|
|
/**
|
|
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;
|
|
};
|
|
|
|
|
|
/** Internal helper to use in operations which need to distinguish
|
|
between TypedArrays which are backed by a SharedArrayBuffer
|
|
from those which are not. */
|
|
const __SAB = ('undefined'===typeof SharedArrayBuffer)
|
|
? function(){} : SharedArrayBuffer;
|
|
/** Returns true if the given TypedArray object is backed by a
|
|
SharedArrayBuffer, else false. */
|
|
const isSharedTypedArray = (aTypedArray)=>(aTypedArray.buffer instanceof __SAB);
|
|
|
|
/**
|
|
Returns either aTypedArray.slice(begin,end) (if
|
|
aTypedArray.buffer is a SharedArrayBuffer) or
|
|
aTypedArray.subarray(begin,end) (if it's not).
|
|
|
|
This distinction is important for APIs which don't like to
|
|
work on SABs, e.g. TextDecoder, and possibly for our
|
|
own APIs which work on memory ranges which "might" be
|
|
modified by other threads while they're working.
|
|
*/
|
|
const typedArrayPart = (aTypedArray, begin, end)=>{
|
|
return isSharedTypedArray(aTypedArray)
|
|
? aTypedArray.slice(begin, end)
|
|
: aTypedArray.subarray(begin, end);
|
|
};
|
|
|
|
/**
|
|
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)=>{
|
|
return 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)=>{
|
|
return 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)=>{
|
|
return isBindableTypedArray(v)
|
|
|| toss3("Value is not of a supported TypedArray type.");
|
|
};
|
|
|
|
const utf8Decoder = new TextDecoder('utf-8');
|
|
|
|
/**
|
|
Uses TextDecoder to decode the given half-open range of the
|
|
given TypedArray to a string. This differs from a simple
|
|
call to TextDecoder in that it accounts for whether the
|
|
first argument is backed by a SharedArrayBuffer or not,
|
|
and can work more efficiently if it's not (TextDecoder
|
|
refuses to act upon an SAB).
|
|
*/
|
|
const typedArrayToString = function(typedArray, begin, end){
|
|
return utf8Decoder.decode(typedArrayPart(typedArray, begin,end));
|
|
};
|
|
|
|
/**
|
|
If v is-a Array, its join("") result is returned. If
|
|
isSQLableTypedArray(v) is true then typedArrayToString(v) is
|
|
returned. If it looks like a WASM pointer, wasm.cstrToJs(v) is
|
|
returned. Else v is returned as-is.
|
|
*/
|
|
const flexibleString = function(v){
|
|
if(isSQLableTypedArray(v)){
|
|
return typedArrayToString(
|
|
(v instanceof ArrayBuffer) ? new Uint8Array(v) : v
|
|
);
|
|
}
|
|
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 can result, or even a
|
|
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_create_function_v2.convertUdfArgs() and
|
|
sqlite3_create_function_v2.setUdfResult(). sqlite3_create_function()
|
|
and sqlite3_create_window_function() have those same methods.
|
|
|
|
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.
|
|
|
|
Once installed, there is currently no way to uninstall the
|
|
automatically-converted WASM-bound JS functions from WASM. They
|
|
can be uninstalled from the database as documented in the C
|
|
API, but this wrapper currently has no infrastructure in place
|
|
to also free the WASM-bound JS wrappers, effectively resulting
|
|
in a memory leak if the client uninstalls the UDF. Improving that
|
|
is a potential TODO, but removing client-installed UDFs is rare
|
|
in practice. 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://www.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)
|
|
|
|
Note that 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,
|
|
typedArrayToString,
|
|
isUIThread: ()=>(globalThis.window===globalThis && !!globalThis.document),
|
|
// is this true for ESM?: 'undefined'===typeof WorkerGlobalScope
|
|
isSharedTypedArray,
|
|
toss: function(...args){throw new Error(args.join(' '))},
|
|
toss3,
|
|
typedArrayPart
|
|
};
|
|
|
|
Object.assign(wasm, {
|
|
/**
|
|
Emscripten APIs have a deep-seated assumption that all pointers
|
|
are 32 bits. We'll remain optimistic that that won't always be
|
|
the case and will use this constant in places where we might
|
|
otherwise use a hard-coded 4.
|
|
*/
|
|
ptrSizeof: config.wasmPtrSizeof || 4,
|
|
/**
|
|
The WASM IR (Intermediate Representation) value for
|
|
pointer-type values. It MUST refer to a value type of the
|
|
size described by this.ptrSizeof.
|
|
*/
|
|
ptrIR: config.wasmPtrIR || "i32",
|
|
/**
|
|
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
|
|
impedence mismatches.
|
|
*/
|
|
bigIntEnabled: !!config.bigIntEnabled,
|
|
/**
|
|
The symbols exported by the WASM environment.
|
|
*/
|
|
exports: config.exports
|
|
|| toss3("Missing API config.exports (WASM module exports)."),
|
|
|
|
/**
|
|
When Emscripten compiles with `-sIMPORT_MEMORY`, it
|
|
initalizes 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.
|
|
*/
|
|
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 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 direct binding of the
|
|
underlying C-level allocator.
|
|
|
|
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 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], pRet
|
|
);
|
|
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(m,n);
|
|
return n ? (m2 || WasmAllocError.toss("Failed to reallocate",n," bytes.")) : 0;
|
|
};
|
|
wasm.realloc.impl = wasm.exports[keyRealloc];
|
|
wasm.dealloc = 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.
|
|
|
|
In all other cases it returns true if the given option was
|
|
active when when compiling the sqlite3 module, else false.
|
|
|
|
Compile-time option names may optionally include their
|
|
"SQLITE_" prefix. When it returns an object of all options,
|
|
the prefix is elided.
|
|
*/
|
|
wasm.compileOptionUsed = function f(optName){
|
|
if(!arguments.length){
|
|
if(f._result) return f._result;
|
|
else if(!f._opt){
|
|
f._rx = /^([^=]+)=(.+)/;
|
|
f._rxInt = /^-?\d+$/;
|
|
f._opt = function(opt, rv){
|
|
const m = f._rx.exec(opt);
|
|
rv[0] = (m ? m[1] : opt);
|
|
rv[1] = m ? (f._rxInt.test(m[2]) ? +m[2] : m[2]) : true;
|
|
};
|
|
}
|
|
const rc = {}, ov = [0,0];
|
|
let i = 0, k;
|
|
while((k = capi.sqlite3_compileoption_get(i++))){
|
|
f._opt(k,ov);
|
|
rc[ov[0]] = ov[1];
|
|
}
|
|
return f._result = rc;
|
|
}else if(Array.isArray(optName)){
|
|
const rc = {};
|
|
optName.forEach((v)=>{
|
|
rc[v] = capi.sqlite3_compileoption_used(v);
|
|
});
|
|
return rc;
|
|
}else if('object' === typeof optName){
|
|
Object.keys(optName).forEach((k)=> {
|
|
optName[k] = capi.sqlite3_compileoption_used(k);
|
|
});
|
|
return optName;
|
|
}
|
|
return (
|
|
'string'===typeof optName
|
|
) ? !!capi.sqlite3_compileoption_used(optName) : false;
|
|
}/*compileOptionUsed()*/;
|
|
|
|
/**
|
|
sqlite3.wasm.pstack (pseudo-stack) holds a special-case
|
|
stack-style allocator intended only for use with _small_ data of
|
|
not more than (in total) a few kb in size, managed as if it were
|
|
stack-based.
|
|
|
|
It has only a single intended usage:
|
|
|
|
```
|
|
const stackPos = pstack.pointer;
|
|
try{
|
|
const ptr = pstack.alloc(8);
|
|
// ==> pstack.pointer === ptr
|
|
const otherPtr = pstack.alloc(8);
|
|
// ==> pstack.pointer === otherPtr
|
|
...
|
|
}finally{
|
|
pstack.restore(stackPos);
|
|
// ==> pstack.pointer === stackPos
|
|
}
|
|
```
|
|
|
|
This allocator is much faster than a general-purpose one but is
|
|
limited to usage patterns like the one shown above.
|
|
|
|
It operates from a static range of memory which lives outside of
|
|
space managed by Emscripten's stack-management, so does not
|
|
collide with Emscripten-provided stack allocation APIs. The
|
|
memory lives in the WASM heap and can be used with routines such
|
|
as wasm.poke() and wasm.heap8u().slice().
|
|
*/
|
|
wasm.pstack = Object.assign(Object.create(null),{
|
|
/**
|
|
Sets the current pstack position to the given pointer. Results
|
|
are undefined if the passed-in value did not come from
|
|
this.pointer.
|
|
*/
|
|
restore: wasm.exports.sqlite3_wasm_pstack_restore,
|
|
/**
|
|
Attempts to allocate the given number of bytes from the
|
|
pstack. On success, it zeroes out a block of memory of the
|
|
given size, adjusts the pstack pointer, and returns a pointer
|
|
to the memory. On error, throws a WasmAllocError. The
|
|
memory must eventually be released using restore().
|
|
|
|
If n is a string, it must be a WASM "IR" value in the set
|
|
accepted by wasm.sizeofIR(), which is mapped to the size of
|
|
that data type. If passed a string not in that set, it throws a
|
|
WasmAllocError.
|
|
|
|
This method always adjusts the given value to be a multiple
|
|
of 8 bytes because failing to do so can lead to incorrect
|
|
results when reading and writing 64-bit values from/to the WASM
|
|
heap. Similarly, the returned address is always 8-byte aligned.
|
|
*/
|
|
alloc: function(n){
|
|
if('string'===typeof n && !(n = wasm.sizeofIR(n))){
|
|
WasmAllocError.toss("Invalid value for pstack.alloc(",arguments[0],")");
|
|
}
|
|
return wasm.exports.sqlite3_wasm_pstack_alloc(n)
|
|
|| WasmAllocError.toss("Could not allocate",n,
|
|
"bytes from the pstack.");
|
|
},
|
|
/**
|
|
alloc()'s n chunks, each sz bytes, as a single memory block and
|
|
returns the addresses as an array of n element, each holding
|
|
the address of one chunk.
|
|
|
|
sz may optionally be an IR string accepted by wasm.sizeofIR().
|
|
|
|
Throws a WasmAllocError if allocation fails.
|
|
|
|
Example:
|
|
|
|
```
|
|
const [p1, p2, p3] = wasm.pstack.allocChunks(3,4);
|
|
```
|
|
*/
|
|
allocChunks: function(n,sz){
|
|
if('string'===typeof sz && !(sz = wasm.sizeofIR(sz))){
|
|
WasmAllocError.toss("Invalid size value for allocChunks(",arguments[1],")");
|
|
}
|
|
const mem = wasm.pstack.alloc(n * sz);
|
|
const rc = [];
|
|
let i = 0, offset = 0;
|
|
for(; i < n; ++i, offset += sz) rc.push(mem + offset);
|
|
return rc;
|
|
},
|
|
/**
|
|
A convenience wrapper for allocChunks() which sizes each chunk
|
|
as either 8 bytes (safePtrSize is truthy) or wasm.ptrSizeof (if
|
|
safePtrSize is falsy).
|
|
|
|
How it returns its result differs depending on its first
|
|
argument: if it's 1, it returns a single pointer value. If it's
|
|
more than 1, it returns the same as allocChunks().
|
|
|
|
When a returned pointers will refer to a 64-bit value, e.g. a
|
|
double or int64, and that value must be written or fetched,
|
|
e.g. using wasm.poke() or wasm.peek(), it is
|
|
important that the pointer in question be aligned to an 8-byte
|
|
boundary or else it will not be fetched or written properly and
|
|
will corrupt or read neighboring memory.
|
|
|
|
However, when all pointers involved point to "small" data, it
|
|
is safe to pass a falsy value to save a tiny bit of memory.
|
|
*/
|
|
allocPtr: (n=1,safePtrSize=true)=>{
|
|
return 1===n
|
|
? wasm.pstack.alloc(safePtrSize ? 8 : wasm.ptrSizeof)
|
|
: wasm.pstack.allocChunks(n, safePtrSize ? 8 : wasm.ptrSizeof);
|
|
}
|
|
})/*wasm.pstack*/;
|
|
Object.defineProperties(wasm.pstack, {
|
|
/**
|
|
sqlite3.wasm.pstack.pointer resolves to the current pstack
|
|
position pointer. This value is intended _only_ to be saved
|
|
for passing to restore(). Writing to this memory, without
|
|
first reserving it via wasm.pstack.alloc() and friends, leads
|
|
to undefined results.
|
|
*/
|
|
pointer: {
|
|
configurable: false, iterable: true, writeable: false,
|
|
get: wasm.exports.sqlite3_wasm_pstack_ptr
|
|
//Whether or not a setter as an alternative to restore() is
|
|
//clearer or would just lead to confusion is unclear.
|
|
//set: wasm.exports.sqlite3_wasm_pstack_restore
|
|
},
|
|
/**
|
|
sqlite3.wasm.pstack.quota to the total number of bytes
|
|
available in the pstack, including any space which is currently
|
|
allocated. This value is a compile-time constant.
|
|
*/
|
|
quota: {
|
|
configurable: false, iterable: true, writeable: false,
|
|
get: wasm.exports.sqlite3_wasm_pstack_quota
|
|
},
|
|
/**
|
|
sqlite3.wasm.pstack.remaining resolves to the amount of space
|
|
remaining in the pstack.
|
|
*/
|
|
remaining: {
|
|
configurable: false, iterable: true, writeable: false,
|
|
get: wasm.exports.sqlite3_wasm_pstack_remaining
|
|
}
|
|
})/*wasm.pstack properties*/;
|
|
|
|
capi.sqlite3_randomness = (...args)=>{
|
|
if(1===args.length && util.isTypedArray(args[0])
|
|
&& 1===args[0].BYTES_PER_ELEMENT){
|
|
const ta = args[0];
|
|
if(0===ta.byteLength){
|
|
wasm.exports.sqlite3_randomness(0,0);
|
|
return ta;
|
|
}
|
|
const stack = wasm.pstack.pointer;
|
|
try {
|
|
let n = ta.byteLength, offset = 0;
|
|
const r = wasm.exports.sqlite3_randomness;
|
|
const heap = wasm.heap8u();
|
|
const nAlloc = n < 512 ? n : 512;
|
|
const ptr = wasm.pstack.alloc(nAlloc);
|
|
do{
|
|
const j = (n>nAlloc ? nAlloc : n);
|
|
r(j, ptr);
|
|
ta.set(typedArrayPart(heap, ptr, ptr+j), offset);
|
|
n -= j;
|
|
offset += j;
|
|
} while(n > 0);
|
|
}catch(e){
|
|
console.error("Highly unexpected (and ignored!) "+
|
|
"exception in sqlite3_randomness():",e);
|
|
}finally{
|
|
wasm.pstack.restore(stack);
|
|
}
|
|
return ta;
|
|
}
|
|
wasm.exports.sqlite3_randomness(...args);
|
|
};
|
|
|
|
/** State for sqlite3_wasmfs_opfs_dir(). */
|
|
let __wasmfsOpfsDir = undefined;
|
|
/**
|
|
2022-12-17: incompatible WASMFS changes have made WASMFS+OPFS
|
|
unavailable from the main thread, which eliminates the most
|
|
significant benefit of supporting WASMFS. This function is now a
|
|
no-op which always returns a falsy value. Before that change,
|
|
this function behaved as documented below (and how it will again
|
|
if we can find a compelling reason to support it).
|
|
|
|
If the wasm environment has a WASMFS/OPFS-backed persistent
|
|
storage directory, its path is returned by this function. If it
|
|
does not then it returns "" (noting that "" is a falsy value).
|
|
|
|
The first time this is called, this function inspects the current
|
|
environment to determine whether persistence support is available
|
|
and, if it is, enables it (if needed).
|
|
|
|
This function currently only recognizes the WASMFS/OPFS storage
|
|
combination and its path refers to storage rooted in the
|
|
Emscripten-managed virtual filesystem.
|
|
*/
|
|
capi.sqlite3_wasmfs_opfs_dir = function(){
|
|
if(undefined !== __wasmfsOpfsDir) return __wasmfsOpfsDir;
|
|
// If we have no OPFS, there is no persistent dir
|
|
const pdir = config.wasmfsOpfsDir;
|
|
console.error("sqlite3_wasmfs_opfs_dir() can no longer work due "+
|
|
"to incompatible WASMFS changes. It will be removed.");
|
|
if(!pdir
|
|
|| !globalThis.FileSystemHandle
|
|
|| !globalThis.FileSystemDirectoryHandle
|
|
|| !globalThis.FileSystemFileHandle){
|
|
return __wasmfsOpfsDir = "";
|
|
}
|
|
try{
|
|
if(pdir && 0===wasm.xCallWrapped(
|
|
'sqlite3_wasm_init_wasmfs', 'i32', ['string'], pdir
|
|
)){
|
|
return __wasmfsOpfsDir = pdir;
|
|
}else{
|
|
return __wasmfsOpfsDir = "";
|
|
}
|
|
}catch(e){
|
|
// sqlite3_wasm_init_wasmfs() is not available
|
|
return __wasmfsOpfsDir = "";
|
|
}
|
|
};
|
|
|
|
/**
|
|
Experimental and subject to change or removal.
|
|
|
|
Returns true if sqlite3.capi.sqlite3_wasmfs_opfs_dir() is a
|
|
non-empty string and the given name starts with (that string +
|
|
'/'), else returns false.
|
|
*/
|
|
capi.sqlite3_wasmfs_filename_is_persistent = function(name){
|
|
const p = capi.sqlite3_wasmfs_opfs_dir();
|
|
return (p && name) ? name.startsWith(p+'/') : false;
|
|
};
|
|
|
|
// This bit is highly arguable and is incompatible with the fiddle shell.
|
|
if(false && 0===wasm.exports.sqlite3_vfs_find(0)){
|
|
/* Assume that sqlite3_initialize() has not yet been called.
|
|
This will be the case in an SQLITE_OS_KV build. */
|
|
wasm.exports.sqlite3_initialize();
|
|
}
|
|
|
|
/**
|
|
Given an `sqlite3*`, an sqlite3_vfs name, and an optional db name
|
|
(defaulting to "main"), returns a truthy value (see below) if
|
|
that db uses that VFS, else returns false. If pDb is falsy then
|
|
the 3rd argument is ignored and this function returns a truthy
|
|
value if the default VFS name matches that of the 2nd
|
|
argument. Results are undefined if pDb is truthy but refers to an
|
|
invalid pointer. The 3rd argument specifies the database name of
|
|
the given database connection to check, defaulting to the main
|
|
db.
|
|
|
|
The 2nd and 3rd arguments may either be a JS string or a WASM
|
|
C-string. If the 2nd argument is a NULL WASM pointer, the default
|
|
VFS is assumed. If the 3rd is a NULL WASM pointer, "main" is
|
|
assumed.
|
|
|
|
The truthy value it returns is a pointer to the `sqlite3_vfs`
|
|
object.
|
|
|
|
To permit safe use of this function from APIs which may be called
|
|
via the C stack (like SQL UDFs), this function does not throw: if
|
|
bad arguments cause a conversion error when passing into
|
|
wasm-space, false is returned.
|
|
*/
|
|
capi.sqlite3_js_db_uses_vfs = function(pDb,vfsName,dbName=0){
|
|
try{
|
|
const pK = capi.sqlite3_vfs_find(vfsName);
|
|
if(!pK) return false;
|
|
else if(!pDb){
|
|
return pK===capi.sqlite3_vfs_find(0) ? pK : false;
|
|
}else{
|
|
return pK===capi.sqlite3_js_db_vfs(pDb,dbName) ? pK : false;
|
|
}
|
|
}catch(e){
|
|
/* Ignore - probably bad args to a wasm-bound function. */
|
|
return false;
|
|
}
|
|
};
|
|
|
|
/**
|
|
Returns an array of the names of all currently-registered sqlite3
|
|
VFSes.
|
|
*/
|
|
capi.sqlite3_js_vfs_list = function(){
|
|
const rc = [];
|
|
let pVfs = capi.sqlite3_vfs_find(0);
|
|
while(pVfs){
|
|
const oVfs = new capi.sqlite3_vfs(pVfs);
|
|
rc.push(wasm.cstrToJs(oVfs.$zName));
|
|
pVfs = oVfs.$pNext;
|
|
oVfs.dispose();
|
|
}
|
|
return rc;
|
|
};
|
|
|
|
/**
|
|
A convenience wrapper around sqlite3_serialize() which serializes
|
|
the given `sqlite3*` pointer to a Uint8Array. The first argument
|
|
may be either an `sqlite3*` or an sqlite3.oo1.DB instance.
|
|
|
|
On success it returns a Uint8Array. If the schema is empty, an
|
|
empty array is returned.
|
|
|
|
`schema` is the schema to serialize. It may be a WASM C-string
|
|
pointer or a JS string. If it is falsy, it defaults to `"main"`.
|
|
|
|
On error it throws with a description of the problem.
|
|
*/
|
|
capi.sqlite3_js_db_export = function(pDb, schema=0){
|
|
pDb = wasm.xWrap.testConvertArg('sqlite3*', pDb);
|
|
if(!pDb) toss3('Invalid sqlite3* argument.');
|
|
if(!wasm.bigIntEnabled) toss3('BigInt64 support is not enabled.');
|
|
const scope = wasm.scopedAllocPush();
|
|
let pOut;
|
|
try{
|
|
const pSize = wasm.scopedAlloc(8/*i64*/ + wasm.ptrSizeof);
|
|
const ppOut = pSize + 8;
|
|
/**
|
|
Maintenance reminder, since this cost a full hour of grief
|
|
and confusion: if the order of pSize/ppOut are reversed in
|
|
that memory block, fetching the value of pSize after the
|
|
export reads a garbage size because it's not on an 8-byte
|
|
memory boundary!
|
|
*/
|
|
const zSchema = schema
|
|
? (wasm.isPtr(schema) ? schema : wasm.scopedAllocCString(''+schema))
|
|
: 0;
|
|
let rc = wasm.exports.sqlite3_wasm_db_serialize(
|
|
pDb, zSchema, ppOut, pSize, 0
|
|
);
|
|
if(rc){
|
|
toss3("Database serialization failed with code",
|
|
sqlite3.capi.sqlite3_js_rc_str(rc));
|
|
}
|
|
pOut = wasm.peekPtr(ppOut);
|
|
const nOut = wasm.peek(pSize, 'i64');
|
|
rc = nOut
|
|
? wasm.heap8u().slice(pOut, pOut + Number(nOut))
|
|
: new Uint8Array();
|
|
return rc;
|
|
}finally{
|
|
if(pOut) wasm.exports.sqlite3_free(pOut);
|
|
wasm.scopedAllocPop(scope);
|
|
}
|
|
};
|
|
|
|
/**
|
|
Given a `sqlite3*` and a database name (JS string or WASM
|
|
C-string pointer, which may be 0), returns a pointer to the
|
|
sqlite3_vfs responsible for it. If the given db name is null/0,
|
|
or not provided, then "main" is assumed.
|
|
*/
|
|
capi.sqlite3_js_db_vfs =
|
|
(dbPointer, dbName=0)=>wasm.sqlite3_wasm_db_vfs(dbPointer, dbName);
|
|
|
|
/**
|
|
A thin wrapper around capi.sqlite3_aggregate_context() which
|
|
behaves the same except that it throws a WasmAllocError if that
|
|
function returns 0. As a special case, if n is falsy it does
|
|
_not_ throw if that function returns 0. That special case is
|
|
intended for use with xFinal() implementations.
|
|
*/
|
|
capi.sqlite3_js_aggregate_context = (pCtx, n)=>{
|
|
return capi.sqlite3_aggregate_context(pCtx, n)
|
|
|| (n ? WasmAllocError.toss("Cannot allocate",n,
|
|
"bytes for sqlite3_aggregate_context()")
|
|
: 0);
|
|
};
|
|
|
|
/**
|
|
Creates a file using the storage appropriate for the given
|
|
sqlite3_vfs. The first argument may be a VFS name (JS string
|
|
only, NOT a WASM C-string), WASM-managed `sqlite3_vfs*`, or
|
|
a capi.sqlite3_vfs instance. Pass 0 (a NULL pointer) to use the
|
|
default VFS. If passed a string which does not resolve using
|
|
sqlite3_vfs_find(), an exception is thrown. (Note that a WASM
|
|
C-string is not accepted because it is impossible to
|
|
distinguish from a C-level `sqlite3_vfs*`.)
|
|
|
|
The second argument, the filename, must be a JS or WASM C-string.
|
|
|
|
The 3rd may either be falsy, a valid WASM memory pointer, an
|
|
ArrayBuffer, or a Uint8Array. The 4th must be the length, in
|
|
bytes, of the data array to copy. If the 3rd argument is an
|
|
ArrayBuffer or Uint8Array and the 4th is not a positive integer
|
|
then the 4th defaults to the array's byteLength value.
|
|
|
|
If data is falsy then a file is created with dataLen bytes filled
|
|
with uninitialized data (whatever truncate() leaves there). If
|
|
data is not falsy then a file is created or truncated and it is
|
|
filled with the first dataLen bytes of the data source.
|
|
|
|
Throws if any arguments are invalid or if creating or writing to
|
|
the file fails.
|
|
|
|
Note that most VFSes do _not_ automatically create directory
|
|
parts of filenames, nor do all VFSes have a concept of
|
|
directories. If the given filename is not valid for the given
|
|
VFS, an exception will be thrown. This function exists primarily
|
|
to assist in implementing file-upload capability, with the caveat
|
|
that clients must have some idea of the VFS into which they want
|
|
to upload and that VFS must support the operation.
|
|
|
|
VFS-specific notes:
|
|
|
|
- "memdb": results are undefined.
|
|
|
|
- "kvvfs": will fail with an I/O error due to strict internal
|
|
requirments of that VFS's xTruncate().
|
|
|
|
- "unix" and related: will use the WASM build's equivalent of the
|
|
POSIX I/O APIs. This will work so long as neither a specific
|
|
VFS nor the WASM environment imposes requirements which break it.
|
|
|
|
- "opfs": uses OPFS storage and creates directory parts of the
|
|
filename.
|
|
*/
|
|
capi.sqlite3_js_vfs_create_file = function(vfs, filename, data, dataLen){
|
|
let pData;
|
|
if(data){
|
|
if(wasm.isPtr(data)){
|
|
pData = data;
|
|
}else if(data instanceof ArrayBuffer){
|
|
data = new Uint8Array(data);
|
|
}
|
|
if(data instanceof Uint8Array){
|
|
pData = wasm.allocFromTypedArray(data);
|
|
if(arguments.length<4 || !util.isInt32(dataLen) || dataLen<0){
|
|
dataLen = data.byteLength;
|
|
}
|
|
}else{
|
|
SQLite3Error.toss("Invalid 3rd argument type for sqlite3_js_vfs_create_file().");
|
|
}
|
|
}else{
|
|
pData = 0;
|
|
}
|
|
if(!util.isInt32(dataLen) || dataLen<0){
|
|
wasm.dealloc(pData);
|
|
SQLite3Error.toss("Invalid 4th argument for sqlite3_js_vfs_create_file().");
|
|
}
|
|
try{
|
|
const rc = wasm.sqlite3_wasm_vfs_create_file(vfs, filename, pData, dataLen);
|
|
if(rc) SQLite3Error.toss("Creation of file failed with sqlite3 result code",
|
|
capi.sqlite3_js_rc_str(rc));
|
|
}finally{
|
|
wasm.dealloc(pData);
|
|
}
|
|
};
|
|
|
|
if( util.isUIThread() ){
|
|
/* Features specific to the main window thread... */
|
|
|
|
/**
|
|
Internal helper for sqlite3_js_kvvfs_clear() and friends.
|
|
Its argument should be one of ('local','session',"").
|
|
*/
|
|
const __kvvfsInfo = function(which){
|
|
const rc = Object.create(null);
|
|
rc.prefix = 'kvvfs-'+which;
|
|
rc.stores = [];
|
|
if('session'===which || ""===which) rc.stores.push(globalThis.sessionStorage);
|
|
if('local'===which || ""===which) rc.stores.push(globalThis.localStorage);
|
|
return rc;
|
|
};
|
|
|
|
/**
|
|
Clears all storage used by the kvvfs DB backend, deleting any
|
|
DB(s) stored there. Its argument must be either 'session',
|
|
'local', or "". In the first two cases, only sessionStorage
|
|
resp. localStorage is cleared. If it's an empty string (the
|
|
default) then both are cleared. Only storage keys which match
|
|
the pattern used by kvvfs are cleared: any other client-side
|
|
data are retained.
|
|
|
|
This function is only available in the main window thread.
|
|
|
|
Returns the number of entries cleared.
|
|
*/
|
|
capi.sqlite3_js_kvvfs_clear = function(which=""){
|
|
let rc = 0;
|
|
const kvinfo = __kvvfsInfo(which);
|
|
kvinfo.stores.forEach((s)=>{
|
|
const toRm = [] /* keys to remove */;
|
|
let i;
|
|
for( i = 0; i < s.length; ++i ){
|
|
const k = s.key(i);
|
|
if(k.startsWith(kvinfo.prefix)) toRm.push(k);
|
|
}
|
|
toRm.forEach((kk)=>s.removeItem(kk));
|
|
rc += toRm.length;
|
|
});
|
|
return rc;
|
|
};
|
|
|
|
/**
|
|
This routine guesses the approximate amount of
|
|
window.localStorage and/or window.sessionStorage in use by the
|
|
kvvfs database backend. Its argument must be one of
|
|
('session', 'local', ""). In the first two cases, only
|
|
sessionStorage resp. localStorage is counted. If it's an empty
|
|
string (the default) then both are counted. Only storage keys
|
|
which match the pattern used by kvvfs are counted. The returned
|
|
value is the "length" value of every matching key and value,
|
|
noting that JavaScript stores each character in 2 bytes.
|
|
|
|
Note that the returned size is not authoritative from the
|
|
perspective of how much data can fit into localStorage and
|
|
sessionStorage, as the precise algorithms for determining
|
|
those limits are unspecified and may include per-entry
|
|
overhead invisible to clients.
|
|
*/
|
|
capi.sqlite3_js_kvvfs_size = function(which=""){
|
|
let sz = 0;
|
|
const kvinfo = __kvvfsInfo(which);
|
|
kvinfo.stores.forEach((s)=>{
|
|
let i;
|
|
for(i = 0; i < s.length; ++i){
|
|
const k = s.key(i);
|
|
if(k.startsWith(kvinfo.prefix)){
|
|
sz += k.length;
|
|
sz += s.getItem(k).length;
|
|
}
|
|
}
|
|
});
|
|
return sz * 2 /* because JS uses 2-byte char encoding */;
|
|
};
|
|
|
|
}/* main-window-only bits */
|
|
|
|
/**
|
|
Wraps all known variants of the C-side variadic
|
|
sqlite3_db_config().
|
|
|
|
Full docs: https://sqlite.org/c3ref/db_config.html
|
|
|
|
Returns capi.SQLITE_MISUSE if op is not a valid operation ID.
|
|
|
|
The variants which take `(int, int*)` arguments treat a
|
|
missing or falsy pointer argument as 0.
|
|
*/
|
|
capi.sqlite3_db_config = function(pDb, op, ...args){
|
|
if(!this.s){
|
|
this.s = wasm.xWrap('sqlite3_wasm_db_config_s','int',
|
|
['sqlite3*', 'int', 'string:static']
|
|
/* MAINDBNAME requires a static string */);
|
|
this.pii = wasm.xWrap('sqlite3_wasm_db_config_pii', 'int',
|
|
['sqlite3*', 'int', '*','int', 'int']);
|
|
this.ip = wasm.xWrap('sqlite3_wasm_db_config_ip','int',
|
|
['sqlite3*', 'int', 'int','*']);
|
|
}
|
|
switch(op){
|
|
case capi.SQLITE_DBCONFIG_ENABLE_FKEY:
|
|
case capi.SQLITE_DBCONFIG_ENABLE_TRIGGER:
|
|
case capi.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER:
|
|
case capi.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION:
|
|
case capi.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE:
|
|
case capi.SQLITE_DBCONFIG_ENABLE_QPSG:
|
|
case capi.SQLITE_DBCONFIG_TRIGGER_EQP:
|
|
case capi.SQLITE_DBCONFIG_RESET_DATABASE:
|
|
case capi.SQLITE_DBCONFIG_DEFENSIVE:
|
|
case capi.SQLITE_DBCONFIG_WRITABLE_SCHEMA:
|
|
case capi.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE:
|
|
case capi.SQLITE_DBCONFIG_DQS_DML:
|
|
case capi.SQLITE_DBCONFIG_DQS_DDL:
|
|
case capi.SQLITE_DBCONFIG_ENABLE_VIEW:
|
|
case capi.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT:
|
|
case capi.SQLITE_DBCONFIG_TRUSTED_SCHEMA:
|
|
case capi.SQLITE_DBCONFIG_STMT_SCANSTATUS:
|
|
case capi.SQLITE_DBCONFIG_REVERSE_SCANORDER:
|
|
return this.ip(pDb, op, args[0], args[1] || 0);
|
|
case capi.SQLITE_DBCONFIG_LOOKASIDE:
|
|
return this.pii(pDb, op, args[0], args[1], args[2]);
|
|
case capi.SQLITE_DBCONFIG_MAINDBNAME:
|
|
return this.s(pDb, op, args[0]);
|
|
default:
|
|
return capi.SQLITE_MISUSE;
|
|
}
|
|
}.bind(Object.create(null));
|
|
|
|
/**
|
|
Given a (sqlite3_value*), this function attempts to convert it
|
|
to an equivalent JS value with as much fidelity as feasible and
|
|
return it.
|
|
|
|
By default it throws if it cannot determine any sensible
|
|
conversion. If passed a falsy second argument, it instead returns
|
|
`undefined` if no suitable conversion is found. Note that there
|
|
is no conversion from SQL to JS which results in the `undefined`
|
|
value, so `undefined` has an unambiguous meaning here. It will
|
|
always throw a WasmAllocError if allocating memory for a
|
|
conversion fails.
|
|
|
|
Caveats:
|
|
|
|
- It does not support sqlite3_value_to_pointer() conversions
|
|
because those require a type name string which this function
|
|
does not have and cannot sensibly be given at the level of the
|
|
API where this is used (e.g. automatically converting UDF
|
|
arguments). Clients using sqlite3_value_to_pointer(), and its
|
|
related APIs, will need to manage those themselves.
|
|
*/
|
|
capi.sqlite3_value_to_js = function(pVal,throwIfCannotConvert=true){
|
|
let arg;
|
|
const valType = capi.sqlite3_value_type(pVal);
|
|
switch(valType){
|
|
case capi.SQLITE_INTEGER:
|
|
if(wasm.bigIntEnabled){
|
|
arg = capi.sqlite3_value_int64(pVal);
|
|
if(util.bigIntFitsDouble(arg)) arg = Number(arg);
|
|
}
|
|
else arg = capi.sqlite3_value_double(pVal)/*yes, double, for larger integers*/;
|
|
break;
|
|
case capi.SQLITE_FLOAT:
|
|
arg = capi.sqlite3_value_double(pVal);
|
|
break;
|
|
case capi.SQLITE_TEXT:
|
|
arg = capi.sqlite3_value_text(pVal);
|
|
break;
|
|
case capi.SQLITE_BLOB:{
|
|
const n = capi.sqlite3_value_bytes(pVal);
|
|
const pBlob = capi.sqlite3_value_blob(pVal);
|
|
if(n && !pBlob) sqlite3.WasmAllocError.toss(
|
|
"Cannot allocate memory for blob argument of",n,"byte(s)"
|
|
);
|
|
arg = n ? wasm.heap8u().slice(pBlob, pBlob + Number(n)) : null;
|
|
break;
|
|
}
|
|
case capi.SQLITE_NULL:
|
|
arg = null; break;
|
|
default:
|
|
if(throwIfCannotConvert){
|
|
toss3(capi.SQLITE_MISMATCH,
|
|
"Unhandled sqlite3_value_type():",valType);
|
|
}
|
|
arg = undefined;
|
|
}
|
|
return arg;
|
|
};
|
|
|
|
/**
|
|
Requires a C-style array of `sqlite3_value*` objects and the
|
|
number of entries in that array. Returns a JS array containing
|
|
the results of passing each C array entry to
|
|
sqlite3_value_to_js(). The 3rd argument to this function is
|
|
passed on as the 2nd argument to that one.
|
|
*/
|
|
capi.sqlite3_values_to_js = function(argc,pArgv,throwIfCannotConvert=true){
|
|
let i;
|
|
const tgt = [];
|
|
for(i = 0; i < argc; ++i){
|
|
/**
|
|
Curiously: despite ostensibly requiring 8-byte
|
|
alignment, the pArgv array is parcelled into chunks of
|
|
4 bytes (1 pointer each). The values those point to
|
|
have 8-byte alignment but the individual argv entries
|
|
do not.
|
|
*/
|
|
tgt.push(capi.sqlite3_value_to_js(
|
|
wasm.peekPtr(pArgv + (wasm.ptrSizeof * i))
|
|
));
|
|
}
|
|
return tgt;
|
|
};
|
|
|
|
/**
|
|
Calls either sqlite3_result_error_nomem(), if e is-a
|
|
WasmAllocError, or sqlite3_result_error(). In the latter case,
|
|
the second arugment is coerced to a string to create the error
|
|
message.
|
|
|
|
The first argument is a (sqlite3_context*). Returns void.
|
|
Does not throw.
|
|
*/
|
|
capi.sqlite3_result_error_js = function(pCtx,e){
|
|
if(e instanceof WasmAllocError){
|
|
capi.sqlite3_result_error_nomem(pCtx);
|
|
}else{
|
|
/* Maintenance reminder: ''+e, rather than e.message,
|
|
will prefix e.message with e.name, so it includes
|
|
the exception's type name in the result. */;
|
|
capi.sqlite3_result_error(pCtx, ''+e, -1);
|
|
}
|
|
};
|
|
|
|
/**
|
|
This function passes its 2nd argument to one of the
|
|
sqlite3_result_xyz() routines, depending on the type of that
|
|
argument:
|
|
|
|
- If (val instanceof Error), this function passes it to
|
|
sqlite3_result_error_js().
|
|
- `null`: `sqlite3_result_null()`
|
|
- `boolean`: `sqlite3_result_int()` with a value of 0 or 1.
|
|
- `number`: `sqlite3_result_int()`, `sqlite3_result_int64()`, or
|
|
`sqlite3_result_double()`, depending on the range of the number
|
|
and whether or not int64 support is enabled.
|
|
- `bigint`: similar to `number` but will trigger an error if the
|
|
value is too big to store in an int64.
|
|
- `string`: `sqlite3_result_text()`
|
|
- Uint8Array or Int8Array or ArrayBuffer: `sqlite3_result_blob()`
|
|
- `undefined`: is a no-op provided to simplify certain use cases.
|
|
|
|
Anything else triggers `sqlite3_result_error()` with a
|
|
description of the problem.
|
|
|
|
The first argument to this function is a `(sqlite3_context*)`.
|
|
Returns void. Does not throw.
|
|
*/
|
|
capi.sqlite3_result_js = function(pCtx,val){
|
|
if(val instanceof Error){
|
|
capi.sqlite3_result_error_js(pCtx, val);
|
|
return;
|
|
}
|
|
try{
|
|
switch(typeof val) {
|
|
case 'undefined':
|
|
/* This is a no-op. This routine originated in the create_function()
|
|
family of APIs and in that context, passing in undefined indicated
|
|
that the caller was responsible for calling sqlite3_result_xxx()
|
|
(if needed). */
|
|
break;
|
|
case 'boolean':
|
|
capi.sqlite3_result_int(pCtx, val ? 1 : 0);
|
|
break;
|
|
case 'bigint':
|
|
if(util.bigIntFits32(val)){
|
|
capi.sqlite3_result_int(pCtx, Number(val));
|
|
}else if(util.bigIntFitsDouble(val)){
|
|
capi.sqlite3_result_double(pCtx, Number(val));
|
|
}else if(wasm.bigIntEnabled){
|
|
if(util.bigIntFits64(val)) capi.sqlite3_result_int64(pCtx, val);
|
|
else toss3("BigInt value",val.toString(),"is too BigInt for int64.");
|
|
}else{
|
|
toss3("BigInt value",val.toString(),"is too BigInt.");
|
|
}
|
|
break;
|
|
case 'number': {
|
|
let f;
|
|
if(util.isInt32(val)){
|
|
f = capi.sqlite3_result_int;
|
|
}else if(wasm.bigIntEnabled
|
|
&& Number.isInteger(val)
|
|
&& util.bigIntFits64(BigInt(val))){
|
|
f = capi.sqlite3_result_int64;
|
|
}else{
|
|
f = capi.sqlite3_result_double;
|
|
}
|
|
f(pCtx, val);
|
|
break;
|
|
}
|
|
case 'string': {
|
|
const [p, n] = wasm.allocCString(val,true);
|
|
capi.sqlite3_result_text(pCtx, p, n, capi.SQLITE_WASM_DEALLOC);
|
|
break;
|
|
}
|
|
case 'object':
|
|
if(null===val/*yes, typeof null === 'object'*/) {
|
|
capi.sqlite3_result_null(pCtx);
|
|
break;
|
|
}else if(util.isBindableTypedArray(val)){
|
|
const pBlob = wasm.allocFromTypedArray(val);
|
|
capi.sqlite3_result_blob(
|
|
pCtx, pBlob, val.byteLength,
|
|
capi.SQLITE_WASM_DEALLOC
|
|
);
|
|
break;
|
|
}
|
|
// else fall through
|
|
default:
|
|
toss3("Don't not how to handle this UDF result value:",(typeof val), val);
|
|
}
|
|
}catch(e){
|
|
capi.sqlite3_result_error_js(pCtx, e);
|
|
}
|
|
};
|
|
|
|
/**
|
|
Returns the result sqlite3_column_value(pStmt,iCol) passed to
|
|
sqlite3_value_to_js(). The 3rd argument of this function is
|
|
ignored by this function except to pass it on as the second
|
|
argument of sqlite3_value_to_js(). If the sqlite3_column_value()
|
|
returns NULL (e.g. because the column index is out of range),
|
|
this function returns `undefined`, regardless of the 3rd
|
|
argument. If the 3rd argument is falsy and conversion fails,
|
|
`undefined` will be returned.
|
|
|
|
Note that sqlite3_column_value() returns an "unprotected" value
|
|
object, but in a single-threaded environment (like this one)
|
|
there is no distinction between protected and unprotected values.
|
|
*/
|
|
capi.sqlite3_column_js = function(pStmt, iCol, throwIfCannotConvert=true){
|
|
const v = capi.sqlite3_column_value(pStmt, iCol);
|
|
return (0===v) ? undefined : capi.sqlite3_value_to_js(v, throwIfCannotConvert);
|
|
};
|
|
|
|
/**
|
|
Internal impl of sqlite3_preupdate_new/old_js() and
|
|
sqlite3changeset_new/old_js().
|
|
*/
|
|
const __newOldValue = function(pObj, iCol, impl){
|
|
impl = capi[impl];
|
|
if(!this.ptr) this.ptr = wasm.allocPtr();
|
|
else wasm.pokePtr(this.ptr, 0);
|
|
const rc = impl(pObj, iCol, this.ptr);
|
|
if(rc) return SQLite3Error.toss(rc,arguments[2]+"() failed with code "+rc);
|
|
const pv = wasm.peekPtr(this.ptr);
|
|
return pv ? capi.sqlite3_value_to_js( pv, true ) : undefined;
|
|
}.bind(Object.create(null));
|
|
|
|
/**
|
|
A wrapper around sqlite3_preupdate_new() which fetches the
|
|
sqlite3_value at the given index and returns the result of
|
|
passing it to sqlite3_value_to_js(). Throws on error.
|
|
*/
|
|
capi.sqlite3_preupdate_new_js =
|
|
(pDb, iCol)=>__newOldValue(pDb, iCol, 'sqlite3_preupdate_new');
|
|
|
|
/**
|
|
The sqlite3_preupdate_old() counterpart of
|
|
sqlite3_preupdate_new_js(), with an identical interface.
|
|
*/
|
|
capi.sqlite3_preupdate_old_js =
|
|
(pDb, iCol)=>__newOldValue(pDb, iCol, 'sqlite3_preupdate_old');
|
|
|
|
/**
|
|
A wrapper around sqlite3changeset_new() which fetches the
|
|
sqlite3_value at the given index and returns the result of
|
|
passing it to sqlite3_value_to_js(). Throws on error.
|
|
|
|
If sqlite3changeset_new() succeeds but has no value to report,
|
|
this function returns the undefined value, noting that undefined
|
|
is a valid conversion from an `sqlite3_value`, so is unambiguous.
|
|
*/
|
|
capi.sqlite3changeset_new_js =
|
|
(pChangesetIter, iCol) => __newOldValue(pChangesetIter, iCol,
|
|
'sqlite3changeset_new');
|
|
|
|
/**
|
|
The sqlite3changeset_old() counterpart of
|
|
sqlite3changeset_new_js(), with an identical interface.
|
|
*/
|
|
capi.sqlite3changeset_old_js =
|
|
(pChangesetIter, iCol)=>__newOldValue(pChangesetIter, iCol,
|
|
'sqlite3changeset_old');
|
|
|
|
/* The remainder of the API will be set up in later steps. */
|
|
const sqlite3 = {
|
|
WasmAllocError: WasmAllocError,
|
|
SQLite3Error: SQLite3Error,
|
|
capi,
|
|
util,
|
|
wasm,
|
|
config,
|
|
/**
|
|
Holds the version info of the sqlite3 source tree from which
|
|
the generated sqlite3-api.js gets built. Note that its version
|
|
may well differ from that reported by sqlite3_libversion(), but
|
|
that should be considered a source file mismatch, as the JS and
|
|
WASM files are intended to be built and distributed together.
|
|
|
|
This object is initially a placeholder which gets replaced by a
|
|
build-generated object.
|
|
*/
|
|
version: Object.create(null),
|
|
|
|
/**
|
|
The library reserves the 'client' property for client-side use
|
|
and promises to never define a property with this name nor to
|
|
ever rely on specific contents of it. It makes no such guarantees
|
|
for other properties.
|
|
*/
|
|
client: undefined,
|
|
|
|
/**
|
|
Performs any optional asynchronous library-level initialization
|
|
which might be required. This function returns a Promise which
|
|
resolves to the sqlite3 namespace object. Any error in the
|
|
async init will be fatal to the init as a whole, but init
|
|
routines are themselves welcome to install dummy catch()
|
|
handlers which are not fatal if their failure should be
|
|
considered non-fatal. If called more than once, the second and
|
|
subsequent calls are no-ops which return a pre-resolved
|
|
Promise.
|
|
|
|
Ideally this function is called as part of the Promise chain
|
|
which handles the loading and bootstrapping of the API. If not
|
|
then it must be called by client-level code, which must not use
|
|
the library until the returned promise resolves.
|
|
|
|
Bug: if called while a prior call is still resolving, the 2nd
|
|
call will resolve prematurely, before the 1st call has finished
|
|
resolving. The current build setup precludes that possibility,
|
|
so it's only a hypothetical problem if/when this function
|
|
ever needs to be invoked by clients.
|
|
|
|
In Emscripten-based builds, this function is called
|
|
automatically and deleted from this object.
|
|
*/
|
|
asyncPostInit: async function(){
|
|
let lip = sqlite3ApiBootstrap.initializersAsync;
|
|
delete sqlite3ApiBootstrap.initializersAsync;
|
|
if(!lip || !lip.length) return Promise.resolve(sqlite3);
|
|
lip = lip.map((f)=>{
|
|
const p = (f instanceof Promise) ? f : f(sqlite3);
|
|
return p.catch((e)=>{
|
|
console.error("an async sqlite3 initializer failed:",e);
|
|
throw e;
|
|
});
|
|
});
|
|
const postInit = ()=>{
|
|
if(!sqlite3.__isUnderTest){
|
|
/* Delete references to internal-only APIs which are used by
|
|
some initializers. Retain them when running in test mode
|
|
so that we can add tests for them. */
|
|
delete sqlite3.util;
|
|
/* It's conceivable that we might want to expose
|
|
StructBinder to client-side code, but it's only useful if
|
|
clients build their own sqlite3.wasm which contains their
|
|
one C struct types. */
|
|
delete sqlite3.StructBinder;
|
|
}
|
|
return sqlite3;
|
|
};
|
|
if(1){
|
|
/* Run all initializers in sequence. The advantage is that it
|
|
allows us to have post-init cleanup defined outside of this
|
|
routine at the end of the list and have it run at a
|
|
well-defined time. */
|
|
let p = lip.shift();
|
|
while(lip.length) p = p.then(lip.shift());
|
|
return p.then(postInit);
|
|
}else{
|
|
/* Run them in an arbitrary order. */
|
|
return Promise.all(lip).then(postInit);
|
|
}
|
|
},
|
|
/**
|
|
scriptInfo ideally gets injected into this object by the
|
|
infrastructure which assembles the JS/WASM module. It contains
|
|
state which must be collected before sqlite3ApiBootstrap() can
|
|
be declared. It is not necessarily available to any
|
|
sqlite3ApiBootstrap.initializers but "should" be in place (if
|
|
it's added at all) by the time that
|
|
sqlite3ApiBootstrap.initializersAsync is processed.
|
|
|
|
This state is not part of the public API, only intended for use
|
|
with the sqlite3 API bootstrapping and wasm-loading process.
|
|
*/
|
|
scriptInfo: undefined
|
|
};
|
|
try{
|
|
sqlite3ApiBootstrap.initializers.forEach((f)=>{
|
|
f(sqlite3);
|
|
});
|
|
}catch(e){
|
|
/* If we don't report this here, it can get completely swallowed
|
|
up and disappear into the abyss of Promises and Workers. */
|
|
console.error("sqlite3 bootstrap initializer threw:",e);
|
|
throw e;
|
|
}
|
|
delete sqlite3ApiBootstrap.initializers;
|
|
sqlite3ApiBootstrap.sqlite3 = sqlite3;
|
|
return sqlite3;
|
|
}/*sqlite3ApiBootstrap()*/;
|
|
/**
|
|
globalThis.sqlite3ApiBootstrap.initializers is an internal detail used by
|
|
the various pieces of the sqlite3 API's amalgamation process. It
|
|
must not be modified by client code except when plugging such code
|
|
into the amalgamation process.
|
|
|
|
Each component of the amalgamation is expected to append a function
|
|
to this array. When sqlite3ApiBootstrap() is called for the first
|
|
time, each such function will be called (in their appended order)
|
|
and passed the sqlite3 namespace object, into which they can install
|
|
their features (noting that most will also require that certain
|
|
features alread have been installed). At the end of that process,
|
|
this array is deleted.
|
|
|
|
Note that the order of insertion into this array is significant for
|
|
some pieces. e.g. sqlite3.capi and sqlite3.wasm cannot be fully
|
|
utilized until the whwasmutil.js part is plugged in via
|
|
sqlite3-api-glue.js.
|
|
*/
|
|
globalThis.sqlite3ApiBootstrap.initializers = [];
|
|
/**
|
|
globalThis.sqlite3ApiBootstrap.initializersAsync is an internal detail
|
|
used by the sqlite3 API's amalgamation process. It must not be
|
|
modified by client code except when plugging such code into the
|
|
amalgamation process.
|
|
|
|
The counterpart of globalThis.sqlite3ApiBootstrap.initializers,
|
|
specifically for initializers which are asynchronous. All entries in
|
|
this list must be either async functions, non-async functions which
|
|
return a Promise, or a Promise. Each function in the list is called
|
|
with the sqlite3 ojbect as its only argument.
|
|
|
|
The resolved value of any Promise is ignored and rejection will kill
|
|
the asyncPostInit() process (at an indeterminate point because all
|
|
of them are run asynchronously in parallel).
|
|
|
|
This list is not processed until the client calls
|
|
sqlite3.asyncPostInit(). This means, for example, that intializers
|
|
added to globalThis.sqlite3ApiBootstrap.initializers may push entries to
|
|
this list.
|
|
*/
|
|
globalThis.sqlite3ApiBootstrap.initializersAsync = [];
|
|
/**
|
|
Client code may 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.
|
|
*/
|
|
globalThis.sqlite3ApiBootstrap.defaultConfig = Object.create(null);
|
|
/**
|
|
Placeholder: gets installed by the first call to
|
|
globalThis.sqlite3ApiBootstrap(). However, it is recommended that the
|
|
caller of sqlite3ApiBootstrap() capture its return value and delete
|
|
globalThis.sqlite3ApiBootstrap after calling it. It returns the same
|
|
value which will be stored here.
|
|
*/
|
|
globalThis.sqlite3ApiBootstrap.sqlite3 = undefined;
|