@birchill/nice-sqlite-wasm 0.0.2 → 0.1.1

package/README.md

@@ -3,10 +3,11 @@
 This is a custom build of SQLite that only supports the "opfs-sahpool" VFS.
 It's "nice" because:
 
-- It remove the "opfs" VFS and worker parts of the JS bindings making for a
+- It removes the "opfs" VFS and worker parts of the JS bindings making for a
   smaller bundle size.
-- It allows passing in a custom path for the WASM module in order to support
-  cache-busting filenames / bundlers.
+- 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).
@@ -14,6 +15,9 @@ It's "nice" because:
 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
@@ -24,7 +28,116 @@ For the official SQLite WASM package see
 
 ## Usage
 
-TODO
+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](https://rspack.rs).
+
+### rspack
+
+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.
+
+### vite
+
+I'm not sure how to configure vite, but if you're only using it for testing
+(i.e. using [vitest](https://vitest.dev/)) then you can just disable
+optimization there as [explained in the official WASM
+module docs](https://github.com/sqlite/sqlite-wasm/#usage-with-vite):
+
+```js
+// vitest.config.js
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  optimizeDeps: { exclude: ['@birchill/nice-sqlite-wasm'] },
+});
+```
 
 ## Developing
 
@@ -85,6 +198,7 @@ Then update the table below.
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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<Response>`.                                               |
 
 ### Building the WASM module
 

package/dist/sqlite-rev.txt

@@ -0,0 +1 @@
+ba76c160c735437de974c6ea24c890a663214c6b

package/dist/sqlite3.d.ts

@@ -2241,7 +2241,10 @@ declare type Sqlite3Static = {
 };
 
 declare type InitOptions = {
-  locateFile?: (path: string, prefix: string) => string;
+  locateFile?: (
+    path: string,
+    prefix: string,
+  ) => string | Response | Promise<Response>;
   print?: (msg: string) => void;
   printErr?: (msg: string) => void;
 };

package/dist/sqlite3.js

@@ -26,11 +26,11 @@
 /*
  ** This code was built from sqlite3 version...
  **
- ** SQLITE_VERSION "3.51.1"
- ** SQLITE_VERSION_NUMBER 3051001
- ** SQLITE_SOURCE_ID "2025-11-28 17:28:25 281fc0e9afc38674b9b0991943b9e9d1e64c6cbdb133d35f6f5c87ff6af3alt1"
+ ** SQLITE_VERSION "3.51.2"
+ ** SQLITE_VERSION_NUMBER 3051002
+ ** SQLITE_SOURCE_ID "2026-01-09 17:27:48 b270f8339eb13b504d0b2ba154ebca966b7dde08e40c3ed7d559749818cbalt1"
  **
- ** Emscripten SDK: 4.0.23
+ ** Emscripten SDK: 5.0.0
  **
  */
 
@@ -73,7 +73,10 @@ async function sqlite3InitModule(moduleArg = {}) {
         'undefined' === typeof scriptDirectory ? '' : scriptDirectory
       );
       sims.debugModule('instantiateWasm() uri =', uri, 'sIMS =', this);
-      const wfetch = () => fetch(uri, { credentials: 'same-origin' });
+      const response =
+        uri instanceof Response || uri instanceof Promise
+          ? uri
+          : fetch(uri, { credentials: 'same-origin' });
       const finalThen = (arg) => {
         arg.imports = imports;
         sims.instantiateWasm = arg;
@@ -81,9 +84,9 @@ async function sqlite3InitModule(moduleArg = {}) {
       };
       const loadWasm = WebAssembly.instantiateStreaming
         ? async () =>
-            WebAssembly.instantiateStreaming(wfetch(), imports).then(finalThen)
+            WebAssembly.instantiateStreaming(response, imports).then(finalThen)
         : async () =>
-            wfetch()
+            Promise.resolve(response)
               .then((response) => response.arrayBuffer())
               .then((bytes) => WebAssembly.instantiate(bytes, imports))
               .then(finalThen);
@@ -9716,17 +9719,17 @@ async function sqlite3InitModule(moduleArg = {}) {
     });
     globalThis.sqlite3ApiBootstrap.initializers.push(function (sqlite3) {
       sqlite3.version = {
-        libVersion: '3.51.1',
-        libVersionNumber: 3051001,
+        libVersion: '3.51.2',
+        libVersionNumber: 3051002,
         sourceId:
-          '2025-11-28 17:28:25 281fc0e9afc38674b9b0991943b9e9d1e64c6cbdb133d35f6f5c87ff6af3alt1',
-        downloadVersion: 3510100,
+          '2026-01-09 17:27:48 b270f8339eb13b504d0b2ba154ebca966b7dde08e40c3ed7d559749818cbalt1',
+        downloadVersion: 3510200,
         scm: {
           'sha3-256':
-            '281fc0e9afc38674b9b0991943b9e9d1e64c6cbdb133d35f6f5c87ff6af3alt1',
+            'b270f8339eb13b504d0b2ba154ebca966b7dde08e40c3ed7d559749818cbalt1',
           branch: 'branch-3.51',
-          tags: 'release version-3.51.1',
-          datetime: '2025-11-28T17:28:25.933Z',
+          tags: 'release version-3.51.2',
+          datetime: '2026-01-09T17:27:48.405Z',
         },
       };
     });
@@ -10261,11 +10264,11 @@ async function sqlite3InitModule(moduleArg = {}) {
               stmt = null;
             }
           } finally {
-            wasm.scopedAllocPop(stack);
             if (stmt) {
               __execLock.delete(stmt);
               stmt.finalize();
             }
+            wasm.scopedAllocPop(stack);
           }
           return arg.returnVal();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birchill/nice-sqlite-wasm",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "private": false,
   "repository": {
     "type": "git",
@@ -23,5 +23,5 @@
   "publishConfig": {
     "provenance": true
   },
-  "publishedAt": "2026-01-14T04:43:12.688Z"
+  "publishedAt": "2026-01-26T07:39:51.875Z"
 }