sqlite-zod-orm 3.11.0 → 3.13.0

package/README.md

@@ -1,412 +1,79 @@
 # sqlite-zod-orm
 
-Type-safe SQLite ORM for Bun. Define schemas with Zod, get a fully-typed database with automatic relationships, lazy navigation, and zero SQL.
+**Type-safe SQLite ORM for Bun** — Zod schemas in, fully typed database out. Zero SQL required.
+
+[![npm](https://img.shields.io/npm/v/sqlite-zod-orm)](https://www.npmjs.com/package/sqlite-zod-orm)
+[![license](https://img.shields.io/npm/l/sqlite-zod-orm)](./LICENSE)
+
+## Install
 
 ```bash
 bun add sqlite-zod-orm
 ```
 
+> **Requires Bun runtime** — uses `bun:sqlite` under the hood.
+
 ## Quick Start
 
 ```typescript
 import { Database, z } from 'sqlite-zod-orm';
 
-const db = new Database(':memory:', {
-  users: z.object({
-    name: z.string(),
-    email: z.string().email(),
-    role: z.string().default('member'),
-  }),
-});
-
-const alice = db.users.insert({ name: 'Alice', email: 'alice@example.com', role: 'admin' });
-const admin = db.users.select().where({ role: 'admin' }).get();  // single row
-const all   = db.users.select().all();                           // all rows
-```
-
----
-
-## Defining Relationships
-
-FK columns go in your schema. The `relations` config declares which FK points to which table:
-
-```typescript
-const AuthorSchema = z.object({ name: z.string(), country: z.string() });
-const BookSchema   = z.object({ title: z.string(), year: z.number(), author_id: z.number().optional() });
-
-const db = new Database(':memory:', {
-  authors: AuthorSchema,
-  books:   BookSchema,
-}, {
-  relations: {
-    books: { author_id: 'authors' },
-  },
-});
-```
-
-`books: { author_id: 'authors' }` tells the ORM that `books.author_id` is a foreign key referencing `authors.id`. The ORM automatically:
-
-- Adds `FOREIGN KEY (author_id) REFERENCES authors(id)` constraint
-- Infers the inverse one-to-many `authors → books`
-- Enables lazy navigation: `book.author()` and `author.books()`
-- Enables fluent joins: `db.books.select().join(db.authors).all()`
-
-The nav method name is derived by stripping `_id` from the FK column: `author_id` → `author()`.
-
----
-
-## Querying — `select()` is the only path
-
-All queries go through `select()`:
-
-```typescript
-// Single row
-const user = db.users.select().where({ id: 1 }).get();
-
-// All matching rows
-const admins = db.users.select().where({ role: 'admin' }).all();
-
-// All rows
-const everyone = db.users.select().all();
-
-// Count
-const count = db.users.select().count();
-```
-
-### Operators
-
-`$gt` `$gte` `$lt` `$lte` `$ne` `$in`
-
-```typescript
-const topScorers = db.users.select()
-  .where({ score: { $gt: 50 } })
-  .orderBy('score', 'desc')
-  .limit(10)
-  .all();
-```
-
-### `$or`
-
-```typescript
-const results = db.users.select()
-  .where({ $or: [{ role: 'admin' }, { score: { $gt: 50 } }] })
-  .all();
-```
-
-### Fluent Join
-
-Auto-infers foreign keys from relationships:
-
-```typescript
-const rows = db.books.select('title', 'year')
-  .join(db.authors, ['name', 'country'])
-  .where({ year: { $gt: 1800 } })
-  .orderBy('year', 'asc')
-  .all();
-// → [{ title: 'War and Peace', year: 1869, authors_name: 'Leo Tolstoy', ... }]
-```
-
-### `db.query()` — Proxy Query (SQL-like)
-
-Full SQL-like control with destructured table aliases:
-
-```typescript
-const rows = db.query(c => {
-  const { authors: a, books: b } = c;
-  return {
-    select: { author: a.name, book: b.title, year: b.year },
-    join: [[b.author_id, a.id]],
-    where: { [a.country]: 'Russia' },
-    orderBy: { [b.year]: 'asc' },
-  };
+const db = new Database('app.db', {
+    users: z.object({
+        name: z.string(),
+        email: z.string(),
+        role: z.string().default('member'),
+    }),
 });
-```
-
----
-
-## Lazy Navigation
-
-Relationship fields become callable methods on entities. The method name is the FK column with `_id` stripped:
-
-```typescript
-// belongs-to: book.author_id → book.author()
-const book = db.books.select().where({ title: 'War and Peace' }).get()!;
-const author = book.author();       // → { name: 'Leo Tolstoy', ... }
-
-// one-to-many: author → books
-const books = tolstoy.books();      // → [{ title: 'War and Peace' }, ...]
 
-// Chain
-const allByAuthor = book.author().books();
-```
-
----
-
-## CRUD
-
-```typescript
-// Insert (defaults fill in automatically)
-const user = db.users.insert({ name: 'Alice', role: 'admin' });
-
-// Insert with FK
-const book = db.books.insert({ title: 'War and Peace', year: 1869, author_id: tolstoy.id });
-
-// Read
-const one   = db.users.select().where({ id: 1 }).get();
-const some  = db.users.select().where({ role: 'admin' }).all();
-const all   = db.users.select().all();
-const count = db.users.select().count();
-
-// Entity-level update
-user.update({ role: 'superadmin' });
-
-// Update by ID
-db.users.update(1, { role: 'superadmin' });
+// Insert
+const alice = db.users.insert({ name: 'Alice', email: 'alice@co.com' });
+alice.id; // auto-increment ID
+alice.role; // 'member' (from Zod default)
 
-// Fluent update with WHERE
-db.users.update({ role: 'member' }).where({ role: 'guest' }).exec();
+// Query
+const admins = db.users.select()
+    .where({ role: 'admin' })
+    .orderBy('name')
+    .all();
 
-// Upsert
-db.users.upsert({ name: 'Alice' }, { name: 'Alice', role: 'admin' });
+// Update
+alice.name = 'Alice Smith'; // auto-persists
 
 // Delete
-db.users.delete(1);
+db.users.delete(alice.id);
 ```
 
-### Auto-Persist Proxy
+## Features
 
-Setting a property on an entity auto-updates the DB:
+- **Zod schemas → typed database** — define once, types flow everywhere
+- **Auto-migration** — new schema fields auto-add columns on startup
+- **Fluent query builder** — `.where()`, `.orderBy()`, `.limit()`, `.join()`, `.groupBy()`, `.having()`
+- **Rich operators** — `$gt`, `$lt`, `$in`, `$like`, `$isNull`, `$isNotNull`, and more
+- **Aggregates** — `.sum()`, `.avg()`, `.min()`, `.max()`, `.count()`
+- **Pagination** — `.paginate(page, perPage)` with metadata
+- **Relationships** — foreign keys, lazy navigation, fluent joins
+- **Reactivity** — `.on('insert' | 'update' | 'delete', callback)` with trigger-based change tracking
+- **Transactions** — `db.transaction(() => { ... })`
+- **Timestamps** — auto `createdAt`/`updatedAt` with `{ timestamps: true }`
+- **Soft deletes** — `{ softDeletes: true }` with `.withTrashed()`, `.onlyTrashed()`, `.restore()`
+- **Unique constraints** — `{ unique: { users: [['email']] } }`
+- **Schema introspection** — `db.tables()`, `db.columns('users')`
+- **Raw SQL** — `db.raw()` / `db.exec()` escape hatch
+- **Debug mode** — `{ debug: true }` logs all SQL to console
+- **Distinct** — `.distinct()` on queries
+- **Proxy queries** — SQL-like DSL with type-safe column references
 
-```typescript
-const alice = db.users.select().where({ id: 1 }).get()!;
-alice.score = 200;    // → UPDATE users SET score = 200 WHERE id = 1
-```
-
----
-
-## Change Listeners — `db.table.on()`
+## Documentation
 
-Register listeners for insert, update, and delete events. Uses SQLite triggers + a single global poller — no per-listener overhead.
+See [SKILL.md](./SKILL.md) for comprehensive documentation with examples for every feature.
 
-```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:
-
-```typescript
-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
-const db = new Database(':memory:', schemas, {
-  indexes: {
-    users: ['email', ['name', 'role']],
-    books: ['author_id', 'year'],
-  },
-});
-```
-
----
-
-## Transactions
-
-```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
-```
-
----
-
-## Examples & Tests
+## Tests
 
 ```bash
-bun examples/messages-demo.ts  # on() change listener demo
-bun examples/example.ts        # comprehensive demo
-bun test                        # 117 tests
+bun test  # 160 tests, ~1.5s
 ```
 
----
-
-## Benchmarks
-
-All benchmarks run on in-memory SQLite via Bun. Reproduce with:
-
-```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
-```
-
-### Why triggers? — Change detection strategies
-
-We compared three approaches for detecting data changes:
-
-| 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 |
-
-**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.
-
-**Write overhead** for triggers is ~1µs per mutation (one extra INSERT into `_changes`):
-
-| 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 |
-
-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.
-
-### Why MAX(id) fast-path?
-
-The poller checks `SELECT MAX(id) FROM _changes` before fetching rows. On idle (no changes), this avoids materializing any row objects:
-
-| Strategy | Per poll (idle) |
-|---|---|
-| `MAX(id)` check only | **153ns** |
-| `SELECT * WHERE id > ?` (returns 0 rows) | 192ns |
-
-~20% faster on the hot path with no penalty when changes exist.
-
-### Index impact
-
-Benchmarked on 100K rows, 10K queries each:
-
-| 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* |
-
-*\*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.
-
----
-
-## API Reference
-
-| Method | Description |
-|---|---|
-| `new Database(path, schemas, options?)` | Create database with Zod schemas |
-| **Querying** | |
-| `db.table.select(...cols?).where(filter).get()` | Single row |
-| `db.table.select(...cols?).where(filter).all()` | Array of rows |
-| `db.table.select().count()` | Count rows |
-| `db.table.select().join(db.other, cols?).all()` | Fluent join (auto FK) |
-| `db.table.select().with('children').all()` | Eager load related entities (no N+1) |
-| `.where({ relation: entity })` | Filter by entity reference |
-| `db.query(c => { ... })` | Proxy callback (SQL-like JOINs) |
-| **Writing** | |
-| `db.table.insert(data)` | Insert with validation |
-| `db.table.update(id, data)` | Update by ID |
-| `db.table.update(data).where(filter).exec()` | Fluent update |
-| `db.table.upsert(match, data)` | Insert or update |
-| `db.table.delete(id)` | Delete by ID |
-| **Navigation** | |
-| `entity.navMethod()` | Lazy navigation (FK name minus `_id`) |
-| `entity.update(data)` | Update entity in-place |
-| `entity.delete()` | Delete entity |
-| **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
-

package/dist/index.js

@@ -4465,6 +4465,11 @@ class QueryBuilder {
     this.iqo.wheres = this.iqo.wheres.filter((w) => !(w.field === "deletedAt" && w.operator === "IS NULL"));
     return this;
   }
+  onlyTrashed() {
+    this.iqo.wheres = this.iqo.wheres.filter((w) => !(w.field === "deletedAt" && w.operator === "IS NULL"));
+    this.iqo.wheres.push({ field: "deletedAt", operator: "IS NOT NULL", value: null });
+    return this;
+  }
   having(conditions) {
     for (const [field, value] of Object.entries(conditions)) {
       if (typeof value === "object" && value !== null && !Array.isArray(value)) {
@@ -4512,6 +4517,15 @@ class QueryBuilder {
     const data = this.all();
     return { data, total, page, perPage, pages };
   }
+  countGrouped() {
+    if (this.iqo.groupBy.length === 0) {
+      throw new Error("countGrouped() requires at least one groupBy() call");
+    }
+    const groupCols = this.iqo.groupBy.map((c) => `"${c}"`).join(", ");
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT ${groupCols}, COUNT(*) as count FROM`);
+    return this.executor(aggSql, params, true);
+  }
   then(onfulfilled, onrejected) {
     try {
       const result = this.all();
@@ -4897,7 +4911,14 @@ function findMany(ctx, entityName, conditions = {}) {
 }
 function insert(ctx, entityName, data) {
   const schema = ctx.schemas[entityName];
-  const validatedData = asZodObject(schema).passthrough().parse(data);
+  let inputData = { ...data };
+  const hooks = ctx.hooks[entityName];
+  if (hooks?.beforeInsert) {
+    const result2 = hooks.beforeInsert(inputData);
+    if (result2)
+      inputData = result2;
+  }
+  const validatedData = asZodObject(schema).passthrough().parse(inputData);
   const transformed = transformForStorage(validatedData);
   if (ctx.timestamps) {
     const now = new Date().toISOString();
@@ -4913,11 +4934,20 @@ function insert(ctx, entityName, data) {
   const newEntity = getById(ctx, entityName, result.lastInsertRowid);
   if (!newEntity)
     throw new Error("Failed to retrieve entity after insertion");
+  if (hooks?.afterInsert)
+    hooks.afterInsert(newEntity);
   return newEntity;
 }
 function update(ctx, entityName, id, data) {
   const schema = ctx.schemas[entityName];
-  const validatedData = asZodObject(schema).partial().parse(data);
+  let inputData = { ...data };
+  const hooks = ctx.hooks[entityName];
+  if (hooks?.beforeUpdate) {
+    const result = hooks.beforeUpdate(inputData, id);
+    if (result)
+      inputData = result;
+  }
+  const validatedData = asZodObject(schema).partial().parse(inputData);
   const transformed = transformForStorage(validatedData);
   if (Object.keys(transformed).length === 0 && !ctx.timestamps)
     return getById(ctx, entityName, id);
@@ -4929,7 +4959,10 @@ function update(ctx, entityName, id, data) {
   if (ctx.debug)
     console.log("[satidb]", sql, [...Object.values(transformed), id]);
   ctx.db.query(sql).run(...Object.values(transformed), id);
-  return getById(ctx, entityName, id);
+  const updated = getById(ctx, entityName, id);
+  if (hooks?.afterUpdate && updated)
+    hooks.afterUpdate(updated);
+  return updated;
 }
 function updateWhere(ctx, entityName, data, conditions) {
   const schema = ctx.schemas[entityName];
@@ -4969,13 +5002,32 @@ function upsert(ctx, entityName, data, conditions = {}) {
   return insert(ctx, entityName, insertData);
 }
 function deleteEntity(ctx, entityName, id) {
+  const hooks = ctx.hooks[entityName];
+  if (hooks?.beforeDelete) {
+    const result = hooks.beforeDelete(id);
+    if (result === false)
+      return;
+  }
   ctx.db.query(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
+  if (hooks?.afterDelete)
+    hooks.afterDelete(id);
 }
 function deleteWhere(ctx, entityName, conditions) {
   const { clause, values } = ctx.buildWhereClause(conditions);
   if (!clause)
     throw new Error("delete().where() requires at least one condition");
-  const result = ctx.db.query(`DELETE FROM "${entityName}" ${clause}`).run(...values);
+  if (ctx.softDeletes) {
+    const now = new Date().toISOString();
+    const sql2 = `UPDATE "${entityName}" SET "deletedAt" = ? ${clause}`;
+    if (ctx.debug)
+      console.log("[satidb]", sql2, [now, ...values]);
+    const result2 = ctx.db.query(sql2).run(now, ...values);
+    return result2.changes ?? 0;
+  }
+  const sql = `DELETE FROM "${entityName}" ${clause}`;
+  if (ctx.debug)
+    console.log("[satidb]", sql, values);
+  const result = ctx.db.query(sql).run(...values);
   return result.changes ?? 0;
 }
 function createDeleteBuilder(ctx, entityName) {
@@ -4994,10 +5046,17 @@ function insertMany(ctx, entityName, rows) {
     return [];
   const schema = ctx.schemas[entityName];
   const zodSchema = asZodObject(schema).passthrough();
+  const hooks = ctx.hooks[entityName];
   const txn = ctx.db.transaction(() => {
     const ids2 = [];
-    for (const data of rows) {
-      const validatedData = zodSchema.parse(data);
+    for (let data of rows) {
+      let inputData = { ...data };
+      if (hooks?.beforeInsert) {
+        const result2 = hooks.beforeInsert(inputData);
+        if (result2)
+          inputData = result2;
+      }
+      const validatedData = zodSchema.parse(inputData);
       const transformed = transformForStorage(validatedData);
       if (ctx.timestamps) {
         const now = new Date().toISOString();
@@ -5013,7 +5072,24 @@ function insertMany(ctx, entityName, rows) {
     return ids2;
   });
   const ids = txn();
-  return ids.map((id) => getById(ctx, entityName, id)).filter(Boolean);
+  const entities = ids.map((id) => getById(ctx, entityName, id)).filter(Boolean);
+  if (hooks?.afterInsert) {
+    for (const entity of entities)
+      hooks.afterInsert(entity);
+  }
+  return entities;
+}
+function upsertMany(ctx, entityName, rows, conditions = {}) {
+  if (rows.length === 0)
+    return [];
+  const txn = ctx.db.transaction(() => {
+    const results = [];
+    for (const data of rows) {
+      results.push(upsert(ctx, entityName, data, conditions));
+    }
+    return results;
+  });
+  return txn();
 }
 
 // src/entity.ts
@@ -5085,7 +5161,8 @@ class _Database {
       buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix),
       debug: this._debug,
       timestamps: this._timestamps,
-      softDeletes: this._softDeletes
+      softDeletes: this._softDeletes,
+      hooks: options.hooks ?? {}
     };
     this.initializeTables();
     if (this._reactive)
@@ -5093,6 +5170,8 @@ class _Database {
     this.runMigrations();
     if (options.indexes)
       this.createIndexes(options.indexes);
+    if (options.unique)
+      this.createUniqueConstraints(options.unique);
     for (const entityName of Object.keys(schemas)) {
       const key = entityName;
       const accessor = {
@@ -5104,17 +5183,33 @@ class _Database {
           return createUpdateBuilder(this._ctx, entityName, idOrData);
         },
         upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
+        upsertMany: (rows, conditions) => upsertMany(this._ctx, entityName, rows, conditions),
         delete: (id) => {
           if (typeof id === "number") {
+            const hooks = this._ctx.hooks[entityName];
+            if (hooks?.beforeDelete) {
+              const result = hooks.beforeDelete(id);
+              if (result === false)
+                return;
+            }
             if (this._softDeletes) {
               const now = new Date().toISOString();
-              this.db.run(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`, now, id);
+              this.db.query(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
+              if (hooks?.afterDelete)
+                hooks.afterDelete(id);
               return;
             }
             return deleteEntity(this._ctx, entityName, id);
           }
           return createDeleteBuilder(this._ctx, entityName);
         },
+        restore: (id) => {
+          if (!this._softDeletes)
+            throw new Error("restore() requires softDeletes: true");
+          if (this._debug)
+            console.log("[satidb]", `UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`, [id]);
+          this.db.query(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
+        },
         select: (...cols) => createQueryBuilder(this._ctx, entityName, cols),
         on: (event, callback) => {
           return this._registerListener(entityName, event, callback);
@@ -5194,6 +5289,14 @@ class _Database {
       }
     }
   }
+  createUniqueConstraints(unique) {
+    for (const [tableName, groups] of Object.entries(unique)) {
+      for (const cols of groups) {
+        const idxName = `uq_${tableName}_${cols.join("_")}`;
+        this.db.run(`CREATE UNIQUE INDEX IF NOT EXISTS "${idxName}" ON "${tableName}" (${cols.map((c) => `"${c}"`).join(", ")})`);
+      }
+    }
+  }
   _registerListener(table, event, callback) {
     if (!this._reactive) {
       throw new Error("Change listeners are disabled. Set { reactive: true } (or omit it) in Database options to enable .on().");
@@ -5249,7 +5352,7 @@ class _Database {
       }
       this._changeWatermark = change.id;
     }
-    this.db.run('DELETE FROM "_changes" WHERE id <= ?', this._changeWatermark);
+    this.db.query('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
   }
   transaction(callback) {
     return this.db.transaction(callback)();
@@ -5275,6 +5378,12 @@ class _Database {
       console.log("[satidb]", sql, params);
     this.db.run(sql, ...params);
   }
+  tables() {
+    return Object.keys(this.schemas);
+  }
+  columns(tableName) {
+    return this.db.query(`PRAGMA table_info("${tableName}")`).all();
+  }
 }
 var Database = _Database;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",

package/src/builder.ts

@@ -313,6 +313,19 @@ export class QueryBuilder<T extends Record<string, any>> {
         return this;
     }
 
+    /**
+     * Return only soft-deleted rows.
+     * Only relevant when `softDeletes: true` is set in Database options.
+     */
+    onlyTrashed(): this {
+        // Remove the auto-injected `deletedAt IS NULL` and add `deletedAt IS NOT NULL`
+        this.iqo.wheres = this.iqo.wheres.filter(
+            w => !(w.field === 'deletedAt' && w.operator === 'IS NULL')
+        );
+        this.iqo.wheres.push({ field: 'deletedAt', operator: 'IS NOT NULL', value: null });
+        return this;
+    }
+
     /**
      * Add HAVING conditions (used after groupBy for aggregate filtering).
      *
@@ -381,6 +394,28 @@ export class QueryBuilder<T extends Record<string, any>> {
         return { data, total, page, perPage, pages };
     }
 
+    /**
+     * Count rows per group. Must call `.groupBy()` first.
+     * Returns an array of objects with the grouped column(s) and a `count` field.
+     *
+     * ```ts
+     * db.users.select('role').groupBy('role').countGrouped()
+     * // → [{ role: 'admin', count: 5 }, { role: 'member', count: 12 }]
+     * ```
+     */
+    countGrouped(): (Record<string, any> & { count: number })[] {
+        if (this.iqo.groupBy.length === 0) {
+            throw new Error('countGrouped() requires at least one groupBy() call');
+        }
+        const groupCols = this.iqo.groupBy.map(c => `"${c}"`).join(', ');
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const aggSql = selectSql.replace(
+            /^SELECT .+? FROM/,
+            `SELECT ${groupCols}, COUNT(*) as count FROM`
+        );
+        return this.executor(aggSql, params, true) as any;
+    }
+
 
 
     // ---------- Thenable (async/await support) ----------

package/src/context.ts

@@ -5,7 +5,7 @@
  * can access the Database's internals without importing the full class.
  */
 import type { Database as SqliteDatabase } from 'bun:sqlite';
-import type { SchemaMap, Relationship, AugmentedEntity } from './types';
+import type { SchemaMap, Relationship, AugmentedEntity, TableHooks } from './types';
 
 export interface DatabaseContext {
     /** The raw bun:sqlite Database handle. */
@@ -31,4 +31,7 @@ export interface DatabaseContext {
 
     /** Whether soft deletes are enabled (deletedAt column). */
     softDeletes: boolean;
+
+    /** Lifecycle hooks keyed by table name. */
+    hooks: Record<string, TableHooks>;
 }

package/src/crud.ts

@@ -40,7 +40,16 @@ export function findMany(ctx: DatabaseContext, entityName: string, conditions: R
 
 export function insert<T extends Record<string, any>>(ctx: DatabaseContext, entityName: string, data: Omit<T, 'id'>): AugmentedEntity<any> {
     const schema = ctx.schemas[entityName]!;
-    const validatedData = asZodObject(schema).passthrough().parse(data);
+    let inputData = { ...data } as Record<string, any>;
+
+    // beforeInsert hook — can transform data
+    const hooks = ctx.hooks[entityName];
+    if (hooks?.beforeInsert) {
+        const result = hooks.beforeInsert(inputData);
+        if (result) inputData = result;
+    }
+
+    const validatedData = asZodObject(schema).passthrough().parse(inputData);
     const transformed = transformForStorage(validatedData);
 
     // Auto-inject timestamps
@@ -62,12 +71,24 @@ export function insert<T extends Record<string, any>>(ctx: DatabaseContext, enti
     const newEntity = getById(ctx, entityName, result.lastInsertRowid as number);
     if (!newEntity) throw new Error('Failed to retrieve entity after insertion');
 
+    // afterInsert hook
+    if (hooks?.afterInsert) hooks.afterInsert(newEntity);
+
     return newEntity;
 }
 
 export function update<T extends Record<string, any>>(ctx: DatabaseContext, entityName: string, id: number, data: Partial<Omit<T, 'id'>>): AugmentedEntity<any> | null {
     const schema = ctx.schemas[entityName]!;
-    const validatedData = asZodObject(schema).partial().parse(data);
+    let inputData = { ...data } as Record<string, any>;
+
+    // beforeUpdate hook — can transform data
+    const hooks = ctx.hooks[entityName];
+    if (hooks?.beforeUpdate) {
+        const result = hooks.beforeUpdate(inputData, id);
+        if (result) inputData = result;
+    }
+
+    const validatedData = asZodObject(schema).partial().parse(inputData);
     const transformed = transformForStorage(validatedData);
     if (Object.keys(transformed).length === 0 && !ctx.timestamps) return getById(ctx, entityName, id);
 
@@ -81,7 +102,12 @@ export function update<T extends Record<string, any>>(ctx: DatabaseContext, enti
     if (ctx.debug) console.log('[satidb]', sql, [...Object.values(transformed), id]);
     ctx.db.query(sql).run(...Object.values(transformed), id);
 
-    return getById(ctx, entityName, id);
+    const updated = getById(ctx, entityName, id);
+
+    // afterUpdate hook
+    if (hooks?.afterUpdate && updated) hooks.afterUpdate(updated);
+
+    return updated;
 }
 
 export function updateWhere(ctx: DatabaseContext, entityName: string, data: Record<string, any>, conditions: Record<string, any>): number {
@@ -131,14 +157,36 @@ export function upsert<T extends Record<string, any>>(ctx: DatabaseContext, enti
 }
 
 export function deleteEntity(ctx: DatabaseContext, entityName: string, id: number): void {
+    // beforeDelete hook — return false to cancel
+    const hooks = ctx.hooks[entityName];
+    if (hooks?.beforeDelete) {
+        const result = hooks.beforeDelete(id);
+        if (result === false) return;
+    }
+
     ctx.db.query(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
+
+    // afterDelete hook
+    if (hooks?.afterDelete) hooks.afterDelete(id);
 }
 
-/** Delete all rows matching the given conditions. Returns the number of rows deleted. */
+/** Delete all rows matching the given conditions. Returns the number of rows affected. */
 export function deleteWhere(ctx: DatabaseContext, entityName: string, conditions: Record<string, any>): number {
     const { clause, values } = ctx.buildWhereClause(conditions);
     if (!clause) throw new Error('delete().where() requires at least one condition');
-    const result = ctx.db.query(`DELETE FROM "${entityName}" ${clause}`).run(...values);
+
+    if (ctx.softDeletes) {
+        // Soft delete: set deletedAt instead of removing rows
+        const now = new Date().toISOString();
+        const sql = `UPDATE "${entityName}" SET "deletedAt" = ? ${clause}`;
+        if (ctx.debug) console.log('[satidb]', sql, [now, ...values]);
+        const result = ctx.db.query(sql).run(now, ...values);
+        return (result as any).changes ?? 0;
+    }
+
+    const sql = `DELETE FROM "${entityName}" ${clause}`;
+    if (ctx.debug) console.log('[satidb]', sql, values);
+    const result = ctx.db.query(sql).run(...values);
     return (result as any).changes ?? 0;
 }
 
@@ -157,11 +205,20 @@ export function insertMany<T extends Record<string, any>>(ctx: DatabaseContext,
     if (rows.length === 0) return [];
     const schema = ctx.schemas[entityName]!;
     const zodSchema = asZodObject(schema).passthrough();
+    const hooks = ctx.hooks[entityName];
 
     const txn = ctx.db.transaction(() => {
         const ids: number[] = [];
-        for (const data of rows) {
-            const validatedData = zodSchema.parse(data);
+        for (let data of rows) {
+            let inputData = { ...data } as Record<string, any>;
+
+            // beforeInsert hook
+            if (hooks?.beforeInsert) {
+                const result = hooks.beforeInsert(inputData);
+                if (result) inputData = result;
+            }
+
+            const validatedData = zodSchema.parse(inputData);
             const transformed = transformForStorage(validatedData);
 
             if (ctx.timestamps) {
@@ -182,5 +239,27 @@ export function insertMany<T extends Record<string, any>>(ctx: DatabaseContext,
     });
 
     const ids = txn();
-    return ids.map((id: number) => getById(ctx, entityName, id)!).filter(Boolean);
+    const entities = ids.map((id: number) => getById(ctx, entityName, id)!).filter(Boolean);
+
+    // afterInsert hooks
+    if (hooks?.afterInsert) {
+        for (const entity of entities) hooks.afterInsert(entity);
+    }
+
+    return entities;
+}
+
+/** Upsert multiple rows in a single transaction. */
+export function upsertMany<T extends Record<string, any>>(ctx: DatabaseContext, entityName: string, rows: any[], conditions: Record<string, any> = {}): AugmentedEntity<any>[] {
+    if (rows.length === 0) return [];
+
+    const txn = ctx.db.transaction(() => {
+        const results: AugmentedEntity<any>[] = [];
+        for (const data of rows) {
+            results.push(upsert(ctx, entityName, data, conditions));
+        }
+        return results;
+    });
+
+    return txn();
 }

package/src/database.ts

@@ -24,7 +24,7 @@ import type { DatabaseContext } from './context';
 import { buildWhereClause } from './helpers';
 import { attachMethods } from './entity';
 import {
-    insert, insertMany, update, upsert, deleteEntity, createDeleteBuilder,
+    insert, insertMany, update, upsert, upsertMany, deleteEntity, createDeleteBuilder,
     getById, getOne, findMany, updateWhere, createUpdateBuilder,
 } from './crud';
 
@@ -86,12 +86,14 @@ class _Database<Schemas extends SchemaMap> {
             debug: this._debug,
             timestamps: this._timestamps,
             softDeletes: this._softDeletes,
+            hooks: options.hooks ?? {},
         };
 
         this.initializeTables();
         if (this._reactive) this.initializeChangeTracking();
         this.runMigrations();
         if (options.indexes) this.createIndexes(options.indexes);
+        if (options.unique) this.createUniqueConstraints(options.unique);
 
         // Create typed entity accessors (db.users, db.posts, etc.)
         for (const entityName of Object.keys(schemas)) {
@@ -104,18 +106,31 @@ class _Database<Schemas extends SchemaMap> {
                     return createUpdateBuilder(this._ctx, entityName, idOrData);
                 },
                 upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
+                upsertMany: (rows: any[], conditions?: any) => upsertMany(this._ctx, entityName, rows, conditions),
                 delete: ((id?: any) => {
                     if (typeof id === 'number') {
+                        // beforeDelete hook — return false to cancel
+                        const hooks = this._ctx.hooks[entityName];
+                        if (hooks?.beforeDelete) {
+                            const result = hooks.beforeDelete(id);
+                            if (result === false) return;
+                        }
                         if (this._softDeletes) {
                             // Soft delete: set deletedAt instead of removing
                             const now = new Date().toISOString();
-                            this.db.run(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`, now, id);
+                            this.db.query(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
+                            if (hooks?.afterDelete) hooks.afterDelete(id);
                             return;
                         }
                         return deleteEntity(this._ctx, entityName, id);
                     }
                     return createDeleteBuilder(this._ctx, entityName);
                 }) as any,
+                restore: ((id: number) => {
+                    if (!this._softDeletes) throw new Error('restore() requires softDeletes: true');
+                    if (this._debug) console.log('[satidb]', `UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`, [id]);
+                    this.db.query(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
+                }) as any,
                 select: (...cols: string[]) => createQueryBuilder(this._ctx, entityName, cols),
                 on: (event: ChangeEvent, callback: (row: any) => void | Promise<void>) => {
                     return this._registerListener(entityName, event, callback);
@@ -228,6 +243,15 @@ class _Database<Schemas extends SchemaMap> {
         }
     }
 
+    private createUniqueConstraints(unique: Record<string, string[][]>): void {
+        for (const [tableName, groups] of Object.entries(unique)) {
+            for (const cols of groups) {
+                const idxName = `uq_${tableName}_${cols.join('_')}`;
+                this.db.run(`CREATE UNIQUE INDEX IF NOT EXISTS "${idxName}" ON "${tableName}" (${cols.map(c => `"${c}"`).join(', ')})`);
+            }
+        }
+    }
+
     // =========================================================================
     // Change Listeners — db.table.on('insert' | 'update' | 'delete', cb)
     // =========================================================================
@@ -306,7 +330,7 @@ class _Database<Schemas extends SchemaMap> {
         }
 
         // Clean up consumed changes
-        this.db.run('DELETE FROM "_changes" WHERE id <= ?', this._changeWatermark);
+        this.db.query('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
     }
 
     // =========================================================================
@@ -356,6 +380,20 @@ class _Database<Schemas extends SchemaMap> {
         if (this._debug) console.log('[satidb]', sql, params);
         this.db.run(sql, ...params);
     }
+
+    // =========================================================================
+    // Schema Introspection
+    // =========================================================================
+
+    /** Return the list of user-defined table names. */
+    public tables(): string[] {
+        return Object.keys(this.schemas);
+    }
+
+    /** Return column info for a table via PRAGMA table_info. */
+    public columns(tableName: string): { name: string; type: string; notnull: number; pk: number }[] {
+        return this.db.query(`PRAGMA table_info("${tableName}")`).all() as any[];
+    }
 }
 
 // =============================================================================

package/src/types.ts

@@ -19,8 +19,24 @@ export const asZodObject = (s: z.ZodType<any>) => s as unknown as z.ZodObject<an
 /** Index definition: single column or composite columns */
 export type IndexDef = string | string[];
 
+/** Lifecycle hooks for a single table. */
+export type TableHooks = {
+    beforeInsert?: (data: Record<string, any>) => Record<string, any> | void;
+    afterInsert?: (entity: Record<string, any>) => void;
+    beforeUpdate?: (data: Record<string, any>, id: number) => Record<string, any> | void;
+    afterUpdate?: (entity: Record<string, any>) => void;
+    beforeDelete?: (id: number) => false | void;
+    afterDelete?: (id: number) => void;
+};
+
 export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
     indexes?: Record<string, IndexDef[]>;
+    /**
+     * Unique constraints per table. Each entry is an array of column groups.
+     * Single column: `{ users: [['email']] }` → UNIQUE INDEX.
+     * Compound: `{ users: [['email'], ['name', 'org_id']] }` → two UNIQUE indexes.
+     */
+    unique?: Record<string, string[][]>;
     /**
      * Declare relationships between tables.
      *
@@ -59,6 +75,17 @@ export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
      * Default: `false`.
      */
     debug?: boolean;
+    /**
+     * Lifecycle hooks per table. Each hook receives data and can transform it.
+     *
+     * - `beforeInsert(data)` — called before insert, return modified data or void
+     * - `afterInsert(entity)` — called after insert with the persisted entity
+     * - `beforeUpdate(data, id)` — called before update, return modified data or void
+     * - `afterUpdate(entity)` — called after update with the updated entity
+     * - `beforeDelete(id)` — called before delete, return false to cancel
+     * - `afterDelete(id)` — called after delete
+     */
+    hooks?: Record<string, TableHooks>;
 };
 
 export type Relationship = {
@@ -178,7 +205,9 @@ export type NavEntityAccessor<
     update: ((id: number, data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => NavEntity<S, R, Table> | null)
     & ((data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => UpdateBuilder<NavEntity<S, R, Table>>);
     upsert: (conditions?: Partial<z.infer<S[Table & keyof S]>>, data?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>;
+    upsertMany: (rows: Partial<z.infer<S[Table & keyof S]>>[], conditions?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>[];
     delete: ((id: number) => void) & (() => DeleteBuilder<NavEntity<S, R, Table>>);
+    restore: (id: number) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
     on: ((event: 'insert' | 'update', callback: (row: NavEntity<S, R, Table>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);
@@ -208,7 +237,10 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     insertMany: (rows: EntityData<S>[]) => AugmentedEntity<S>[];
     update: ((id: number, data: Partial<EntityData<S>>) => AugmentedEntity<S> | null) & ((data: Partial<EntityData<S>>) => UpdateBuilder<AugmentedEntity<S>>);
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
+    upsertMany: (rows: Partial<InferSchema<S>>[], conditions?: Partial<InferSchema<S>>) => AugmentedEntity<S>[];
     delete: ((id: number) => void) & (() => DeleteBuilder<AugmentedEntity<S>>);
+    /** Undo a soft delete by setting deletedAt = null. Requires softDeletes. */
+    restore: (id: number) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
     on: ((event: 'insert' | 'update', callback: (row: AugmentedEntity<S>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);