ts-prorm-orm 1.1.0 → 1.2.0

package/dist/query-builders/sql-compiler.d.ts

@@ -0,0 +1,562 @@
+/**
+ * SQL Compiler
+ * Compiles query objects to SQL strings with parameter substitution
+ */
+import { Dialect } from '../dialects/dialect';
+import { WhereOptions, Order, IncludeOptions, WindowFunctionOptions, WindowFrame, ModelStatic, PivotOptions, UnpivotOptions } from '../types';
+/**
+ * Field mapping for attribute to column name translation
+ */
+export interface FieldMapping {
+    /**
+     * Map of attribute name to DB column name
+     * e.g., { firstName: 'first_name', lastName: 'last_name' }
+     */
+    attributeToColumn: Record<string, string>;
+    /**
+     * Map of DB column name to attribute name
+     * e.g., { first_name: 'firstName', last_name: 'lastName' }
+     */
+    columnToAttribute: Record<string, string>;
+}
+/**
+ * SQL Compiler options
+ */
+export interface SqlCompilerOptions {
+    /**
+     * The dialect to use for compilation
+     */
+    dialect?: Dialect;
+    /**
+     * Whether to use parameterized queries
+     */
+    parameterized?: boolean;
+    /**
+     * The character used for parameter placeholders
+     */
+    paramChar?: string;
+    /**
+     * Whether to inline values (not use parameters)
+     */
+    inlineValues?: boolean;
+    /**
+     * Pretty print the SQL
+     */
+    pretty?: boolean;
+    /**
+     * Field mapping for attribute to column name translation
+     * Used when model uses 'field' property in attributes
+     */
+    fieldMapping?: FieldMapping;
+}
+/**
+ * SQL Compiler class
+ * Compiles query objects to SQL strings with proper escaping
+ */
+export declare class SqlCompiler {
+    private dialect;
+    private options;
+    private fieldMapping;
+    constructor(dialect?: Dialect, options?: SqlCompilerOptions);
+    /**
+     * Set the field mapping
+     */
+    setFieldMapping(fieldMapping: FieldMapping): void;
+    /**
+     * Get the DB column name for an attribute
+     */
+    getColumnName(attributeName: string): string;
+    /**
+     * Get the attribute name for a DB column
+     */
+    getAttributeName(columnName: string): string;
+    /**
+     * Set the dialect
+     */
+    setDialect(dialect: Dialect): void;
+    /**
+     * Set compiler options
+     */
+    setOptions(options: SqlCompilerOptions): void;
+    /**
+     * Escape a value for use in SQL
+     */
+    escape(value: any): string;
+    /**
+     * Escape an identifier (column, table name)
+     */
+    escapeId(identifier: unknown): string;
+    /**
+     * Convert an attribute expression to SQL
+     * Handles fn(), col(), literal(), and plain strings
+     * @param attr - The attribute value (string, FnExpression, ColExpression, LiteralExpression, or array)
+     * @param tableAlias - Optional table alias to prepend to column names
+     * @returns The SQL representation of the attribute
+     */
+    attributeToSql(attr: any, tableAlias?: string): string;
+    /**
+     * Process an attribute value (which could be a column name, fn expression, col expression, or literal)
+     * into a SQL expression string
+     *
+     * @param attr - The attribute value to process
+     * @param tableAlias - Optional table alias to prefix column names with
+     * @returns The SQL expression string
+     */
+    processAttribute(attr: any, tableAlias?: string): string;
+    /**
+     * Convert an attribute to SQL with optional alias
+     * Handles formats like:
+     * - 'columnName' -> "columnName"
+     * - ['columnName', 'alias'] -> "columnName" AS "alias"
+     * - [fn('COUNT', col('id')), 'count'] -> COUNT("id") AS "count"
+     * - ['COUNT(*)', 'count'] -> COUNT(*) AS "count"
+     *
+     * @param attr - The attribute (string or array with alias)
+     * @param tableAlias - Optional table alias
+     * @returns SQL fragment with optional alias
+     */
+    attributeToSqlWithAlias(attr: any, tableAlias?: string): string;
+    /**
+     * Compile WHERE clause
+     */
+    compileWhere(where: WhereOptions, options?: {
+        paramChar?: string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build WHERE clause from WhereOptions
+     */
+    private buildWhereClause;
+    /**
+     * Build logical WHERE clause (AND, OR, NOT)
+     */
+    private buildLogicalWhereClause;
+    /**
+     * Build a single field condition
+     */
+    private buildFieldCondition;
+    /**
+     * Compile ORDER BY clause
+     */
+    compileOrder(order: Order): string;
+    /**
+     * Compile LIMIT/OFFSET clause
+     * Handles SQLite which requires LIMIT when using OFFSET
+     */
+    compileLimitOffset(limit?: number | string, offset?: number | string): string;
+    /**
+     * Compile GROUP BY clause
+     * Supports:
+     * - Plain strings: 'role', 'userId'
+     * - Arrays of strings: ['role', 'status']
+     * - col() expressions: col('role'), col('table.column')
+     * - fn() expressions: fn('UPPER', col('name'))
+     * - literal expressions: literal('YEAR(created_at)')
+     * - Array of mixed expressions
+     *
+     * @example
+     * group: 'role'
+     * group: ['role', 'status']
+     * group: col('role')
+     * group: [col('role'), fn('COUNT', col('id'))]
+     */
+    compileGroupBy(group?: string | string[], groupType?: 'rollup' | 'cube' | 'grouping' | 'none', groupingSets?: string[][]): string;
+    /**
+     * Compile Common Table Expression (CTE) clause
+     * Supports both regular WITH and WITH RECURSIVE
+     */
+    compileCTE(ctes?: Array<{
+        name: string;
+        columns?: string[];
+        query: string;
+        recursive?: boolean;
+    }>): string;
+    /**
+     * Compile HAVING clause for aggregation filtering
+     * Similar to WHERE but specifically for aggregated results
+     * Supports all operators: Op.gt, Op.eq, Op.between, etc.
+     * Also supports direct aggregation functions: COUNT(), SUM(), AVG(), MAX(), MIN()
+     */
+    compileHaving(having: any, options?: {
+        paramChar?: string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Get SQL operator from operator key
+     */
+    private getOperatorSql;
+    /**
+     * Build HAVING clause from having options
+     */
+    private buildHavingClause;
+    /**
+     * Build logical HAVING clause (AND, OR, NOT)
+     */
+    private buildLogicalHavingClause;
+    /**
+     * Build a single HAVING condition
+     */
+    private buildHavingCondition;
+    /**
+     * Compile a full SELECT query
+     */
+    compileSelect(options: {
+        tableName: string;
+        attributes?: string[] | {
+            include?: string[];
+            exclude?: string[];
+        };
+        where?: WhereOptions;
+        include?: IncludeOptions[];
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+        group?: string | string[];
+        groupType?: 'rollup' | 'cube' | 'grouping' | 'none';
+        groupingSets?: string[][];
+        having?: WhereOptions;
+        cte?: Array<{
+            name: string;
+            columns?: string[];
+            query: string;
+            recursive?: boolean;
+        }>;
+        pivot?: PivotOptions;
+        unpivot?: UnpivotOptions;
+        pivotValues?: string[];
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile a PIVOT query - transform rows to columns
+     */
+    compilePivot(options: {
+        tableName: string;
+        pivot: PivotOptions;
+        groupBy: string | string[];
+        where?: WhereOptions;
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile a PIVOT query with specific pivot values (after they're resolved)
+     */
+    compilePivotWithValues(options: {
+        tableName: string;
+        pivot: PivotOptions;
+        pivotValues: string[];
+        groupBy: string | string[];
+        where?: WhereOptions;
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile an UNPIVOT query - transform columns to rows
+     */
+    compileUnpivot(options: {
+        tableName: string;
+        unpivot: UnpivotOptions;
+        where?: WhereOptions;
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile an INSERT query
+     */
+    compileInsert(options: {
+        tableName: string;
+        values: Record<string, any>;
+        returning?: boolean | string[];
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile an UPDATE query
+     */
+    compileUpdate(options: {
+        tableName: string;
+        values: Record<string, any>;
+        where: WhereOptions;
+        limit?: number;
+        returning?: boolean | string[];
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile a DELETE query
+     */
+    compileDelete(options: {
+        tableName: string;
+        where: WhereOptions;
+        limit?: number;
+        returning?: boolean | string[];
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile a UNION/EXCEPT/INTERSECT query
+     * Supports combining multiple queries with UNION, UNION ALL, EXCEPT, or INTERSECT
+     */
+    compileUnion(options: {
+        /** The main query (uses same structure as compileSelect) */
+        main: {
+            tableName: string;
+            attributes?: string[] | {
+                include?: string[];
+                exclude?: string[];
+            };
+            where?: WhereOptions;
+            include?: IncludeOptions[];
+            order?: Order;
+            limit?: number | string;
+            offset?: number | string;
+        };
+        /** Array of union queries */
+        union: Array<{
+            type: 'UNION' | 'UNION ALL' | 'EXCEPT' | 'INTERSECT';
+            model?: ModelStatic<any>;
+            tableName?: string;
+            where?: WhereOptions;
+            attributes?: string[] | {
+                include?: string[];
+                exclude?: string[];
+            };
+            order?: Order;
+            limit?: number | string;
+            offset?: number | string;
+            include?: IncludeOptions[];
+        }>;
+        /** Order by for the combined result */
+        order?: Order;
+        /** Limit for the combined result */
+        limit?: number | string;
+        /** Offset for the combined result */
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile an EXCEPT query - returns rows from main query that don't exist in except query
+     */
+    compileExcept(mainQuery: {
+        tableName: string;
+        attributes?: string[] | {
+            include?: string[];
+            exclude?: string[];
+        };
+        where?: WhereOptions;
+        include?: IncludeOptions[];
+    }, exceptQuery: {
+        tableName: string;
+        attributes?: string[] | {
+            include?: string[];
+            exclude?: string[];
+        };
+        where?: WhereOptions;
+        include?: IncludeOptions[];
+    }, options?: {
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Compile an INTERSECT query - returns rows that exist in both queries
+     */
+    compileIntersect(mainQuery: {
+        tableName: string;
+        attributes?: string[] | {
+            include?: string[];
+            exclude?: string[];
+        };
+        where?: WhereOptions;
+        include?: IncludeOptions[];
+    }, intersectQuery: {
+        tableName: string;
+        attributes?: string[] | {
+            include?: string[];
+            exclude?: string[];
+        };
+        where?: WhereOptions;
+        include?: IncludeOptions[];
+    }, options?: {
+        order?: Order;
+        limit?: number | string;
+        offset?: number | string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Format SQL for different dialects
+     */
+    formatForDialect(sql: string, dialect: string): string;
+    /**
+     * Format SQL for MySQL
+     */
+    private formatForMySQL;
+    /**
+     * Format SQL for PostgreSQL
+     */
+    private formatForPostgres;
+    /**
+     * Format SQL for SQLite
+     */
+    private formatForSQLite;
+    /**
+     * Format SQL for MSSQL
+     */
+    private formatForMSSQL;
+    /**
+     * Resolve the 'all' include option to actual include configurations
+     */
+    private resolveAllInclude;
+    /**
+     * Flatten nested includes for proper JOIN ordering
+     * Returns a flat array of include objects with parent alias information
+     */
+    private flattenIncludesForJoins;
+    /**
+     * Build anti-join subquery for NOT EXISTS or NOT IN patterns
+     */
+    private buildAntiJoinSubquery;
+    /**
+     * Build lateral subquery for inline subqueries with LATERAL keyword
+     */
+    private buildLateralSubquery;
+    /**
+     * Generate column list with proper aliasing to avoid duplicates
+     */
+    private generateSelectColumns;
+    /**
+     * Compile PARTITION BY clause
+     */
+    compilePartitionBy(partitionBy: string | string[] | undefined): string;
+    /**
+     * Compile window frame specification
+     * Examples:
+     * - ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
+     * - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+     * - GROUPS 2 PRECEDING AND CURRENT ROW
+     */
+    compileWindowFrame(windowFrame: WindowFrame | undefined): string;
+    /**
+     * Compile a single frame bound (start or end)
+     */
+    private compileFrameBound;
+    /**
+     * Compile lock options for row-level locking
+     * Supports NOWAIT and SKIP LOCKED for PostgreSQL and MySQL 8.0+
+     * @param lock - Lock options
+     * @param dialect - The database dialect
+     * @returns The compiled lock SQL clause
+     */
+    compileLockOptions(lock: any, dialect?: string): string;
+    /**
+     * Compile OVER clause with partition, order, and window frame
+     */
+    compileOverClause(options: WindowFunctionOptions): string;
+    /**
+     * Compile a window function expression
+     * @param functionName - The window function name (ROW_NUMBER, RANK, etc.)
+     * @param args - Arguments to the window function
+     * @param options - Window function options
+     * @returns The compiled SQL expression
+     */
+    compileWindowFunction(functionName: string, args?: any[], options?: WindowFunctionOptions): string;
+    /**
+     * Pretty print SQL
+     */
+    prettyPrint(sql: string): string;
+}
+/**
+ * Generate MySQL JSON_EXTRACT function
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path (e.g., '$.key' or '$.array[0]')
+ */
+export declare function jsonExtract(columnName: string, path: string): string;
+/**
+ * Generate MySQL JSON_UNQUOTE(JSON_EXTRACT(...)) for unquoted values
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path (e.g., '$.key' or '$.array[0]')
+ */
+export declare function jsonExtractUnquote(columnName: string, path: string): string;
+/**
+ * Generate MySQL JSON_SET function to set a value in JSON
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path
+ * @param value - The value to set (can be a column reference or literal)
+ * @param extraPaths - Additional paths and values to set
+ */
+export declare function jsonSet(columnName: string, path: string, value: string, ...extraPaths: [string, string][]): string;
+/**
+ * Generate MySQL JSON_INSERT function to insert a value in JSON
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path
+ * @param value - The value to insert
+ */
+export declare function jsonInsert(columnName: string, path: string, value: string): string;
+/**
+ * Generate MySQL JSON_REPLACE function to replace a value in JSON
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path
+ * @param value - The value to replace
+ */
+export declare function jsonReplace(columnName: string, path: string, value: string): string;
+/**
+ * Generate MySQL JSON_REMOVE function to remove a value from JSON
+ * @param columnName - The column containing JSON data
+ * @param path - The JSON path to remove
+ */
+export declare function jsonRemove(columnName: string, path: string): string;
+/**
+ * Generate MySQL JSON_KEYS function to get keys from JSON object
+ * @param columnName - The column containing JSON data
+ * @param path - Optional path to get keys from specific object
+ */
+export declare function jsonKeys(columnName: string, path?: string): string;
+/**
+ * Generate MySQL JSON_LENGTH function to get length of JSON array/object
+ * @param columnName - The column containing JSON data
+ * @param path - Optional path to get length of specific array/object
+ */
+export declare function jsonLength(columnName: string, path?: string): string;
+/**
+ * Generate MySQL JSON_CONTAINS function to check if JSON contains a value
+ * @param columnName - The column containing JSON data
+ * @param value - The value to check for
+ * @param path - The path to check at
+ */
+export declare function jsonContains(columnName: string, value: string, path: string): string;
+/**
+ * Generate MySQL JSON_SEARCH function for full-text search in JSON
+ * @param columnName - The column containing JSON data
+ * @param searchString - The string to search for
+ * @param escapeChar - Optional escape character
+ * @param path - Optional path to search within
+ */
+export declare function jsonSearch(columnName: string, searchString: string, escapeChar?: string, path?: string): string;
+export default SqlCompiler;

package/dist/query-builders/subquery-builder.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Subquery Builder
+ * Provides an ORM-like way to build subqueries without raw SQL
+ */
+/**
+ * Subquery builder options
+ */
+export interface SubqueryOptions {
+    /** Model or table name to use for the subquery */
+    model: string | {
+        tableName?: string;
+        name?: string;
+    };
+    /** Where conditions */
+    where?: Record<string, any>;
+    /** Columns to select */
+    columns?: string[];
+    /** Order by */
+    order?: any;
+    /** Group by */
+    group?: string | string[];
+    /** Having conditions */
+    having?: Record<string, any>;
+    /** Limit results */
+    limit?: number;
+    /** Offset results */
+    offset?: number;
+}
+/**
+ * Exists subquery options
+ */
+export interface ExistsSubqueryOptions {
+    /** Model or table name to check existence in */
+    model: string | {
+        tableName?: string;
+        name?: string;
+    };
+    /** Where conditions */
+    where?: Record<string, any>;
+    /** Join type for EXISTS */
+    correlation?: 'INNER' | 'LEFT';
+}
+/**
+ * Scalar subquery options (returns single value)
+ */
+export interface ScalarSubqueryOptions {
+    /** Model or table name for the subquery */
+    model: string | {
+        tableName?: string;
+        name?: string;
+    };
+    /** Column to aggregate */
+    column: string;
+    /** Aggregate function */
+    aggregate?: 'COUNT' | 'SUM' | 'AVG' | 'MAX' | 'MIN';
+    /** Where conditions */
+    where?: Record<string, any>;
+}
+/**
+ * Builder for creating subqueries programmatically
+ */
+export declare class SubqueryBuilder {
+    /**
+     * Create an IN subquery
+     * @example
+     * // Find users with posts using model class
+     * User.findAll({
+     *   where: {
+     *     id: { [Op.in]: SubqueryBuilder.select('userId', { model: Post }) }
+     *   }
+     * })
+     * @example
+     * // Using table name string
+     * SubqueryBuilder.select('userId', { model: 'posts' })
+     */
+    static select(column: string, options: SubqueryOptions): string;
+    /**
+     * Create an EXISTS subquery
+     * @example
+     * // Find users who have posts using model class
+     * User.findAll({
+     *   where: {
+     *     [Op.exists]: SubqueryBuilder.exists({
+     *       model: Post,
+     *       where: { userId: { [Op.col]: 'User.id' } }
+     *     })
+     *   }
+     * })
+     * @example
+     * // Using table name string
+     * SubqueryBuilder.exists({ model: 'posts', where: {...} })
+     */
+    static exists(options: ExistsSubqueryOptions): object;
+    /**
+     * Create a NOT EXISTS subquery
+     */
+    static notExists(options: ExistsSubqueryOptions): object;
+    /**
+     * Create a scalar subquery (COUNT, SUM, etc.)
+     * @example
+     * // Get user with post count using model class
+     * User.findAll({
+     *   attributes: {
+     *     include: [
+     *       [SubqueryBuilder.count({ model: Post, column: 'userId' }), 'postCount']
+     *     ]
+     *   }
+     * })
+     */
+    static count(options: ScalarSubqueryOptions): object;
+    static sum(options: ScalarSubqueryOptions): object;
+    static avg(options: ScalarSubqueryOptions): object;
+    static max(options: ScalarSubqueryOptions): object;
+    static min(options: ScalarSubqueryOptions): object;
+    /**
+     * Create a correlated subquery using column reference
+     * @example
+     * SubqueryBuilder.correlated({ outerModel: User, outerColumn: 'id', innerModel: Post, innerColumn: 'userId' })
+     */
+    static correlated(options: {
+        outerModel: string | {
+            tableName?: string;
+            name?: string;
+        };
+        outerColumn: string;
+        innerModel: string | {
+            tableName?: string;
+            name?: string;
+        };
+        innerColumn: string;
+    }): object;
+}
+export default SubqueryBuilder;