sqlite-zod-orm 3.0.0 → 3.2.0

package/src/proxy-query.ts

@@ -1,49 +1,47 @@
-import { z } from 'zod';
-
-// ---------- SQL Identifier Quoting ----------
-
-/** Quote an identifier (table name, alias, column) to handle reserved words. */
-function q(name: string): string {
-    return `"${name}"`;
-}
+/**
+ * proxy-query.ts — Proxy-based SQL query builder
+ *
+ * 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.
+ */
 
-/** Quote a fully qualified alias.column reference. */
-function qRef(alias: string, column: string): string {
-    return `${q(alias)}.${q(column)}`;
-}
+import { z } from 'zod';
 
-// ---------- AST Node Types ----------
+// ---------- Column Node ----------
 
-/** Represents a column reference in the query AST. */
+/**
+ * Represents a reference to a specific table column with an alias.
+ * Used as a building block for SQL query construction.
+ */
 export class ColumnNode {
     readonly _type = 'COL' as const;
-    readonly table: string;
-    readonly column: string;
-    readonly alias: string;
-
-    constructor(table: string, column: string, alias: string) {
-        this.table = table;
-        this.column = column;
-        this.alias = alias;
-    }
+    constructor(
+        readonly table: string,
+        readonly column: string,
+        readonly alias: string,
+    ) { }
 
-    /** 
-     * When used as object key via `[t.id]`, JS calls toString().
-     * This returns the qualified column name for the ORM to parse.
-     */
+    /** Quoted alias.column for use as computed property key */
     toString(): string {
-        return `${q(this.alias)}.${q(this.column)}`;
+        return `"${this.alias}"."${this.column}"`;
     }
 
-    /** Also override valueOf for numeric contexts. */
-    valueOf(): string {
+    [Symbol.toPrimitive](): string {
         return this.toString();
     }
+}
 
-    /** Convenience for Symbol.toPrimitive */
-    [Symbol.toPrimitive](hint: string): string {
-        return this.toString();
-    }
+// ---------- 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 ----------
@@ -62,7 +60,6 @@ function createTableProxy(
             if (prop === Symbol.toPrimitive as any || prop === 'toString' || prop === 'valueOf') {
                 return undefined;
             }
-            // Allow any property access — the column may be inferred or wildcard
             return new ColumnNode(tableName, prop, alias);
         },
         ownKeys() {
@@ -100,9 +97,10 @@ export function createContextProxy(
             if (typeof tableName !== 'string') return undefined;
 
             const schema = schemas[tableName];
-            const columns = schema
-                ? new Set(Object.keys((schema as unknown as z.ZodObject<any>).shape))
-                : new Set<string>();
+            const shape = schema
+                ? (schema as unknown as z.ZodObject<any>).shape
+                : {};
+            const columns = new Set(Object.keys(shape));
 
             aliasCounter++;
             const alias = `t${aliasCounter}`;
@@ -122,14 +120,16 @@ export function createContextProxy(
 
 // ---------- Query Result Shape ----------
 
+type AnyColumn = ColumnNode | (ColumnNode & string);
+
 export interface ProxyQueryResult {
-    select: Record<string, ColumnNode>;
-    join?: [ColumnNode, ColumnNode] | [ColumnNode, ColumnNode][];
+    select: Record<string, AnyColumn | undefined>;
+    join?: [AnyColumn | undefined, AnyColumn | undefined] | [AnyColumn | undefined, AnyColumn | undefined][];
     where?: Record<string, any>;
     orderBy?: Record<string, 'asc' | 'desc'>;
     limit?: number;
     offset?: number;
-    groupBy?: ColumnNode[];
+    groupBy?: (AnyColumn | undefined)[];
 }
 
 // ---------- Query Compiler ----------
@@ -173,7 +173,6 @@ export function compileProxyQuery(
     }
 
     // ---------- FROM / JOIN ----------
-    // First table in aliases is the primary; rest are joined
     const allAliases = [...tablesUsed.values()];
     if (allAliases.length === 0) throw new Error('No tables referenced in query.');
 
@@ -187,13 +186,11 @@ export function compileProxyQuery(
             : [queryResult.join as [ColumnNode, ColumnNode]];
 
         for (const [left, right] of joins) {
-            // Determine which side is the joined table (not the primary)
             const leftTable = tablesUsed.get(left.alias);
             const rightTable = tablesUsed.get(right.alias);
 
             if (!leftTable || !rightTable) throw new Error('Join references unknown table alias.');
 
-            // The non-primary side needs a JOIN clause
             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)}`;
@@ -205,21 +202,17 @@ export function compileProxyQuery(
         const whereParts: string[] = [];
 
         for (const [key, value] of Object.entries(queryResult.where)) {
-            // The key could be '"t1"."column"' (from toString trick) or a plain string
             let fieldRef: string;
 
             // Match quoted alias.column pattern: "alias"."column"
             const quotedMatch = key.match(/^"([^"]+)"\."([^"]+)"$/);
             if (quotedMatch && tablesUsed.has(quotedMatch[1]!)) {
-                // Already fully quoted
                 fieldRef = key;
             } else {
-                // Plain field name — use the first table
                 fieldRef = qRef(primaryAlias.alias, key);
             }
 
             if (isColumnNode(value)) {
-                // Column-to-column comparison
                 whereParts.push(`${fieldRef} = ${qRef(value.alias, value.column)}`);
             } else if (Array.isArray(value)) {
                 if (value.length === 0) {
@@ -230,8 +223,18 @@ export function compileProxyQuery(
                     params.push(...value);
                 }
             } else if (typeof value === 'object' && value !== null && !(value instanceof Date)) {
-                // Operator object like { $gt: 5 }
                 for (const [op, operand] of Object.entries(value)) {
+                    if (op === '$in') {
+                        const arr = operand as any[];
+                        if (arr.length === 0) {
+                            whereParts.push('1 = 0');
+                        } else {
+                            const placeholders = arr.map(() => '?').join(', ');
+                            whereParts.push(`${fieldRef} IN (${placeholders})`);
+                            params.push(...arr);
+                        }
+                        continue;
+                    }
                     const opMap: Record<string, string> = {
                         $gt: '>', $gte: '>=', $lt: '<', $lte: '<=', $ne: '!=',
                     };
@@ -271,7 +274,7 @@ export function compileProxyQuery(
 
     // ---------- GROUP BY ----------
     if (queryResult.groupBy && queryResult.groupBy.length > 0) {
-        const parts = queryResult.groupBy.map(col => qRef(col.alias, col.column));
+        const parts = queryResult.groupBy.filter(Boolean).map(col => qRef(col!.alias, col!.column));
         sql += ` GROUP BY ${parts.join(', ')}`;
     }
 
@@ -290,7 +293,7 @@ export function compileProxyQuery(
 
 /**
  * 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.
@@ -306,3 +309,4 @@ export function executeProxyQuery<T>(
     const { sql, params } = compileProxyQuery(queryResult, aliasMap);
     return executor(sql, params);
 }
+

package/src/query-builder.ts

@@ -15,10 +15,19 @@ interface WhereCondition {
     value: any;
 }
 
+interface JoinClause {
+    table: string;
+    fromCol: string;
+    toCol: string;
+    columns: string[];   // columns to SELECT from the joined table
+}
+
 interface IQO {
     selects: string[];
     wheres: WhereCondition[];
+    whereOrs: WhereCondition[][];  // Each sub-array is an OR group
     whereAST: ASTNode | null;
+    joins: JoinClause[];
     limit: number | null;
     offset: number | null;
     orderBy: { field: string; direction: OrderDirection }[];
@@ -49,11 +58,27 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
     const params: any[] = [];
 
     // SELECT clause
-    const selectClause = iqo.selects.length > 0
-        ? iqo.selects.map(s => `${tableName}.${s}`).join(', ')
-        : `${tableName}.*`;
+    const selectParts: string[] = [];
+    if (iqo.selects.length > 0) {
+        selectParts.push(...iqo.selects.map(s => `${tableName}.${s}`));
+    } else {
+        selectParts.push(`${tableName}.*`);
+    }
+    // Add columns from joins
+    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 ${selectClause} FROM ${tableName}`;
+    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) {
@@ -80,6 +105,31 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         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}`;
+            }
+        }
+    }
+
     // ORDER BY clause
     if (iqo.orderBy.length > 0) {
         const parts = iqo.orderBy.map(o => `${o.field} ${o.direction.toUpperCase()}`);
@@ -115,19 +165,27 @@ export class QueryBuilder<T extends Record<string, any>> {
     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;
 
     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,
     ) {
         this.tableName = tableName;
         this.executor = executor;
         this.singleExecutor = singleExecutor;
+        this.joinResolver = joinResolver ?? null;
+        this.conditionResolver = conditionResolver ?? null;
         this.iqo = {
             selects: [],
             wheres: [],
+            whereOrs: [],
             whereAST: null,
+            joins: [],
             limit: null,
             offset: null,
             orderBy: [],
@@ -162,7 +220,7 @@ export class QueryBuilder<T extends Record<string, any>> {
      * ))
      * ```
      */
-    where(criteriaOrCallback: Partial<Record<keyof T & string, any>> | WhereCallback<T>): this {
+    where(criteriaOrCallback: (Partial<Record<keyof T & string, any>> & { $or?: Partial<Record<keyof T & string, any>>[] }) | WhereCallback<T>): this {
         if (typeof criteriaOrCallback === 'function') {
             // Callback-style: evaluate with proxies to produce AST
             const ast = (criteriaOrCallback as WhereCallback<T>)(
@@ -177,8 +235,35 @@ export class QueryBuilder<T extends Record<string, any>> {
                 this.iqo.whereAST = ast;
             }
         } else {
+            // Resolve entity references: { author: tolstoy } → { authorId: tolstoy.id }
+            const resolved = this.conditionResolver
+                ? this.conditionResolver(criteriaOrCallback as Record<string, any>)
+                : criteriaOrCallback;
+
             // Object-style: parse into IQO conditions
-            for (const [key, value] of Object.entries(criteriaOrCallback)) {
+            for (const [key, value] of Object.entries(resolved)) {
+                // Handle $or: [{ field1: val1 }, { field2: val2 }]
+                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];
@@ -221,6 +306,60 @@ export class QueryBuilder<T extends Record<string, any>> {
         return this;
     }
 
+    /**
+     * Join another table. Two calling styles:
+     *
+     * **Accessor-based** (auto-infers FK from relationships, type-safe columns):
+     * ```ts
+     * db.trees.select('name').join(db.forests, ['name']).all()
+     * // → [{ name: 'Oak', forests_name: 'Sherwood' }]
+     * ```
+     *
+     * **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) {
+            // Accessor-based: .join(db.forests, ['name', 'address'])
+            table = tableOrAccessor._tableName;
+            columns = Array.isArray(fkOrCols) ? fkOrCols : [];
+
+            // Auto-resolve FK from relationships
+            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 {
+            // String-based: .join('forests', 'forestId', ['name'], 'id')
+            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;

package/src/schema.ts

@@ -0,0 +1,122 @@
+/**
+ * schema.ts — Schema parsing, relationship detection, and DDL helpers
+ */
+import { z } from 'zod';
+import type { SchemaMap, ZodType, Relationship } from './types';
+import { asZodObject } from './types';
+
+/**
+ * Parse declarative `relations` config into Relationship[] objects.
+ *
+ * Config format: `{ childTable: { fkColumn: 'parentTable' } }`
+ * Example: `{ books: { author_id: 'authors' } }` produces:
+ *   - books → authors  (belongs-to, FK = author_id, nav = author)
+ *   - authors → books  (one-to-many, nav = books)
+ */
+export function parseRelationsConfig(
+    relations: Record<string, Record<string, string>>,
+    schemas: SchemaMap,
+): Relationship[] {
+    const relationships: Relationship[] = [];
+    const added = new Set<string>();
+
+    for (const [fromTable, rels] of Object.entries(relations)) {
+        if (!schemas[fromTable]) {
+            throw new Error(`relations: unknown table '${fromTable}'`);
+        }
+        for (const [fkColumn, toTable] of Object.entries(rels)) {
+            if (!schemas[toTable]) {
+                throw new Error(`relations: unknown target table '${toTable}' in ${fromTable}.${fkColumn}`);
+            }
+
+            // Derive navigation name: author_id → author
+            const navField = fkColumn.replace(/_id$/, '');
+
+            // belongs-to: books.author_id → authors
+            const btKey = `${fromTable}.${fkColumn}:belongs-to`;
+            if (!added.has(btKey)) {
+                relationships.push({
+                    type: 'belongs-to',
+                    from: fromTable,
+                    to: toTable,
+                    relationshipField: navField,
+                    foreignKey: fkColumn,
+                });
+                added.add(btKey);
+            }
+
+            // auto-infer one-to-many inverse: authors.books → books[]
+            const otmKey = `${toTable}.${fromTable}:one-to-many`;
+            if (!added.has(otmKey)) {
+                relationships.push({
+                    type: 'one-to-many',
+                    from: toTable,
+                    to: fromTable,
+                    relationshipField: fromTable, // e.g. 'books'
+                    foreignKey: '',
+                });
+                added.add(otmKey);
+            }
+        }
+    }
+
+    return relationships;
+}
+
+/** Get storable (non-id) fields from a schema */
+export function getStorableFields(schema: z.ZodType<any>): { name: string; type: ZodType }[] {
+    return Object.entries(asZodObject(schema).shape)
+        .filter(([key]) => key !== 'id')
+        .map(([name, type]) => ({ name, type: type as ZodType }));
+}
+
+/** Map a Zod type to its SQLite column type */
+export function zodTypeToSqlType(zodType: ZodType): string {
+    if (zodType instanceof z.ZodOptional) {
+        zodType = zodType._def.innerType;
+    }
+    if (zodType instanceof z.ZodDefault) {
+        zodType = zodType._def.innerType;
+    }
+    if (zodType instanceof z.ZodString || zodType instanceof z.ZodDate) return 'TEXT';
+    if (zodType instanceof z.ZodNumber || zodType instanceof z.ZodBoolean) return 'INTEGER';
+    if ((zodType as any)._def.typeName === 'ZodInstanceOf' && (zodType as any)._def.type === Buffer) return 'BLOB';
+    return 'TEXT';
+}
+
+/** Transform JS values to SQLite storage format */
+export function transformForStorage(data: Record<string, any>): Record<string, any> {
+    const transformed: Record<string, any> = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (value instanceof Date) {
+            transformed[key] = value.toISOString();
+        } else if (typeof value === 'boolean') {
+            transformed[key] = value ? 1 : 0;
+        } else {
+            transformed[key] = value;
+        }
+    }
+    return transformed;
+}
+
+/** Transform SQLite row back to JS types based on schema */
+export function transformFromStorage(row: Record<string, any>, schema: z.ZodType<any>): Record<string, any> {
+    const transformed: Record<string, any> = {};
+    for (const [key, value] of Object.entries(row)) {
+        let fieldSchema = asZodObject(schema).shape[key];
+        if (fieldSchema instanceof z.ZodOptional) {
+            fieldSchema = fieldSchema._def.innerType;
+        }
+        if (fieldSchema instanceof z.ZodDefault) {
+            fieldSchema = fieldSchema._def.innerType;
+        }
+        if (fieldSchema instanceof z.ZodDate && typeof value === 'string') {
+            transformed[key] = new Date(value);
+        } else if (fieldSchema instanceof z.ZodBoolean && typeof value === 'number') {
+            transformed[key] = value === 1;
+        } else {
+            transformed[key] = value;
+        }
+    }
+    return transformed;
+}