feat: add omit-api bundler variants

Author: jurerotar

README.md

@@ -169,6 +169,22 @@ this package.
 
 2. Run the build:
 
+   The Docker build writes the full upstream npm bundle to `src/bin`. During `npm run build`, the
+   `split:bundler` prebuild step splits `sqlite3-bundler-friendly.mjs` into one shared core module
+   and small optional initializer modules. The `/bundler` package subpaths all omit the deprecated
+   Worker1 API and share the same generated core chunk:
+
+   - `@sqlite.org/sqlite-wasm/bundler/core`: core runtime only
+   - `@sqlite.org/sqlite-wasm/bundler/vtab`: core plus virtual table helpers
+   - `@sqlite.org/sqlite-wasm/bundler/kvvfs`: core plus kvvfs
+   - `@sqlite.org/sqlite-wasm/bundler/opfs`: core plus OPFS
+   - `@sqlite.org/sqlite-wasm/bundler/opfs-wl`: core plus OPFS WebLocks
+   - `@sqlite.org/sqlite-wasm/bundler/sah-pool`: core plus OPFS SAH Pool
+
+   The split files are generated in `src/bin` from the upstream bundler-friendly artifact and are
+   built into `dist/bundler/*` plus shared chunks. The default package entry remains the full
+   backwards-compatible bundle.
+
    **Unix (Linux/macOS):**
 
    ```bash

package.json

@@ -39,7 +39,13 @@
       "browser": "./dist/index.mjs"
     },
     "./package.json": "./package.json",
-    "./sqlite3.wasm": "./dist/sqlite3.wasm"
+    "./sqlite3.wasm": "./dist/sqlite3.wasm",
+    "./bundler/core": "./dist/bundler/core.mjs",
+    "./bundler/vtab": "./dist/bundler/vtab.mjs",
+    "./bundler/kvvfs": "./dist/bundler/kvvfs.mjs",
+    "./bundler/opfs": "./dist/bundler/opfs.mjs",
+    "./bundler/opfs-wl": "./dist/bundler/opfs-wl.mjs",
+    "./bundler/sah-pool": "./dist/bundler/sah-pool.mjs"
   },
   "workspaces": [
     "demos/*"
@@ -49,6 +55,8 @@
     "README.md"
   ],
   "scripts": {
+    "split:bundler": "node scripts/split-bundler-friendly-apis.mjs",
+    "prebuild": "npm run split:bundler",
     "test": "vitest",
     "test:node": "vitest --project node",
     "test:browser": "vitest --project browser",

scripts/split-bundler-friendly-apis.mjs

@@ -0,0 +1,128 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const sourcePath = path.join(rootDir, 'src/bin/sqlite3-bundler-friendly.mjs');
+const outputDir = path.join(rootDir, 'src/bin');
+
+const generatedHeader = (sourceFile) =>
+  `// Generated by scripts/split-bundler-friendly-apis.mjs from ${sourceFile}.\n// Do not edit this file directly.\n\n`;
+
+const initRegistry = `const sqlite3BundlerFriendlyOptionalState =\n  (globalThis.__sqlite3BundlerFriendlyOptional ??= {\n    initializers: Object.create(null),\n    initializersAsync: Object.create(null),\n  });\n\nconst sqlite3BundlerFriendlyRegisterOptionalInitializer = (slot, initializer) => {\n  if (globalThis.sqlite3ApiBootstrap?.initializers) {\n    globalThis.sqlite3ApiBootstrap.initializers.push(initializer);\n  } else {\n    (sqlite3BundlerFriendlyOptionalState.initializers[slot] ??= []).push(initializer);\n  }\n};\n\nconst sqlite3BundlerFriendlyRegisterOptionalAsyncInitializer = (slot, initializer) => {\n  if (globalThis.sqlite3ApiBootstrap?.initializersAsync) {\n    globalThis.sqlite3ApiBootstrap.initializersAsync.push(initializer);\n  } else {\n    (sqlite3BundlerFriendlyOptionalState.initializersAsync[slot] ??= []).push(initializer);\n  }\n};\n\n`;
+
+const baseHook = `const sqlite3BundlerFriendlyInstallOptionalInitializers = (slot) => {\n  const optionalState = globalThis.__sqlite3BundlerFriendlyOptional;\n  const initializers = optionalState?.initializers?.[slot];\n  if (initializers?.length) {\n    globalThis.sqlite3ApiBootstrap.initializers.push(...initializers);\n  }\n  const initializersAsync = optionalState?.initializersAsync?.[slot];\n  if (initializersAsync?.length) {\n    globalThis.sqlite3ApiBootstrap.initializersAsync.push(...initializersAsync);\n  }\n};\n\n`;
+
+const markerSpecs = {
+  worker1: 'This file implements the initializer for SQLite\'s "Worker API #1"',
+  helper: 'This file installs sqlite3.vfs, a namespace of helpers',
+  vtab: 'This file installs sqlite3.vtab, a namespace of helpers',
+  kvvfs: 'This file houses the "kvvfs" pieces of the SQLite3 JS API',
+  opfsShared: 'This file holds code shared by sqlite3-vfs-opfs{,-wl}.c-pp.js',
+  opfs: 'This file holds the synchronous half of an sqlite3_vfs',
+  sahpool: 'This file holds a sqlite3_vfs backed by OPFS storage',
+  opfsWl: 'This file is a reimplementation of the "opfs" VFS',
+  tail: 'This file is the tail end of the sqlite3-api.js constellation',
+};
+
+const findCommentStart = (source, marker) => {
+  const markerIndex = source.indexOf(marker);
+  if (markerIndex < 0) {
+    throw new Error(`Unable to find marker: ${marker}`);
+  }
+  const commentStart = source.lastIndexOf('/*', markerIndex);
+  if (commentStart < 0) {
+    throw new Error(`Unable to find comment start for marker: ${marker}`);
+  }
+  return commentStart;
+};
+
+const replaceAll = (value, replacements) => {
+  let result = value;
+  for (const [from, to] of replacements) {
+    result = result.split(from).join(to);
+  }
+  return result;
+};
+
+const source = await readFile(sourcePath, 'utf8');
+const markers = Object.fromEntries(
+  Object.entries(markerSpecs).map(([name, marker]) => [name, findCommentStart(source, marker)]),
+);
+
+const ranges = {
+  worker1: [markers.worker1, markers.helper],
+  helper: [markers.helper, markers.vtab],
+  vtab: [markers.vtab, markers.kvvfs],
+  kvvfs: [markers.kvvfs, markers.opfsShared],
+  opfsShared: [markers.opfsShared, markers.opfs],
+  opfs: [markers.opfs, markers.sahpool],
+  sahpool: [markers.sahpool, markers.opfsWl],
+  opfsWl: [markers.opfsWl, markers.tail],
+};
+
+for (const [name, [start, end]] of Object.entries(ranges)) {
+  if (start >= end) {
+    throw new Error(`Invalid ${name} range: ${start} >= ${end}`);
+  }
+}
+
+const bootstrapAsyncMarker = 'globalThis.sqlite3ApiBootstrap.initializersAsync = [];\n';
+if (!source.includes(bootstrapAsyncMarker)) {
+  throw new Error(`Unable to find bootstrap hook marker: ${bootstrapAsyncMarker.trim()}`);
+}
+
+const strippedSource = Object.entries(ranges)
+  .sort((a, b) => b[1][0] - a[1][0])
+  .reduce(
+    (current, [name, [start, end]]) =>
+      current.slice(0, start) +
+      `\n/* Optional initializer slot removed by scripts/split-bundler-friendly-apis.mjs: ${name} */\n` +
+      `sqlite3BundlerFriendlyInstallOptionalInitializers('${name}');\n` +
+      current.slice(end),
+    source,
+  )
+  .replace(bootstrapAsyncMarker, bootstrapAsyncMarker + baseHook);
+
+const outputFileNames = {
+  worker1: 'sqlite3-bundler-optional-worker1.mjs',
+  helper: 'sqlite3-bundler-optional-vfs-helper.mjs',
+  vtab: 'sqlite3-bundler-optional-vtab.mjs',
+  kvvfs: 'sqlite3-bundler-optional-kvvfs.mjs',
+  opfsShared: 'sqlite3-bundler-optional-opfs-shared.mjs',
+  opfs: 'sqlite3-bundler-optional-opfs.mjs',
+  sahpool: 'sqlite3-bundler-optional-sah-pool.mjs',
+  opfsWl: 'sqlite3-bundler-optional-opfs-wl.mjs',
+};
+
+const toOptionalModule = (slot, chunk) =>
+  generatedHeader('sqlite3-bundler-friendly.mjs') +
+  initRegistry +
+  replaceAll(chunk, [
+    [
+      'globalThis.sqlite3ApiBootstrap.initializers.push(',
+      `sqlite3BundlerFriendlyRegisterOptionalInitializer('${slot}', `,
+    ],
+    [
+      'globalThis.sqlite3ApiBootstrap.initializersAsync.push(',
+      `sqlite3BundlerFriendlyRegisterOptionalAsyncInitializer('${slot}', `,
+    ],
+  ]);
+
+await mkdir(outputDir, { recursive: true });
+
+await writeFile(
+  path.join(outputDir, 'sqlite3-bundler-friendly.core.mjs'),
+  generatedHeader('sqlite3-bundler-friendly.mjs') + strippedSource,
+);
+
+await Promise.all(
+  Object.entries(ranges)
+    .filter(([name]) => name !== 'worker1')
+    .map(([name, [start, end]]) =>
+      writeFile(
+        path.join(outputDir, outputFileNames[name]),
+        toOptionalModule(name, source.slice(start, end)),
+      ),
+    ),
+);