sqlite-zod-orm 3.19.0 → 3.21.0

package/README.md

@@ -1,18 +1,11 @@
 # sqlite-zod-orm
 
-**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
+Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL.
 
 ```bash
 bun add sqlite-zod-orm
 ```
 
-> **Requires Bun runtime** — uses `bun:sqlite` under the hood.
-
 ## Quick Start
 
 ```typescript
@@ -22,58 +15,224 @@ const db = new Database('app.db', {
     users: z.object({
         name: z.string(),
         email: z.string(),
-        role: z.string().default('member'),
+        score: z.number().default(0),
     }),
+    posts: z.object({
+        title: z.string(),
+        body: z.string(),
+        userId: z.number(),
+    }),
+}, {
+    relations: { posts: { userId: 'users' } },
+    timestamps: true,
+    softDeletes: true,
 });
+```
 
+Tables are auto-created and auto-migrated from your Zod schemas. No SQL required.
+
+## CRUD
+
+```typescript
 // Insert
-const alice = db.users.insert({ name: 'Alice', email: 'alice@co.com' });
-alice.id; // auto-increment ID
-alice.role; // 'member' (from Zod default)
-
-// Query
-const admins = db.users.select()
-    .where({ role: 'admin' })
-    .orderBy('name')
-    .all();
+const user = db.users.insert({ name: 'Alice', email: 'alice@co.com' });
 
-// Update
-alice.name = 'Alice Smith'; // auto-persists
+// Read
+const all = db.users.select().all();
+const one = db.users.get(1);
+const found = db.users.select().where({ name: 'Alice' }).first();
+
+// Update (auto-persists via proxy)
+user.score = 100;  // ← saved to DB automatically
 
 // Delete
-db.users.delete(alice.id);
+db.users.delete(1);
+
+// Batch
+db.users.insertMany([{ name: 'Bob', email: 'b@co.com' }, { name: 'Charlie', email: 'c@co.com' }]);
+db.users.upsertMany([{ id: 1, name: 'Updated Alice' }], 'id');
 ```
 
-## Features
+## Fluent Query Builder
 
-- **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
+db.users.select()
+    .where({ score: { $gte: 50 } })
+    .orderBy('score', 'DESC')
+    .limit(10)
+    .all();
 
-## Documentation
+// Operators: $gt, $gte, $lt, $lte, $ne, $like, $in, $notIn, $between
+db.users.select().where({ name: { $like: '%ali%' } }).all();
 
-See [SKILL.md](./SKILL.md) for comprehensive documentation with examples for every feature.
+// whereIn / whereNotIn (array or subquery)
+db.users.select().whereIn('id', [1, 2, 3]).all();
+const sub = db.orders.select('userId');
+db.users.select().whereIn('id', sub).all();
 
-## Tests
+// Raw WHERE fragments
+db.users.select().whereRaw('score > ? AND name != ?', [50, 'Bot']).all();
+```
 
-```bash
-bun test  # 160 tests, ~1.5s
+## Relationships
+
+```typescript
+// Navigation (lazy, proxy-based)
+const post = db.posts.get(1);
+post.user;           // → related user object
+const user = db.users.get(1);
+user.posts;          // → array of user's posts
+
+// Eager loading (no N+1)
+db.posts.select().with('user').all();
 ```
 
+## Aggregates
+
+```typescript
+db.users.count();                                   // shorthand
+db.users.select().where({ role: 'admin' }).count(); // filtered
+db.users.select().sum('score');
+db.users.select().avg('score');
+db.users.select().min('score');
+db.users.select().max('score');
+```
+
+## Batch Mutations
+
+```typescript
+db.users.select().where({ role: 'guest' }).updateAll({ role: 'member' }); // → affected count
+db.users.select().where({ role: 'spam' }).deleteAll();                    // → deleted count
+```
+
+## Pagination
+
+```typescript
+const page = db.users.select().orderBy('name').paginate(1, 20);
+// { data: [...], total: 42, page: 1, perPage: 20, pages: 3 }
+```
+
+## Select Type Narrowing
+
+```typescript
+const names = db.users.select('name', 'email').all();
+names[0].name;  // ✅ string
+names[0].score; // ❌ TypeScript error — not selected
+```
+
+## Computed Getters
+
+```typescript
+const db = new Database(':memory:', { users: UserSchema }, {
+    computed: {
+        users: { fullName: (u) => `${u.first} ${u.last}` },
+    },
+});
+user.fullName; // 'Alice Smith' — recomputes on access
+```
+
+## Cascade Deletes
+
+```typescript
+const db = new Database(':memory:', { authors: AuthorSchema, books: BookSchema }, {
+    relations: { books: { author_id: 'authors' } },
+    cascade: { authors: ['books'] },
+});
+db.authors.delete(1); // → books with author_id=1 also deleted
+```
+
+## Transactions
+
+```typescript
+db.transaction(() => {
+    db.users.insert({ name: 'Alice' });
+    db.orders.insert({ userId: 1, amount: 100 });
+}); // auto-commits; rolls back on error
+```
+
+## Data Import / Export
+
+```typescript
+const backup = db.dump();                      // export all tables as JSON
+db.load(backup);                               // restore (truncates first)
+db.load(backup, { append: true });             // restore without truncating
+db.seed({ users: [{ name: 'Test User' }] });   // additive fixture seeding
+```
+
+## Schema Diffing
+
+```typescript
+const diff = db.diff();
+// { users: { added: ['bio'], removed: ['legacy'], typeChanged: [] } }
+```
+
+## Lifecycle Hooks
+
+```typescript
+const db = new Database(':memory:', { users: UserSchema }, {
+    hooks: {
+        users: {
+            beforeInsert: (data) => ({ ...data, name: data.name.trim() }),
+            afterInsert: (entity) => console.log('Created:', entity.id),
+            beforeUpdate: (id, data) => data,
+            afterUpdate: (entity) => {},
+            beforeDelete: (id) => true,  // return false to cancel
+            afterDelete: (id) => {},
+        },
+    },
+});
+```
+
+## Soft Deletes & Timestamps
+
+```typescript
+// With softDeletes: true
+db.users.delete(1);                                  // sets deletedAt
+db.users.select().all();                             // excludes deleted
+db.users.select().withTrashed().all();               // includes deleted
+db.users.select().onlyTrashed().all();               // only deleted
+db.users.restore(1);                                 // un-deletes
+
+// With timestamps: true
+user.createdAt;  // auto-set on insert
+user.updatedAt;  // auto-bumped on update
+```
+
+## Raw SQL
+
+```typescript
+db.raw<User>('SELECT * FROM users WHERE score > ?', 50);
+db.exec('UPDATE users SET score = 0 WHERE role = ?', 'guest');
+```
+
+## Full Feature List
+
+- Zod-powered schema definition & runtime validation
+- Auto table creation & migration (add columns)
+- Fluent query builder with 10+ operators
+- Type-safe select narrowing
+- Relationship navigation (lazy proxy + eager loading)
+- Soft deletes, timestamps, auto-persist proxy
+- Lifecycle hooks (before/after insert/update/delete)
+- Aggregates (sum, avg, min, max, count, countGrouped)
+- Batch mutations (insertMany, upsertMany, updateAll, deleteAll, findOrCreate)
+- Cascade deletes
+- Computed/virtual getters
+- Data import/export (dump, load, seed)
+- Schema diffing
+- Transactions
+- Pagination
+- whereIn/whereNotIn with subquery support
+- JSON column auto-serialization
+- Unique constraints
+- Debug mode (SQL logging)
+- Raw SQL escape hatch
+
+## Requirements
+
+- **Bun** ≥ 1.0 (uses `bun:sqlite` native bindings)
+- **Zod** ≥ 3.0
+
 ## License
 
 MIT

package/dist/index.js

@@ -4572,6 +4572,17 @@ class QueryBuilder {
     const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT ${groupCols}, COUNT(*) as count FROM`);
     return this.executor(aggSql, params, true);
   }
+  pluck(column) {
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const pluckSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT "${column}" FROM`);
+    const results = this.executor(pluckSql, params, true);
+    return results.map((r) => r[column]);
+  }
+  clone() {
+    const cloned = new QueryBuilder(this.tableName, this.executor, this.singleExecutor, this.joinResolver, this.conditionResolver, this.eagerLoader);
+    cloned.iqo = JSON.parse(JSON.stringify(this.iqo));
+    return cloned;
+  }
   updateAll(data) {
     const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
     const whereMatch = selectSql.match(/WHERE (.+?)(?:\s+ORDER|\s+LIMIT|\s+GROUP|\s+HAVING|$)/s);
@@ -5235,7 +5246,8 @@ class _Database {
   _pollInterval;
   constructor(dbFile, schemas, options = {}) {
     this.db = new SqliteDatabase(dbFile);
-    this.db.run("PRAGMA journal_mode = WAL");
+    if (options.wal !== false)
+      this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA foreign_keys = ON");
     this.schemas = schemas;
     this.options = options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.19.0",
+  "version": "3.21.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

@@ -465,6 +465,36 @@ export class QueryBuilder<T extends Record<string, any>, TResult extends Record<
         return this.executor(aggSql, params, true) as any;
     }
 
+    // ---------- Convenience Methods ----------
+
+    /**
+     * Return a flat array of values for a single column.
+     * ```ts
+     * db.users.select().pluck('name') // → ['Alice', 'Bob', 'Charlie']
+     * ```
+     */
+    pluck(column: keyof T & string): any[] {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const pluckSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT "${column}" FROM`);
+        const results = this.executor(pluckSql, params, true);
+        return results.map((r: any) => r[column]);
+    }
+
+    /** Clone this QueryBuilder so you can fork a query. */
+    clone(): QueryBuilder<T, TResult> {
+        const cloned = new QueryBuilder<T, TResult>(
+            this.tableName,
+            this.executor,
+            this.singleExecutor,
+            this.joinResolver,
+            this.conditionResolver,
+            this.eagerLoader,
+        );
+        // Deep-copy the IQO state
+        (cloned as any).iqo = JSON.parse(JSON.stringify(this.iqo));
+        return cloned;
+    }
+
     // ---------- Batch Mutations ----------
 
     /**

package/src/database.ts

@@ -65,7 +65,7 @@ class _Database<Schemas extends SchemaMap> {
 
     constructor(dbFile: string, schemas: Schemas, options: DatabaseOptions = {}) {
         this.db = new SqliteDatabase(dbFile);
-        this.db.run('PRAGMA journal_mode = WAL');
+        if (options.wal !== false) this.db.run('PRAGMA journal_mode = WAL');
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;

package/src/types.ts

@@ -75,6 +75,12 @@ export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
      * Default: `false`.
      */
     debug?: boolean;
+    /**
+     * Enable WAL (Write-Ahead Logging) journal mode for better
+     * concurrent read/write performance. Recommended for production.
+     * Default: `false`.
+     */
+    wal?: boolean;
     /**
      * Lifecycle hooks per table. Each hook receives data and can transform it.
      *