@gblikas/querykit 0.0.0

package/src/translators/drizzle/index.ts

@@ -0,0 +1,346 @@
+/**
+ * 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.
+ */
+
+import {
+  SQL,
+  SQLWrapper,
+  eq,
+  gt,
+  gte,
+  inArray,
+  lt,
+  lte,
+  ne,
+  notInArray,
+  sql
+} from 'drizzle-orm';
+import {
+  IComparisonExpression,
+  ILogicalExpression,
+  QueryExpression
+} from '../../parser/types';
+import { ITranslator, ITranslatorOptions } from '../types';
+
+/**
+ * Options specific to the Drizzle translator
+ */
+export interface IDrizzleTranslatorOptions extends ITranslatorOptions {
+  /**
+   * Schema information for type safety
+   */
+  schema?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Error thrown when translation fails
+ */
+export class DrizzleTranslationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DrizzleTranslationError';
+  }
+}
+
+/**
+ * Translates QueryKit AST expressions to Drizzle ORM conditions
+ */
+export class DrizzleTranslator implements ITranslator<SQL> {
+  private options: Required<IDrizzleTranslatorOptions>;
+
+  constructor(options: IDrizzleTranslatorOptions = {}) {
+    this.options = {
+      normalizeFieldNames: options.normalizeFieldNames ?? false,
+      fieldMappings: options.fieldMappings ?? {},
+      schema: options.schema ?? {}
+    };
+  }
+
+  /**
+   * Translate a QueryKit expression to a Drizzle ORM condition
+   */
+  public translate(expression: QueryExpression): SQL {
+    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
+   */
+  public canTranslate(expression: QueryExpression): boolean {
+    try {
+      this.translateExpression(expression);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Translate any QueryKit expression to a Drizzle ORM condition
+   */
+  private translateExpression(expression: QueryExpression): SQL {
+    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 as { type: string }).type}`
+        );
+    }
+  }
+
+  /**
+   * Translate a comparison expression to a Drizzle ORM condition
+   */
+  private translateComparisonExpression(
+    expression: IComparisonExpression
+  ): SQL {
+    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 eq(schemaField, value);
+        case '!=':
+          return ne(schemaField, value);
+        case '>':
+          return gt(schemaField, value);
+        case '>=':
+          return gte(schemaField, value);
+        case '<':
+          return lt(schemaField, value);
+        case '<=':
+          return 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 sql`${schemaField} LIKE ${sqlPattern}`;
+        }
+        case 'IN':
+          if (!Array.isArray(value)) {
+            throw new DrizzleTranslationError(
+              'IN operator requires an array value'
+            );
+          }
+          return inArray(schemaField, value);
+        case 'NOT IN':
+          if (!Array.isArray(value)) {
+            throw new DrizzleTranslationError(
+              'NOT IN operator requires an array value'
+            );
+          }
+          return 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
+   */
+  private buildSqlForOperator(
+    fieldName: string,
+    operator: string,
+    value: unknown
+  ): SQL {
+    // 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 sql`${sql.identifier(fieldName)} = ${value}`;
+      case '!=':
+        return sql`${sql.identifier(fieldName)} != ${value}`;
+      case '>':
+        return sql`${sql.identifier(fieldName)} > ${value}`;
+      case '>=':
+        return sql`${sql.identifier(fieldName)} >= ${value}`;
+      case '<':
+        return sql`${sql.identifier(fieldName)} < ${value}`;
+      case '<=':
+        return sql`${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 sql`${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 sql`FALSE`;
+        }
+        return sql`${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 sql`TRUE`;
+        }
+        return sql`${sql.identifier(fieldName)} NOT IN (${value})`;
+      }
+      default:
+        throw new DrizzleTranslationError(`Unsupported operator: ${operator}`);
+    }
+  }
+
+  /**
+   * Convert wildcard pattern to SQL LIKE pattern
+   */
+  private wildcardToSqlPattern(pattern: string): string {
+    // 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
+   */
+  private translateLogicalExpression(expression: ILogicalExpression): SQL {
+    const { operator, left, right } = expression;
+
+    const leftSql = this.translateExpression(left);
+
+    if (operator === 'NOT') {
+      return sql`NOT (${leftSql})`;
+    }
+
+    if (!right) {
+      throw new DrizzleTranslationError(
+        `${operator} operator requires two operands`
+      );
+    }
+
+    const rightSql = this.translateExpression(right);
+
+    switch (operator) {
+      case 'AND':
+        return sql`(${leftSql}) AND (${rightSql})`;
+      case 'OR':
+        return sql`(${leftSql}) OR (${rightSql})`;
+      default:
+        throw new DrizzleTranslationError(
+          `Unsupported logical operator: ${operator}`
+        );
+    }
+  }
+
+  /**
+   * Normalize a field name based on translator options
+   */
+  private normalizeField(field: string): string {
+    const normalizedField = this.options.normalizeFieldNames
+      ? field.toLowerCase()
+      : field;
+
+    return this.options.fieldMappings[normalizedField] ?? normalizedField;
+  }
+
+  /**
+   * Get a field from the schema if it exists
+   */
+  private getSchemaField(fieldName: string): SQLWrapper | null {
+    // 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] as
+        | Record<string, unknown>
+        | undefined;
+
+      if (table && columnName in table) {
+        return table[columnName] as SQLWrapper;
+      }
+    }
+
+    // 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] as
+          | Record<string, unknown>
+          | undefined;
+        const columnName = parts[0];
+        if (table && columnName in table) {
+          return table[columnName] as SQLWrapper;
+        }
+      }
+    }
+
+    // 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.
+   */
+  private isValidFieldName(fieldName: string): boolean {
+    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
+    );
+  }
+}

package/src/translators/index.ts

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

package/src/translators/sql/index.test.ts

@@ -0,0 +1,45 @@
+import { SqlTranslator } from './index';
+
+describe('SqlTranslator', () => {
+  let translator: SqlTranslator;
+
+  beforeEach(() => {
+    translator = new SqlTranslator();
+  });
+
+  // Helper function to access private wildcardToSqlPattern method
+  function testWildcardPattern(pattern: string): string {
+    // We need to access a private method for testing - using type assertion
+    return (translator as unknown as { 
+      wildcardToSqlPattern: (p: string) => string 
+    }).wildcardToSqlPattern(pattern);
+  }
+
+  // Other tests...
+
+  describe('wildcardToSqlPattern', () => {
+    it('should convert * wildcard to % SQL pattern', () => {
+      expect(testWildcardPattern('foo*')).toBe('foo%');
+      expect(testWildcardPattern('*bar')).toBe('%bar');
+      expect(testWildcardPattern('foo*bar')).toBe('foo%bar');
+      expect(testWildcardPattern('*foo*')).toBe('%foo%');
+    });
+
+    it('should convert ? wildcard to _ SQL pattern', () => {
+      expect(testWildcardPattern('foo?')).toBe('foo_');
+      expect(testWildcardPattern('?bar')).toBe('_bar');
+      expect(testWildcardPattern('foo?bar')).toBe('foo_bar');
+    });
+
+    it('should handle mixed wildcards', () => {
+      expect(testWildcardPattern('f*o?bar*')).toBe('f%o_bar%');
+      expect(testWildcardPattern('*test?')).toBe('%test_');
+    });
+
+    it('should escape existing SQL special characters', () => {
+      expect(testWildcardPattern('foo%bar')).toBe('foo\\%bar');
+      expect(testWildcardPattern('foo_bar')).toBe('foo\\_bar');
+      expect(testWildcardPattern('foo_%bar*')).toBe('foo\\_\\%bar%');
+    });
+  });
+});