README.md
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- `sqlite3-api-prologue.js`\
27 Contains the initial bootstrap setup of the sqlite3 API
28 objects. This is exposed as a function, rather than objects, so that
29 the next step can pass in a config object which abstracts away parts
30 of the WASM environment, to facilitate plugging it in to arbitrary
31 WASM toolchains.
32- `../common/whwasmutil.js`\
33 A semi-third-party collection of JS/WASM utility code intended to
34 replace much of the Emscripten glue. The sqlite3 APIs internally use
35 these APIs instead of their Emscripten counterparts, in order to be
36 more portable to arbitrary WASM toolchains. This API is
37 configurable, in principle, for use with arbitrary WASM
38 toolchains. It is "semi-third-party" in that it was created in order
39 to support this tree but is standalone and maintained together
40 with...
41- `../jaccwabyt/jaccwabyt.js`\
42 Another semi-third-party API which creates bindings between JS
43 and C structs, such that changes to the struct state from either JS
44 or C are visible to the other end of the connection. This is also an
45 independent spinoff project, conceived for the sqlite3 project but
46 maintained separately.
47- `sqlite3-api-glue.js`\
48 Invokes functionality exposed by the previous two files to
49 flesh out low-level parts of `sqlite3-api-prologue.js`. Most of
50 these pieces related to the `sqlite3.capi.wasm` object.
51- `sqlite3-api-build-version.js`\
52 Gets created by the build process and populates the
53 `sqlite3.version` object. This part is not critical, but records the
54 version of the library against which this module was built.
55- `sqlite3-api-oo1.js`\
56 Provides a high-level object-oriented wrapper to the lower-level C
57 API, colloquially known as OO API #1. Its API is similar to other
58 high-level sqlite3 JS wrappers and should feel relatively familiar
59 to anyone familiar with such APIs. That said, it is not a "required
60 component" and can be elided from builds which do not want it.
61- `sqlite3-api-worker1.js`\
62 A Worker-thread-based API which uses OO API #1 to provide an
63 interface to a database which can be driven from the main Window
64 thread via the Worker message-passing interface. Like OO API #1,
65 this is an optional component, offering one of any number of
66 potential implementations for such an API.
67 - `sqlite3-worker1.js`\
68 Is not part of the amalgamated sources and is intended to be
69 loaded by a client Worker thread. It loads the sqlite3 module
70 and runs the Worker #1 API which is implemented in
71 `sqlite3-api-worker1.js`.
72 - `sqlite3-worker1-promiser.js`\
73 Is likewise not part of the amalgamated sources and provides
74 a Promise-based interface into the Worker #1 API. This is
75 a far user-friendlier way to interface with databases running
76 in a Worker thread.
77- `sqlite3-api-opfs.js`\
78 is an sqlite3 VFS implementation which supports Google Chrome's
79 Origin-Private FileSystem (OPFS) as a storage layer to provide
80 persistent storage for database files in a browser. It requires...
81 - `sqlite3-opfs-async-proxy.js`\
82 is the asynchronous backend part of the OPFS proxy. It speaks
83 directly to the (async) OPFS API and channels those results back
84 to its synchronous counterpart. This file, because it must be
85 started in its own Worker, is not part of the amalgamation.
86- **`api/sqlite3-api-cleanup.js`**\
87 The previous files do not immediately extend the library. Instead
88 they add callback functions to be called during its
89 bootstrapping. Some also temporarily create global objects in order
90 to communicate their state to the files which follow them. This file
91 cleans up any dangling globals and runs the API bootstrapping
92 process, which is what finally executes the initialization code
93 installed by the previous files. As of this writing, this code
94 ensures that the previous files leave no more than a single global
95 symbol installed. When adapting the API for non-Emscripten
96 toolchains, this "should" be the only file where changes are needed.
97
98The build process glues those files together, resulting in
99`sqlite3-api.js`, which is everything except for the `post-js-*.js`
100files, and `sqlite3.js`, which is the Emscripten-generated amalgamated
101output and includes the `post-js-*.js` parts, as well as the
102Emscripten-provided module loading pieces.
103
104The non-JS outlier file is `sqlite3-wasm.c`: it is a proxy for
105`sqlite3.c` which `#include`'s that file and adds a couple more
106WASM-specific helper functions, at least one of which requires access
107to private/static `sqlite3.c` internals. `sqlite3.wasm` is compiled
108from this file rather than `sqlite3.c`.
109
110The following files are part of the build process but are injected
111into the build-generated `sqlite3.js` along with `sqlite3-api.js`.
112
113- `extern-pre-js.js`\
114 Emscripten-specific header for Emscripten's `--extern-pre-js`
115 flag. As of this writing, that file is only used for experimentation
116 purposes and holds no code relevant to the production deliverables.
117- `pre-js.js`\
118 Emscripten-specific header for Emscripten's `--pre-js` flag. This
119 file is intended as a place to override certain Emscripten behavior
120 before it starts up, but corner-case Emscripten bugs keep that from
121 being a reality.
122- `post-js-header.js`\
123 Emscripten-specific header for the `--post-js` input. It opens up
124 a lexical scope by starting a post-run handler for Emscripten.
125- `post-js-footer.js`\
126 Emscripten-specific footer for the `--post-js` input. This closes
127 off the lexical scope opened by `post-js-header.js`.
128- `extern-post-js.js`\
129 Emscripten-specific header for Emscripten's `--extern-post-js`
130 flag. This file overwrites the Emscripten-installed
131 `sqlite3InitModule()` function with one which, after the module is
132 loaded, also initializes the asynchronous parts of the sqlite3
133 module. For example, the OPFS VFS support.
134