chore: added worker1Promiser deprecation notices

README.md

@@ -2,6 +2,12 @@
 
 SQLite Wasm conveniently wrapped as an ES Module.
 
+## Installation
+
+```bash
+npm install @sqlite.org/sqlite-wasm
+```
+
 ## Bug reports
 
 > [!Warning]
@@ -21,73 +27,16 @@ SQLite Wasm conveniently wrapped as an ES Module.
 > Node.js is currently only supported for in-memory databases without
 > persistence.
 
-## Installation
-
-```bash
-npm install @sqlite.org/sqlite-wasm
-```
-
 ## Usage
 
-There are three ways to use SQLite Wasm:
+There are two ways to use SQLite Wasm:
 
-- [in the main thread with a wrapped worker](#in-a-wrapped-worker-with-opfs-if-available)
-  (🏆 preferred option)
 - [in a worker](#in-a-worker-with-opfs-if-available)
 - [in the main thread](#in-the-main-thread-without-opfs)
 
 Only the worker versions allow you to use the origin private file system (OPFS)
 storage back-end.
 
-### In a wrapped worker (with OPFS if available):
-
-> [!Warning]
->
-> For this to work, you need to set the following headers on your server:
->
-> `Cross-Origin-Opener-Policy: same-origin`
->
-> `Cross-Origin-Embedder-Policy: require-corp`
-
-```ts
-import {
-  sqlite3Worker1Promiser,
-  type Worker1Promiser,
-} from '@sqlite.org/sqlite-wasm';
-
-const initializeSQLite = async () => {
-  try {
-    const promiser = await sqlite3Worker1Promiser.v2();
-
-    const configResponse = await promiser('config-get', {});
-
-    console.log(
-      'Running SQLite3 version',
-      configResponse.result.version.libVersion,
-    );
-
-    const openResponse = await promiser('open', {
-      filename: 'file:mydb-v2.sqlite3?vfs=opfs',
-    });
-
-    console.log(
-      'OPFS is available, created persisted database at',
-      openResponse.result.filename.replace(/^file:(.*?)\?vfs=opfs$/, '$1'),
-    );
-  } catch (err: any) {
-    if (!(err instanceof Error)) {
-      err = new Error(err.result.message || 'Unknown error');
-    }
-    console.error(err.name, err.message);
-  }
-};
-
-await initializeSQLite();
-```
-
-The `promiser` object above implements the
-[Worker1 API](https://sqlite.org/wasm/doc/trunk/api-worker1.md#worker1-methods).
-
 ### In a worker (with OPFS if available):
 
 > [!Warning]
@@ -107,16 +56,13 @@ const worker = new Worker('worker.js', { type: 'module' });
 // In `worker.js`.
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 
-const log = console.log;
-const error = console.error;
-
 const start = (sqlite3) => {
-  log('Running SQLite3 version', sqlite3.version.libVersion);
+  console.log('Running SQLite3 version', sqlite3.version.libVersion);
   const db =
     'opfs' in sqlite3
       ? new sqlite3.oo1.OpfsDb('/mydb.sqlite3')
       : new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
-  log(
+  console.log(
     'opfs' in sqlite3
       ? `OPFS is available, created persisted database at ${db.filename}`
       : `OPFS is not available, created transient database ${db.filename}`,
@@ -126,51 +72,47 @@ const start = (sqlite3) => {
 
 const initializeSQLite = async () => {
   try {
-    log('Loading and initializing SQLite3 module...');
+    console.log('Loading and initializing SQLite3 module...');
     const sqlite3 = await sqlite3InitModule();
-    log('Done initializing. Running demo...');
+    console.log('Done initializing. Running demo...');
     start(sqlite3);
   } catch (err) {
-    error('Initialization error:', err.name, err.message);
+    console.error('Initialization error:', err.name, err.message);
   }
 };
 
 initializeSQLite();
 ```
 
 The `db` object above implements the
-[Object Oriented API #1](https://sqlite.org/wasm/doc/trunk/api-oo1.md).
+[Object-Oriented API #1](https://sqlite.org/wasm/doc/trunk/api-oo1.md).
 
 ### In the main thread (without OPFS):
 
 ```js
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 
-const log = console.log;
-const error = console.error;
-
 const start = (sqlite3) => {
   log('Running SQLite3 version', sqlite3.version.libVersion);
   const db = new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
   // Your SQLite code here.
 };
-
 const initializeSQLite = async () => {
   try {
-    log('Loading and initializing SQLite3 module...');
+    console.log('Loading and initializing SQLite3 module...');
     const sqlite3 = await sqlite3InitModule();
-    log('Done initializing. Running demo...');
+    console.log('Done initializing. Running demo...');
     start(sqlite3);
   } catch (err) {
-    error('Initialization error:', err.name, err.message);
+    console.error('Initialization error:', err.name, err.message);
   }
 };
 
 initializeSQLite();
 ```
 
 The `db` object above implements the
-[Object Oriented API #1](https://sqlite.org/wasm/doc/trunk/api-oo1.md).
+[Object-Oriented API #1](https://sqlite.org/wasm/doc/trunk/api-oo1.md).
 
 ## Usage with vite
 
@@ -228,67 +170,75 @@ for this package.
 
 ## Building the SQLite Wasm locally
 
-1.  Build the Docker image:
+1. Build the Docker image:
 
-    ```bash
-    docker build -t sqlite-wasm-builder:env .
-    ```
+   ```bash
+   docker build -t sqlite-wasm-builder:env .
+   ```
 
-2.  Run the build:
+2. Run the build:
 
-    **Unix (Linux/macOS):**
+   **Unix (Linux/macOS):**
 
-    ```bash
-    docker run --rm \
-      -e SQLITE_REF="master" \
-      -v "$(pwd)/out":/out \
-      -v "$(pwd)/src/bin":/src/bin \
-      sqlite-wasm-builder:env build
-    ```
+   ```bash
+   docker run --rm \
+     -e SQLITE_REF="master" \
+     -v "$(pwd)/out":/out \
+     -v "$(pwd)/src/bin":/src/bin \
+     sqlite-wasm-builder:env build
+   ```
 
-    **Windows (PowerShell):**
+   **Windows (PowerShell):**
 
-    ```powershell
-    docker run --rm `
-      -e SQLITE_REF="master" `
-      -v "${PWD}/out:/out" `
-      -v "${PWD}/src/bin:/src/bin" `
-      sqlite-wasm-builder:env build
-    ```
+   ```powershell
+   docker run --rm `
+     -e SQLITE_REF="master" `
+     -v "${PWD}/out:/out" `
+     -v "${PWD}/src/bin:/src/bin" `
+     sqlite-wasm-builder:env build
+   ```
 
-    **Windows (Command Prompt):**
+   **Windows (Command Prompt):**
 
-    ```cmd
-    docker run --rm ^
-      -e SQLITE_REF="master" ^
-      -v "%cd%/out:/out" ^
-      -v "%cd%/src/bin:/src/bin" ^
-      sqlite-wasm-builder:env build
-    ```
+   ```cmd
+   docker run --rm ^
+     -e SQLITE_REF="master" ^
+     -v "%cd%/out:/out" ^
+     -v "%cd%/src/bin:/src/bin" ^
+     sqlite-wasm-builder:env build
+   ```
 
 ## Running tests
 
 The test suite consists of Node.js tests and browser-based tests (using Vitest
 Browser Mode). Tests aim to sanity-check the exported scripts. We test for
 correct exports and **very** basic functionality.
 
-1.  Install dependencies:
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Install Playwright browsers (required for browser tests):
 
-    ```bash
-    npm install
-    ```
+   ```bash
+   npx playwright install chromium --with-deps --no-shell
+   ```
 
-2.  Install Playwright browsers (required for browser tests):
+3. Run all tests:
 
-    ```bash
-    npx playwright install chromium --with-deps --no-shell
-    ```
+   ```bash
+   npm test
+   ```
 
-3.  Run all tests:
+## Deprecations
 
-    ```bash
-    npm test
-    ```
+The Worker1 and Promiser1 APIs are, as of 2026-04-15, deprecated. They _will not
+be removed_, but they also will not be extended further. It is their author's
+considered opinion that they are too fragile, too imperformant, and too limited
+for any non-toy software, and their use is _actively discouraged_. The "correct"
+way to use this library is documented in [Usage](#usage) section above.
 
 ## License
 

src/index.d.ts

@@ -1718,7 +1718,10 @@ type Worker1ResultMap = {
   'config-get': Worker1ConfigGetResult;
 };
 
-/** Function type returned by Worker1PromiserFactory. */
+/**
+ * @deprecated Sqlite3Worker1Promiser is deprecated as of 2026-04-15. Function
+ *   type returned by Worker1PromiserFactory.
+ */
 export type Worker1Promiser = {
   /**
    * Sends a message to the worker and returns a Promise which resolves to the
@@ -1738,7 +1741,10 @@ export type Worker1Promiser = {
   ): Promise<Worker1OutputEnvelope<T, Worker1ResultMap[T]>>;
 };
 
-/** Configuration for Worker1PromiserFactory. */
+/**
+ * @deprecated Sqlite3Worker1Promiser is deprecated as of 2026-04-15.
+ *   Configuration for Worker1PromiserFactory.
+ */
 type Worker1PromiserConfig = {
   /** A Worker instance or a function which returns one. */
   worker?: Worker | (() => Worker);
@@ -1759,7 +1765,10 @@ type Worker1PromiserConfig = {
   onerror?: (...args: unknown[]) => void;
 };
 
-/** Factory for creating Worker1Promiser instances. */
+/**
+ * @deprecated Sqlite3Worker1Promiser is deprecated as of 2026-04-15. Factory
+ *   for creating Worker1Promiser instances.
+ */
 type Worker1PromiserFactory = {
   /** Creates a Worker1Promiser. */
   (config?: Worker1PromiserConfig): Worker1Promiser;
@@ -2615,6 +2624,7 @@ export type Sqlite3Static = {
  */
 export default function init(): Promise<Sqlite3Static>;
 
+/** @deprecated Sqlite3Worker1Promiser is deprecated as of 2026-04-15. */
 export const sqlite3Worker1Promiser: Worker1PromiserFactory;
 
 export type ListLike<T> = {

src/index.js

@@ -1,2 +1,3 @@
+/** @deprecated Sqlite3Worker1Promiser is deprecated as of 2026-04-15. */
 export { default as sqlite3Worker1Promiser } from './bin/sqlite3-worker1-promiser.mjs';
 export { default } from './bin/sqlite3-bundler-friendly.mjs';