History

stephan 2f06bf2541 Lots of tweaking in batch-runner.js. Minor internal API update in OO #1 API. FossilOrigin-Name: 24b82b9504db3d8e1335c2300b133f897dc1a541026dc24be5b0ffd8be66d977		2022-08-29 18:58:38 +00:00
..
EXPORTED_FUNCTIONS.sqlite3-api	Build fiddle with WASMFS OPFS support and attempt to use it if available. It does not work because of an inexplicable exception in Emscripten-generated code and perpetually-locked db, but it's not yet clear why.	2022-08-12 17:57:09 +00:00
EXPORTED_RUNTIME_METHODS.sqlite3-api	wasm refactoring part 2 of (apparently) 2: moved ext/fiddle/... into ext/wasm and restructured the core API-related parts of the JS/WASM considerably.	2022-08-10 11:26:08 +00:00
post-js-footer.js	wasm refactoring part 2 of (apparently) 2: moved ext/fiddle/... into ext/wasm and restructured the core API-related parts of the JS/WASM considerably.	2022-08-10 11:26:08 +00:00
post-js-header.js	wasm refactoring part 2 of (apparently) 2: moved ext/fiddle/... into ext/wasm and restructured the core API-related parts of the JS/WASM considerably.	2022-08-10 11:26:08 +00:00
README.md	Minor cleanups, reorgs, and doc updates for the JS APIs. Renamed sqlite3(-api)-worker.js to sqlite3(-api)-worker1.js, for symmetry with sqlite3-api-oo1.js.	2022-08-17 16:44:05 +00:00
sqlite3-api-cleanup.js	js: resolve the mysterious "extra" unhandled exception notification, caused by inadvertently forking one promise into two separate ones (failing to properly reassign a then() result). Fix a typo in new Worker 1 code which caused the DB(filename) name to be incorrect.	2022-08-24 14:50:10 +00:00
sqlite3-api-glue.js	Refactor JS API amalgamation such that the bootstrapping/configuration is deferred until the whole amalgamation is available, to facilitate providing clients with a way to initialize the API with their own config (noting that we're still one small level of refactoring away from being able to actually do that).	2022-08-22 13:34:13 +00:00
sqlite3-api-oo1.js	Lots of tweaking in batch-runner.js. Minor internal API update in OO #1 API.	2022-08-29 18:58:38 +00:00
sqlite3-api-opfs.js	Refactor JS API amalgamation such that the bootstrapping/configuration is deferred until the whole amalgamation is available, to facilitate providing clients with a way to initialize the API with their own config (noting that we're still one small level of refactoring away from being able to actually do that).	2022-08-22 13:34:13 +00:00
sqlite3-api-prologue.js	js: resolve the mysterious "extra" unhandled exception notification, caused by inadvertently forking one promise into two separate ones (failing to properly reassign a then() result). Fix a typo in new Worker 1 code which caused the DB(filename) name to be incorrect.	2022-08-24 14:50:10 +00:00
sqlite3-api-worker1.js	Consolidate oo1.DB.exec() and oo1.DB.execMulti() into oo1.DB.exec(). This is a bit less efficient but certainly easier for a client to deal with and lightens the maintenance burden.	2022-08-25 13:27:52 +00:00
sqlite3-wasi.h	wasm refactoring part 2 of (apparently) 2: moved ext/fiddle/... into ext/wasm and restructured the core API-related parts of the JS/WASM considerably.	2022-08-10 11:26:08 +00:00
sqlite3-wasm.c	Refactor JS API amalgamation such that the bootstrapping/configuration is deferred until the whole amalgamation is available, to facilitate providing clients with a way to initialize the API with their own config (noting that we're still one small level of refactoring away from being able to actually do that).	2022-08-22 13:34:13 +00:00

README.md

sqlite3-api.js And Friends

This is the README for the files sqlite3-*.js and sqlite3-wasm.c. This collection of files is used to build a single-file distribution of the sqlite3 WASM API. It is broken into multiple JS files because:

To facilitate including or excluding certain components for specific use cases. e.g. by removing sqlite3-api-oo1.js if the OO#1 API is not needed.
To facilitate modularizing the pieces for use in different WASM build environments. e.g. the files post-js-*.js are for use with Emscripten's --post-js feature, and nowhere else.
Certain components must be in their own standalone files in order to be loaded as JS Workers.

Note that the structure described here is the current state of things, not necessarily the "final" state.

The overall idea is that the following files get concatenated together, in the listed order, the resulting file is loaded by a browser client:

post-js-header.js\
Emscripten-specific header for the --post-js input.
sqlite3-api-prologue.js\
Contains the initial bootstrap setup of the sqlite3 API objects. This is exposed as a function, rather than objects, so that the next step can pass in a config object which abstracts away parts of the WASM environment, to facilitate plugging it in to arbitrary WASM toolchains.
../common/whwasmutil.js\
A semi-third-party collection of JS/WASM utility code intended to replace much of the Emscripten glue. The sqlite3 APIs internally use these APIs instead of their Emscripten counterparts, in order to be more portable to arbitrary WASM toolchains. This API is configurable, in principle, for use with arbitrary WASM toolchains. It is "semi-third-party" in that it was created in order to support this tree but is standalone and maintained together with...
../jaccwabyt/jaccwabyt.js\
Another semi-third-party API which creates bindings between JS and C structs, such that changes to the struct state from either JS or C are visible to the other end of the connection. This is also an independent spinoff project, conceived for the sqlite3 project but maintained separately.
sqlite3-api-glue.js\
Invokes the function exposed by sqlite3-api-prologue.js, passing it a configuration object to configure it for the current WASM toolchain (noting that it currently requires Emscripten), then removes that function from the global scope. The result of this file is a global-scope sqlite3 object which acts as a namespace for the API's functionality. This object gets removed from the global scope after the following files have attached their own features to it.
sqlite3-api-oo1.js\
Provides a high-level object-oriented wrapper to the lower-level C API, colloquially known as OO API #1. Its API is similar to other high-level sqlite3 JS wrappers and should feel relatively familiar to anyone familiar with such APIs. That said, it is not a "required component" and can be elided from builds which do not want it.
sqlite3-api-worker1.js\
A Worker-thread-based API which uses OO API #1 to provide an interface to a database which can be driven from the main Window thread via the Worker message-passing interface. Like OO API #1, this is an optional component, offering one of any number of potential implementations for such an API.
- sqlite3-worker1.js\
  Is not part of the amalgamated sources and is intended to be loaded by a client Worker thread. It loads the sqlite3 module and runs the Worker #1 API which is implemented in sqlite3-api-worker1.js.
sqlite3-api-opfs.js\
is an in-development/experimental sqlite3 VFS wrapper, the goal of which being to use Google Chrome's Origin-Private FileSystem (OPFS) storage layer to provide persistent storage for database files in a browser. It is far from complete.
sqlite3-api-cleanup.js\
the previous files temporarily create global objects in order to communicate their state to the files which follow them, and this file connects any final components together and cleans up those globals. As of this writing, this code ensures that the previous files leave no global symbols installed, and it moves the sqlite3 namespace object into the in-scope Emscripten module. Abstracting this for other WASM toolchains is TODO.
post-js-footer.js\
Emscripten-specific footer for the --post-js input. This closes off the lexical scope opened by post-js-header.js.

The build process glues those files together, resulting in sqlite3-api.js, which is everything except for the post-js-*.js files, and sqlite3.js, which is the Emscripten-generated amalgamated output and includes the post-js-*.js parts, as well as the Emscripten-provided module loading pieces.

The non-JS outlier file is sqlite3-wasm.c: it is a proxy for sqlite3.c which #include's that file and adds a couple more WASM-specific helper functions, at least one of which requires access to private/static sqlite3.c internals. sqlite3.wasm is compiled from this file rather than sqlite3.c.