database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-12-20 01:22:32 +03:00
Code Activity

Generic internal JS cleanups towards improving portability of sqlite3-api.js to other build systems.

Browse Source 
FossilOrigin-Name: 5bc37e5c2fcd83fd0bc40234144072363f1cbf7d811a15b74a0991e397a35eb8
This commit is contained in:
stephan
2025-11-15 11:30:45 +00:00
parent a804a65617
commit 987870a6a0
7 changed files with 96 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
ext/wasm/api/sqlite3-api-prologue.js
View File

@@ -27,13 +27,14 @@
/**
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`.
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.
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
@@ -93,9 +94,10 @@
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.
- `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).
[^1] = This property may optionally be a function, in which case
this function calls that function to fetch the value,
@@ -125,7 +127,8 @@
Both sqlite3ApiBootstrap.defaultConfig and
globalThis.sqlite3ApiConfig get deleted by sqlite3ApiBootstrap()
because any changes to them made after that point would have no
useful effect.
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
@@ -177,14 +180,6 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
}
});
/**
Eliminate any confusion about whether these config objects may
be used after library initialization by eliminating the outward-facing
objects...
*/
delete globalThis.sqlite3ApiConfig;
delete sqlite3ApiBootstrap.defaultConfig;
/**
The main sqlite3 binding API gets installed into this object,
mimicking the C API as closely as we can. The numerous members
@@ -796,7 +791,8 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
/**
wasm.X properties which are used for configuring the wasm
environment via whwashutil.js.
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, {
@@ -809,8 +805,9 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
/**
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.
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']
@@ -956,7 +953,11 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
};
wasm.realloc.impl = wasm.exports[keyRealloc];
wasm.dealloc = function f(m){
f.impl(wasm.ptr.coerce(m)/*tag:64bit*/);
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];
}
@@ -1027,18 +1028,18 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
}/*compileOptionUsed()*/;
/**
sqlite3.wasm.pstack (pseudo-stack) holds a special-case intended
solely for short-lived, small data. In practice, it's primarily
used to allocate output pointers. It mus not be used for any
memory which needs to outlive the scope in which it's obtained
from pstack.
sqlite3.wasm.pstack (pseudo-stack) holds a special-case allocator
intended solely for short-lived, small data. In practice, it's
primarily used to allocate output pointers. It must not be used
for any memory which needs to outlive the scope in which it's
obtained from pstack.
The library guarantees only that a minimum of 2kb are available
in this allocator, and it may provide more (it's a build-time
value). pstack.quota and pstack.remaining can be used to get the
total resp. remaining amount of memory.
It has only a single intended usage:
It has only a single intended usage pattern:
```
const stackPos = pstack.pointer;
@@ -1055,13 +1056,11 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
```
This allocator is much faster than a general-purpose one but is
limited to usage patterns like the one shown above.
limited to usage patterns like the one shown above (which are
pretty common when using sqlite3.capi).
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().
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),{
/**
@@ -1135,7 +1134,7 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
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
When a returned pointer 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
@@ -1203,6 +1202,9 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
}
})/*wasm.pstack properties*/;
/**
Docs: https://sqlite.org/wasm/doc/trunk/api-c-style.md#sqlite3_randomness
*/
capi.sqlite3_randomness = (...args)=>{
if(1===args.length
&& util.isTypedArray(args[0])
@@ -1237,8 +1239,6 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
wasm.exports.sqlite3_randomness(...args);
};
/** State for sqlite3_wasmfs_opfs_dir(). */
let __wasmfsOpfsDir = undefined;
/**
If the wasm environment has a WASMFS/OPFS-backed persistent
storage directory, its path is returned by this function. If it
@@ -1262,7 +1262,7 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
WASMFS capability requires a custom build.
*/
capi.sqlite3_wasmfs_opfs_dir = function(){
if(undefined !== __wasmfsOpfsDir) return __wasmfsOpfsDir;
if(undefined !== this.dir) return this.dir;
// If we have no OPFS, there is no persistent dir
const pdir = config.wasmfsOpfsDir;
if(!pdir
@@ -1270,21 +1270,21 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
|| !globalThis.FileSystemDirectoryHandle
|| !globalThis.FileSystemFileHandle
|| !wasm.exports.sqlite3__wasm_init_wasmfs){
return __wasmfsOpfsDir = "";
return this.dir = "";
}
try{
if(pdir && 0===wasm.xCallWrapped(
'sqlite3__wasm_init_wasmfs', 'i32', ['string'], pdir
)){
return __wasmfsOpfsDir = pdir;
return this.dir = pdir;
}else{
return __wasmfsOpfsDir = "";
return this.dir = "";
}
}catch(e){
// sqlite3__wasm_init_wasmfs() is not available
return __wasmfsOpfsDir = "";
return this.dir = "";
}
};
}.bind(Object.create(null));
/**
Returns true if sqlite3.capi.sqlite3_wasmfs_opfs_dir() is a
@@ -1340,7 +1340,7 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
*/
capi.sqlite3_js_vfs_list = function(){
const rc = [];
let pVfs = capi.sqlite3_vfs_find(wasm.ptr.coerce(0));
let pVfs = capi.sqlite3_vfs_find(wasm.ptr.null);
while(pVfs){
const oVfs = new capi.sqlite3_vfs(pVfs);
rc.push(wasm.cstrToJs(oVfs.$zName));
@@ -2068,8 +2068,8 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
*/
asyncPostInit: async function ff(){
if(ff.isReady instanceof Promise) return ff.isReady;
let lia = sqlite3ApiBootstrap.initializersAsync;
delete sqlite3ApiBootstrap.initializersAsync;
let lia = this.initializersAsync;
delete this.initializersAsync;
const postInit = async ()=>{
if(!sqlite3.__isUnderTest){
/* Delete references to internal-only APIs which are used by
@@ -2094,7 +2094,7 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
let p = Promise.resolve(sqlite3);
while(lia.length) p = p.then(lia.shift());
return ff.isReady = p.catch(catcher);
},
}.bind(sqlite3ApiBootstrap),
/**
scriptInfo ideally gets injected into this object by the
infrastructure which assembles the JS/WASM module. It contains
@@ -2121,15 +2121,23 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
}
delete sqlite3ApiBootstrap.initializers;
sqlite3ApiBootstrap.sqlite3 = sqlite3;
delete globalThis.sqlite3ApiBootstrap;
delete globalThis.sqlite3ApiConfig;
sqlite3InitScriptInfo.debugModule(
"sqlite3ApiBootstrap() complete", sqlite3
);
sqlite3.scriptInfo /* used by some async init code */ =
sqlite3InitScriptInfo /* from post-js-header.js */;
if( (sqlite3.__isUnderTest = sqlite3IsUnderTest /* from post-js-header.js */) ){
sqlite3.config.emscripten = EmscriptenModule;
if( 'undefined'!==typeof sqlite3InitScriptInfo/* from post-js-header.js */ ){
sqlite3InitScriptInfo.debugModule(
"sqlite3ApiBootstrap() complete", sqlite3
);
sqlite3.scriptInfo
/* Used by some async init code. As of 2025-11-15 this is still
in use by the OPFS VFS for locating its worker. In non-Emscripten
builds, this would need to be injected in somewhere to get
that VFS loading. */ = sqlite3InitScriptInfo;
}
sqlite3.__isUnderTest =
('undefined'===typeof sqlite3IsUnderTest /* from post-js-header.js */)
? false : !!sqlite3IsUnderTest;
if( sqlite3.__isUnderTest ){
if( 'undefined'!==typeof EmscriptenModule ){
sqlite3.config.emscripten = EmscriptenModule;
}
/*
The problem with exposing these pieces (in non-testing runs) via
sqlite3.wasm is that it exposes non-SQLite pieces to the
@@ -2143,7 +2151,7 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
imports into WASM from its JS glue, but it's not
SQLite-related.
*/
const iw = sqlite3InitScriptInfo.instantiateWasm;
const iw = sqlite3.scriptInfo?.instantiateWasm;
if( iw ){
/* Metadata injected by the custom Module.instantiateWasm()
in pre-js.c-pp.js. */
@@ -2152,6 +2160,15 @@ globalThis.sqlite3ApiBootstrap = async function sqlite3ApiBootstrap(
sqlite3.wasm.imports = iw.imports;
}
}
/**
Eliminate any confusion about whether these config objects may
be used after library initialization by eliminating the outward-facing
objects...
*/
delete globalThis.sqlite3ApiConfig;
delete globalThis.sqlite3ApiBootstrap;
delete sqlite3ApiBootstrap.defaultConfig;
return sqlite3.asyncPostInit().then((s)=>{
sqlite3InitScriptInfo.debugModule(
"sqlite3.asyncPostInit() complete", sqlite3