web-sqlite-js 2.1.0 → 2.3.0

package/README.md

@@ -14,7 +14,7 @@
     <img src="https://img.shields.io/npm/v/web-sqlite-js.svg" alt="NPM Version" />
   </a>
   <a href="https://github.com/wuchuheng/web-sqlite-js/discussions" target="_blank">
-    <img src="https://img.shields.io/badge/v2.0.0-new%20features-blue" alt="v2.0.0" />
+    <img src="https://img.shields.io/badge/v2.2.0-two--tier%20validation-brightgreen" alt="v2.2.0" />
   </a>
   <a href="https://github.com/wuchuheng/web-sqlite-js/blob/main/LICENSE" target="_blank">
     <img src="https://img.shields.io/github/license/wuchuheng/web-sqlite-js.svg" alt="License" />
@@ -36,11 +36,10 @@ Designed to be truly effortless, it allows you to get a high-performance relatio
 - [Quick start](#quick-start)
 - [Setup HTTP headers](#setup-http-headers)
 - [Usage](#usage)
-- [Debug mode](#debug-mode)
 - [Transactions](#transactions)
-- [Structured Logging (v2.0.0)](#structured-logging-v200)
-- [Global Database Access (v2.0.0)](#global-database-access-v200)
-- [Database Events (v2.0.0)](#database-events-v200)
+- [Schema Migrations](#schema-migrations)
+- [Debug mode](#debug-mode)
+- [Structured Logging](#structured-logging)
 
 ## Features
 
@@ -49,10 +48,10 @@ Designed to be truly effortless, it allows you to get a high-performance relatio
 - **Concurrency Safe**: Built-in mutex ensures safe, sequential execution of commands.
 - **Type-Safe**: Written in TypeScript with full type definitions.
 - **Transactions**: Supports atomic transactions with automatic rollback on error.
-- **Structured Logging** (v2.0.0): Subscribe to SQL execution logs via `onLog()`.
-- **Global Namespace** (v2.0.0): Access databases from anywhere via `window.__web_sqlite`.
-- **Database Events** (v2.0.0): Listen to database open/close events for UI synchronization.
-- **Database Registry** (v2.0.0): Prevents duplicate database opens with automatic tracking.
+- **Schema Migrations**: Built-in versioning system for database schema changes.
+- **Two-Tier Validation** (v2.2.0): Distinguishes between whitespace-only changes and actual SQL changes.
+- **Enhanced Error Messages** (v2.2.0): SQL diffs and truncation for better debugging.
+- **Structured Logging**: Subscribe to SQL execution logs via `onLog()`.
 
 ## Quick start
 
@@ -76,7 +75,7 @@ For quick demos or plain HTML pages you can load the prebuilt module directly:
 
 ```html
 <script type="module">
-  import openDB from "https://cdn.jsdelivr.net/npm/web-sqlite-js@1.0.9/dist/index.js";
+  import openDB from "https://cdn.jsdelivr.net/npm/web-sqlite-js@2.2.0/dist/index.js";
   // ...
 </script>
 ```
@@ -286,7 +285,120 @@ await db.transaction(async (tx) => {
 });
 ```
 
-## Structured Logging (v2.0.0)
+## Schema Migrations
+
+Manage database schema changes across releases using the built-in versioning system. Define releases with migration SQL and optional seed data.
+
+### Basic Usage
+
+```typescript
+const db = await openDB("myapp", {
+  releases: [
+    {
+      version: "1.0.0",
+      migrationSQL: `
+        CREATE TABLE users (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          name TEXT NOT NULL,
+          email TEXT UNIQUE
+        );
+      `,
+      seedSQL: `
+        INSERT INTO users (name, email) VALUES
+        ('Alice', 'alice@example.com'),
+        ('Bob', 'bob@example.com');
+      `,
+    },
+    {
+      version: "1.1.0",
+      migrationSQL: `
+        ALTER TABLE users ADD COLUMN created_at TEXT DEFAULT (datetime('now'));
+      `,
+    },
+  ],
+});
+
+// Database is now at version 1.1.0 with all migrations applied
+const users = await db.query("SELECT * FROM users");
+console.log(users);
+// Output: [{ id: 1, name: 'Alice', email: 'alice@example.com', created_at: '...' }, ...]
+```
+
+### Two-Tier Validation (v2.2.0)
+
+Starting with v2.2.0, web-sqlite-js uses a two-tier validation system that intelligently handles SQL formatting changes:
+
+**Tier 1: Fast Path** (< 0.1ms)
+
+- Trims whitespace and compares hashes
+- Passes immediately if SQL hasn't changed
+
+**Tier 2: Slow Path** (1-5ms, only on hash mismatch)
+
+- Normalizes SQL using SQLite prepare
+- Auto-updates hash for whitespace-only changes
+- Throws enhanced error for actual SQL changes
+
+**What this means for you:**
+
+```typescript
+// You can reformat your SQL without breaking migrations!
+const db1 = await openDB("myapp", {
+  releases: [
+    {
+      version: "1.0.0",
+      migrationSQL: "CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT);",
+    },
+  ],
+});
+await db1.close();
+
+// Reopen with reformatted SQL (whitespace-only change)
+const db2 = await openDB("myapp", {
+  releases: [
+    {
+      version: "1.0.0",
+      migrationSQL: `
+        CREATE TABLE items (
+          id INTEGER PRIMARY KEY,
+          name TEXT
+        );
+      `,
+    },
+  ],
+});
+// ✅ Works! Hash auto-updated (no error)
+```
+
+**Enhanced Error Messages:**
+
+If you accidentally change the SQL semantics, you'll get detailed error messages:
+
+```
+Hash mismatch for 1.0.0 migrationSQL:
+Expected: abc123...
+Actual: def456...
+SQL has changed:
+- Original: CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT);
++ Current:  CREATE TABLE items (id INTEGER PRIMARY KEY, email TEXT);
+```
+
+### How It Works
+
+1. **Version Tracking**: Each release has a semantic version (e.g., "1.0.0")
+2. **Automatic Migration**: When opening a database, new releases are applied in order
+3. **Hash Verification**: Migration SQL is hashed to prevent tampering
+4. **Two-Tier Validation**: Distinguishes whitespace-only changes from actual SQL changes
+5. **OPFS Storage**: Each version is stored as a separate file (`1.0.0.sqlite3`, `1.1.0.sqlite3`)
+
+### Best Practices
+
+- **Use Semantic Versioning**: Follow `MAJOR.MINOR.PATCH` format
+- **Idempotent Migrations**: Each migration should handle re-runs safely
+- **Test Migrations**: Always test migrations on a clean database
+- **Incremental Changes**: Keep migrations focused on single schema changes
+
+## Structured Logging
 
 Subscribe to structured log events for monitoring, debugging, and analytics. The `onLog()` API allows you to capture SQL execution details, errors, and application events.
 
@@ -330,97 +442,6 @@ const cancel2 = db.onLog((log) => {
 });
 ```
 
----
-
-## Global Database Access (v2.0.0)
-
-Access opened databases from anywhere in your application without imports. The `window.__web_sqlite` global namespace provides direct references to all opened database instances.
-
-```typescript
-// Open database in module A
-const db = await openDB("app");
-
-// In module B (no import needed):
-const db = window.__web_sqlite.databases["app.sqlite3"];
-const users = await db.query("SELECT * FROM users");
-
-// List all opened databases
-console.log(Object.keys(window.__web_sqlite.databases));
-// Output: ["app.sqlite3", "users.sqlite3"]
-```
-
-**Use Cases**:
-
-- **DevTools Integration**: Access databases from browser console for debugging
-- **Cross-Module Communication**: Share database state without prop drilling
-- **Debugging**: Inspect and query databases directly from DevTools console
-
-**Browser Console Example**:
-
-```javascript
-// From browser DevTools console:
-window.__web_sqlite.databases["app.sqlite3"]
-  .query("SELECT * FROM users")
-  .then((users) => console.table(users));
-```
-
----
-
-## Database Events (v2.0.0)
-
-Subscribe to database open/close events for UI synchronization and monitoring. The `onDatabaseChange()` API notifies you when databases are opened or closed.
-
-```typescript
-// Subscribe to database changes
-const unsubscribe = window.__web_sqlite.onDatabaseChange((event) => {
-  if (event.action === "opened") {
-    console.log(`Database opened: ${event.dbName}`);
-    updateDatabaseList(event.databases);
-  } else if (event.action === "closed") {
-    console.log(`Database closed: ${event.dbName}`);
-    updateDatabaseList(event.databases);
-  }
-  console.log("Current databases:", event.databases);
-});
-
-// Open a database
-await openDB("app");
-// Output: Database opened: app.sqlite3
-// Output: Current databases: ["app.sqlite3"]
-
-// Open another database
-await openDB("users");
-// Output: Database opened: users.sqlite3
-// Output: Current databases: ["app.sqlite3", "users.sqlite3"]
-
-// Close first database
-await window.__web_sqlite.databases["app.sqlite3"].close();
-// Output: Database closed: app.sqlite3
-// Output: Current databases: ["users.sqlite3"]
-
-// Unsubscribe when done
-// unsubscribe();
-```
-
-**Event Structure**:
-
-```typescript
-interface DatabaseChangeEvent {
-  action: "opened" | "closed"; // What happened
-  dbName: string; // Which database (normalized name)
-  databases: string[]; // All currently opened database names
-}
-```
-
-**Use Cases**:
-
-- **DevTools Panels**: Show active databases in browser DevTools
-- **UI Updates**: Refresh database list when databases open/close
-- **Monitoring**: Track database lifecycle for debugging
-- **Multi-Window Sync**: Coordinate database access across browser windows
-
----
-
 ## Star History
 
 <p align="left">

package/dist/index.d.ts

@@ -3,45 +3,96 @@ declare interface DBInterface {
     /**
      * Execute a SQL script (one or more statements) without returning rows.
      * Intended for migrations, schema setup, or bulk SQL execution.
+     *
      * @param sql - SQL string to execute.
      * @param params - Optional bind parameters for the statement.
+     * @returns Result metadata (changes, lastInsertRowid).
+     *
+     * @example
+     * ```ts
+     * await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
+     * await db.exec("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     * ```
      */
     exec(sql: string, params?: SQLParams): Promise<ExecResult>;
     /**
      * Execute a query and return all result rows as an array of objects.
+     *
      * @param sql - SELECT SQL to execute.
      * @param params - Optional bind parameters for the query.
+     * @returns Array of result rows.
+     *
+     * @example
+     * ```ts
+     * const users = await db.query<{ id: number; name: string }>(
+     *   "SELECT id, name FROM users WHERE id = ?",
+     *   [1]
+     * );
+     * ```
      */
     query<T = unknown>(sql: string, params?: SQLParams): Promise<T[]>;
     /**
-     * Run a callback inside a transaction. The implementation should BEGIN before calling `fn`
-     * and COMMIT on success or ROLLBACK on error.
-     * @param fn - Callback that receives a DBInterface and performs transactional work.
+     * Execute a transaction with automatic rollback on error.
+     *
+     * @param fn - Transaction callback receiving transaction interface.
+     * @returns Result of the transaction callback.
+     *
+     * @example
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *   await tx.exec("INSERT INTO users (name) VALUES (?)", ["Bob"]);
+     *   await tx.exec("INSERT INTO posts (title) VALUES (?)", ["Hello"]);
+     * });
+     * ```
      */
     transaction<T>(fn: transactionCallback<T>): Promise<T>;
-    /** Close the database and release resources. */
+    /**
+     * Close the database and release worker resources.
+     *
+     * @example
+     * ```ts
+     * await db.close();
+     * ```
+     */
     close(): Promise<void>;
     /**
-     * Subscribe to log events
-     * Logs include SQL execution, timing, errors, and application events
+     * Register a callback for database logs (worker SQL execution logs).
      *
-     * @param callback - Called for each log entry
-     * @returns Unsubscribe function
+     * @param callback - Function to receive log entries.
+     * @returns Unregister function.
      *
      * @example
-     * const unsubscribe = db.onLog((log) => {
-     *     console.log(`[${log.level}]`, log.data);
+     * ```ts
+     * const unregister = db.onLog((log) => {
+     *   console.log(`[${log.level}]`, log.data);
      * });
-     * // Later: unsubscribe();
+     * // Later: unregister();
+     * ```
      */
     onLog(callback: (log: LogEntry) => void): () => void;
-    /** Dev tooling APIs for release testing. */
+    /**
+     * Dev tooling for creating and managing dev versions.
+     */
     devTool: DevTool;
 }
 
+/**
+ * Dev tooling interface for creating and rolling back dev versions.
+ */
 declare type DevTool = {
     /**
-     * Create a new dev version using migration and seed SQL.
+     * Create a new dev version with migration and seed SQL.
+     *
+     * @param input - Release config with version, migration SQL, and optional seed SQL.
+     *
+     * @example
+     * ```ts
+     * await db.devTool.release({
+     *   version: "1.0.1",
+     *   migrationSQL: "ALTER TABLE users ADD COLUMN email TEXT",
+     *   seedSQL: "UPDATE users SET email = 'test@example.com' WHERE email IS NULL",
+     * });
+     * ```
      */
     release(input: ReleaseConfig): Promise<void>;
     /**
@@ -118,6 +169,25 @@ declare type SQLParams = SqlValue[] | Record<string, SqlValue>;
  */
 declare type SqlValue = null | number | string | boolean | bigint | Uint8Array | ArrayBuffer;
 
-declare type transactionCallback<T> = (db: Pick<DBInterface, "exec" | "query">) => Promise<T>;
+/**
+ * Transaction interface passed to transaction callbacks.
+ * All operations execute within the same transaction.
+ */
+declare interface Transaction {
+    /**
+     * Execute a SQL statement within the transaction.
+     */
+    exec(sql: string, params?: SQLParams): Promise<ExecResult>;
+    /**
+     * Execute a query within the transaction.
+     */
+    query<T = unknown>(sql: string, params?: SQLParams): Promise<T[]>;
+}
+
+/**
+ * Transaction callback interface.
+ * Provides exec and query methods scoped to the transaction.
+ */
+declare type transactionCallback<T> = (tx: Transaction) => Promise<T>;
 
 export { }