sqlite-zod-orm 3.9.0 → 3.11.0

package/src/iqo.ts

@@ -0,0 +1,198 @@
+/**
+ * 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' | '$isNull' | '$isNotNull';
+
+export interface WhereCondition {
+    field: string;
+    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN' | 'IS NULL' | 'IS NOT NULL';
+    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[];
+    having: WhereCondition[];
+    limit: number | null;
+    offset: number | null;
+    orderBy: { field: string; direction: OrderDirection }[];
+    includes: string[];
+    raw: boolean;
+    distinct: boolean;
+}
+
+export const OPERATOR_MAP: Record<WhereOperator, string> = {
+    $gt: '>',
+    $gte: '>=',
+    $lt: '<',
+    $lte: '<=',
+    $ne: '!=',
+    $in: 'IN',
+    $like: 'LIKE',
+    $notIn: 'NOT IN',
+    $between: 'BETWEEN',
+    $isNull: 'IS NULL',
+    $isNotNull: 'IS NOT NULL',
+};
+
+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 ${iqo.distinct ? 'DISTINCT ' : ''}${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 if (w.operator === 'IS NULL') {
+                whereParts.push(`${qualify(w.field)} IS NULL`);
+            } else if (w.operator === 'IS NOT NULL') {
+                whereParts.push(`${qualify(w.field)} IS NOT NULL`);
+            } else {
+                whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
+                params.push(transformValueForStorage(w.value));
+            }
+        }
+        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(', ')}`;
+    }
+
+    // HAVING
+    if (iqo.having && iqo.having.length > 0) {
+        const havingParts: string[] = [];
+        for (const h of iqo.having) {
+            if (h.operator === 'IS NULL') {
+                havingParts.push(`${h.field} IS NULL`);
+            } else if (h.operator === 'IS NOT NULL') {
+                havingParts.push(`${h.field} IS NOT NULL`);
+            } else {
+                havingParts.push(`${h.field} ${h.operator} ?`);
+                params.push(transformValueForStorage(h.value));
+            }
+        }
+        if (havingParts.length > 0) {
+            sql += ` HAVING ${havingParts.join(' AND ')}`;
+        }
+    }
+
+    // ORDER BY
+    if (iqo.orderBy.length > 0) {
+        const parts = iqo.orderBy.map(o => `${o.field} ${o.direction.toUpperCase()}`);
+        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.ts

@@ -0,0 +1,276 @@
+/**
+ * proxy.ts — Proxy Query System
+ *
+ * Enables `db.query(c => { ... })` for SQL-like multi-table queries
+ * using destructured proxied table references.
+ */
+
+import type { z } from 'zod';
+
+// =============================================================================
+// ColumnNode
+// =============================================================================
+
+/**
+ * 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;
+    constructor(
+        readonly table: string,
+        readonly column: string,
+        readonly alias: string,
+    ) { }
+
+    /** Quoted alias.column for use as computed property key */
+    toString(): string {
+        return `"${this.alias}"."${this.column}"`;
+    }
+
+    [Symbol.toPrimitive](): string {
+        return this.toString();
+    }
+}
+
+// ---------- SQL Quoting Helpers ----------
+
+function q(name: string): string {
+    return `"${name}"`;
+}
+
+function qRef(alias: string, column: string): string {
+    return `"${alias}"."${column}"`;
+}
+
+// ---------- Table Proxy ----------
+
+function createTableProxy(
+    tableName: string,
+    alias: string,
+    columns: Set<string>,
+): Record<string, ColumnNode> {
+    return new Proxy({} as Record<string, ColumnNode>, {
+        get(_target, prop: string): ColumnNode | undefined {
+            if (prop === Symbol.toPrimitive as any || prop === 'toString' || prop === 'valueOf') {
+                return undefined;
+            }
+            return new ColumnNode(tableName, prop, alias);
+        },
+        ownKeys() {
+            return [...columns];
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (columns.has(prop as string)) {
+                return { configurable: true, enumerable: true, value: new ColumnNode(tableName, prop as string, alias) };
+            }
+            return undefined;
+        },
+    });
+}
+
+// ---------- Context Proxy ----------
+
+interface AliasEntry {
+    tableName: string;
+    alias: string;
+    proxy: Record<string, ColumnNode>;
+}
+
+export function createContextProxy(
+    schemas: Record<string, z.ZodType<any>>,
+): { proxy: Record<string, Record<string, ColumnNode>>; aliasMap: Map<string, AliasEntry[]> } {
+    const aliases = new Map<string, AliasEntry[]>();
+    let aliasCounter = 0;
+
+    const proxy = new Proxy({} as Record<string, Record<string, ColumnNode>>, {
+        get(_target, tableName: string) {
+            if (typeof tableName !== 'string') return undefined;
+
+            const schema = schemas[tableName];
+            const shape = schema
+                ? (schema as unknown as z.ZodObject<any>).shape
+                : {};
+            const columns = new Set(Object.keys(shape));
+
+            aliasCounter++;
+            const alias = `t${aliasCounter}`;
+            const tableProxy = createTableProxy(tableName, alias, columns);
+
+            const entries = aliases.get(tableName) || [];
+            entries.push({ tableName, alias, proxy: tableProxy });
+            aliases.set(tableName, entries);
+
+            return tableProxy;
+        },
+    });
+
+    return { proxy, aliasMap: aliases };
+}
+
+// ---------- Proxy Query Result ----------
+
+type AnyColumn = ColumnNode | (ColumnNode & string);
+
+export interface ProxyQueryResult {
+    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?: (AnyColumn | undefined)[];
+}
+
+// ---------- Proxy Query Compiler ----------
+
+function isColumnNode(val: any): val is ColumnNode {
+    return val && typeof val === 'object' && val._type === 'COL';
+}
+
+export function compileProxyQuery(
+    queryResult: ProxyQueryResult,
+    aliasMap: Map<string, AliasEntry[]>,
+): { sql: string; params: any[] } {
+    const params: any[] = [];
+
+    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
+    const selectParts: string[] = [];
+    for (const [outputName, colOrValue] of Object.entries(queryResult.select)) {
+        if (isColumnNode(colOrValue)) {
+            if (outputName === colOrValue.column) {
+                selectParts.push(qRef(colOrValue.alias, colOrValue.column));
+            } else {
+                selectParts.push(`${qRef(colOrValue.alias, colOrValue.column)} AS ${q(outputName)}`);
+            }
+        } else {
+            selectParts.push(`? AS ${q(outputName)}`);
+            params.push(colOrValue);
+        }
+    }
+
+    // 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)}`;
+
+    if (queryResult.join) {
+        const joins: [ColumnNode, ColumnNode][] = Array.isArray(queryResult.join[0])
+            ? queryResult.join as [ColumnNode, ColumnNode][]
+            : [queryResult.join as [ColumnNode, ColumnNode]];
+
+        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
+    if (queryResult.where && Object.keys(queryResult.where).length > 0) {
+        const whereParts: string[] = [];
+
+        for (const [key, value] of Object.entries(queryResult.where)) {
+            let fieldRef: string;
+            const quotedMatch = key.match(/^"([^"]+)"\."([^"]+)"$/);
+            if (quotedMatch && tablesUsed.has(quotedMatch[1]!)) {
+                fieldRef = key;
+            } else {
+                fieldRef = qRef(primaryAlias.alias, key);
+            }
+
+            if (isColumnNode(value)) {
+                whereParts.push(`${fieldRef} = ${qRef(value.alias, value.column)}`);
+            } else if (Array.isArray(value)) {
+                if (value.length === 0) {
+                    whereParts.push('1 = 0');
+                } else {
+                    const placeholders = value.map(() => '?').join(', ');
+                    whereParts.push(`${fieldRef} IN (${placeholders})`);
+                    params.push(...value);
+                }
+            } else if (typeof value === 'object' && value !== null && !(value instanceof Date)) {
+                for (const [pOp, operand] of Object.entries(value)) {
+                    if (pOp === '$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: '!=',
+                    };
+                    const sqlOp = opMap[pOp];
+                    if (!sqlOp) throw new Error(`Unsupported where operator: ${pOp}`);
+                    whereParts.push(`${fieldRef} ${sqlOp} ?`);
+                    params.push(operand);
+                }
+            } else {
+                whereParts.push(`${fieldRef} = ?`);
+                params.push(value instanceof Date ? value.toISOString() : value);
+            }
+        }
+
+        if (whereParts.length > 0) {
+            sql += ` WHERE ${whereParts.join(' AND ')}`;
+        }
+    }
+
+    // ORDER BY
+    if (queryResult.orderBy) {
+        const parts: string[] = [];
+        for (const [key, dir] of Object.entries(queryResult.orderBy)) {
+            let fieldRef: string;
+            const quotedMatch = key.match(/^"([^"]+)"\."([^"]+)"$/);
+            if (quotedMatch && tablesUsed.has(quotedMatch[1]!)) {
+                fieldRef = key;
+            } else {
+                fieldRef = qRef(primaryAlias.alias, key);
+            }
+            parts.push(`${fieldRef} ${dir.toUpperCase()}`);
+        }
+        if (parts.length > 0) {
+            sql += ` ORDER BY ${parts.join(', ')}`;
+        }
+    }
+
+    // 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}`;
+
+    return { sql, params };
+}
+
+/** The main `db.query(c => {...})` entry point. */
+export function executeProxyQuery<T>(
+    schemas: Record<string, z.ZodType<any>>,
+    callback: (ctx: any) => ProxyQueryResult,
+    executor: (sql: string, params: any[]) => T[],
+): T[] {
+    const { proxy, aliasMap } = createContextProxy(schemas);
+    const queryResult = callback(proxy);
+    const { sql, params } = compileProxyQuery(queryResult, aliasMap);
+    return executor(sql, params);
+}