sqlite-zod-orm 3.9.0 → 3.11.0

package/src/builder.ts

@@ -0,0 +1,399 @@
+/**
+ * builder.ts — Fluent QueryBuilder class
+ *
+ * Accumulates query state via chaining and executes when a
+ * terminal method (.all(), .get(), .count()) is called.
+ */
+
+import {
+    type ASTNode, type WhereCallback, type TypedColumnProxy, type FunctionProxy, type Operators,
+    createColumnProxy, createFunctionProxy, op,
+} from './ast';
+import {
+    type IQO, type WhereCondition, type WhereOperator, type OrderDirection,
+    OPERATOR_MAP, compileIQO,
+} from './iqo';
+
+// =============================================================================
+// QueryBuilder Class
+// =============================================================================
+
+/**
+ * A Fluent Query Builder that accumulates query state via chaining
+ * and only executes when a terminal method is called (.all(), .get())
+ * or when it is `await`-ed (thenable).
+ *
+ * Supports two WHERE styles:
+ * - Object-style: `.where({ name: 'Alice', age: { $gt: 18 } })`
+ * - Callback-style (AST): `.where((c, f, op) => op.and(op.eq(c.name, 'Alice'), op.gt(c.age, 18)))`
+ */
+export class QueryBuilder<T extends Record<string, any>> {
+    private iqo: IQO;
+    private tableName: string;
+    private executor: (sql: string, params: any[], raw: boolean) => any[];
+    private singleExecutor: (sql: string, params: any[], raw: boolean) => any | null;
+    private joinResolver: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null;
+    private conditionResolver: ((conditions: Record<string, any>) => Record<string, any>) | null;
+    private eagerLoader: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null;
+
+    constructor(
+        tableName: string,
+        executor: (sql: string, params: any[], raw: boolean) => any[],
+        singleExecutor: (sql: string, params: any[], raw: boolean) => any | null,
+        joinResolver?: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null,
+        conditionResolver?: ((conditions: Record<string, any>) => Record<string, any>) | null,
+        eagerLoader?: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null,
+    ) {
+        this.tableName = tableName;
+        this.executor = executor;
+        this.singleExecutor = singleExecutor;
+        this.joinResolver = joinResolver ?? null;
+        this.conditionResolver = conditionResolver ?? null;
+        this.eagerLoader = eagerLoader ?? null;
+        this.iqo = {
+            selects: [],
+            wheres: [],
+            whereOrs: [],
+            whereAST: null,
+            joins: [],
+            groupBy: [],
+            having: [],
+            limit: null,
+            offset: null,
+            orderBy: [],
+            includes: [],
+            raw: false,
+            distinct: false,
+        };
+    }
+
+    /** Specify which columns to select. If called with no arguments, defaults to `*`. */
+    select(...cols: (keyof T & string)[]): this {
+        this.iqo.selects.push(...cols);
+        return this;
+    }
+
+    /**
+     * Add WHERE conditions. Two calling styles:
+     *
+     * **Object-style** (simple equality and operators):
+     * ```ts
+     * .where({ name: 'Alice' })
+     * .where({ age: { $gt: 18 } })
+     * ```
+     *
+     * **Callback-style** (AST-based, full SQL expression power):
+     * ```ts
+     * .where((c, f, op) => op.and(
+     *   op.eq(f.lower(c.name), 'alice'),
+     *   op.gt(c.age, 18)
+     * ))
+     * ```
+     */
+    where(criteriaOrCallback: (Partial<Record<keyof T & string, any>> & { $or?: Partial<Record<keyof T & string, any>>[] }) | WhereCallback<T>): this {
+        if (typeof criteriaOrCallback === 'function') {
+            const ast = (criteriaOrCallback as WhereCallback<T>)(
+                createColumnProxy<T>(),
+                createFunctionProxy(),
+                op,
+            );
+            if (this.iqo.whereAST) {
+                this.iqo.whereAST = { type: 'operator', op: 'AND', left: this.iqo.whereAST, right: ast };
+            } else {
+                this.iqo.whereAST = ast;
+            }
+        } else {
+            const resolved = this.conditionResolver
+                ? this.conditionResolver(criteriaOrCallback as Record<string, any>)
+                : criteriaOrCallback;
+
+            for (const [key, value] of Object.entries(resolved)) {
+                if (key === '$or' && Array.isArray(value)) {
+                    const orConditions: WhereCondition[] = [];
+                    for (const branch of value as Record<string, any>[]) {
+                        const resolvedBranch = this.conditionResolver
+                            ? this.conditionResolver(branch)
+                            : branch;
+                        for (const [bKey, bValue] of Object.entries(resolvedBranch)) {
+                            if (typeof bValue === 'object' && bValue !== null && !Array.isArray(bValue) && !(bValue instanceof Date)) {
+                                for (const [opKey, operand] of Object.entries(bValue)) {
+                                    const sqlOp = OPERATOR_MAP[opKey as WhereOperator];
+                                    if (sqlOp) orConditions.push({ field: bKey, operator: sqlOp as WhereCondition['operator'], value: operand });
+                                }
+                            } else {
+                                orConditions.push({ field: bKey, operator: '=', value: bValue });
+                            }
+                        }
+                    }
+                    if (orConditions.length > 0) this.iqo.whereOrs.push(orConditions);
+                    continue;
+                }
+
+                if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+                    for (const [opKey, operand] of Object.entries(value)) {
+                        const sqlOp = OPERATOR_MAP[opKey as WhereOperator];
+                        if (!sqlOp) throw new Error(`Unsupported query operator: '${opKey}' on field '${key}'.`);
+                        if (opKey === '$between') {
+                            if (!Array.isArray(operand) || operand.length !== 2) throw new Error(`$between for '${key}' requires [min, max]`);
+                        }
+                        this.iqo.wheres.push({
+                            field: key,
+                            operator: sqlOp as WhereCondition['operator'],
+                            value: operand,
+                        });
+                    }
+                } else {
+                    this.iqo.wheres.push({ field: key, operator: '=', value });
+                }
+            }
+        }
+        return this;
+    }
+
+    /** Set the maximum number of rows to return. */
+    limit(n: number): this {
+        this.iqo.limit = n;
+        return this;
+    }
+
+    /** Set the offset for pagination. */
+    offset(n: number): this {
+        this.iqo.offset = n;
+        return this;
+    }
+
+    /** Add ORDER BY clauses. */
+    orderBy(field: keyof T & string, direction: OrderDirection = 'asc'): this {
+        this.iqo.orderBy.push({ field, direction });
+        return this;
+    }
+
+    /**
+     * Join another table. Two calling styles:
+     *
+     * **Accessor-based** (auto-infers FK from relationships):
+     * ```ts
+     * db.trees.select('name').join(db.forests, ['name']).all()
+     * ```
+     *
+     * **String-based** (manual FK):
+     * ```ts
+     * db.trees.select('name').join('forests', 'forestId', ['name']).all()
+     * ```
+     */
+    join(accessor: { _tableName: string }, columns?: string[]): this;
+    join(table: string, fk: string, columns?: string[], pk?: string): this;
+    join(tableOrAccessor: string | { _tableName: string }, fkOrCols?: string | string[], colsOrPk?: string[] | string, pk?: string): this {
+        let table: string;
+        let fromCol: string;
+        let toCol: string;
+        let columns: string[];
+
+        if (typeof tableOrAccessor === 'object' && '_tableName' in tableOrAccessor) {
+            table = tableOrAccessor._tableName;
+            columns = Array.isArray(fkOrCols) ? fkOrCols : [];
+            if (!this.joinResolver) throw new Error(`Cannot auto-resolve join: no relationship data available`);
+            const resolved = this.joinResolver(this.tableName, table);
+            if (!resolved) throw new Error(`No relationship found between '${this.tableName}' and '${table}'`);
+            fromCol = resolved.fk;
+            toCol = resolved.pk;
+        } else {
+            table = tableOrAccessor;
+            fromCol = fkOrCols as string;
+            columns = Array.isArray(colsOrPk) ? colsOrPk : [];
+            toCol = (typeof colsOrPk === 'string' ? colsOrPk : pk) ?? 'id';
+        }
+
+        this.iqo.joins.push({ table, fromCol, toCol, columns });
+        this.iqo.raw = true;
+        return this;
+    }
+
+    /** Skip Zod parsing and return raw SQLite row objects. */
+    raw(): this {
+        this.iqo.raw = true;
+        return this;
+    }
+
+    /**
+     * Eagerly load a related entity and attach as an array property.
+     *
+     * Runs a single batched query (WHERE fk IN (...)) per relation,
+     * avoiding the N+1 problem of lazy navigation.
+     */
+    with(...relations: string[]): this {
+        this.iqo.includes.push(...relations);
+        return this;
+    }
+
+    /** Internal: apply eager loads to a set of results */
+    private _applyEagerLoads(results: T[]): T[] {
+        if (this.iqo.includes.length === 0 || !this.eagerLoader || results.length === 0) {
+            return results;
+        }
+
+        const parentIds = results.map((r: any) => r.id).filter((id: any) => typeof id === 'number');
+        if (parentIds.length === 0) return results;
+
+        for (const relation of this.iqo.includes) {
+            const loaded = this.eagerLoader(this.tableName, relation, parentIds);
+            if (!loaded) continue;
+
+            for (const row of results as any[]) {
+                row[loaded.key] = loaded.groups.get(row.id) ?? [];
+            }
+        }
+
+        return results;
+    }
+
+    // ---------- Terminal / Execution Methods ----------
+
+    /** Execute the query and return all matching rows. */
+    all(): T[] {
+        const { sql, params } = compileIQO(this.tableName, this.iqo);
+        const results = this.executor(sql, params, this.iqo.raw);
+        return this._applyEagerLoads(results);
+    }
+
+    /** Execute the query and return the first matching row, or null. */
+    get(): T | null {
+        this.iqo.limit = 1;
+        const { sql, params } = compileIQO(this.tableName, this.iqo);
+        const result = this.singleExecutor(sql, params, this.iqo.raw);
+        if (!result) return null;
+        const [loaded] = this._applyEagerLoads([result]);
+        return loaded ?? null;
+    }
+
+    /** Execute the query and return the count of matching rows. */
+    count(): number {
+        // Reuse compileIQO to avoid duplicating WHERE logic
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        // Replace "SELECT ... FROM" with "SELECT COUNT(*) as count FROM"
+        const countSql = selectSql.replace(/^SELECT .+? FROM/, 'SELECT COUNT(*) as count FROM');
+        const results = this.executor(countSql, params, true);
+        return (results[0] as any)?.count ?? 0;
+    }
+
+    /** Alias for get() — returns the first matching row or null. */
+    first(): T | null {
+        return this.get();
+    }
+
+    /** Returns true if at least one row matches the query. */
+    exists(): boolean {
+        const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
+        const existsSql = selectSql.replace(/^SELECT .+? FROM/, 'SELECT 1 FROM').replace(/ LIMIT \d+/, '') + ' LIMIT 1';
+        const results = this.executor(existsSql, params, true);
+        return results.length > 0;
+    }
+
+    /** Group results by one or more columns. */
+    groupBy(...fields: string[]): this {
+        this.iqo.groupBy.push(...fields);
+        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) ----------
+
+    then<TResult1 = T[], TResult2 = never>(
+        onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2> {
+        try {
+            const result = this.all();
+            return Promise.resolve(result).then(onfulfilled, onrejected);
+        } catch (err) {
+            return Promise.reject(err).then(onfulfilled, onrejected);
+        }
+    }
+}

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

@@ -4,7 +4,7 @@
  * Each function accepts a `DatabaseContext` so it can access
  * the db handle, schemas, and entity methods without tight coupling.
  */
-import type { AugmentedEntity, UpdateBuilder } from './types';
+import type { AugmentedEntity, UpdateBuilder, DeleteBuilder } from './types';
 import { asZodObject } from './types';
 import { transformForStorage, transformFromStorage } from './schema';
 import type { DatabaseContext } from './context';
@@ -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);
 }
@@ -118,6 +134,24 @@ export function deleteEntity(ctx: DatabaseContext, entityName: string, id: numbe
     ctx.db.query(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
 }
 
+/** Delete all rows matching the given conditions. Returns the number of rows deleted. */
+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);
+    return (result as any).changes ?? 0;
+}
+
+/** Create a fluent delete builder: db.table.delete().where({...}).exec() */
+export function createDeleteBuilder(ctx: DatabaseContext, entityName: string): DeleteBuilder<any> {
+    let _conditions: Record<string, any> = {};
+    const builder: DeleteBuilder<any> = {
+        where: (conditions) => { _conditions = { ..._conditions, ...conditions }; return builder; },
+        exec: () => deleteWhere(ctx, entityName, _conditions),
+    };
+    return builder;
+}
+
 /** Insert multiple rows in a single transaction for better performance. */
 export function insertMany<T extends Record<string, any>>(ctx: DatabaseContext, entityName: string, rows: Omit<T, 'id'>[]): AugmentedEntity<any>[] {
     if (rows.length === 0) return [];
@@ -129,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

@@ -24,7 +24,7 @@ import type { DatabaseContext } from './context';
 import { buildWhereClause } from './helpers';
 import { attachMethods } from './entity';
 import {
-    insert, insertMany, update, upsert, deleteEntity,
+    insert, insertMany, update, upsert, deleteEntity, createDeleteBuilder,
     getById, getOne, findMany, updateWhere, createUpdateBuilder,
 } from './crud';
 
@@ -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();
@@ -95,7 +104,18 @@ class _Database<Schemas extends SchemaMap> {
                     return createUpdateBuilder(this._ctx, entityName, idOrData);
                 },
                 upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
-                delete: (id) => deleteEntity(this._ctx, entityName, id),
+                delete: ((id?: any) => {
+                    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),
                 on: (event: ChangeEvent, callback: (row: any) => void | Promise<void>) => {
                     return this._registerListener(entityName, event, callback);
@@ -114,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(
@@ -303,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';