sqlite-zod-orm 3.8.0 → 3.10.0

package/src/entity.ts

@@ -0,0 +1,62 @@
+/**
+ * entity.ts — Entity augmentation logic extracted from Database class.
+ *
+ * Handles attaching .update(), .delete(), relationship navigation methods,
+ * and the auto-persist proxy to raw row objects.
+ */
+import type { AugmentedEntity, Relationship } from './types';
+import { getStorableFields, transformForStorage } from './schema';
+import type { DatabaseContext } from './context';
+import { getById, findMany, update, deleteEntity } from './crud';
+
+/**
+ * Augment a raw entity with:
+ * - .update(data) → persist partial update
+ * - .delete() → delete from DB
+ * - Lazy relationship accessors (author(), books(), etc.)
+ * - Auto-persist proxy: `entity.name = 'New'` auto-updates DB
+ */
+export function attachMethods<T extends Record<string, any>>(
+    ctx: DatabaseContext,
+    entityName: string,
+    entity: T,
+): AugmentedEntity<any> {
+    const augmented = entity as any;
+    augmented.update = (data: any) => update(ctx, entityName, entity.id, data);
+    augmented.delete = () => deleteEntity(ctx, entityName, entity.id);
+
+    // Attach lazy relationship navigation
+    for (const rel of ctx.relationships) {
+        if (rel.from === entityName && rel.type === 'belongs-to') {
+            // book.author() → lazy load parent via author_id FK
+            augmented[rel.relationshipField] = () => {
+                const fkValue = entity[rel.foreignKey];
+                return fkValue ? getById(ctx, rel.to, fkValue) : null;
+            };
+        } else if (rel.from === entityName && rel.type === 'one-to-many') {
+            // author.books() → lazy load children
+            const belongsToRel = ctx.relationships.find(
+                r => r.type === 'belongs-to' && r.from === rel.to && r.to === rel.from
+            );
+            if (belongsToRel) {
+                const fk = belongsToRel.foreignKey;
+                augmented[rel.relationshipField] = () => {
+                    return findMany(ctx, rel.to, { [fk]: entity.id });
+                };
+            }
+        }
+    }
+
+    // Auto-persist proxy: setting a field auto-updates the DB row
+    const storableFieldNames = new Set(getStorableFields(ctx.schemas[entityName]!).map(f => f.name));
+    return new Proxy(augmented, {
+        set: (target, prop: string, value) => {
+            if (storableFieldNames.has(prop) && target[prop] !== value) {
+                update(ctx, entityName, target.id, { [prop]: value });
+            }
+            target[prop] = value;
+            return true;
+        },
+        get: (target, prop, receiver) => Reflect.get(target, prop, receiver),
+    });
+}

package/src/helpers.ts

@@ -0,0 +1,87 @@
+/**
+ * sql-helpers.ts — SQL utility functions extracted from Database class.
+ *
+ * Contains WHERE clause building and other SQL-level helpers.
+ */
+import { transformForStorage } from './schema';
+
+/**
+ * Build a parameterized WHERE clause from a conditions object.
+ *
+ * Supports:
+ * - Simple equality: `{ name: 'Alice' }`
+ * - Operators: `{ age: { $gt: 18 } }`
+ * - $in: `{ status: { $in: ['active', 'pending'] } }`
+ * - $or: `{ $or: [{ name: 'Alice' }, { name: 'Bob' }] }`
+ */
+export function buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] } {
+    const parts: string[] = [];
+    const values: any[] = [];
+
+    for (const key in conditions) {
+        if (key.startsWith('$')) {
+            if (key === '$or' && Array.isArray(conditions[key])) {
+                const orBranches = conditions[key] as Record<string, any>[];
+                const orParts: string[] = [];
+                for (const branch of orBranches) {
+                    const sub = buildWhereClause(branch, tablePrefix);
+                    if (sub.clause) {
+                        orParts.push(`(${sub.clause.replace(/^WHERE /, '')})`);
+                        values.push(...sub.values);
+                    }
+                }
+                if (orParts.length > 0) parts.push(`(${orParts.join(' OR ')})`);
+            }
+            continue;
+        }
+        const value = conditions[key];
+        const fieldName = tablePrefix ? `"${tablePrefix}"."${key}"` : `"${key}"`;
+
+        if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+            const operator = Object.keys(value)[0];
+            if (!operator?.startsWith('$')) {
+                throw new Error(`Querying on nested object '${key}' not supported. Use operators like $gt.`);
+            }
+            const operand = value[operator];
+
+            if (operator === '$in') {
+                if (!Array.isArray(operand)) throw new Error(`$in for '${key}' requires an array`);
+                if (operand.length === 0) { parts.push('1 = 0'); continue; }
+                parts.push(`${fieldName} IN (${operand.map(() => '?').join(', ')})`);
+                values.push(...operand.map((v: any) => transformForStorage({ v }).v));
+                continue;
+            }
+
+            if (operator === '$notIn') {
+                if (!Array.isArray(operand)) throw new Error(`$notIn for '${key}' requires an array`);
+                if (operand.length === 0) continue; // no-op: everything is "not in" an empty set
+                parts.push(`${fieldName} NOT IN (${operand.map(() => '?').join(', ')})`);
+                values.push(...operand.map((v: any) => transformForStorage({ v }).v));
+                continue;
+            }
+
+            if (operator === '$like') {
+                parts.push(`${fieldName} LIKE ?`);
+                values.push(operand);
+                continue;
+            }
+
+            if (operator === '$between') {
+                if (!Array.isArray(operand) || operand.length !== 2) throw new Error(`$between for '${key}' requires [min, max]`);
+                parts.push(`${fieldName} BETWEEN ? AND ?`);
+                values.push(transformForStorage({ v: operand[0] }).v, transformForStorage({ v: operand[1] }).v);
+                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} ?`);
+            values.push(transformForStorage({ operand }).operand);
+        } else {
+            parts.push(`${fieldName} = ?`);
+            values.push(transformForStorage({ value }).value);
+        }
+    }
+
+    return { clause: parts.length > 0 ? `WHERE ${parts.join(' AND ')}` : '', values };
+}

package/src/index.ts

@@ -9,14 +9,13 @@ export type { DatabaseType } from './database';
 export type {
     SchemaMap, DatabaseOptions, Relationship,
     EntityAccessor, TypedAccessors, AugmentedEntity, UpdateBuilder,
-    InferSchema, EntityData, IndexDef,
+    InferSchema, EntityData, IndexDef, ChangeEvent,
     ProxyColumns, ColumnRef,
 } from './types';
 
 export { z } from 'zod';
 
-export { QueryBuilder } from './query-builder';
-export { ColumnNode, type ProxyQueryResult } from './proxy-query';
+export { QueryBuilder, ColumnNode, compileIQO, type ProxyQueryResult } from './query';
 export {
     type ASTNode, type WhereCallback, type SetCallback,
     type TypedColumnProxy, type FunctionProxy, type Operators,

package/src/iqo.ts

@@ -0,0 +1,172 @@
+/**
+ * iqo.ts — Internal Query Object types and SQL compiler
+ *
+ * Defines the IQO structure, WHERE operators, and the `compileIQO` function
+ * that transforms an IQO into executable SQL + params.
+ */
+
+import { type ASTNode, compileAST } from './ast';
+
+// =============================================================================
+// IQO — Internal Query Object
+// =============================================================================
+
+export type OrderDirection = 'asc' | 'desc';
+export type WhereOperator = '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$like' | '$notIn' | '$between';
+
+export interface WhereCondition {
+    field: string;
+    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN';
+    value: any;
+}
+
+export interface JoinClause {
+    table: string;
+    fromCol: string;
+    toCol: string;
+    columns: string[];   // columns to SELECT from the joined table
+}
+
+export interface IQO {
+    selects: string[];
+    wheres: WhereCondition[];
+    whereOrs: WhereCondition[][];  // Each sub-array is an OR group
+    whereAST: ASTNode | null;
+    joins: JoinClause[];
+    groupBy: string[];
+    limit: number | null;
+    offset: number | null;
+    orderBy: { field: string; direction: OrderDirection }[];
+    includes: string[];
+    raw: boolean;
+}
+
+export const OPERATOR_MAP: Record<WhereOperator, string> = {
+    $gt: '>',
+    $gte: '>=',
+    $lt: '<',
+    $lte: '<=',
+    $ne: '!=',
+    $in: 'IN',
+    $like: 'LIKE',
+    $notIn: 'NOT IN',
+    $between: 'BETWEEN',
+};
+
+export function transformValueForStorage(value: any): any {
+    if (value instanceof Date) return value.toISOString();
+    if (typeof value === 'boolean') return value ? 1 : 0;
+    return value;
+}
+
+/**
+ * Compile an Internal Query Object into executable SQL + params.
+ * Handles SELECT, JOIN, WHERE (object + AST + $or), ORDER BY, LIMIT, OFFSET.
+ */
+export function compileIQO(tableName: string, iqo: IQO): { sql: string; params: any[] } {
+    const params: any[] = [];
+
+    // SELECT clause
+    const selectParts: string[] = [];
+    if (iqo.selects.length > 0) {
+        selectParts.push(...iqo.selects.map(s => `${tableName}.${s}`));
+    } else {
+        selectParts.push(`${tableName}.*`);
+    }
+    for (const j of iqo.joins) {
+        if (j.columns.length > 0) {
+            selectParts.push(...j.columns.map(c => `${j.table}.${c} AS ${j.table}_${c}`));
+        } else {
+            selectParts.push(`${j.table}.*`);
+        }
+    }
+
+    let sql = `SELECT ${selectParts.join(', ')} FROM ${tableName}`;
+
+    // JOIN clauses
+    for (const j of iqo.joins) {
+        sql += ` JOIN ${j.table} ON ${tableName}.${j.fromCol} = ${j.table}.${j.toCol}`;
+    }
+
+    // WHERE clause — AST-based takes precedence if set
+    if (iqo.whereAST) {
+        const compiled = compileAST(iqo.whereAST);
+        sql += ` WHERE ${compiled.sql}`;
+        params.push(...compiled.params);
+    } else if (iqo.wheres.length > 0) {
+        const hasJoins = iqo.joins.length > 0;
+        const qualify = (field: string) =>
+            hasJoins && !field.includes('.') ? `${tableName}.${field}` : field;
+
+        const whereParts: string[] = [];
+        for (const w of iqo.wheres) {
+            if (w.operator === 'IN') {
+                const arr = w.value as any[];
+                if (arr.length === 0) {
+                    whereParts.push('1 = 0');
+                } else {
+                    const placeholders = arr.map(() => '?').join(', ');
+                    whereParts.push(`${qualify(w.field)} IN (${placeholders})`);
+                    params.push(...arr.map(transformValueForStorage));
+                }
+            } else if (w.operator === 'NOT IN') {
+                const arr = w.value as any[];
+                if (arr.length === 0) continue; // no-op
+                const placeholders = arr.map(() => '?').join(', ');
+                whereParts.push(`${qualify(w.field)} NOT IN (${placeholders})`);
+                params.push(...arr.map(transformValueForStorage));
+            } else if (w.operator === 'BETWEEN') {
+                const [min, max] = w.value as [any, any];
+                whereParts.push(`${qualify(w.field)} BETWEEN ? AND ?`);
+                params.push(transformValueForStorage(min), transformValueForStorage(max));
+            } else {
+                whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
+                params.push(transformValueForStorage(w.value));
+            }
+        }
+        if (whereParts.length > 0) {
+            sql += ` WHERE ${whereParts.join(' AND ')}`;
+        }
+    }
+
+    // Append OR groups (from $or)
+    if (iqo.whereOrs.length > 0) {
+        for (const orGroup of iqo.whereOrs) {
+            const orParts: string[] = [];
+            for (const w of orGroup) {
+                if (w.operator === 'IN') {
+                    const arr = w.value as any[];
+                    if (arr.length === 0) {
+                        orParts.push('1 = 0');
+                    } else {
+                        orParts.push(`${w.field} IN (${arr.map(() => '?').join(', ')})`);
+                        params.push(...arr.map(transformValueForStorage));
+                    }
+                } else {
+                    orParts.push(`${w.field} ${w.operator} ?`);
+                    params.push(transformValueForStorage(w.value));
+                }
+            }
+            if (orParts.length > 0) {
+                const orClause = `(${orParts.join(' OR ')})`;
+                sql += sql.includes(' WHERE ') ? ` AND ${orClause}` : ` WHERE ${orClause}`;
+            }
+        }
+    }
+
+    // GROUP BY
+    if (iqo.groupBy.length > 0) {
+        sql += ` GROUP BY ${iqo.groupBy.join(', ')}`;
+    }
+
+    // ORDER BY
+    if (iqo.orderBy.length > 0) {
+        const parts = iqo.orderBy.map(o => `${o.field} ${o.direction.toUpperCase()}`);
+        sql += ` ORDER BY ${parts.join(', ')}`;
+    }
+
+    if (iqo.limit !== null) sql += ` LIMIT ${iqo.limit}`;
+    if (iqo.offset !== null) sql += ` OFFSET ${iqo.offset}`;
+
+    return { sql, params };
+}

package/src/{proxy-query.ts → proxy.ts}

@@ -1,14 +1,15 @@
 /**
- * proxy-query.ts — Proxy-based SQL query builder
+ * proxy.ts — Proxy Query System
  *
- * Enables db.query(c => { const { users: u, posts: p } = c; ... }) syntax.
- * Table/column access through the proxy creates ColumnNode AST nodes,
- * which are then compiled into parameterized SQL.
+ * Enables `db.query(c => { ... })` for SQL-like multi-table queries
+ * using destructured proxied table references.
  */
 
-import { z } from 'zod';
+import type { z } from 'zod';
 
-// ---------- Column Node ----------
+// =============================================================================
+// ColumnNode
+// =============================================================================
 
 /**
  * Represents a reference to a specific table column with an alias.
@@ -34,22 +35,16 @@ export class ColumnNode {
 
 // ---------- SQL Quoting Helpers ----------
 
-/** Quote an identifier with double quotes */
 function q(name: string): string {
     return `"${name}"`;
 }
 
-/** Quote a fully qualified reference: alias.column */
 function qRef(alias: string, column: string): string {
     return `"${alias}"."${column}"`;
 }
 
 // ---------- Table Proxy ----------
 
-/**
- * Creates a proxy representing a table with a given alias.
- * Property access returns ColumnNode objects.
- */
 function createTableProxy(
     tableName: string,
     alias: string,
@@ -82,10 +77,6 @@ interface AliasEntry {
     proxy: Record<string, ColumnNode>;
 }
 
-/**
- * Creates the root context proxy `c` that the user destructures.
- * Each table access generates a unique alias.
- */
 export function createContextProxy(
     schemas: Record<string, z.ZodType<any>>,
 ): { proxy: Record<string, Record<string, ColumnNode>>; aliasMap: Map<string, AliasEntry[]> } {
@@ -106,7 +97,6 @@ export function createContextProxy(
             const alias = `t${aliasCounter}`;
             const tableProxy = createTableProxy(tableName, alias, columns);
 
-            // Track alias
             const entries = aliases.get(tableName) || [];
             entries.push({ tableName, alias, proxy: tableProxy });
             aliases.set(tableName, entries);
@@ -118,7 +108,7 @@ export function createContextProxy(
     return { proxy, aliasMap: aliases };
 }
 
-// ---------- Query Result Shape ----------
+// ---------- Proxy Query Result ----------
 
 type AnyColumn = ColumnNode | (ColumnNode & string);
 
@@ -132,31 +122,26 @@ export interface ProxyQueryResult {
     groupBy?: (AnyColumn | undefined)[];
 }
 
-// ---------- Query Compiler ----------
+// ---------- Proxy Query Compiler ----------
 
 function isColumnNode(val: any): val is ColumnNode {
     return val && typeof val === 'object' && val._type === 'COL';
 }
 
-/**
- * Compile the result of the user's callback into SQL.
- */
 export function compileProxyQuery(
     queryResult: ProxyQueryResult,
     aliasMap: Map<string, AliasEntry[]>,
 ): { sql: string; params: any[] } {
     const params: any[] = [];
 
-    // Collect all tables/aliases referenced
     const tablesUsed = new Map<string, { tableName: string; alias: string }>();
-
     for (const [tableName, entries] of aliasMap) {
         for (const entry of entries) {
             tablesUsed.set(entry.alias, { tableName, alias: entry.alias });
         }
     }
 
-    // ---------- SELECT ----------
+    // SELECT
     const selectParts: string[] = [];
     for (const [outputName, colOrValue] of Object.entries(queryResult.select)) {
         if (isColumnNode(colOrValue)) {
@@ -166,20 +151,18 @@ export function compileProxyQuery(
                 selectParts.push(`${qRef(colOrValue.alias, colOrValue.column)} AS ${q(outputName)}`);
             }
         } else {
-            // Literal value
             selectParts.push(`? AS ${q(outputName)}`);
             params.push(colOrValue);
         }
     }
 
-    // ---------- FROM / JOIN ----------
+    // FROM / JOIN
     const allAliases = [...tablesUsed.values()];
     if (allAliases.length === 0) throw new Error('No tables referenced in query.');
 
     const primaryAlias = allAliases[0]!;
     let sql = `SELECT ${selectParts.join(', ')} FROM ${q(primaryAlias.tableName)} ${q(primaryAlias.alias)}`;
 
-    // Process JOINs
     if (queryResult.join) {
         const joins: [ColumnNode, ColumnNode][] = Array.isArray(queryResult.join[0])
             ? queryResult.join as [ColumnNode, ColumnNode][]
@@ -188,23 +171,18 @@ export function compileProxyQuery(
         for (const [left, right] of joins) {
             const leftTable = tablesUsed.get(left.alias);
             const rightTable = tablesUsed.get(right.alias);
-
             if (!leftTable || !rightTable) throw new Error('Join references unknown table alias.');
-
             const joinAlias = leftTable.alias === primaryAlias.alias ? rightTable : leftTable;
-
             sql += ` JOIN ${q(joinAlias.tableName)} ${q(joinAlias.alias)} ON ${qRef(left.alias, left.column)} = ${qRef(right.alias, right.column)}`;
         }
     }
 
-    // ---------- WHERE ----------
+    // WHERE
     if (queryResult.where && Object.keys(queryResult.where).length > 0) {
         const whereParts: string[] = [];
 
         for (const [key, value] of Object.entries(queryResult.where)) {
             let fieldRef: string;
-
-            // Match quoted alias.column pattern: "alias"."column"
             const quotedMatch = key.match(/^"([^"]+)"\."([^"]+)"$/);
             if (quotedMatch && tablesUsed.has(quotedMatch[1]!)) {
                 fieldRef = key;
@@ -223,8 +201,8 @@ export function compileProxyQuery(
                     params.push(...value);
                 }
             } else if (typeof value === 'object' && value !== null && !(value instanceof Date)) {
-                for (const [op, operand] of Object.entries(value)) {
-                    if (op === '$in') {
+                for (const [pOp, operand] of Object.entries(value)) {
+                    if (pOp === '$in') {
                         const arr = operand as any[];
                         if (arr.length === 0) {
                             whereParts.push('1 = 0');
@@ -238,8 +216,8 @@ export function compileProxyQuery(
                     const opMap: Record<string, string> = {
                         $gt: '>', $gte: '>=', $lt: '<', $lte: '<=', $ne: '!=',
                     };
-                    const sqlOp = opMap[op];
-                    if (!sqlOp) throw new Error(`Unsupported where operator: ${op}`);
+                    const sqlOp = opMap[pOp];
+                    if (!sqlOp) throw new Error(`Unsupported where operator: ${pOp}`);
                     whereParts.push(`${fieldRef} ${sqlOp} ?`);
                     params.push(operand);
                 }
@@ -254,7 +232,7 @@ export function compileProxyQuery(
         }
     }
 
-    // ---------- ORDER BY ----------
+    // ORDER BY
     if (queryResult.orderBy) {
         const parts: string[] = [];
         for (const [key, dir] of Object.entries(queryResult.orderBy)) {
@@ -272,33 +250,20 @@ export function compileProxyQuery(
         }
     }
 
-    // ---------- GROUP BY ----------
+    // GROUP BY
     if (queryResult.groupBy && queryResult.groupBy.length > 0) {
         const parts = queryResult.groupBy.filter(Boolean).map(col => qRef(col!.alias, col!.column));
         sql += ` GROUP BY ${parts.join(', ')}`;
     }
 
-    // ---------- LIMIT / OFFSET ----------
-    if (queryResult.limit !== undefined) {
-        sql += ` LIMIT ${queryResult.limit}`;
-    }
-    if (queryResult.offset !== undefined) {
-        sql += ` OFFSET ${queryResult.offset}`;
-    }
+    // LIMIT / OFFSET
+    if (queryResult.limit !== undefined) sql += ` LIMIT ${queryResult.limit}`;
+    if (queryResult.offset !== undefined) sql += ` OFFSET ${queryResult.offset}`;
 
     return { sql, params };
 }
 
-// ---------- Public API ----------
-
-/**
- * The main `db.query(c => {...})` entry point.
- *
- * @param schemas The schema map for all registered tables.
- * @param callback The user's query callback that receives the context proxy.
- * @param executor A function that runs the compiled SQL and returns rows.
- * @returns The query results.
- */
+/** The main `db.query(c => {...})` entry point. */
 export function executeProxyQuery<T>(
     schemas: Record<string, z.ZodType<any>>,
     callback: (ctx: any) => ProxyQueryResult,
@@ -309,4 +274,3 @@ export function executeProxyQuery<T>(
     const { sql, params } = compileProxyQuery(queryResult, aliasMap);
     return executor(sql, params);
 }
-