web-sqlite-js 1.1.2 → 2.2.0

package/README.md

@@ -13,6 +13,9 @@
   <a href="https://www.npmjs.com/package/web-sqlite-js" target="_blank">
     <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" />
+  </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" />
   </a>
@@ -33,8 +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)
+- [Schema Migrations](#schema-migrations)
+- [Debug mode](#debug-mode)
+- [Structured Logging](#structured-logging)
 
 ## Features
 
@@ -43,6 +48,8 @@ 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.
+- **Schema Migrations**: Built-in versioning system for database schema changes.
+- **Structured Logging**: Subscribe to SQL execution logs via `onLog()`.
 
 ## Quick start
 
@@ -66,8 +73,8 @@ 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@1.0.9/dist/index.js";
+  // ...
 </script>
 ```
 
@@ -95,18 +102,18 @@ Update your `vite.config.ts`:
 import { defineConfig } from "vite";
 
 export default defineConfig({
-    server: {
-        headers: {
-            "Cross-Origin-Opener-Policy": "same-origin",
-            "Cross-Origin-Embedder-Policy": "require-corp",
-        },
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
     },
-    preview: {
-        headers: {
-            "Cross-Origin-Opener-Policy": "same-origin",
-            "Cross-Origin-Embedder-Policy": "require-corp",
-        },
+  },
+  preview: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
     },
+  },
 });
 ```
 
@@ -120,23 +127,23 @@ Update your `next.config.js`:
 ```javascript
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-    async headers() {
-        return [
-            {
-                source: "/(.*)",
-                headers: [
-                    {
-                        key: "Cross-Origin-Opener-Policy",
-                        value: "same-origin",
-                    },
-                    {
-                        key: "Cross-Origin-Embedder-Policy",
-                        value: "require-corp",
-                    },
-                ],
-            },
-        ];
-    },
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          {
+            key: "Cross-Origin-Opener-Policy",
+            value: "same-origin",
+          },
+          {
+            key: "Cross-Origin-Embedder-Policy",
+            value: "require-corp",
+          },
+        ],
+      },
+    ];
+  },
 };
 
 module.exports = nextConfig;
@@ -151,13 +158,13 @@ Update your `webpack.config.js`:
 
 ```javascript
 module.exports = {
-    // ...
-    devServer: {
-        headers: {
-            "Cross-Origin-Opener-Policy": "same-origin",
-            "Cross-Origin-Embedder-Policy": "require-corp",
-        },
+  // ...
+  devServer: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
     },
+  },
 };
 ```
 
@@ -189,9 +196,9 @@ const express = require("express");
 const app = express();
 
 app.use((req, res, next) => {
-    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
-    res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
-    next();
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+  next();
 });
 
 // ...
@@ -227,12 +234,12 @@ await db.exec(`
 
 // 3. Insert data (Parameterized)
 await db.exec("INSERT INTO users (name, email) VALUES (?, ?)", [
-    "Alice",
-    "alice@example.com",
+  "Alice",
+  "alice@example.com",
 ]);
 await db.exec("INSERT INTO users (name, email) VALUES ($name, $email)", {
-    $name: "Bob",
-    $email: "bob@example.com",
+  $name: "Bob",
+  $email: "bob@example.com",
 });
 
 // 4. Query data
@@ -266,13 +273,110 @@ Transactions are atomic. If any command inside the callback fails, the entire tr
 
 ```typescript
 await db.transaction(async (tx) => {
-    await tx.exec("INSERT INTO users (name) VALUES (?)", ["Charlie"]);
+  await tx.exec("INSERT INTO users (name) VALUES (?)", ["Charlie"]);
+
+  // You can perform multiple operations safely
+  await tx.exec("INSERT INTO logs (action) VALUES (?)", ["User Created"]);
+
+  // If you throw an error here, both INSERTs will be rolled back!
+  // throw new Error('Something went wrong');
+});
+```
+
+## Schema Migrations
 
-    // You can perform multiple operations safely
-    await tx.exec("INSERT INTO logs (action) VALUES (?)", ["User Created"]);
+Manage database schema changes across releases using the built-in versioning system. Define releases with migration SQL and optional seed data.
 
-    // If you throw an error here, both INSERTs will be rolled back!
-    // throw new Error('Something went wrong');
+### 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: '...' }, ...]
+```
+
+### 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. **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.
+
+```typescript
+const db = await openDB("myapp");
+
+// Register log listener
+const cancelLog = db.onLog((log) => {
+  if (log.level === "error") {
+    // Send errors to tracking service
+    errorTracking.capture(log.data);
+  } else if (log.level === "debug") {
+    // Log SQL execution details
+    console.log(`SQL: ${log.data.sql}, Duration: ${log.data.duration}ms`);
+  } else if (log.level === "info") {
+    // Track application events (open, close, transactions)
+    console.log(`Event: ${log.data.action}`);
+  }
+});
+
+// Execute some SQL to generate logs
+await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
+await db.exec("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+
+// Later: stop listening
+cancelLog();
+```
+
+**Log Levels**:
+
+- `"debug"` - SQL execution details (sql, duration, bind parameters)
+- `"info"` - Application events (open, close, commit, rollback)
+- `"error"` - SQL errors and exceptions
+
+**Multiple Callbacks**: You can register multiple log listeners simultaneously:
+
+```typescript
+const cancel1 = db.onLog((log) => console.log("Logger 1:", log));
+const cancel2 = db.onLog((log) => {
+  if (log.level === "error") sendToAlerting(log.data);
 });
 ```
 

package/dist/index.d.ts

@@ -21,6 +21,20 @@ declare interface DBInterface {
     transaction<T>(fn: transactionCallback<T>): Promise<T>;
     /** Close the database and release resources. */
     close(): Promise<void>;
+    /**
+     * Subscribe to log events
+     * Logs include SQL execution, timing, errors, and application events
+     *
+     * @param callback - Called for each log entry
+     * @returns Unsubscribe function
+     *
+     * @example
+     * const unsubscribe = db.onLog((log) => {
+     *     console.log(`[${log.level}]`, log.data);
+     * });
+     * // Later: unsubscribe();
+     */
+    onLog(callback: (log: LogEntry) => void): () => void;
     /** Dev tooling APIs for release testing. */
     devTool: DevTool;
 }
@@ -46,6 +60,20 @@ declare type ExecResult = {
     lastInsertRowid?: number | bigint;
 };
 
+/**
+ * Log entry with level and structured data
+ */
+declare type LogEntry = {
+    /**
+     * Log level: 'info' | 'debug' | 'error'
+     */
+    level: "info" | "debug" | "error";
+    /**
+     * Log data (SQL, timing, errors, events, etc.)
+     */
+    data: unknown;
+};
+
 /**
  * Opens a SQLite database connection with release-versioning support.
  *