@birchill/nice-sqlite-wasm

This is a custom build of SQLite that only supports the "opfs-sahpool" VFS.
It's "nice" because:

- It removes the "opfs" VFS and worker parts of the JS bindings making for a
smaller bundle size.
- It allows overriding the locateFile function so that you can provide a
custom path for the WASM module (e.g. in order to support cache-busting
filenames) or even a Response object (e.g. so you can abort the download).
- It fixes some warnings that otherwise might occur at build or run-time
(e.g. the COOP/COEP header warning which is only relevant to the "opfs" VFS
and a warning about dependencies based on expressions).

In general, it should be nicer for apps using bundlers that only need the
"opfs-sahpool" VFS.

As an extra bonus, the whole build (including building the WASM module) is done
in CI and published to npm with provenance data so you get full traceability.

> [!NOTE]
> The JS/WASM part of SQLite is under heavy development and is expected to
> change a lot in future (e.g. using WASI instead of Emscripten). As a result
> this project may no longer be necessary or may become impractical to update.

For the official SQLite WASM package see
sqlite-wasm.

Usage

Install:

``
npm install @birchill/nice-sqlite-wasm
`

You _could_ probably just do an import sqlite3InitModule from
'@birchill/nice-sqlite-wasm' and be done with it but the whole point of this
module is to allow you to set it up for better caching and pre-loading.
How you do that will depend on your bundler.

Following is an example for rspack.

$3

First, we set up a way to generated the name of the WASM module so we can pass
it to sqlite3InitModule.

In your rspack.config.js:

`js
export default defineConfig((env) => {
// ...
module: {
rules: [
{ resourceQuery: /url$/, type: 'asset/resource' },
],
},
});
`

Second, we set up rspack to produce the desired output filename for the asset,
otherwise you'll get something like [hash].wasm which isn't very helpful.

Furthermore, we want to drop the query string we enabled above.

`js
export default defineConfig((env) => {
// ...
output: {
assetModuleFilename: (fileInfo) => {
// Generate a cacheable but readable filename for WASM files
if (
fileInfo.filename.endsWith('.wasm') ||
fileInfo.filename.endsWith('.wasm?url')
) {
return '[name].[hash].wasm';
}
return '[hash][ext][query]';
},
},
});
`

Then in your worker code:

`js
import wasmUrl from '@birchill/nice-sqlite-wasm/sqlite3.wasm?url';
import sqlite3InitModule from '@birchill/nice-sqlite-wasm';
`

Then when you initialize SQLite:

`js
const sqlite = await sqlite3InitModule({
// Override SQLite's locateFile implementation which wants to resolve
// the SQLite WASM binary relative to the source directory instead of
// the asset name assigned by rspack.
locateFile: (file) => {
if (file === 'sqlite3.wasm') {
// Since we strip the query string in our assetModuleFilename
// option in rspack.config.js we don't need to worry about dropping
// it here.
//
// If we were to stop doing that, however, we'd need to do
// something like:
//
// return new URL(wasmUrl, self.location.href).pathname;
//
// instead.
return fetch(wasmUrl, {
credentials: 'same-origin',
// If you want to make the fetch abortable...
signal: abortController.signal,
});
} else {
throw new Error(Unknown file: ${file});
}
},
});
`

You can also just return wasmUrl from locateFile if don't need to control
the fetch yourself.

$3

I'm not sure how to configure vite, but if you're only using it for testing
(i.e. using vitest) then you can just disable
optimization there as explained in the official WASM
module docs:

`js
// vitest.config.js
import { defineConfig } from 'vite';

export default defineConfig({
optimizeDeps: { exclude: ['@birchill/nice-sqlite-wasm'] },
});
`

Developing

$3

`
pnpm install
`

This will install some tools we use like
oxfmt.

$3

Ensure sqlite-revision.txt contains the desired SQLite version (e.g.
version-3.51.1 or any tag from the
SQLite git repository).

Then run:

`
pnpm run fetch
`

$3

`
pnpm run patch
`

#### Creating new patches

First fetch the source then apply any
existing patches.

Then go to work/sqlite-src, make edits and run
git diff > ../../patches/patch-name.patch.

Something like:

`
pnpm run fetch
pnpm run patch
cd work/sqlite-src
git commit -am "Existing patches"
vim ext/wasm/api/pre-js.c-pp.js # For example
git diff > ../../patches/000x-patch-description.patch
git stash
cd ../..
git add patches/000x-patch-description.patch
`

Then update the table below.

#### Current patches

| Patch name | Purpose |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 0001-locatefile-nullish-coalesce.patch | Allow a user-provided locateFile function to be used (rather than clobbered). |
| 0002-hardcode-locatefile-path.patch | Hardcodes the path used in the default locateFile implementation so that bundlers don't complain about dependencies based on expressions. |
| 0003-locatefile-with-response.patch | Allows a user-provided locateFile function to return a Response or a Promise. |

$3

#### Getting Emscripten

First you need to install
Emscripten.

`
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh # Or source ./emsdk_env.fish etc.
`

Note that you need to run the emsdk_env.* script every time so you might want
to add something to your shell's startup script.

e.g. for fish

`fish
if test -e ~/emsdk/emsdk_env.fish
EMSDK_QUIET=1 source ~/emsdk/emsdk_env.fish
end
`

#### Getting wasm-strip (from wabt)

Then you need to install
wabt for to make
wasm-strip available.

Critically, this must be version 1.0.36 or higher or else wasm-strip will fail
on the 64-bit build with "tables may not be 64-bit". We don't actually need the
64-bit build but there's no way to turn it off easily.

As of this writing, using sudo apt install wabt gives you version 1.0.34 which
is not high enough.

Instead you probably want to download the latest release from
https://github.com/WebAssembly/wabt/releases:

`
wget https://github.com/WebAssembly/wabt/releases/download/1.0.39/wabt-1.0.39-linux-x64.tar.gz
tar -xzf wabt-1.0.39-linux-x64.tar.gz
sudo mv ~/wabt-1.0.39 /usr/local/wabt-1.0.39
sudo ln -s /usr/local/wabt-1.0.39 /usr/local/wabt
sudo ln -s /usr/local/wabt/bin/* /usr/local/bin/
`

(or brew install wabt on macOS)

#### Actually building

Then run:

`
pnpm build
`

$3

After making changes, to update the changelog run:

`
pnpm changeset
`

Don't forget to add the changeset file created in /.changeset` to the commit.