@gblikas/querykit 0.0.0

package/dist/translators/drizzle/index.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * Drizzle ORM Translator for QueryKit
+ *
+ * This translator converts QueryKit AST expressions into Drizzle ORM
+ * query conditions that can be used in Drizzle's SQL query builder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrizzleTranslator = exports.DrizzleTranslationError = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+/**
+ * Error thrown when translation fails
+ */
+class DrizzleTranslationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DrizzleTranslationError';
+    }
+}
+exports.DrizzleTranslationError = DrizzleTranslationError;
+/**
+ * Translates QueryKit AST expressions to Drizzle ORM conditions
+ */
+class DrizzleTranslator {
+    constructor(options = {}) {
+        this.options = {
+            normalizeFieldNames: options.normalizeFieldNames ?? false,
+            fieldMappings: options.fieldMappings ?? {},
+            schema: options.schema ?? {}
+        };
+    }
+    /**
+     * Translate a QueryKit expression to a Drizzle ORM condition
+     */
+    translate(expression) {
+        try {
+            return this.translateExpression(expression);
+        }
+        catch (error) {
+            throw new DrizzleTranslationError(`Failed to translate expression: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if an expression can be translated to Drizzle ORM
+     */
+    canTranslate(expression) {
+        try {
+            this.translateExpression(expression);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Translate any QueryKit expression to a Drizzle ORM condition
+     */
+    translateExpression(expression) {
+        if (!expression) {
+            throw new DrizzleTranslationError('Empty expression');
+        }
+        switch (expression.type) {
+            case 'comparison':
+                return this.translateComparisonExpression(expression);
+            case 'logical':
+                return this.translateLogicalExpression(expression);
+            default:
+                throw new DrizzleTranslationError(`Unsupported expression type: ${expression.type}`);
+        }
+    }
+    /**
+     * Translate a comparison expression to a Drizzle ORM condition
+     */
+    translateComparisonExpression(expression) {
+        const { field, operator, value } = expression;
+        const fieldName = this.normalizeField(field);
+        // Get the field from the schema if available
+        const schemaField = this.getSchemaField(fieldName);
+        // If we have a schema field, use it directly with Drizzle operators
+        if (schemaField) {
+            switch (operator) {
+                case '==':
+                    return (0, drizzle_orm_1.eq)(schemaField, value);
+                case '!=':
+                    return (0, drizzle_orm_1.ne)(schemaField, value);
+                case '>':
+                    return (0, drizzle_orm_1.gt)(schemaField, value);
+                case '>=':
+                    return (0, drizzle_orm_1.gte)(schemaField, value);
+                case '<':
+                    return (0, drizzle_orm_1.lt)(schemaField, value);
+                case '<=':
+                    return (0, drizzle_orm_1.lte)(schemaField, value);
+                case 'LIKE': {
+                    if (typeof value !== 'string') {
+                        throw new DrizzleTranslationError('LIKE operator requires a string value');
+                    }
+                    // Convert wildcard to SQL pattern and use the like function
+                    const sqlPattern = this.wildcardToSqlPattern(value);
+                    return (0, drizzle_orm_1.sql) `${schemaField} LIKE ${sqlPattern}`;
+                }
+                case 'IN':
+                    if (!Array.isArray(value)) {
+                        throw new DrizzleTranslationError('IN operator requires an array value');
+                    }
+                    return (0, drizzle_orm_1.inArray)(schemaField, value);
+                case 'NOT IN':
+                    if (!Array.isArray(value)) {
+                        throw new DrizzleTranslationError('NOT IN operator requires an array value');
+                    }
+                    return (0, drizzle_orm_1.notInArray)(schemaField, value);
+                default:
+                    throw new DrizzleTranslationError(`Unsupported operator: ${operator}`);
+            }
+        }
+        // If we don't have a schema field, we need to build the SQL manually
+        // Handle each operator type
+        return this.buildSqlForOperator(fieldName, operator, value);
+    }
+    /**
+     * Build SQL for a specific operator with raw field name
+     * Security: Validates field names to prevent SQL injection
+     */
+    buildSqlForOperator(fieldName, operator, value) {
+        // Security fix: Validate field name format before using it (prevents SQL injection)
+        if (!this.isValidFieldName(fieldName)) {
+            throw new DrizzleTranslationError(`Invalid field name: ${fieldName}`);
+        }
+        switch (operator) {
+            case '==':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} = ${value}`;
+            case '!=':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} != ${value}`;
+            case '>':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} > ${value}`;
+            case '>=':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} >= ${value}`;
+            case '<':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} < ${value}`;
+            case '<=':
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} <= ${value}`;
+            case 'LIKE': {
+                if (typeof value !== 'string') {
+                    throw new DrizzleTranslationError('LIKE operator requires a string value');
+                }
+                // Convert wildcard to SQL pattern
+                const sqlPattern = this.wildcardToSqlPattern(value);
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} LIKE ${sqlPattern}`;
+            }
+            case 'IN': {
+                if (!Array.isArray(value)) {
+                    throw new DrizzleTranslationError('IN operator requires an array value');
+                }
+                if (value.length === 0) {
+                    // Empty IN clause should always be false
+                    return (0, drizzle_orm_1.sql) `FALSE`;
+                }
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} IN (${value})`;
+            }
+            case 'NOT IN': {
+                if (!Array.isArray(value)) {
+                    throw new DrizzleTranslationError('NOT IN operator requires an array value');
+                }
+                if (value.length === 0) {
+                    // Empty NOT IN clause should always be true
+                    return (0, drizzle_orm_1.sql) `TRUE`;
+                }
+                return (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(fieldName)} NOT IN (${value})`;
+            }
+            default:
+                throw new DrizzleTranslationError(`Unsupported operator: ${operator}`);
+        }
+    }
+    /**
+     * Convert wildcard pattern to SQL LIKE pattern
+     */
+    wildcardToSqlPattern(pattern) {
+        // Replace * with % and ? with _ for SQL LIKE syntax
+        // Also escape any existing SQL LIKE special characters
+        return pattern
+            .replace(/%/g, '\\%') // Escape existing %
+            .replace(/_/g, '\\_') // Escape existing _
+            .replace(/\*/g, '%') // * → %
+            .replace(/\?/g, '_'); // ? → _
+    }
+    /**
+     * Translate a logical expression to a Drizzle ORM condition
+     */
+    translateLogicalExpression(expression) {
+        const { operator, left, right } = expression;
+        const leftSql = this.translateExpression(left);
+        if (operator === 'NOT') {
+            return (0, drizzle_orm_1.sql) `NOT (${leftSql})`;
+        }
+        if (!right) {
+            throw new DrizzleTranslationError(`${operator} operator requires two operands`);
+        }
+        const rightSql = this.translateExpression(right);
+        switch (operator) {
+            case 'AND':
+                return (0, drizzle_orm_1.sql) `(${leftSql}) AND (${rightSql})`;
+            case 'OR':
+                return (0, drizzle_orm_1.sql) `(${leftSql}) OR (${rightSql})`;
+            default:
+                throw new DrizzleTranslationError(`Unsupported logical operator: ${operator}`);
+        }
+    }
+    /**
+     * Normalize a field name based on translator options
+     */
+    normalizeField(field) {
+        const normalizedField = this.options.normalizeFieldNames
+            ? field.toLowerCase()
+            : field;
+        return this.options.fieldMappings[normalizedField] ?? normalizedField;
+    }
+    /**
+     * Get a field from the schema if it exists
+     */
+    getSchemaField(fieldName) {
+        // Extract table and column names from fieldName (e.g., 'users.id' -> { table: 'users', column: 'id' })
+        const parts = fieldName.split('.');
+        if (parts.length === 2) {
+            const [tableName, columnName] = parts;
+            const table = this.options.schema[tableName];
+            if (table && columnName in table) {
+                return table[columnName];
+            }
+        }
+        // Heuristic: if there's only one table in the schema, allow bare field lookup
+        if (parts.length === 1) {
+            const [onlyTableName] = Object.keys(this.options.schema);
+            if (onlyTableName) {
+                const table = this.options.schema[onlyTableName];
+                const columnName = parts[0];
+                if (table && columnName in table) {
+                    return table[columnName];
+                }
+            }
+        }
+        // If the field is not found in the schema
+        return null;
+    }
+    /**
+     * Security: Validates field names to prevent SQL injection
+     * Only allows alphanumeric chars, dots, underscores. Max 64 chars per part.
+     */
+    isValidFieldName(fieldName) {
+        const validFieldPattern = /^[a-zA-Z][a-zA-Z0-9._]*$/;
+        const parts = fieldName.split('.');
+        // Only allow table.column format (max 2 parts)
+        if (parts.length > 2)
+            return false;
+        return parts.every(part => validFieldPattern.test(part) &&
+            part.length <= 64 &&
+            !part.includes('__') // Prevent reserved patterns
+        );
+    }
+}
+exports.DrizzleTranslator = DrizzleTranslator;

package/dist/translators/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * QueryKit Translators
+ *
+ * Exports all translator implementations for different target platforms.
+ */
+export * from './types';
+export * from './drizzle';
+export * from './sql';

package/dist/translators/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * QueryKit Translators
+ *
+ * Exports all translator implementations for different target platforms.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Export base types
+__exportStar(require("./types"), exports);
+// Export Drizzle translator
+__exportStar(require("./drizzle"), exports);
+// Export SQL translator
+__exportStar(require("./sql"), exports);

package/dist/translators/sql/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SQL Translator for QueryKit
+ *
+ * This translator converts QueryKit AST expressions into generic SQL
+ * WHERE clause conditions that can be used in any SQL query.
+ */
+import { QueryExpression } from '../../parser/types';
+import { ITranslator, ITranslatorOptions } from '../types';
+/**
+ * Options specific to the SQL translator
+ */
+export interface ISqlTranslatorOptions extends ITranslatorOptions {
+    /**
+     * Quote character for identifiers (field names)
+     * Default is double quotes (ANSI SQL standard)
+     */
+    identifierQuote?: string;
+    /**
+     * Quote character for string literals
+     * Default is single quotes (ANSI SQL standard)
+     */
+    stringLiteralQuote?: string;
+    /**
+     * Whether to use parameters instead of inline values
+     * If true, translate() will return an object with sql and params
+     * Default is true for security reasons (protection against SQL injection)
+     *
+     * @warning Setting this to false may expose your application to SQL injection attacks.
+     * Only disable this if you have a very specific reason and you're handling the security
+     * implications yourself.
+     */
+    useParameters?: boolean;
+}
+/**
+ * The result of SQL translation
+ */
+export interface ISqlTranslationResult {
+    /**
+     * The SQL query string with placeholders for parameters
+     */
+    sql: string;
+    /**
+     * The parameters to be used with the query
+     */
+    params: unknown[];
+}
+/**
+ * Error thrown when translation fails
+ */
+export declare class SqlTranslationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Translates QueryKit AST expressions to SQL WHERE clauses
+ */
+export declare class SqlTranslator implements ITranslator<ISqlTranslationResult | string> {
+    private options;
+    private params;
+    constructor(options?: ISqlTranslatorOptions);
+    /**
+     * Translate a QueryKit expression to an SQL WHERE clause
+     */
+    translate(expression: QueryExpression): ISqlTranslationResult | string;
+    /**
+     * Check if an expression can be translated to SQL
+     */
+    canTranslate(expression: QueryExpression): boolean;
+    /**
+     * Translate any QueryKit expression to SQL
+     */
+    private translateExpression;
+    /**
+     * Translate a comparison expression to SQL
+     */
+    private translateComparisonExpression;
+    /**
+     * Convert wildcard pattern to SQL LIKE pattern
+     */
+    private wildcardToSqlPattern;
+    /**
+     * Translate a logical expression to SQL
+     */
+    private translateLogicalExpression;
+    /**
+     * Format a comparison expression
+     */
+    private formatComparison;
+    /**
+     * Format an IN clause
+     */
+    private formatInClause;
+    /**
+     * Format a value for SQL
+     */
+    private formatValue;
+    /**
+     * Escape a string literal for SQL
+     */
+    private escapeString;
+    /**
+     * Quote an identifier (field name) for SQL
+     */
+    private quoteIdentifier;
+    /**
+     * Normalize a field name based on translator options
+     */
+    private normalizeField;
+}

package/dist/translators/sql/index.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * SQL Translator for QueryKit
+ *
+ * This translator converts QueryKit AST expressions into generic SQL
+ * WHERE clause conditions that can be used in any SQL query.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlTranslator = exports.SqlTranslationError = void 0;
+/**
+ * Error thrown when translation fails
+ */
+class SqlTranslationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SqlTranslationError';
+    }
+}
+exports.SqlTranslationError = SqlTranslationError;
+/**
+ * Translates QueryKit AST expressions to SQL WHERE clauses
+ */
+class SqlTranslator {
+    constructor(options = {}) {
+        this.params = [];
+        this.options = {
+            normalizeFieldNames: options.normalizeFieldNames ?? false,
+            fieldMappings: options.fieldMappings ?? {},
+            identifierQuote: options.identifierQuote ?? '"',
+            stringLiteralQuote: options.stringLiteralQuote ?? "'",
+            useParameters: options.useParameters ?? true
+        };
+    }
+    /**
+     * Translate a QueryKit expression to an SQL WHERE clause
+     */
+    translate(expression) {
+        this.params = [];
+        try {
+            const sql = this.translateExpression(expression);
+            return this.options.useParameters
+                ? { sql, params: [...this.params] }
+                : sql;
+        }
+        catch (error) {
+            throw new SqlTranslationError(`Failed to translate expression: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if an expression can be translated to SQL
+     */
+    canTranslate(expression) {
+        try {
+            this.translateExpression(expression);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Translate any QueryKit expression to SQL
+     */
+    translateExpression(expression) {
+        if (!expression) {
+            throw new SqlTranslationError('Empty expression');
+        }
+        switch (expression.type) {
+            case 'comparison':
+                return this.translateComparisonExpression(expression);
+            case 'logical':
+                return this.translateLogicalExpression(expression);
+            default:
+                throw new SqlTranslationError(`Unsupported expression type: ${expression.type}`);
+        }
+    }
+    /**
+     * Translate a comparison expression to SQL
+     */
+    translateComparisonExpression(expression) {
+        const { field, operator, value } = expression;
+        const fieldName = this.normalizeField(field);
+        const quotedField = this.quoteIdentifier(fieldName);
+        // Handle each operator type
+        switch (operator) {
+            case '==':
+                return this.formatComparison(quotedField, '=', value);
+            case '!=':
+                return this.formatComparison(quotedField, '<>', value);
+            case '>':
+                return this.formatComparison(quotedField, '>', value);
+            case '>=':
+                return this.formatComparison(quotedField, '>=', value);
+            case '<':
+                return this.formatComparison(quotedField, '<', value);
+            case '<=':
+                return this.formatComparison(quotedField, '<=', value);
+            case 'LIKE': {
+                if (typeof value !== 'string') {
+                    throw new SqlTranslationError('LIKE operator requires a string value');
+                }
+                // Convert wildcard syntax to SQL LIKE pattern
+                const sqlPattern = this.wildcardToSqlPattern(value);
+                return this.formatComparison(quotedField, 'LIKE', sqlPattern);
+            }
+            case 'IN': {
+                if (!Array.isArray(value)) {
+                    throw new SqlTranslationError('IN operator requires an array value');
+                }
+                if (value.length === 0) {
+                    // Empty IN clause should always be false
+                    return 'FALSE';
+                }
+                return this.formatInClause(quotedField, value, false);
+            }
+            case 'NOT IN': {
+                if (!Array.isArray(value)) {
+                    throw new SqlTranslationError('NOT IN operator requires an array value');
+                }
+                if (value.length === 0) {
+                    // Empty NOT IN clause should always be true
+                    return 'TRUE';
+                }
+                return this.formatInClause(quotedField, value, true);
+            }
+            default:
+                throw new SqlTranslationError(`Unsupported operator: ${operator}`);
+        }
+    }
+    /**
+     * Convert wildcard pattern to SQL LIKE pattern
+     */
+    wildcardToSqlPattern(pattern) {
+        // Replace * with % and ? with _ for SQL LIKE syntax
+        // Also escape any existing SQL LIKE special characters
+        return pattern
+            .replace(/%/g, '\\%') // Escape existing %
+            .replace(/_/g, '\\_') // Escape existing _
+            .replace(/\*/g, '%') // * → %
+            .replace(/\?/g, '_'); // ? → _
+    }
+    /**
+     * Translate a logical expression to SQL
+     */
+    translateLogicalExpression(expression) {
+        const { operator, left, right } = expression;
+        const leftSql = this.translateExpression(left);
+        if (operator === 'NOT') {
+            return `NOT (${leftSql})`;
+        }
+        if (!right) {
+            throw new SqlTranslationError(`${operator} operator requires two operands`);
+        }
+        const rightSql = this.translateExpression(right);
+        switch (operator) {
+            case 'AND':
+                return `(${leftSql}) AND (${rightSql})`;
+            case 'OR':
+                return `(${leftSql}) OR (${rightSql})`;
+            default:
+                throw new SqlTranslationError(`Unsupported logical operator: ${operator}`);
+        }
+    }
+    /**
+     * Format a comparison expression
+     */
+    formatComparison(field, sqlOperator, value) {
+        if (value === null) {
+            // Handle NULL comparisons
+            return sqlOperator === '='
+                ? `${field} IS NULL`
+                : `${field} IS NOT NULL`;
+        }
+        const formattedValue = this.formatValue(value);
+        return `${field} ${sqlOperator} ${formattedValue}`;
+    }
+    /**
+     * Format an IN clause
+     */
+    formatInClause(field, values, isNot) {
+        const operator = isNot ? 'NOT IN' : 'IN';
+        if (this.options.useParameters) {
+            const placeholders = values.map(() => `?`);
+            this.params.push(...values);
+            return `${field} ${operator} (${placeholders.join(', ')})`;
+        }
+        else {
+            const formattedValues = values.map(v => this.formatValue(v, false));
+            return `${field} ${operator} (${formattedValues.join(', ')})`;
+        }
+    }
+    /**
+     * Format a value for SQL
+     */
+    formatValue(value, addToParams = true) {
+        if (this.options.useParameters && addToParams) {
+            this.params.push(value);
+            return '?';
+        }
+        if (value === null) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            return `${this.options.stringLiteralQuote}${this.escapeString(value)}${this.options.stringLiteralQuote}`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        if (value instanceof Date) {
+            return `${this.options.stringLiteralQuote}${value.toISOString()}${this.options.stringLiteralQuote}`;
+        }
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            throw new SqlTranslationError(`Complex objects are not supported as values. Got: ${Object.prototype.toString.call(value)}`);
+        }
+        if (Array.isArray(value)) {
+            const formattedValues = value.map(v => this.formatValue(v, false));
+            return formattedValues.join(', ');
+        }
+        throw new SqlTranslationError(`Unsupported value type: ${typeof value}`);
+    }
+    /**
+     * Escape a string literal for SQL
+     */
+    escapeString(str) {
+        // Escape any quotes in the string by doubling them
+        return str.replace(new RegExp(this.options.stringLiteralQuote, 'g'), `${this.options.stringLiteralQuote}${this.options.stringLiteralQuote}`);
+    }
+    /**
+     * Quote an identifier (field name) for SQL
+     */
+    quoteIdentifier(identifier) {
+        // Handle table.column format
+        if (identifier.includes('.')) {
+            const parts = identifier.split('.');
+            return parts.map(part => this.quoteIdentifier(part)).join('.');
+        }
+        const quote = this.options.identifierQuote;
+        // Escape any quotes in the identifier by doubling them
+        const escaped = identifier.replace(new RegExp(quote, 'g'), `${quote}${quote}`);
+        return `${quote}${escaped}${quote}`;
+    }
+    /**
+     * Normalize a field name based on translator options
+     */
+    normalizeField(field) {
+        const normalizedField = this.options.normalizeFieldNames
+            ? field.toLowerCase()
+            : field;
+        return this.options.fieldMappings[normalizedField] ?? normalizedField;
+    }
+}
+exports.SqlTranslator = SqlTranslator;

package/dist/translators/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * QueryKit Translator Types
+ *
+ * These are the core interfaces for translators, which convert QueryKit's
+ * internal AST representation into formats that specific data sources can understand.
+ */
+import { QueryExpression } from '../parser/types';
+/**
+ * Options for configuring a translator
+ */
+export interface ITranslatorOptions {
+    /**
+     * Whether to normalize field names (e.g., lowercase them)
+     */
+    normalizeFieldNames?: boolean;
+    /**
+     * Custom field mappings from QueryKit fields to target fields
+     */
+    fieldMappings?: Record<string, string>;
+}
+/**
+ * Interface for a query translator
+ */
+export interface ITranslator<T = unknown> {
+    /**
+     * Translate a QueryKit expression into the target format
+     *
+     * @param expression The QueryKit expression to translate
+     * @returns The translated query in the target format
+     */
+    translate(expression: QueryExpression): T;
+    /**
+     * Check if an expression can be translated
+     *
+     * @param expression The expression to check
+     * @returns true if the expression can be translated, false otherwise
+     */
+    canTranslate(expression: QueryExpression): boolean;
+}