js-bao 0.5.1 → 0.5.2

package/README.md

@@ -29,17 +29,21 @@ npm install js-bao yjs
 yarn add js-bao yjs
 # or
 pnpm add js-bao yjs
-
-# For SQL.js engine:
-npm install sql.js
 ```
 
+The default **SQL.js** engine works out of the box in both the browser and
+headless Node — `sql.js` is a direct dependency of `js-bao`, so there's nothing
+extra to install. (In the browser you do need to serve `sql-wasm.wasm`; see
+[SQL.js — the universal default](#sqljs-type-sqljs--the-universal-default).)
+
 ### Optional Dependencies
 
-For Node.js environments, you can install native database engines:
+For native, file-backed SQLite in Node.js (the `node-sqlite` engine), install
+`better-sqlite3`. This is a **one-line opt-in** — `js-bao` never switches engines
+on you automatically:
 
 ```bash
-# For SQLite support in Node.js
+# Native SQLite in Node.js (then set databaseConfig: { type: "node-sqlite" })
 npm install better-sqlite3
 ```
 
@@ -51,8 +55,10 @@ npm install better-sqlite3
 
 ### Node.js
 
-- **better-sqlite3**: Native SQLite with file system support
-- **SQL.js**: SQLite WASM (fallback option)
+- **SQL.js (`sqljs`)**: SQLite WASM — the default; works out of the box in
+  headless Node (resolves its wasm automatically, no config).
+- **better-sqlite3 (`node-sqlite`)**: native, file-backed SQLite. One-line opt-in
+  (`npm install better-sqlite3` + `databaseConfig: { type: "node-sqlite" }`).
 
 ## Core Concepts
 
@@ -1251,22 +1257,106 @@ const tagStats = await Article.aggregate({
 
 ## Database Engine Specifics
 
-### SQL.js (`type: 'sqljs'`)
-
-- **WASM File**: `sql-wasm.wasm` (from the `sql.js` package) must be publicly accessible in your application.
-  - By default, the library expects it at `/sql-wasm.wasm` (root of your public server path).
-  - **Vite/Create React App**: Place `sql-wasm.wasm` in your project's `public` directory.
-  - **Custom Path**: If the WASM file is located elsewhere, configure it in `DatabaseConfig`:
-    ```typescript
-    const dbConfig: DatabaseConfig = {
-      type: "sqljs",
-      options: {
-        wasmURL: "/path/to/your/sql-wasm.wasm",
-        // or use locateFile for more complex scenarios:
-        // locateFile: (file) => `/assets/wasm/${file}`
-      },
-    };
-    ```
+### SQL.js (`type: 'sqljs'`) — the universal default
+
+`sqljs` is SQLite compiled to WebAssembly. It is the **default engine** and now
+works **out of the box in both the browser and headless Node** — no manual wasm
+configuration required in either environment.
+
+#### Browser
+
+The `sql-wasm.wasm` file (from the `sql.js` package) must be served from your
+app. By default the library expects it at `/sql-wasm.wasm` (the root of your
+public server path).
+
+- **Vite / Create React App**: copy `node_modules/sql.js/dist/sql-wasm.wasm` into
+  your project's `public/` directory so it is served at `/sql-wasm.wasm`.
+- **Custom path**: if the wasm lives elsewhere, point at it via `DatabaseConfig`:
+
+  ```typescript
+  const dbConfig: DatabaseConfig = {
+    type: "sqljs",
+    options: {
+      wasmURL: "/assets/wasm/sql-wasm.wasm",
+      // or, for more complex layouts:
+      // locateFile: (file) => `/assets/wasm/${file}`,
+    },
+  };
+  ```
+
+#### Headless Node
+
+Under Node, `sqljs` automatically resolves sql.js's bundled
+`sql-wasm.wasm` **relative to the installed js-bao package** (using
+`createRequire(import.meta.url).resolve("sql.js/dist/sql-wasm.wasm")`, with a
+`__dirname`-based fallback for the CommonJS build). **No `wasmURL` / `locateFile`
+override and no extra setup is needed** — `new SqljsEngine()` (or the client's
+default `{ type: "sqljs" }`) just works:
+
+```typescript
+import { SqljsEngine } from "js-bao/node";
+
+const engine = new SqljsEngine(); // resolves sql.js's wasm automatically
+await engine.ensureReady();
+```
+
+An explicit `wasmURL` / `locateFile` still takes precedence if you provide one.
+
+##### Graceful, catchable failure
+
+If the wasm genuinely cannot be located (e.g. you pass a bad `locateFile`),
+initialization now **rejects with a single, catchable `Error`** carrying
+remediation guidance:
+
+```typescript
+try {
+  const engine = new SqljsEngine({ locateFile: () => "/bad/path.wasm" });
+  await engine.ensureReady();
+} catch (err) {
+  // "sql.js wasm not found at "/bad/path.wasm". Pass `locateFile`/`wasmURL` ...,
+  //  or install `better-sqlite3` and use the `node-sqlite` engine ..."
+  console.error(err.message);
+}
+```
+
+Previously a missing/corrupt wasm caused sql.js's emscripten runtime to abort
+asynchronously with an **uncatchable `RuntimeError: Aborted`** that escaped
+`try/catch` and crashed the Node process. The engine now preflights the wasm path
+and installs a defensive `onAbort` handler so the failure surfaces as a normal
+rejected promise instead.
+
+### Native SQLite in Node (`type: 'node-sqlite'`) — easy opt-in
+
+`sqljs` is fine for most Node usage, but if you want native, file-backed SQLite
+(via the `better-sqlite3` addon) it is a **one-line opt-in** — `sqljs` is never
+silently swapped out for you. Install the optional dependency and set the engine
+type:
+
+```bash
+npm install better-sqlite3
+```
+
+```typescript
+// Flip the client (or initJsBao) to native SQLite in one line:
+const client = new JsBaoClient({
+  // ...other options...
+  databaseConfig: {
+    type: "node-sqlite",
+    options: { filePath: ":memory:" }, // or "/path/to/app.db" for persistence
+  },
+});
+```
+
+To pick the engine programmatically based on what's installed, use the helper
+exported from `js-bao/node`:
+
+```typescript
+import { getRecommendedNodeEngine } from "js-bao/node";
+
+// Returns "node-sqlite" when better-sqlite3 is installed, else "sqljs".
+const type = await getRecommendedNodeEngine();
+const databaseConfig = { type, options: { filePath: ":memory:" } };
+```
 
 ## Building the Library (for Contributors)
 
@@ -1405,25 +1495,29 @@ Key exports: `connectDoDb`, `DOClientEngine`, and types (`DoDb`, `DocumentFilter
 
 ## Database Configuration
 
-### SQLite (Node.js)
+### SQL.js (Browser / Node.js) — default
 
 ```javascript
 {
-  type: 'node-sqlite',
+  type: 'sqljs',
   options: {
-    filePath: ':memory:' // or '/path/to/database.db'
+    // Browser: serves /sql-wasm.wasm (place it in public/), or override via
+    //   wasmURL / locateFile.
+    // Node.js: resolves sql.js's bundled wasm automatically — no config needed.
   }
 }
 ```
 
-### SQL.js (Browser/Node.js)
+### Native SQLite (Node.js) — `node-sqlite` (better-sqlite3)
+
+One-line opt-in for native, file-backed SQLite. Requires `better-sqlite3`
+(`npm install better-sqlite3`):
 
 ```javascript
 {
-  type: 'sqljs',
+  type: 'node-sqlite',
   options: {
-    // Browser: automatically loads WASM
-    // Node.js: fallback option
+    filePath: ':memory:' // or '/path/to/database.db'
   }
 }
 ```