sqlite-zod-orm 3.10.0 → 3.11.0

package/dist/index.js

@@ -4149,7 +4149,9 @@ var OPERATOR_MAP = {
   $in: "IN",
   $like: "LIKE",
   $notIn: "NOT IN",
-  $between: "BETWEEN"
+  $between: "BETWEEN",
+  $isNull: "IS NULL",
+  $isNotNull: "IS NOT NULL"
 };
 function transformValueForStorage(value) {
   if (value instanceof Date)
@@ -4173,7 +4175,7 @@ function compileIQO(tableName, iqo) {
       selectParts.push(`${j.table}.*`);
     }
   }
-  let sql = `SELECT ${selectParts.join(", ")} FROM ${tableName}`;
+  let sql = `SELECT ${iqo.distinct ? "DISTINCT " : ""}${selectParts.join(", ")} FROM ${tableName}`;
   for (const j of iqo.joins) {
     sql += ` JOIN ${j.table} ON ${tableName}.${j.fromCol} = ${j.table}.${j.toCol}`;
   }
@@ -4206,6 +4208,10 @@ function compileIQO(tableName, iqo) {
         const [min, max] = w.value;
         whereParts.push(`${qualify(w.field)} BETWEEN ? AND ?`);
         params.push(transformValueForStorage(min), transformValueForStorage(max));
+      } else if (w.operator === "IS NULL") {
+        whereParts.push(`${qualify(w.field)} IS NULL`);
+      } else if (w.operator === "IS NOT NULL") {
+        whereParts.push(`${qualify(w.field)} IS NOT NULL`);
       } else {
         whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
         params.push(transformValueForStorage(w.value));
@@ -4241,6 +4247,22 @@ function compileIQO(tableName, iqo) {
   if (iqo.groupBy.length > 0) {
     sql += ` GROUP BY ${iqo.groupBy.join(", ")}`;
   }
+  if (iqo.having && iqo.having.length > 0) {
+    const havingParts = [];
+    for (const h of iqo.having) {
+      if (h.operator === "IS NULL") {
+        havingParts.push(`${h.field} IS NULL`);
+      } else if (h.operator === "IS NOT NULL") {
+        havingParts.push(`${h.field} IS NOT NULL`);
+      } else {
+        havingParts.push(`${h.field} ${h.operator} ?`);
+        params.push(transformValueForStorage(h.value));
+      }
+    }
+    if (havingParts.length > 0) {
+      sql += ` HAVING ${havingParts.join(" AND ")}`;
+    }
+  }
   if (iqo.orderBy.length > 0) {
     const parts = iqo.orderBy.map((o) => `${o.field} ${o.direction.toUpperCase()}`);
     sql += ` ORDER BY ${parts.join(", ")}`;
@@ -4274,11 +4296,13 @@ class QueryBuilder {
       whereAST: null,
       joins: [],
       groupBy: [],
+      having: [],
       limit: null,
       offset: null,
       orderBy: [],
       includes: [],
-      raw: false
+      raw: false,
+      distinct: false
     };
   }
   select(...cols) {
@@ -4433,6 +4457,61 @@ class QueryBuilder {
     this.iqo.groupBy.push(...fields);
     return this;
   }
+  distinct() {
+    this.iqo.distinct = true;
+    return this;
+  }
+  withTrashed() {
+    this.iqo.wheres = this.iqo.wheres.filter((w) => !(w.field === "deletedAt" && w.operator === "IS NULL"));
+    return this;
+  }
+  having(conditions) {
+    for (const [field, value] of Object.entries(conditions)) {
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        for (const [opKey, operand] of Object.entries(value)) {
+          const sqlOp = OPERATOR_MAP[opKey];
+          if (!sqlOp)
+            throw new Error(`Unsupported having operator: '${opKey}'`);
+          this.iqo.having.push({ field, operator: sqlOp, value: operand });
+        }
+      } else {
+        this.iqo.having.push({ field, operator: "=", value });
+      }
+    }
+    return this;
+  }
+  sum(field) {
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT COALESCE(SUM("${field}"), 0) as val FROM`);
+    const results = this.executor(aggSql, params, true);
+    return results[0]?.val ?? 0;
+  }
+  avg(field) {
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT AVG("${field}") as val FROM`);
+    const results = this.executor(aggSql, params, true);
+    return results[0]?.val ?? 0;
+  }
+  min(field) {
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT MIN("${field}") as val FROM`);
+    const results = this.executor(aggSql, params, true);
+    return results[0]?.val ?? null;
+  }
+  max(field) {
+    const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+    const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT MAX("${field}") as val FROM`);
+    const results = this.executor(aggSql, params, true);
+    return results[0]?.val ?? null;
+  }
+  paginate(page = 1, perPage = 20) {
+    const total = this.count();
+    const pages = Math.ceil(total / perPage);
+    this.iqo.limit = perPage;
+    this.iqo.offset = (page - 1) * perPage;
+    const data = this.all();
+    return { data, total, page, perPage, pages };
+  }
   then(onfulfilled, onrejected) {
     try {
       const result = this.all();
@@ -4638,6 +4717,8 @@ function executeProxyQuery(schemas, callback, executor) {
 function createQueryBuilder(ctx, entityName, initialCols) {
   const schema = ctx.schemas[entityName];
   const executor = (sql, params, raw) => {
+    if (ctx.debug)
+      console.log("[satidb]", sql, params);
     const rows = ctx.db.query(sql).all(...params);
     if (raw)
       return rows;
@@ -4707,6 +4788,9 @@ function createQueryBuilder(ctx, entityName, initialCols) {
   const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, eagerLoader);
   if (initialCols.length > 0)
     builder.select(...initialCols);
+  if (ctx.softDeletes) {
+    builder.where({ deletedAt: { $isNull: true } });
+  }
   return builder;
 }
 
@@ -4771,6 +4855,14 @@ function buildWhereClause(conditions, tablePrefix) {
         values.push(transformForStorage({ v: operand[0] }).v, transformForStorage({ v: operand[1] }).v);
         continue;
       }
+      if (operator === "$isNull") {
+        parts.push(`${fieldName} IS NULL`);
+        continue;
+      }
+      if (operator === "$isNotNull") {
+        parts.push(`${fieldName} IS NOT NULL`);
+        continue;
+      }
       const sqlOp = { $gt: ">", $gte: ">=", $lt: "<", $lte: "<=", $ne: "!=" }[operator];
       if (!sqlOp)
         throw new Error(`Unsupported operator '${operator}' on '${key}'`);
@@ -4807,9 +4899,16 @@ function insert(ctx, entityName, data) {
   const schema = ctx.schemas[entityName];
   const validatedData = asZodObject(schema).passthrough().parse(data);
   const transformed = transformForStorage(validatedData);
+  if (ctx.timestamps) {
+    const now = new Date().toISOString();
+    transformed.createdAt = now;
+    transformed.updatedAt = now;
+  }
   const columns = Object.keys(transformed);
   const quotedCols = columns.map((c) => `"${c}"`);
   const sql = columns.length === 0 ? `INSERT INTO "${entityName}" DEFAULT VALUES` : `INSERT INTO "${entityName}" (${quotedCols.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`;
+  if (ctx.debug)
+    console.log("[satidb]", sql, Object.values(transformed));
   const result = ctx.db.query(sql).run(...Object.values(transformed));
   const newEntity = getById(ctx, entityName, result.lastInsertRowid);
   if (!newEntity)
@@ -4820,10 +4919,16 @@ function update(ctx, entityName, id, data) {
   const schema = ctx.schemas[entityName];
   const validatedData = asZodObject(schema).partial().parse(data);
   const transformed = transformForStorage(validatedData);
-  if (Object.keys(transformed).length === 0)
+  if (Object.keys(transformed).length === 0 && !ctx.timestamps)
     return getById(ctx, entityName, id);
+  if (ctx.timestamps) {
+    transformed.updatedAt = new Date().toISOString();
+  }
   const setClause = Object.keys(transformed).map((key) => `"${key}" = ?`).join(", ");
-  ctx.db.query(`UPDATE "${entityName}" SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
+  const sql = `UPDATE "${entityName}" SET ${setClause} WHERE id = ?`;
+  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);
 }
 function updateWhere(ctx, entityName, data, conditions) {
@@ -4894,6 +4999,11 @@ function insertMany(ctx, entityName, rows) {
     for (const data of rows) {
       const validatedData = zodSchema.parse(data);
       const transformed = transformForStorage(validatedData);
+      if (ctx.timestamps) {
+        const now = new Date().toISOString();
+        transformed.createdAt = now;
+        transformed.updatedAt = now;
+      }
       const columns = Object.keys(transformed);
       const quotedCols = columns.map((c) => `"${c}"`);
       const sql = columns.length === 0 ? `INSERT INTO "${entityName}" DEFAULT VALUES` : `INSERT INTO "${entityName}" (${quotedCols.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`;
@@ -4944,6 +5054,9 @@ function attachMethods(ctx, entityName, entity) {
 class _Database {
   db;
   _reactive;
+  _timestamps;
+  _softDeletes;
+  _debug;
   schemas;
   relationships;
   options;
@@ -4959,6 +5072,9 @@ class _Database {
     this.schemas = schemas;
     this.options = options;
     this._reactive = options.reactive !== false;
+    this._timestamps = options.timestamps === true;
+    this._softDeletes = options.softDeletes === true;
+    this._debug = options.debug === true;
     this._pollInterval = options.pollInterval ?? 100;
     this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
     this._ctx = {
@@ -4966,7 +5082,10 @@ class _Database {
       schemas: this.schemas,
       relationships: this.relationships,
       attachMethods: (name, entity) => attachMethods(this._ctx, name, entity),
-      buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix)
+      buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix),
+      debug: this._debug,
+      timestamps: this._timestamps,
+      softDeletes: this._softDeletes
     };
     this.initializeTables();
     if (this._reactive)
@@ -4986,8 +5105,14 @@ class _Database {
         },
         upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
         delete: (id) => {
-          if (typeof id === "number")
+          if (typeof id === "number") {
+            if (this._softDeletes) {
+              const now = new Date().toISOString();
+              this.db.run(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`, now, id);
+              return;
+            }
             return deleteEntity(this._ctx, entityName, id);
+          }
           return createDeleteBuilder(this._ctx, entityName);
         },
         select: (...cols) => createQueryBuilder(this._ctx, entityName, cols),
@@ -5003,6 +5128,13 @@ class _Database {
     for (const [entityName, schema] of Object.entries(this.schemas)) {
       const storableFields = getStorableFields(schema);
       const columnDefs = storableFields.map((f) => `"${f.name}" ${zodTypeToSqlType(f.type)}`);
+      if (this._timestamps) {
+        columnDefs.push('"createdAt" TEXT');
+        columnDefs.push('"updatedAt" TEXT');
+      }
+      if (this._softDeletes) {
+        columnDefs.push('"deletedAt" TEXT');
+      }
       const constraints = [];
       const belongsToRels = this.relationships.filter((rel) => rel.type === "belongs-to" && rel.from === entityName);
       for (const rel of belongsToRels) {
@@ -5127,7 +5259,21 @@ class _Database {
     this.db.close();
   }
   query(callback) {
-    return executeProxyQuery(this.schemas, callback, (sql, params) => this.db.query(sql).all(...params));
+    return executeProxyQuery(this.schemas, callback, (sql, params) => {
+      if (this._debug)
+        console.log("[satidb]", sql, params);
+      return this.db.query(sql).all(...params);
+    });
+  }
+  raw(sql, ...params) {
+    if (this._debug)
+      console.log("[satidb]", sql, params);
+    return this.db.query(sql).all(...params);
+  }
+  exec(sql, ...params) {
+    if (this._debug)
+      console.log("[satidb]", sql, params);
+    this.db.run(sql, ...params);
   }
 }
 var Database = _Database;

package/package.json

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

@@ -57,11 +57,13 @@ export class QueryBuilder<T extends Record<string, any>> {
             whereAST: null,
             joins: [],
             groupBy: [],
+            having: [],
             limit: null,
             offset: null,
             orderBy: [],
             includes: [],
             raw: false,
+            distinct: false,
         };
     }
 
@@ -293,6 +295,92 @@ export class QueryBuilder<T extends Record<string, any>> {
         return this;
     }
 
+    /** Return only distinct rows. */
+    distinct(): this {
+        this.iqo.distinct = true;
+        return this;
+    }
+
+    /**
+     * Include soft-deleted rows in query results.
+     * Only relevant when `softDeletes: true` is set in Database options.
+     */
+    withTrashed(): this {
+        // Remove the auto-injected `deletedAt IS NULL` filter
+        this.iqo.wheres = this.iqo.wheres.filter(
+            w => !(w.field === 'deletedAt' && w.operator === 'IS NULL')
+        );
+        return this;
+    }
+
+    /**
+     * Add HAVING conditions (used after groupBy for aggregate filtering).
+     *
+     * ```ts
+     * db.orders.select('user_id').groupBy('user_id')
+     *   .having({ 'COUNT(*)': { $gt: 5 } })
+     *   .raw().all()
+     * ```
+     */
+    having(conditions: Record<string, any>): this {
+        for (const [field, value] of Object.entries(conditions)) {
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                for (const [opKey, operand] of Object.entries(value)) {
+                    const sqlOp = OPERATOR_MAP[opKey as WhereOperator];
+                    if (!sqlOp) throw new Error(`Unsupported having operator: '${opKey}'`);
+                    this.iqo.having.push({ field, operator: sqlOp as WhereCondition['operator'], value: operand });
+                }
+            } else {
+                this.iqo.having.push({ field, operator: '=', value });
+            }
+        }
+        return this;
+    }
+
+    // ---------- Aggregate Methods ----------
+
+    /** Returns the SUM of a numeric column. */
+    sum(field: keyof T & string): number {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT COALESCE(SUM("${field}"), 0) as val FROM`);
+        const results = this.executor(aggSql, params, true);
+        return (results[0] as any)?.val ?? 0;
+    }
+
+    /** Returns the AVG of a numeric column. */
+    avg(field: keyof T & string): number {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT AVG("${field}") as val FROM`);
+        const results = this.executor(aggSql, params, true);
+        return (results[0] as any)?.val ?? 0;
+    }
+
+    /** Returns the MIN of a column. */
+    min(field: keyof T & string): number | string | null {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT MIN("${field}") as val FROM`);
+        const results = this.executor(aggSql, params, true);
+        return (results[0] as any)?.val ?? null;
+    }
+
+    /** Returns the MAX of a column. */
+    max(field: keyof T & string): number | string | null {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT MAX("${field}") as val FROM`);
+        const results = this.executor(aggSql, params, true);
+        return (results[0] as any)?.val ?? null;
+    }
+
+    /** Paginate results. Returns { data, total, page, perPage, pages }. */
+    paginate(page: number = 1, perPage: number = 20): { data: T[]; total: number; page: number; perPage: number; pages: number } {
+        const total = this.count();
+        const pages = Math.ceil(total / perPage);
+        this.iqo.limit = perPage;
+        this.iqo.offset = (page - 1) * perPage;
+        const data = this.all();
+        return { data, total, page, perPage, pages };
+    }
+
 
 
     // ---------- Thenable (async/await support) ----------

package/src/context.ts

@@ -22,4 +22,13 @@ export interface DatabaseContext {
 
     /** Build a WHERE clause from a conditions object. */
     buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] };
+
+    /** Whether to log SQL to console. */
+    debug: boolean;
+
+    /** Whether tables have createdAt/updatedAt columns. */
+    timestamps: boolean;
+
+    /** Whether soft deletes are enabled (deletedAt column). */
+    softDeletes: boolean;
 }

package/src/crud.ts

@@ -42,6 +42,14 @@ export function insert<T extends Record<string, any>>(ctx: DatabaseContext, enti
     const schema = ctx.schemas[entityName]!;
     const validatedData = asZodObject(schema).passthrough().parse(data);
     const transformed = transformForStorage(validatedData);
+
+    // Auto-inject timestamps
+    if (ctx.timestamps) {
+        const now = new Date().toISOString();
+        transformed.createdAt = now;
+        transformed.updatedAt = now;
+    }
+
     const columns = Object.keys(transformed);
 
     const quotedCols = columns.map(c => `"${c}"`);
@@ -49,6 +57,7 @@ export function insert<T extends Record<string, any>>(ctx: DatabaseContext, enti
         ? `INSERT INTO "${entityName}" DEFAULT VALUES`
         : `INSERT INTO "${entityName}" (${quotedCols.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`;
 
+    if (ctx.debug) console.log('[satidb]', sql, Object.values(transformed));
     const result = ctx.db.query(sql).run(...Object.values(transformed));
     const newEntity = getById(ctx, entityName, result.lastInsertRowid as number);
     if (!newEntity) throw new Error('Failed to retrieve entity after insertion');
@@ -60,10 +69,17 @@ export function update<T extends Record<string, any>>(ctx: DatabaseContext, enti
     const schema = ctx.schemas[entityName]!;
     const validatedData = asZodObject(schema).partial().parse(data);
     const transformed = transformForStorage(validatedData);
-    if (Object.keys(transformed).length === 0) return getById(ctx, entityName, id);
+    if (Object.keys(transformed).length === 0 && !ctx.timestamps) return getById(ctx, entityName, id);
+
+    // Auto-update timestamp
+    if (ctx.timestamps) {
+        transformed.updatedAt = new Date().toISOString();
+    }
 
     const setClause = Object.keys(transformed).map(key => `"${key}" = ?`).join(', ');
-    ctx.db.query(`UPDATE "${entityName}" SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
+    const sql = `UPDATE "${entityName}" SET ${setClause} WHERE id = ?`;
+    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);
 }
@@ -147,6 +163,13 @@ export function insertMany<T extends Record<string, any>>(ctx: DatabaseContext,
         for (const data of rows) {
             const validatedData = zodSchema.parse(data);
             const transformed = transformForStorage(validatedData);
+
+            if (ctx.timestamps) {
+                const now = new Date().toISOString();
+                transformed.createdAt = now;
+                transformed.updatedAt = now;
+            }
+
             const columns = Object.keys(transformed);
             const quotedCols = columns.map(c => `"${c}"`);
             const sql = columns.length === 0

package/src/database.ts

@@ -41,6 +41,9 @@ type Listener = {
 class _Database<Schemas extends SchemaMap> {
     private db: SqliteDatabase;
     private _reactive: boolean;
+    private _timestamps: boolean;
+    private _softDeletes: boolean;
+    private _debug: boolean;
     private schemas: Schemas;
     private relationships: Relationship[];
     private options: DatabaseOptions;
@@ -67,6 +70,9 @@ class _Database<Schemas extends SchemaMap> {
         this.schemas = schemas;
         this.options = options;
         this._reactive = options.reactive !== false; // default true
+        this._timestamps = options.timestamps === true;
+        this._softDeletes = options.softDeletes === true;
+        this._debug = options.debug === true;
         this._pollInterval = options.pollInterval ?? 100;
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
 
@@ -77,6 +83,9 @@ class _Database<Schemas extends SchemaMap> {
             relationships: this.relationships,
             attachMethods: (name, entity) => attachMethods(this._ctx, name, entity),
             buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix),
+            debug: this._debug,
+            timestamps: this._timestamps,
+            softDeletes: this._softDeletes,
         };
 
         this.initializeTables();
@@ -96,7 +105,15 @@ class _Database<Schemas extends SchemaMap> {
                 },
                 upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
                 delete: ((id?: any) => {
-                    if (typeof id === 'number') return deleteEntity(this._ctx, entityName, id);
+                    if (typeof id === 'number') {
+                        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);
+                            return;
+                        }
+                        return deleteEntity(this._ctx, entityName, id);
+                    }
                     return createDeleteBuilder(this._ctx, entityName);
                 }) as any,
                 select: (...cols: string[]) => createQueryBuilder(this._ctx, entityName, cols),
@@ -117,6 +134,17 @@ class _Database<Schemas extends SchemaMap> {
         for (const [entityName, schema] of Object.entries(this.schemas)) {
             const storableFields = getStorableFields(schema);
             const columnDefs = storableFields.map(f => `"${f.name}" ${zodTypeToSqlType(f.type)}`);
+
+            // Add timestamp columns
+            if (this._timestamps) {
+                columnDefs.push('"createdAt" TEXT');
+                columnDefs.push('"updatedAt" TEXT');
+            }
+            // Add soft delete column
+            if (this._softDeletes) {
+                columnDefs.push('"deletedAt" TEXT');
+            }
+
             const constraints: string[] = [];
 
             const belongsToRels = this.relationships.filter(
@@ -306,9 +334,28 @@ class _Database<Schemas extends SchemaMap> {
         return executeProxyQuery(
             this.schemas,
             callback as any,
-            (sql: string, params: any[]) => this.db.query(sql).all(...params) as T[],
+            (sql: string, params: any[]) => {
+                if (this._debug) console.log('[satidb]', sql, params);
+                return this.db.query(sql).all(...params) as T[];
+            },
         );
     }
+
+    // =========================================================================
+    // Raw SQL
+    // =========================================================================
+
+    /** Execute a raw SQL query and return results. */
+    public raw<T = any>(sql: string, ...params: any[]): T[] {
+        if (this._debug) console.log('[satidb]', sql, params);
+        return this.db.query(sql).all(...params) as T[];
+    }
+
+    /** Execute a raw SQL statement (INSERT/UPDATE/DELETE) without returning rows. */
+    public exec(sql: string, ...params: any[]): void {
+        if (this._debug) console.log('[satidb]', sql, params);
+        this.db.run(sql, ...params);
+    }
 }
 
 // =============================================================================

package/src/helpers.ts

@@ -13,6 +13,7 @@ import { transformForStorage } from './schema';
  * - Operators: `{ age: { $gt: 18 } }`
  * - $in: `{ status: { $in: ['active', 'pending'] } }`
  * - $or: `{ $or: [{ name: 'Alice' }, { name: 'Bob' }] }`
+ * - $isNull / $isNotNull: `{ deletedAt: { $isNull: true } }`
  */
 export function buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] } {
     const parts: string[] = [];
@@ -73,6 +74,16 @@ export function buildWhereClause(conditions: Record<string, any>, tablePrefix?:
                 continue;
             }
 
+            if (operator === '$isNull') {
+                parts.push(`${fieldName} IS NULL`);
+                continue;
+            }
+
+            if (operator === '$isNotNull') {
+                parts.push(`${fieldName} IS NOT NULL`);
+                continue;
+            }
+
             const sqlOp = ({ $gt: '>', $gte: '>=', $lt: '<', $lte: '<=', $ne: '!=' } as Record<string, string>)[operator];
             if (!sqlOp) throw new Error(`Unsupported operator '${operator}' on '${key}'`);
             parts.push(`${fieldName} ${sqlOp} ?`);

package/src/index.ts

@@ -8,7 +8,7 @@ export type { DatabaseType } from './database';
 
 export type {
     SchemaMap, DatabaseOptions, Relationship,
-    EntityAccessor, TypedAccessors, AugmentedEntity, UpdateBuilder,
+    EntityAccessor, TypedAccessors, AugmentedEntity, UpdateBuilder, DeleteBuilder,
     InferSchema, EntityData, IndexDef, ChangeEvent,
     ProxyColumns, ColumnRef,
 } from './types';

package/src/iqo.ts

@@ -12,11 +12,11 @@ import { type ASTNode, compileAST } from './ast';
 // =============================================================================
 
 export type OrderDirection = 'asc' | 'desc';
-export type WhereOperator = '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$like' | '$notIn' | '$between';
+export type WhereOperator = '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$like' | '$notIn' | '$between' | '$isNull' | '$isNotNull';
 
 export interface WhereCondition {
     field: string;
-    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN';
+    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN' | 'IS NULL' | 'IS NOT NULL';
     value: any;
 }
 
@@ -34,11 +34,13 @@ export interface IQO {
     whereAST: ASTNode | null;
     joins: JoinClause[];
     groupBy: string[];
+    having: WhereCondition[];
     limit: number | null;
     offset: number | null;
     orderBy: { field: string; direction: OrderDirection }[];
     includes: string[];
     raw: boolean;
+    distinct: boolean;
 }
 
 export const OPERATOR_MAP: Record<WhereOperator, string> = {
@@ -51,6 +53,8 @@ export const OPERATOR_MAP: Record<WhereOperator, string> = {
     $like: 'LIKE',
     $notIn: 'NOT IN',
     $between: 'BETWEEN',
+    $isNull: 'IS NULL',
+    $isNotNull: 'IS NOT NULL',
 };
 
 export function transformValueForStorage(value: any): any {
@@ -81,7 +85,7 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         }
     }
 
-    let sql = `SELECT ${selectParts.join(', ')} FROM ${tableName}`;
+    let sql = `SELECT ${iqo.distinct ? 'DISTINCT ' : ''}${selectParts.join(', ')} FROM ${tableName}`;
 
     // JOIN clauses
     for (const j of iqo.joins) {
@@ -119,6 +123,10 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
                 const [min, max] = w.value as [any, any];
                 whereParts.push(`${qualify(w.field)} BETWEEN ? AND ?`);
                 params.push(transformValueForStorage(min), transformValueForStorage(max));
+            } else if (w.operator === 'IS NULL') {
+                whereParts.push(`${qualify(w.field)} IS NULL`);
+            } else if (w.operator === 'IS NOT NULL') {
+                whereParts.push(`${qualify(w.field)} IS NOT NULL`);
             } else {
                 whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
                 params.push(transformValueForStorage(w.value));
@@ -159,6 +167,24 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         sql += ` GROUP BY ${iqo.groupBy.join(', ')}`;
     }
 
+    // HAVING
+    if (iqo.having && iqo.having.length > 0) {
+        const havingParts: string[] = [];
+        for (const h of iqo.having) {
+            if (h.operator === 'IS NULL') {
+                havingParts.push(`${h.field} IS NULL`);
+            } else if (h.operator === 'IS NOT NULL') {
+                havingParts.push(`${h.field} IS NOT NULL`);
+            } else {
+                havingParts.push(`${h.field} ${h.operator} ?`);
+                params.push(transformValueForStorage(h.value));
+            }
+        }
+        if (havingParts.length > 0) {
+            sql += ` HAVING ${havingParts.join(' AND ')}`;
+        }
+    }
+
     // ORDER BY
     if (iqo.orderBy.length > 0) {
         const parts = iqo.orderBy.map(o => `${o.field} ${o.direction.toUpperCase()}`);

package/src/query.ts

@@ -39,6 +39,7 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
     const schema = ctx.schemas[entityName]!;
 
     const executor = (sql: string, params: any[], raw: boolean): any[] => {
+        if (ctx.debug) console.log('[satidb]', sql, params);
         const rows = ctx.db.query(sql).all(...params);
         if (raw) return rows;
         return rows.map((row: any) => ctx.attachMethods(entityName, transformFromStorage(row, schema)));
@@ -132,5 +133,11 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
 
     const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, eagerLoader);
     if (initialCols.length > 0) builder.select(...initialCols);
+
+    // Auto-filter soft-deleted rows unless withTrashed() is called
+    if (ctx.softDeletes) {
+        builder.where({ deletedAt: { $isNull: true } });
+    }
+
     return builder;
 }

package/src/types.ts

@@ -19,7 +19,6 @@ 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[];
 
-/** Options for the Database constructor */
 export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
     indexes?: Record<string, IndexDef[]>;
     /**
@@ -42,6 +41,24 @@ export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
      * `.on()` will throw. Default: `true`.
      */
     reactive?: boolean;
+    /**
+     * Auto-add `createdAt` and `updatedAt` TEXT columns to every table.
+     * `createdAt` is set on insert, `updatedAt` on insert + update.
+     * Default: `false`.
+     */
+    timestamps?: boolean;
+    /**
+     * Enable soft deletes. Adds a `deletedAt` TEXT column to every table.
+     * `delete()` sets `deletedAt` instead of removing the row.
+     * Use `.withTrashed()` on queries to include soft-deleted rows.
+     * Default: `false`.
+     */
+    softDeletes?: boolean;
+    /**
+     * Log every SQL query to the console. Useful for debugging.
+     * Default: `false`.
+     */
+    debug?: boolean;
 };
 
 export type Relationship = {