feat: add omit-api bundler variants

Author: jurerotar

README.md

@@ -169,6 +169,34 @@ this package.
 
 2. Run the build:
 
+   By default, this builds the full upstream npm bundle plus these omit-API variants. All variants
+   omit the deprecated Worker1 API:
+
+   - `core`: `omit-api="kvvfs OPFS vtab worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/core`
+   - `core-vtab`: `omit-api="kvvfs OPFS worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/vtab`
+   - `core-kvvfs`: `omit-api="OPFS vtab worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/kvvfs`
+   - `core-opfs`: `omit-api="kvvfs opfs-wl opfs-sahpool vtab worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/opfs`
+   - `core-opfs-wl`: `omit-api="kvvfs opfs opfs-sahpool vtab worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/opfs-wl`
+   - `core-opfs-sahpool`: `omit-api="kvvfs opfs opfs-wl vtab worker1"`, exported as
+     `@sqlite.org/sqlite-wasm/bundler/sah-pool`
+
+   To customize the generated variants, set `SQLITE_WASM_OMIT_API_BUILDS` to a semicolon-separated
+   list of `name=api api` entries. Set it to an empty string to build only the full bundle. Custom
+   variants are written to `src/bin`; add them to `tsdown.config.ts` and `package.json` if they
+   should be published as package subpaths.
+
+   Only bundler-friendly JavaScript artifacts are kept for generated variants. They are written to
+   `src/bin` with their variant name in the filename, for example
+   `sqlite3-core-bundler-friendly.mjs`, and load the default `sqlite3.wasm` from the full npm bundle
+   build. The package build emits optimized copies into `dist` and exports the fixed variants under
+   the `/bundler` package subpaths shown above. If the selected SQLite ref does not support
+   `omit-api`, set `SQLITE_WASM_OMIT_API_BUILDS` to an empty string to build only the full 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/sqlite3-core-bundler-friendly.mjs",
+    "./bundler/vtab": "./dist/sqlite3-core-vtab-bundler-friendly.mjs",
+    "./bundler/kvvfs": "./dist/sqlite3-core-kvvfs-bundler-friendly.mjs",
+    "./bundler/opfs": "./dist/sqlite3-core-opfs-bundler-friendly.mjs",
+    "./bundler/opfs-wl": "./dist/sqlite3-core-opfs-wl-bundler-friendly.mjs",
+    "./bundler/sah-pool": "./dist/sqlite3-core-opfs-sahpool-bundler-friendly.mjs"
   },
   "workspaces": [
     "demos/*"

scripts/build-sqlite3-wasm.sh

@@ -7,6 +7,13 @@ OUT_DIR="${OUT_DIR:-/out}"
 SRC_DIR="${WORKDIR:-/build/sqlite-src}"
 HOST_UID="${HOST_UID:-}"
 HOST_GID="${HOST_GID:-}"
+DEFAULT_OMIT_API_BUILDS="core=kvvfs OPFS vtab worker1;core-vtab=kvvfs OPFS worker1;core-kvvfs=OPFS vtab worker1;core-opfs=kvvfs opfs-wl opfs-sahpool vtab worker1;core-opfs-wl=kvvfs opfs opfs-sahpool vtab worker1;core-opfs-sahpool=kvvfs opfs opfs-wl vtab worker1"
+
+if [ "${SQLITE_WASM_OMIT_API_BUILDS+x}" = "x" ]; then
+  OMIT_API_BUILDS="$SQLITE_WASM_OMIT_API_BUILDS"
+elif [ "${OMIT_API_BUILDS+x}" != "x" ]; then
+  OMIT_API_BUILDS="$DEFAULT_OMIT_API_BUILDS"
+fi
 
 # Ensure out exists and is writable
 mkdir -p "$OUT_DIR"
@@ -34,6 +41,84 @@ check_mounts() {
 # Helper: log
 log() { printf '\033[1;34m[build]\033[0m %s\n' "$*"; }
 
+trim() {
+  local value="$*"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  printf '%s' "$value"
+}
+
+extract_npm_bundle() {
+  local zip_file="$1"
+  local target_dir="$2"
+
+  mkdir -p "$target_dir"
+  find "$target_dir" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
+  unzip -q -o "$zip_file" -d "$target_dir"
+
+  shopt -s nullglob
+  local entries=("$target_dir"/*)
+  if [ "${#entries[@]}" -eq 1 ] && [ -d "${entries[0]}" ]; then
+    log "Zip contained top-level dir: moving contents up"
+    mv "${entries[0]}"/* "$target_dir"/ || true
+    rmdir "${entries[0]}" || true
+  fi
+  shopt -u nullglob
+}
+
+copy_if_exists() {
+  local source_file="$1"
+  local target_file="$2"
+
+  if [ -f "$source_file" ]; then
+    cp -f "$source_file" "$target_file"
+  fi
+}
+
+install_variant_artifacts() {
+  local variant="$1"
+  local extracted_dir="$2"
+
+  log "Installing bundler-friendly variant artifacts for: $variant"
+  copy_if_exists "$extracted_dir/sqlite3-bundler-friendly.mjs" "/src/bin/sqlite3-${variant}-bundler-friendly.mjs"
+}
+
+create_variant_zip() {
+  local variant="$1"
+  local zip_file="$2"
+  local staging_dir="/tmp/sqlite-wasm-variant-${variant}"
+
+  rm -rf "$staging_dir"
+  mkdir -p "$staging_dir"
+  cp -f "/src/bin/sqlite3-${variant}-bundler-friendly.mjs" "$staging_dir/"
+
+  rm -f "$zip_file"
+  (cd "$staging_dir" && zip -q -r "$zip_file" .)
+  chmod a+r "$zip_file"
+}
+
+build_npm_bundle() {
+  local label="$1"
+  local omit_apis="$2"
+
+  log "Running make clean for $label"
+  make clean >/dev/null 2>&1 || true
+  rm -f npm-bundle.zip
+
+  if [ -n "$omit_apis" ]; then
+    log "Running make -j4 npm omit-api=\"$omit_apis\" (ext/wasm)"
+    make -j4 npm omit-api="$omit_apis"
+  else
+    log "Running make -j4 npm (ext/wasm)"
+    make -j4 npm
+  fi
+
+  if [ ! -f npm-bundle.zip ]; then
+    log "ERROR: npm-bundle.zip not found in ext/wasm"
+    exit 3
+  fi
+}
+
 # Handle ownership fixup on exit
 cleanup() {
   if [ -n "$HOST_UID" ] && [ -n "$HOST_GID" ]; then
@@ -58,6 +143,7 @@ log "Repo: $SQLITE_REPO"
 log "Ref:  $SQLITE_REF"
 log "Out: $OUT_DIR"
 log "Src dir: $SRC_DIR"
+log "Omit API builds: ${OMIT_API_BUILDS:-<none>}"
 
 # prepare source dir: clone shallow or fetch+reset if exists
 if [ -d "$SRC_DIR/.git" ]; then
@@ -106,37 +192,54 @@ make sqlite3.c
 
 cd ext/wasm
 
-log "Running make -j4 npm (ext/wasm)"
-make -j4 npm
-
-# ensure artifact exists
-if [ ! -f npm-bundle.zip ]; then
-  log "ERROR: npm-bundle.zip not found in ext/wasm"
-  exit 3
+if [ -n "${OMIT_API_BUILDS:-}" ] && ! grep -q 'omit-api' GNUmakefile; then
+  log "ERROR: omit API builds were requested, but this SQLite ref does not support omit-api."
+  log "Set SQLITE_WASM_OMIT_API_BUILDS= to build only the full bundle, or use a SQLite ref with omit-api support."
+  exit 5
 fi
 
-# copy zip into OUT_DIR
+build_npm_bundle "full" ""
+
+# copy zip into OUT_DIR and extract the full build into /src/bin
 log "Copying npm-bundle.zip to $OUT_DIR"
 cp -f npm-bundle.zip "$OUT_DIR/npm-bundle.zip"
 chmod a+r "$OUT_DIR/npm-bundle.zip"
 
 # extract into /src/bin (normalize single top-level dir)
 log "Extracting npm-bundle.zip into /src/bin"
-# Clear existing contents to ensure a clean overwrite
-rm -rf /src/bin/*
-mkdir -p /src/bin
-unzip -q -o "$OUT_DIR/npm-bundle.zip" -d /src/bin
-rm -f "$OUT_DIR/npm-bundle.zip"
-
-# If a single top-level directory exists, move its contents up
-shopt -s nullglob
-entries=(/src/bin/*)
-if [ "${#entries[@]}" -eq 1 ] && [ -d "${entries[0]}" ]; then
-  log "Zip contained top-level dir: moving contents up"
-  mv "${entries[0]}"/* /src/bin/ || true
-  rmdir "${entries[0]}" || true
+extract_npm_bundle "$OUT_DIR/npm-bundle.zip" /src/bin
+
+if [ -n "${OMIT_API_BUILDS:-}" ]; then
+  IFS=';' read -r -a omit_build_specs <<< "$OMIT_API_BUILDS"
+  for spec in "${omit_build_specs[@]}"; do
+    spec="$(trim "$spec")"
+    if [ -z "$spec" ]; then
+      continue
+    fi
+
+    if [[ "$spec" != *=* ]]; then
+      log "ERROR: invalid omit API build spec '$spec'. Expected name=api api."
+      exit 4
+    fi
+
+    variant="$(trim "${spec%%=*}")"
+    omit_apis="$(trim "${spec#*=}")"
+    if [[ ! "$variant" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+      log "ERROR: invalid variant name '$variant'. Use lowercase letters, numbers, and hyphens."
+      exit 4
+    fi
+
+    build_npm_bundle "$variant" "$omit_apis"
+
+    variant_zip="$OUT_DIR/npm-bundle-${variant}.zip"
+    variant_dir="/tmp/sqlite-wasm-npm-${variant}"
+    log "Extracting variant bundle for artifact renaming"
+    extract_npm_bundle npm-bundle.zip "$variant_dir"
+    install_variant_artifacts "$variant" "$variant_dir"
+    log "Writing bundler-friendly variant bundle to $variant_zip"
+    create_variant_zip "$variant" "$variant_zip"
+  done
 fi
-shopt -u nullglob
 
 log "Build complete. Extracted contents are in /src/bin"
 exec /bin/ls -la /src/bin

src/bin/sqlite3-bundler-friendly.mjs

@@ -29,7 +29,7 @@
 **
 ** SQLITE_VERSION "3.53.4"
 ** SQLITE_VERSION_NUMBER 3053004
-** SQLITE_SOURCE_ID "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e09459bcc"
+** SQLITE_SOURCE_ID "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e0945alt1"
 **
 ** Emscripten SDK: 5.0.5
 */
@@ -4733,7 +4733,7 @@ Module.runSQLite3PostLoadInit = async function(
 **
 ** SQLITE_VERSION "3.53.4"
 ** SQLITE_VERSION_NUMBER 3053004
-** SQLITE_SOURCE_ID "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e09459bcc"
+** SQLITE_SOURCE_ID "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e0945alt1"
 **
 ** Emscripten SDK: 5.0.5
 */
@@ -6978,7 +6978,7 @@ globalThis.sqlite3ApiBootstrap.defaultConfig = Object.create(null);
 */
 globalThis.sqlite3ApiBootstrap.sqlite3 = undefined;
 globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
-  sqlite3.version = {"libVersion": "3.53.4", "libVersionNumber": 3053004, "sourceId": "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e09459bcc","downloadVersion": 3530400,"scm":{ "sha3-256": "bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e09459bcc","branch": "branch-3.53","tags": "release version-3.53.4","datetime": "2026-07-24T19:02:57.525Z"}};
+  sqlite3.version = {"libVersion": "3.53.4", "libVersionNumber": 3053004, "sourceId": "2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e0945alt1","downloadVersion": 3530400,"scm":{ "sha3-256": "bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e0945alt1","branch": "branch-3.53","tags": "release version-3.53.4","datetime": "2026-07-24T19:02:57.525Z"}};
 });
 /**
   2022-07-08
@@ -19565,6 +19565,9 @@ globalThis.sqlite3ApiBootstrap.initializersAsync.push(async (sqlite3)=>{
   - Also because of that, it does not require the SharedArrayBuffer,
   so can function without the COOP/COEP HTTP response headers.
 
+  - Also because of that, this one is much faster and the performance
+  gap increases as the job sizes increase.
+
   - It can hypothetically support Safari 16.4+, whereas the "opfs" VFS
   requires v17 due to a subworker/storage bug in 16.x which makes it
   incompatible with that VFS.