sqlite-zod-orm 3.8.0 → 3.10.0

package/README.md

@@ -41,7 +41,6 @@ const db = new Database(':memory:', {
   relations: {
     books: { author_id: 'authors' },
   },
-  pollInterval: 300, // global default for .on() and .subscribe() (default: 500ms)
 });
 ```
 
@@ -185,6 +184,60 @@ alice.score = 200;    // → UPDATE users SET score = 200 WHERE id = 1
 
 ---
 
+## Change Listeners — `db.table.on()`
+
+Register listeners for insert, update, and delete events. Uses SQLite triggers + a single global poller — no per-listener overhead.
+
+```typescript
+// Listen for new users
+const unsub = db.users.on('insert', (user) => {
+  console.log('New user:', user.name, user.email);
+});
+
+// Listen for updates
+db.users.on('update', (user) => {
+  console.log('Updated:', user.name);
+});
+
+// Listen for deletes (row is gone, only id available)
+db.users.on('delete', ({ id }) => {
+  console.log('Deleted user id:', id);
+});
+
+// Stop listening
+unsub();
+```
+
+### How it works
+
+```
+┌──────────────────────────────────────────────────┐
+│  SQLite triggers log every mutation:             │
+│                                                  │
+│  INSERT → _changes (tbl, op='insert', row_id)    │
+│  UPDATE → _changes (tbl, op='update', row_id)    │
+│  DELETE → _changes (tbl, op='delete', row_id)    │
+│                                                  │
+│  Single global poller (default 100ms):           │
+│  1. SELECT * FROM _changes WHERE id > @watermark │
+│  2. Re-fetch affected rows                       │
+│  3. Dispatch to registered on() listeners        │
+│  4. Advance watermark, clean up consumed entries  │
+└──────────────────────────────────────────────────┘
+```
+
+| Feature | Detail |
+|---|---|
+| **Granularity** | Row-level (knows exactly which row changed) |
+| **Operations** | INSERT, UPDATE, DELETE — all detected |
+| **Cross-process** | ✅ Triggers fire regardless of which connection writes |
+| **Overhead** | Single poller for all listeners, no per-listener timers |
+| **Cleanup** | Consumed changes auto-deleted after dispatch |
+
+Run `bun examples/messages-demo.ts` for a full working demo.
+
+---
+
 ## Schema Validation
 
 Zod validates every insert and update at runtime:
@@ -195,6 +248,35 @@ db.users.insert({ name: '', email: 'bad', age: -1 });  // throws ZodError
 
 ---
 
+## Automatic Migrations
+
+When you add new fields to your Zod schema, the ORM automatically adds the corresponding columns to the SQLite table on startup. No migration files, no manual ALTER TABLE statements.
+
+```typescript
+// v1: initial schema
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+});
+
+// v2: added a new field — just update the Zod schema
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  bio: z.string().default(''),      // ← new column added automatically
+  score: z.number().default(0),     // ← new column added automatically
+});
+```
+
+**How it works:**
+1. On startup, the ORM reads `PRAGMA table_info(...)` to get existing columns
+2. Compares them against the Zod schema fields
+3. Any missing columns are added via `ALTER TABLE ... ADD COLUMN`
+
+This handles the common case of additive schema evolution. For destructive changes (renaming or dropping columns), use the SQLite CLI directly.
+
+---
+
 ## Indexes
 
 ```typescript
@@ -208,122 +290,86 @@ const db = new Database(':memory:', schemas, {
 
 ---
 
-## Reactivity
+## Transactions
 
-Two complementary APIs for watching data changes:
-
-| API | Receives | Fires on | Use case |
-|---|---|---|---|
-| **`db.table.on(cb)`** | One row at a time, in order | New inserts only | Message streams, event queues |
-| **`select().subscribe(cb)`** | Full result snapshot | Any change (insert/update/delete) | Live dashboards, filtered views |
+```typescript
+const result = db.transaction(() => {
+  const author = db.authors.insert({ name: 'New Author', country: 'US' });
+  const book = db.books.insert({ title: 'New Book', year: 2024, author_id: author.id });
+  return { author, book };
+});
+// Automatically rolls back on error
+```
 
 ---
 
-### Row Stream — `db.table.on(callback)`
-
-Streams new rows one at a time, in insertion order. Only emits rows created **after** subscription starts.
-
-```typescript
-const unsub = db.messages.on((msg) => {
-  console.log(`${msg.author}: ${msg.text}`);
-}, { interval: 200 });
+## Examples & Tests
 
-// Later: stop listening
-unsub();
+```bash
+bun examples/messages-demo.ts  # on() change listener demo
+bun examples/example.ts        # comprehensive demo
+bun test                        # 117 tests
 ```
 
-If 5 messages arrive between polls, the callback fires 5 times — once per row, in order. Uses a watermark (`id > lastSeen`) internally.
-
 ---
 
-### Snapshot — `select().subscribe(callback)`
+## Benchmarks
 
-Returns the **full query result** whenever data changes. Detects all mutations (inserts, updates, deletes).
+All benchmarks run on in-memory SQLite via Bun. Reproduce with:
 
-```typescript
-const unsub = db.users.select()
-  .where({ role: 'admin' })
-  .orderBy('name', 'asc')
-  .subscribe((admins) => {
-    console.log('Admin list:', admins.map(a => a.name));
-  }, { interval: 1000 });
-
-// Stop watching
-unsub();
+```bash
+bun bench/triggers-vs-naive.ts  # change detection strategies
+bun bench/poll-strategy.ts      # MAX(id) vs SELECT WHERE
+bun bench/indexes.ts            # index impact on queries
 ```
 
-**Options:**
+### Why triggers? — Change detection strategies
 
-| Option | Default | Description |
-|---|---|---|
-| `interval` | `500` | Polling interval in milliseconds |
-| `immediate` | `true` | Fire callback immediately with current data |
+We compared three approaches for detecting data changes:
 
-### How it works
+| Strategy | Idle poll cost | Write overhead | Granularity |
+|---|---|---|---|
+| **Triggers + `_changes` table** (ours) | 147ns/poll | ~1µs/mutation | row + table + operation |
+| `PRAGMA data_version` | 136ns/poll | zero | boolean only (any write?) |
+| `COUNT(*) + MAX(id)` fingerprint | 138,665ns/poll | zero | count only, misses updates |
 
-```
-┌──────────────────────────────────────────────────┐
-│  Every {interval}ms:                             │
-│                                                  │
-│  1. Check revision (in-memory + data_version)    │
-│  2. Run: SELECT COUNT(*), MAX(id)                │
-│     FROM users WHERE role = 'admin'              │
-│                                                  │
-│  3. Combine into fingerprint: "count:max:rev:dv" │
-│                                                  │
-│  4. If fingerprint changed → re-run full query   │
-│     and call your callback                       │
-└──────────────────────────────────────────────────┘
-```
+**Idle poll cost** (the common hot path — nothing changed) is near-identical for triggers and `data_version` (~150ns). The `COUNT+MAX` approach is **~1000x slower** because it must scan the table every poll.
 
-Two signals combine to detect **all** changes from **any** source:
+**Write overhead** for triggers is ~1µs per mutation (one extra INSERT into `_changes`):
 
-| Signal | Catches | How |
-|---|---|---|
-| **In-memory revision** | Same-process writes | Bumped by CRUD methods |
-| **PRAGMA data_version** | Cross-process writes | SQLite bumps it on external commits |
+| Operation | With triggers | Without | Overhead |
+|---|---|---|---|
+| INSERT (10K rows) | 2.4µs/row | 1.4µs/row | +1.0µs |
+| UPDATE (10K rows) | 1.8µs/row | 0.9µs/row | +0.9µs |
 
-| Operation | Detected | Source |
-|---|---|---|
-| INSERT | ✅ | Same or other process |
-| DELETE | ✅ | Same or other process |
-| UPDATE | ✅ | Same or other process |
+In exchange, triggers give you **row-level, operation-level, table-level** granularity — you know exactly which row changed, how, and in which table. `PRAGMA data_version` just tells you "something changed somewhere." For apps that don't need listeners, `{ reactive: false }` eliminates all trigger overhead.
 
-No triggers. No `_changes` table. Zero disk overhead. WAL mode is enabled by default for concurrent read/write.
+### Why MAX(id) fast-path?
 
-### Multi-process example
+The poller checks `SELECT MAX(id) FROM _changes` before fetching rows. On idle (no changes), this avoids materializing any row objects:
 
-```typescript
-// Process A — watches for new/edited messages
-const unsub = db.messages.select()
-  .orderBy('id', 'asc')
-  .subscribe((messages) => {
-    console.log('Messages:', messages);
-  }, { interval: 200 });
-
-// Process B — writes to the same DB file (different process)
-// sqlite3 chat.db "INSERT INTO messages (text, author) VALUES ('hello', 'Bob')"
-// → Process A's callback fires with updated message list!
-```
+| Strategy | Per poll (idle) |
+|---|---|
+| `MAX(id)` check only | **153ns** |
+| `SELECT * WHERE id > ?` (returns 0 rows) | 192ns |
 
-Run `bun examples/messages-demo.ts` for a full working demo.
+~20% faster on the hot path with no penalty when changes exist.
 
-**Use cases:**
-- Live dashboards (poll every 1-5s)
-- Real-time chat / message lists
-- Auto-refreshing data tables
-- Watching filtered subsets of data
-- Cross-process data synchronization
+### Index impact
 
----
+Benchmarked on 100K rows, 10K queries each:
 
-## Examples & Tests
+| Query pattern | No index | With index | Speedup |
+|---|---|---|---|
+| Point lookup (`WHERE email = ?`) | 2,447µs | **2.2µs** | **1,112x** |
+| Top-N (`ORDER BY score DESC LIMIT 10`) | 2,777µs | **7.1µs** | **391x** |
+| COUNT with filter | 2,526µs | **344µs** | **7x** |
+| Range scan (`WHERE score > ? LIMIT 100`) | 54µs | 75µs | 0.7x* |
+| Category filter (`WHERE role = ?`, ~20K rows) | 11,084µs | 14,809µs | 0.7x* |
 
-```bash
-bun examples/messages-demo.ts  # .on() vs .subscribe() demo
-bun examples/example.ts        # comprehensive demo
-bun test                        # 100 tests
-```
+*\*Range scans and wide category filters can be slightly slower with indexes due to random I/O — SQLite's full scan is faster when returning a large fraction of the table.*
+
+**Write overhead:** 4 indexes add ~2.8x to INSERT cost (1.9µs → 5.3µs per insert). This is typical and a good tradeoff for read-heavy workloads.
 
 ---
 
@@ -350,10 +396,17 @@ bun test                        # 100 tests
 | `entity.navMethod()` | Lazy navigation (FK name minus `_id`) |
 | `entity.update(data)` | Update entity in-place |
 | `entity.delete()` | Delete entity |
-| **Reactivity** | |
-| `db.table.on(cb, opts?)` | Stream new rows one at a time, in order |
-| `select().subscribe(cb, opts?)` | Watch query result snapshot (all mutations) |
+| **Change Listeners** | |
+| `db.table.on('insert', cb)` | Listen for new rows (receives full row) |
+| `db.table.on('update', cb)` | Listen for updated rows (receives full row) |
+| `db.table.on('delete', cb)` | Listen for deleted rows (receives `{ id }`) |
+| **Options** | |
+| `{ reactive: false }` | Disable triggers entirely (no .on() support) |
+| `{ pollInterval: 100 }` | Global poller interval in ms (default: 100) |
+| **Transactions** | |
+| `db.transaction(fn)` | Atomic operation with auto-rollback |
 
 ## License
 
 MIT
+