1# sqlite3-api.js And Friends 2 3This is the README for the files `sqlite3-*.js` and 4`sqlite3-wasm.c`. This collection of files is used to build a 5single-file distribution of the sqlite3 WASM API. It is broken into 6multiple JS files because: 7 81. To facilitate including or excluding certain components for 9 specific use cases. e.g. by removing `sqlite3-api-oo1.js` if the 10 OO#1 API is not needed. 11 122. To facilitate modularizing the pieces for use in different WASM 13 build environments. e.g. the files `post-js-*.js` are for use with 14 Emscripten's `--post-js` feature, and nowhere else. 15 163. Certain components must be in their own standalone files in order 17 to be loaded as JS Workers. 18 19Note that the structure described here is the current state of things, 20not necessarily the "final" state. 21 22The overall idea is that the following files get concatenated 23together, in the listed order, the resulting file is loaded by a 24browser client: 25 26- `post-js-header.js`\ 27 Emscripten-specific header for the `--post-js` input. 28- `sqlite3-api-prologue.js`\ 29 Contains the initial bootstrap setup of the sqlite3 API 30 objects. This is exposed as a function, rather than objects, so that 31 the next step can pass in a config object which abstracts away parts 32 of the WASM environment, to facilitate plugging it in to arbitrary 33 WASM toolchains. 34- `../common/whwasmutil.js`\ 35 A semi-third-party collection of JS/WASM utility code intended to 36 replace much of the Emscripten glue. The sqlite3 APIs internally use 37 these APIs instead of their Emscripten counterparts, in order to be 38 more portable to arbitrary WASM toolchains. This API is 39 configurable, in principle, for use with arbitrary WASM 40 toolchains. It is "semi-third-party" in that it was created in order 41 to support this tree but is standalone and maintained together 42 with... 43- `../jaccwabyt/jaccwabyt.js`\ 44 Another semi-third-party API which creates bindings between JS 45 and C structs, such that changes to the struct state from either JS 46 or C are visible to the other end of the connection. This is also an 47 independent spinoff project, conceived for the sqlite3 project but 48 maintained separately. 49- `sqlite3-api-glue.js`\ 50 Invokes the function exposed by `sqlite3-api-prologue.js`, passing 51 it a configuration object to configure it for the current WASM 52 toolchain (noting that it currently requires Emscripten), then 53 removes that function from the global scope. The result of this file 54 is a global-scope `sqlite3` object which acts as a namespace for the 55 API's functionality. This object gets removed from the global scope 56 after the following files have attached their own features to it. 57- `sqlite3-api-oo1.js`\ 58 Provides a high-level object-oriented wrapper to the lower-level C 59 API, colloquially known as OO API #1. Its API is similar to other 60 high-level sqlite3 JS wrappers and should feel relatively familiar 61 to anyone familiar with such APIs. That said, it is not a "required 62 component" and can be elided from builds which do not want it. 63- `sqlite3-api-worker1.js`\ 64 A Worker-thread-based API which uses OO API #1 to provide an 65 interface to a database which can be driven from the main Window 66 thread via the Worker message-passing interface. Like OO API #1, 67 this is an optional component, offering one of any number of 68 potential implementations for such an API. 69 - `sqlite3-worker1.js`\ 70 Is not part of the amalgamated sources and is intended to be 71 loaded by a client Worker thread. It loads the sqlite3 module 72 and runs the Worker #1 API which is implemented in 73 `sqlite3-api-worker1.js`. 74- `sqlite3-api-opfs.js`\ 75 is an in-development/experimental sqlite3 VFS wrapper, the goal of 76 which being to use Google Chrome's Origin-Private FileSystem (OPFS) 77 storage layer to provide persistent storage for database files in a 78 browser. It is far from complete. 79- `sqlite3-api-cleanup.js`\ 80 the previous files temporarily create global objects in order to 81 communicate their state to the files which follow them, and _this_ 82 file connects any final components together and cleans up those 83 globals. As of this writing, this code ensures that the previous 84 files leave no global symbols installed, and it moves the sqlite3 85 namespace object into the in-scope Emscripten module. Abstracting 86 this for other WASM toolchains is TODO. 87- `post-js-footer.js`\ 88 Emscripten-specific footer for the `--post-js` input. This closes 89 off the lexical scope opened by `post-js-header.js`. 90 91The build process glues those files together, resulting in 92`sqlite3-api.js`, which is everything except for the `post-js-*.js` 93files, and `sqlite3.js`, which is the Emscripten-generated amalgamated 94output and includes the `post-js-*.js` parts, as well as the 95Emscripten-provided module loading pieces. 96 97The non-JS outlier file is `sqlite3-wasm.c`: it is a proxy for 98`sqlite3.c` which `#include`'s that file and adds a couple more 99WASM-specific helper functions, at least one of which requires access 100to private/static `sqlite3.c` internals. `sqlite3.wasm` is compiled 101from this file rather than `sqlite3.c`. 102