sqlite-zod-orm 3.8.0 → 3.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,8 +13,10 @@
     }
   },
   "scripts": {
-    "build": "bun run ./src/build.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm",
+    "clean": "rm -rf dist",
     "test": "bun test",
+    "bench": "bun bench/triggers-vs-naive.ts && bun bench/poll-strategy.ts && bun bench/indexes.ts",
     "prepublishOnly": "bun run build"
   },
   "files": [
@@ -52,4 +54,4 @@
   "engines": {
     "bun": ">=1.0.0"
   }
-}
+}

package/src/ast.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+
 
 // ==========================================
 // AST Node Types

package/src/builder.ts

@@ -0,0 +1,311 @@
+/**
+ * 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: [],
+            limit: null,
+            offset: null,
+            orderBy: [],
+            includes: [],
+            raw: 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;
+    }
+
+
+
+    // ---------- 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

@@ -0,0 +1,25 @@
+/**
+ * context.ts — Shared context interface for Database internals.
+ *
+ * Provides a slim interface so extracted modules (crud.ts, entity.ts, etc.)
+ * 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';
+
+export interface DatabaseContext {
+    /** The raw bun:sqlite Database handle. */
+    db: SqliteDatabase;
+
+    /** All registered Zod schemas, keyed by entity name. */
+    schemas: SchemaMap;
+
+    /** Parsed relationship descriptors. */
+    relationships: Relationship[];
+
+    /** Augment a raw row with .update()/.delete()/nav methods + auto-persist proxy. */
+    attachMethods<T extends Record<string, any>>(entityName: string, entity: T): AugmentedEntity<any>;
+
+    /** Build a WHERE clause from a conditions object. */
+    buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] };
+}

package/src/crud.ts

@@ -0,0 +1,163 @@
+/**
+ * crud.ts — CRUD operations extracted from Database class.
+ *
+ * Each function accepts a `DatabaseContext` so it can access
+ * the db handle, schemas, and entity methods without tight coupling.
+ */
+import type { AugmentedEntity, UpdateBuilder, DeleteBuilder } from './types';
+import { asZodObject } from './types';
+import { transformForStorage, transformFromStorage } from './schema';
+import type { DatabaseContext } from './context';
+
+// ---------------------------------------------------------------------------
+// Read helpers
+// ---------------------------------------------------------------------------
+
+export function getById(ctx: DatabaseContext, entityName: string, id: number): AugmentedEntity<any> | null {
+    const row = ctx.db.query(`SELECT * FROM "${entityName}" WHERE id = ?`).get(id) as any;
+    if (!row) return null;
+    return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!));
+}
+
+export function getOne(ctx: DatabaseContext, entityName: string, conditions: Record<string, any>): AugmentedEntity<any> | null {
+    const { clause, values } = ctx.buildWhereClause(conditions);
+    const row = ctx.db.query(`SELECT * FROM "${entityName}" ${clause} LIMIT 1`).get(...values) as any;
+    if (!row) return null;
+    return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!));
+}
+
+export function findMany(ctx: DatabaseContext, entityName: string, conditions: Record<string, any> = {}): AugmentedEntity<any>[] {
+    const { clause, values } = ctx.buildWhereClause(conditions);
+    const rows = ctx.db.query(`SELECT * FROM "${entityName}" ${clause}`).all(...values);
+    return rows.map((row: any) =>
+        ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!))
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Write operations
+// ---------------------------------------------------------------------------
+
+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);
+    const transformed = transformForStorage(validatedData);
+    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(', ')})`;
+
+    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');
+
+    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);
+    const transformed = transformForStorage(validatedData);
+    if (Object.keys(transformed).length === 0) return getById(ctx, entityName, id);
+
+    const setClause = Object.keys(transformed).map(key => `"${key}" = ?`).join(', ');
+    ctx.db.query(`UPDATE "${entityName}" SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
+
+    return getById(ctx, entityName, id);
+}
+
+export function updateWhere(ctx: DatabaseContext, entityName: string, data: Record<string, any>, conditions: Record<string, any>): number {
+    const schema = ctx.schemas[entityName]!;
+    const validatedData = asZodObject(schema).partial().parse(data);
+    const transformed = transformForStorage(validatedData);
+    if (Object.keys(transformed).length === 0) return 0;
+
+    const { clause, values: whereValues } = ctx.buildWhereClause(conditions);
+    if (!clause) throw new Error('update().where() requires at least one condition');
+
+    const setCols = Object.keys(transformed);
+    const setClause = setCols.map(key => `"${key}" = ?`).join(', ');
+    const result = ctx.db.query(`UPDATE "${entityName}" SET ${setClause} ${clause}`).run(
+        ...setCols.map(key => transformed[key]),
+        ...whereValues
+    );
+
+    return (result as any).changes ?? 0;
+}
+
+export function createUpdateBuilder(ctx: DatabaseContext, entityName: string, data: Record<string, any>): UpdateBuilder<any> {
+    let _conditions: Record<string, any> = {};
+    const builder: UpdateBuilder<any> = {
+        where: (conditions) => { _conditions = { ..._conditions, ...conditions }; return builder; },
+        exec: () => updateWhere(ctx, entityName, data, _conditions),
+    };
+    return builder;
+}
+
+export function upsert<T extends Record<string, any>>(ctx: DatabaseContext, entityName: string, data: any, conditions: any = {}): AugmentedEntity<any> {
+    const hasId = data?.id && typeof data.id === 'number';
+    const existing = hasId
+        ? getById(ctx, entityName, data.id)
+        : Object.keys(conditions ?? {}).length > 0
+            ? getOne(ctx, entityName, conditions)
+            : null;
+
+    if (existing) {
+        const updateData = { ...data };
+        delete updateData.id;
+        return update(ctx, entityName, existing.id, updateData) as AugmentedEntity<any>;
+    }
+    const insertData = { ...(conditions ?? {}), ...(data ?? {}) };
+    delete insertData.id;
+    return insert(ctx, entityName, insertData);
+}
+
+export function deleteEntity(ctx: DatabaseContext, entityName: string, id: number): void {
+    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 [];
+    const schema = ctx.schemas[entityName]!;
+    const zodSchema = asZodObject(schema).passthrough();
+
+    const txn = ctx.db.transaction(() => {
+        const ids: number[] = [];
+        for (const data of rows) {
+            const validatedData = zodSchema.parse(data);
+            const transformed = transformForStorage(validatedData);
+            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(', ')})`;
+            const result = ctx.db.query(sql).run(...Object.values(transformed));
+            ids.push(result.lastInsertRowid as number);
+        }
+        return ids;
+    });
+
+    const ids = txn();
+    return ids.map((id: number) => getById(ctx, entityName, id)!).filter(Boolean);
+}