@warlock.js/cascade 4.0.92 → 4.0.93

package/esm/drivers/postgres/postgres-query-parser.js

@@ -0,0 +1,706 @@
+import {PostgresDialect}from'./postgres-dialect.js';/**
+ * PostgreSQL Query Parser
+ *
+ * Translates Cascade query operations into PostgreSQL SQL queries.
+ * Mirrors the MongoQueryParser pattern but generates SQL instead
+ * of MongoDB aggregation pipelines.
+ *
+ * @module cascade/drivers/postgres
+ */
+/**
+ * PostgreSQL Query Parser.
+ *
+ * Converts a list of query operations into a SQL query string with parameters.
+ * Handles SELECT, WHERE, JOIN, ORDER BY, GROUP BY, LIMIT/OFFSET clauses.
+ *
+ * @example
+ * ```typescript
+ * const parser = new PostgresQueryParser({
+ *   table: 'users',
+ *   operations: [
+ *     { type: 'where', data: { field: 'name', operator: '=', value: 'Alice' } },
+ *     { type: 'orderBy', data: { field: 'createdAt', direction: 'desc' } },
+ *     { type: 'limit', data: { value: 10 } }
+ *   ]
+ * });
+ *
+ * const { sql, params } = parser.parse();
+ * // sql: 'SELECT * FROM "users" WHERE "name" = $1 ORDER BY "createdAt" DESC LIMIT 10'
+ * // params: ['Alice']
+ * ```
+ */
+class PostgresQueryParser {
+    /**
+     * Target table name.
+     */
+    table;
+    /**
+     * Table alias.
+     */
+    alias;
+    /**
+     * Operations to process.
+     */
+    operations;
+    /**
+     * SQL dialect for syntax.
+     */
+    dialect;
+    /**
+     * Current parameter index (1-based for PostgreSQL).
+     */
+    paramIndex = 1;
+    /**
+     * Collected parameters.
+     */
+    params = [];
+    /**
+     * SELECT columns.
+     */
+    selectColumns = [];
+    /**
+     * Deselected (excluded) columns.
+     */
+    deselectColumns = [];
+    /**
+     * Raw SELECT expressions.
+     */
+    selectRaw = [];
+    /**
+     * WHERE clauses.
+     */
+    whereClauses = [];
+    /**
+     * JOIN clauses.
+     */
+    joinClauses = [];
+    /**
+     * ORDER BY clauses.
+     */
+    orderClauses = [];
+    /**
+     * GROUP BY columns.
+     */
+    groupColumns = [];
+    /**
+     * HAVING clauses.
+     */
+    havingClauses = [];
+    /**
+     * LIMIT value.
+     */
+    limitValue;
+    /**
+     * OFFSET value.
+     */
+    offsetValue;
+    /**
+     * DISTINCT flag.
+     */
+    isDistinct = false;
+    /**
+     * Tracked joined tables (for table reference detection).
+     */
+    joinedTables = new Set();
+    /**
+     * Create a new query parser.
+     *
+     * @param options - Parser configuration
+     */
+    constructor(options) {
+        this.table = options.table;
+        this.alias = options.alias;
+        this.operations = options.operations;
+        this.dialect = options.dialect ?? new PostgresDialect();
+    }
+    /**
+     * Parse all operations and build the SQL query.
+     *
+     * @returns Object with SQL string and parameter values
+     */
+    parse() {
+        // Process each operation
+        for (const operation of this.operations) {
+            this.processOperation(operation);
+        }
+        // Build the final SQL query
+        const sql = this.buildSql();
+        return { sql, params: this.params };
+    }
+    /**
+     * Get a formatted string representation of the query.
+     *
+     * @returns Formatted SQL with parameters
+     */
+    toPrettyString() {
+        const { sql, params } = this.parse();
+        return `${sql}\n-- Parameters: ${JSON.stringify(params)}`;
+    }
+    /**
+     * Process a single operation.
+     *
+     * @param operation - The operation to process
+     */
+    processOperation(operation) {
+        const { type, data } = operation;
+        switch (type) {
+            // WHERE operations
+            case "where":
+                this.processWhere(data, "AND");
+                break;
+            case "orWhere":
+                this.processWhere(data, "OR");
+                break;
+            case "whereRaw":
+                this.processWhereRaw(data, "AND");
+                break;
+            case "orWhereRaw":
+                this.processWhereRaw(data, "OR");
+                break;
+            case "whereIn":
+                this.processWhereIn(data, false);
+                break;
+            case "whereNotIn":
+                this.processWhereIn(data, true);
+                break;
+            case "whereNull":
+                this.processWhereNull(data, false);
+                break;
+            case "whereNotNull":
+                this.processWhereNull(data, true);
+                break;
+            case "whereBetween":
+                this.processWhereBetween(data, false);
+                break;
+            case "whereNotBetween":
+                this.processWhereBetween(data, true);
+                break;
+            case "whereLike":
+                this.processWhereLike(data, false);
+                break;
+            case "whereNotLike":
+                this.processWhereLike(data, true);
+                break;
+            case "whereColumn":
+                this.processWhereColumn(data, "AND");
+                break;
+            case "orWhereColumn":
+                this.processWhereColumn(data, "OR");
+                break;
+            case "whereJsonContains":
+                this.processWhereJsonContains(data, false);
+                break;
+            case "whereJsonDoesntContain":
+                this.processWhereJsonContains(data, true);
+                break;
+            case "whereFullText":
+                this.processWhereFullText(data);
+                break;
+            // SELECT operations
+            case "select":
+                this.processSelect(data);
+                break;
+            case "selectRaw":
+                this.processSelectRaw(data);
+                break;
+            case "deselect":
+                this.processDeselect(data);
+                break;
+            // JOIN operations
+            case "join":
+            case "innerJoin":
+                this.processJoin(data, "INNER");
+                break;
+            case "leftJoin":
+                this.processJoin(data, "LEFT");
+                break;
+            case "rightJoin":
+                this.processJoin(data, "RIGHT");
+                break;
+            case "fullJoin":
+                this.processJoin(data, "FULL OUTER");
+                break;
+            case "crossJoin":
+                this.processCrossJoin(data);
+                break;
+            case "joinRaw":
+                this.processJoinRaw(data);
+                break;
+            // ORDER operations
+            case "orderBy":
+                this.processOrderBy(data);
+                break;
+            case "orderByRaw":
+                this.processOrderByRaw(data);
+                break;
+            // GROUP operations
+            case "groupBy":
+                this.processGroupBy(data);
+                break;
+            case "having":
+                this.processHaving(data);
+                break;
+            case "havingRaw":
+                this.processHavingRaw(data);
+                break;
+            // LIMIT operations
+            case "limit":
+                this.limitValue = data.value;
+                break;
+            case "offset":
+                this.offsetValue = data.value;
+                break;
+            // Other
+            case "distinct":
+                this.isDistinct = true;
+                break;
+            // joinWith select related columns
+            case "selectRelatedColumns":
+                this.processSelectRelatedColumns(data);
+                break;
+        }
+    }
+    /**
+     * Build the final SQL query from collected clauses.
+     *
+     * @returns Complete SQL query string
+     */
+    buildSql() {
+        const parts = [];
+        // SELECT clause
+        parts.push(this.buildSelectClause());
+        // FROM clause
+        const quotedTable = this.dialect.quoteIdentifier(this.table);
+        const fromClause = this.alias
+            ? `FROM ${quotedTable} AS ${this.dialect.quoteIdentifier(this.alias)}`
+            : `FROM ${quotedTable}`;
+        parts.push(fromClause);
+        // JOIN clauses
+        if (this.joinClauses.length > 0) {
+            parts.push(this.joinClauses.join(" "));
+        }
+        // WHERE clause
+        if (this.whereClauses.length > 0) {
+            parts.push(`WHERE ${this.whereClauses.join(" ")}`);
+        }
+        // GROUP BY clause
+        if (this.groupColumns.length > 0) {
+            const quotedCols = this.groupColumns.map((c) => this.dialect.quoteIdentifier(c));
+            parts.push(`GROUP BY ${quotedCols.join(", ")}`);
+        }
+        // HAVING clause
+        if (this.havingClauses.length > 0) {
+            parts.push(`HAVING ${this.havingClauses.join(" AND ")}`);
+        }
+        // ORDER BY clause
+        if (this.orderClauses.length > 0) {
+            parts.push(`ORDER BY ${this.orderClauses.join(", ")}`);
+        }
+        // LIMIT/OFFSET
+        const limitOffset = this.dialect.limitOffset(this.limitValue, this.offsetValue);
+        if (limitOffset) {
+            parts.push(limitOffset);
+        }
+        return parts.join(" ");
+    }
+    /**
+     * Build the SELECT clause.
+     *
+     * @returns SELECT clause string
+     */
+    buildSelectClause() {
+        const distinct = this.isDistinct ? "DISTINCT " : "";
+        // If no specific columns, select all
+        if (this.selectColumns.length === 0 && this.selectRaw.length === 0) {
+            // Handle deselect by explicitly listing columns (would need schema info)
+            // For now, just use *
+            return `SELECT ${distinct}*`;
+        }
+        const columns = [];
+        // Add selected columns
+        for (const col of this.selectColumns) {
+            if (!this.deselectColumns.includes(col)) {
+                columns.push(this.dialect.quoteIdentifier(col));
+            }
+        }
+        // Add raw expressions
+        columns.push(...this.selectRaw);
+        return `SELECT ${distinct}${columns.join(", ")}`;
+    }
+    /**
+     * Add a placeholder and parameter.
+     *
+     * @param value - Parameter value
+     * @returns Placeholder string ($1, $2, etc.)
+     */
+    addParam(value) {
+        this.params.push(value);
+        return this.dialect.placeholder(this.paramIndex++);
+    }
+    /**
+     * Process a basic WHERE operation.
+     */
+    processWhere(data, boolean) {
+        const field = data.field;
+        const operator = data.operator ?? "=";
+        const value = data.value;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const placeholder = this.addParam(value);
+        const clause = `${quotedField} ${this.mapOperator(operator)} ${placeholder}`;
+        this.addWhereClause(clause, boolean);
+    }
+    /**
+     * Process a raw WHERE operation.
+     */
+    processWhereRaw(data, boolean) {
+        const expression = data.expression;
+        const bindings = data.bindings ?? [];
+        // Replace ? placeholders with $n
+        let processed = expression;
+        for (const binding of bindings) {
+            processed = processed.replace("?", this.addParam(binding));
+        }
+        this.addWhereClause(processed, boolean);
+    }
+    /**
+     * Process WHERE IN / NOT IN.
+     */
+    processWhereIn(data, negate) {
+        const field = data.field;
+        const values = data.values;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const operator = negate ? "!= ALL" : "= ANY";
+        const placeholder = this.addParam(values);
+        this.addWhereClause(`${quotedField} ${operator}(${placeholder})`, "AND");
+    }
+    /**
+     * Process WHERE NULL / NOT NULL.
+     */
+    processWhereNull(data, negate) {
+        const field = data.field;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const clause = negate ? `${quotedField} IS NOT NULL` : `${quotedField} IS NULL`;
+        this.addWhereClause(clause, "AND");
+    }
+    /**
+     * Process WHERE BETWEEN / NOT BETWEEN.
+     */
+    processWhereBetween(data, negate) {
+        const field = data.field;
+        const range = data.range;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const placeholder1 = this.addParam(range[0]);
+        const placeholder2 = this.addParam(range[1]);
+        const keyword = negate ? "NOT BETWEEN" : "BETWEEN";
+        this.addWhereClause(`${quotedField} ${keyword} ${placeholder1} AND ${placeholder2}`, "AND");
+    }
+    /**
+     * Process WHERE LIKE / NOT LIKE.
+     */
+    processWhereLike(data, negate) {
+        const field = data.field;
+        const pattern = data.pattern;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const { operator } = this.dialect.likePattern(pattern, true);
+        const placeholder = this.addParam(pattern);
+        const keyword = negate ? `NOT ${operator}` : operator;
+        this.addWhereClause(`${quotedField} ${keyword} ${placeholder}`, "AND");
+    }
+    /**
+     * Process WHERE column comparison.
+     */
+    processWhereColumn(data, boolean) {
+        const first = data.first;
+        const operator = data.operator ?? "=";
+        const second = data.second;
+        const quotedFirst = this.dialect.quoteIdentifier(first);
+        const quotedSecond = this.dialect.quoteIdentifier(second);
+        this.addWhereClause(`${quotedFirst} ${operator} ${quotedSecond}`, boolean);
+    }
+    /**
+     * Process WHERE JSON contains.
+     */
+    processWhereJsonContains(data, negate) {
+        const path = data.path;
+        const value = data.value;
+        const quotedPath = this.dialect.quoteIdentifier(path);
+        const jsonValue = JSON.stringify(value);
+        const operator = negate ? "NOT @>" : "@>";
+        this.addWhereClause(`${quotedPath} ${operator} '${jsonValue}'::jsonb`, "AND");
+    }
+    /**
+     * Process full-text search WHERE.
+     */
+    processWhereFullText(data) {
+        const fields = data.fields;
+        const query = data.query;
+        // Build tsvector from fields
+        const tsVectors = fields
+            .map((f) => `to_tsvector('english', ${this.dialect.quoteIdentifier(f)})`)
+            .join(" || ");
+        const placeholder = this.addParam(query);
+        this.addWhereClause(`(${tsVectors}) @@ plainto_tsquery('english', ${placeholder})`, "AND");
+    }
+    /**
+     * Process SELECT operation.
+     */
+    processSelect(data) {
+        const fields = data.fields;
+        if (Array.isArray(fields)) {
+            this.selectColumns.push(...fields);
+        }
+        else {
+            // Handle aliases: { field: 'alias' }
+            for (const [field, alias] of Object.entries(fields)) {
+                const quotedField = this.dialect.quoteIdentifier(field);
+                const quotedAlias = this.dialect.quoteIdentifier(alias);
+                this.selectRaw.push(`${quotedField} AS ${quotedAlias}`);
+            }
+        }
+    }
+    /**
+     * Process raw SELECT expression.
+     */
+    processSelectRaw(data) {
+        const expression = data.expression;
+        if (typeof expression === "string") {
+            this.selectRaw.push(expression);
+        }
+        else {
+            // Handle object expressions (for compatibility)
+            for (const [alias, expr] of Object.entries(expression)) {
+                this.selectRaw.push(`${expr} AS ${this.dialect.quoteIdentifier(alias)}`);
+            }
+        }
+    }
+    /**
+     * Process DESELECT operation.
+     */
+    processDeselect(data) {
+        const fields = data.fields;
+        this.deselectColumns.push(...fields);
+    }
+    /**
+     * Process SELECT for related columns (joinWith).
+     * Uses row_to_json to package all related columns into a single JSON column.
+     * Also ensures main table columns are selected.
+     */
+    processSelectRelatedColumns(data) {
+        const alias = data.alias;
+        const quotedAlias = this.dialect.quoteIdentifier(alias);
+        const quotedTable = this.dialect.quoteIdentifier(this.table);
+        // Ensure main table columns are selected (only add once)
+        if (!this.selectRaw.includes(`${quotedTable}.*`)) {
+            this.selectRaw.unshift(`${quotedTable}.*`);
+        }
+        // Use row_to_json to get all columns from the joined table as a single JSON object
+        // The column will be named like "_rel_author" and contain { id, name, email, ... }
+        this.selectRaw.push(`row_to_json(${quotedAlias}.*) AS ${quotedAlias}`);
+    }
+    /**
+     * Process JOIN operation with smart field detection.
+     *
+     * Handles both regular columns and JSONB nested paths:
+     * - "id" → "table"."id" (auto-prefixed)
+     * - "users.id" → "users"."id" (explicit table)
+     * - "createdBy.id" → "table"."createdBy"->>'id' (JSONB path)
+     * - "posts.createdBy.id" → "posts"."createdBy"->>'id' (JSONB with table)
+     */
+    processJoin(data, type) {
+        const options = data;
+        const joinTable = "table" in options ? options.table : "";
+        const localField = "localField" in options ? options.localField : "";
+        const foreignField = "foreignField" in options ? options.foreignField : "";
+        const alias = "alias" in options ? options.alias : undefined;
+        const quotedTable = this.dialect.quoteIdentifier(joinTable);
+        const tableRef = alias
+            ? `${quotedTable} AS ${this.dialect.quoteIdentifier(alias)}`
+            : quotedTable;
+        const tableAlias = alias ?? joinTable;
+        // Track the joined table for reference detection
+        this.joinedTables.add(joinTable);
+        if (alias) {
+            this.joinedTables.add(alias);
+        }
+        // Parse local field (belongs to main table)
+        const quotedLocal = this.parseJoinField(localField, this.table, this.alias);
+        // Parse foreign field (belongs to join table)
+        const quotedForeign = this.parseJoinField(foreignField, joinTable, tableAlias);
+        this.joinClauses.push(`${type} JOIN ${tableRef} ON ${quotedLocal} = ${quotedForeign}`);
+    }
+    /**
+     * Parse a join field with smart detection for table prefixes and JSONB paths.
+     *
+     * @param field - The field string (e.g., "id", "users.id", "createdBy.id")
+     * @param defaultTable - Default table to use if no prefix
+     * @param tableAlias - Table alias to use if provided
+     * @returns Properly quoted SQL expression
+     */
+    parseJoinField(field, defaultTable, tableAlias) {
+        if (!field)
+            return "";
+        const effectiveTable = tableAlias ?? defaultTable;
+        const parts = field.split(".");
+        // Single part: just a column name, prefix with default table
+        if (parts.length === 1) {
+            return `${this.dialect.quoteIdentifier(effectiveTable)}.${this.dialect.quoteIdentifier(field)}`;
+        }
+        // Two parts: could be "table.column" or "jsonbColumn.key"
+        if (parts.length === 2) {
+            const [first, second] = parts;
+            // Check if first part is a known table (main table, join table, or alias)
+            if (this.isTableReference(first)) {
+                // It's table.column - regular column reference
+                return `${this.dialect.quoteIdentifier(first)}.${this.dialect.quoteIdentifier(second)}`;
+            }
+            // It's jsonbColumn.key - JSONB path
+            return this.buildJsonbPath(effectiveTable, first, [second]);
+        }
+        // Three or more parts: "table.jsonbColumn.key..." or "jsonbColumn.key1.key2..."
+        const [first, second, ...rest] = parts;
+        if (this.isTableReference(first)) {
+            // First part is table: "posts.createdBy.id" → table is "posts", JSONB is "createdBy.id"
+            return this.buildJsonbPath(first, second, rest);
+        }
+        // No table prefix: "createdBy.address.city" → use default table
+        return this.buildJsonbPath(effectiveTable, first, [second, ...rest]);
+    }
+    /**
+     * Check if a string is a table reference (main table or join table).
+     */
+    isTableReference(name) {
+        if (name === this.table || name === this.alias) {
+            return true;
+        }
+        if (this.joinedTables.has(name)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Build a JSONB path expression.
+     *
+     * @param table - Table name
+     * @param column - JSONB column name
+     * @param path - Array of nested keys
+     * @returns PostgreSQL JSONB path expression
+     *
+     * @example
+     * buildJsonbPath("posts", "createdBy", ["id"])
+     * // Returns: ("posts"."createdBy"->>'id')::integer
+     *
+     * buildJsonbPath("posts", "createdBy", ["address", "city"])
+     * // Returns: "posts"."createdBy"->'address'->>'city'
+     */
+    buildJsonbPath(table, column, path) {
+        const quotedTable = this.dialect.quoteIdentifier(table);
+        const quotedColumn = this.dialect.quoteIdentifier(column);
+        if (path.length === 0) {
+            return `${quotedTable}.${quotedColumn}`;
+        }
+        // Build JSONB path: use -> for intermediate keys, ->> for final key (returns text)
+        let expression = `${quotedTable}.${quotedColumn}`;
+        for (let i = 0; i < path.length; i++) {
+            const isLast = i === path.length - 1;
+            const operator = isLast ? "->>" : "->";
+            expression += `${operator}'${path[i]}'`;
+        }
+        // Cast to integer if the path ends with 'id' (common pattern for foreign keys)
+        const lastKey = path[path.length - 1].toLowerCase();
+        if (lastKey === "id" || lastKey.endsWith("id")) {
+            expression = `(${expression})::integer`;
+        }
+        return expression;
+    }
+    /**
+     * Process CROSS JOIN operation.
+     */
+    processCrossJoin(data) {
+        const table = data.table;
+        const quotedTable = this.dialect.quoteIdentifier(table);
+        this.joinClauses.push(`CROSS JOIN ${quotedTable}`);
+    }
+    /**
+     * Process raw JOIN expression.
+     */
+    processJoinRaw(data) {
+        const expression = data.expression;
+        const bindings = data.bindings ?? [];
+        let processed = expression;
+        for (const binding of bindings) {
+            processed = processed.replace("?", this.addParam(binding));
+        }
+        this.joinClauses.push(processed);
+    }
+    /**
+     * Process ORDER BY operation.
+     */
+    processOrderBy(data) {
+        const field = data.field;
+        const direction = (data.direction ?? "asc").toUpperCase();
+        const quotedField = this.dialect.quoteIdentifier(field);
+        this.orderClauses.push(`${quotedField} ${direction}`);
+    }
+    /**
+     * Process raw ORDER BY expression.
+     */
+    processOrderByRaw(data) {
+        const expression = data.expression;
+        this.orderClauses.push(expression);
+    }
+    /**
+     * Process GROUP BY operation.
+     */
+    processGroupBy(data) {
+        const fields = data.fields;
+        const columns = Array.isArray(fields) ? fields : [fields];
+        this.groupColumns.push(...columns);
+    }
+    /**
+     * Process HAVING operation.
+     */
+    processHaving(data) {
+        const field = data.field;
+        const operator = data.operator ?? "=";
+        const value = data.value;
+        const quotedField = this.dialect.quoteIdentifier(field);
+        const placeholder = this.addParam(value);
+        this.havingClauses.push(`${quotedField} ${operator} ${placeholder}`);
+    }
+    /**
+     * Process raw HAVING expression.
+     */
+    processHavingRaw(data) {
+        const expression = data.expression;
+        this.havingClauses.push(expression);
+    }
+    /**
+     * Add a WHERE clause with boolean operator.
+     */
+    addWhereClause(clause, boolean) {
+        if (this.whereClauses.length === 0) {
+            this.whereClauses.push(clause);
+        }
+        else {
+            this.whereClauses.push(`${boolean} ${clause}`);
+        }
+    }
+    /**
+     * Map Cascade operators to SQL operators.
+     */
+    mapOperator(operator) {
+        const mapping = {
+            "=": "=",
+            "!=": "!=",
+            "<>": "<>",
+            ">": ">",
+            ">=": ">=",
+            "<": "<",
+            "<=": "<=",
+            like: "LIKE",
+            notLike: "NOT LIKE",
+            ilike: "ILIKE",
+        };
+        return mapping[operator.toLowerCase()] ?? operator;
+    }
+}export{PostgresQueryParser};//# sourceMappingURL=postgres-query-parser.js.map