@gblikas/querykit 0.0.0

package/src/parser/parser.ts

@@ -0,0 +1,268 @@
+import { parse as liqeParse } from 'liqe';
+import type {
+  BooleanOperatorToken,
+  ExpressionToken,
+  FieldToken,
+  ImplicitBooleanOperatorToken,
+  LiqeQuery,
+  LogicalExpressionToken,
+  ParenthesizedExpressionToken,
+  TagToken,
+  UnaryOperatorToken
+} from 'liqe';
+import {
+  ComparisonOperator,
+  IComparisonExpression,
+  ILogicalExpression,
+  IParserOptions,
+  IQueryParser,
+  QueryExpression,
+  QueryValue
+} from './types';
+
+/**
+ * Error thrown when query parsing fails
+ */
+export class QueryParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QueryParseError';
+  }
+}
+
+/**
+ * Implementation of the QueryKit parser using Liqe
+ */
+export class QueryParser implements IQueryParser {
+  private options: Required<IParserOptions>;
+
+  constructor(options: IParserOptions = {}) {
+    this.options = {
+      caseInsensitiveFields: options.caseInsensitiveFields ?? false,
+      fieldMappings: options.fieldMappings ?? {}
+    };
+  }
+
+  /**
+   * Parse a query string into a QueryKit AST
+   */
+  public parse(query: string): QueryExpression {
+    try {
+      const liqeAst = liqeParse(query);
+      return this.convertLiqeAst(liqeAst);
+    } catch (error) {
+      throw new QueryParseError(
+        `Failed to parse query: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Validate a query string
+   */
+  public validate(query: string): boolean {
+    try {
+      const ast = liqeParse(query);
+      this.convertLiqeAst(ast);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Convert a Liqe AST node to a QueryKit expression
+   */
+  private convertLiqeAst(node: LiqeQuery): QueryExpression {
+    if (!node || typeof node !== 'object') {
+      throw new QueryParseError('Invalid AST node');
+    }
+
+    switch (node.type) {
+      case 'LogicalExpression': {
+        const logicalNode = node as LogicalExpressionToken;
+        const operator = (logicalNode.operator as BooleanOperatorToken | ImplicitBooleanOperatorToken).operator;
+        return this.createLogicalExpression(
+          this.convertLogicalOperator(operator),
+          logicalNode.left,
+          logicalNode.right
+        );
+      }
+
+      case 'UnaryOperator': {
+        const unaryNode = node as UnaryOperatorToken;
+        return this.createLogicalExpression('NOT', unaryNode.operand);
+      }
+
+      case 'Tag': {
+        const tagNode = node as TagToken;
+        const field = tagNode.field as FieldToken;
+        const expression = tagNode.expression as ExpressionToken & { value: QueryValue };
+        
+        if (!field || !expression) {
+          throw new QueryParseError('Invalid field or expression in Tag node');
+        }
+
+        const fieldName = this.normalizeFieldName(field.name);
+        const operator = this.convertLiqeOperator(tagNode.operator.operator);
+        const value = this.convertLiqeValue(expression.value);
+
+        // Check for wildcard patterns in string values
+        if (operator === '==' && typeof value === 'string' && (value.includes('*') || value.includes('?'))) {
+          return this.createComparisonExpression(
+            fieldName,
+            'LIKE',
+            value
+          );
+        }
+
+        return this.createComparisonExpression(
+          fieldName,
+          operator,
+          value
+        );
+      }
+
+      case 'EmptyExpression':
+        if ('left' in node && node.left) {
+          return this.convertLiqeAst(node.left);
+        }
+        throw new QueryParseError('Invalid empty expression');
+
+      case 'ParenthesizedExpression': {
+        const parenNode = node as ParenthesizedExpressionToken;
+        if (parenNode.expression) {
+          return this.convertLiqeAst(parenNode.expression);
+        }
+        throw new QueryParseError('Invalid parenthesized expression');
+      }
+
+      default:
+        throw new QueryParseError(`Unsupported node type: ${(node as { type: string }).type}`);
+    }
+  }
+
+  /**
+   * Convert a Liqe logical operator to a QueryKit operator
+   */
+  private convertLogicalOperator(operator: string): 'AND' | 'OR' | 'NOT' {
+    switch (operator.toLowerCase()) {
+      case 'and':
+        return 'AND';
+      case 'or':
+        return 'OR';
+      case 'not':
+        return 'NOT';
+      default:
+        throw new QueryParseError(`Unsupported logical operator: ${operator}`);
+    }
+  }
+
+  /**
+   * Create a logical expression from Liqe nodes
+   */
+  private createLogicalExpression(
+    operator: 'AND' | 'OR' | 'NOT',
+    left: LiqeQuery,
+    right?: LiqeQuery
+  ): ILogicalExpression {
+    return {
+      type: 'logical',
+      operator,
+      left: this.convertLiqeAst(left),
+      ...(right && { right: this.convertLiqeAst(right) })
+    };
+  }
+
+  /**
+   * Create a comparison expression
+   */
+  private createComparisonExpression(
+    field: string,
+    operator: ComparisonOperator,
+    value: QueryValue
+  ): IComparisonExpression {
+    return {
+      type: 'comparison',
+      field,
+      operator,
+      value
+    };
+  }
+
+  /**
+   * Convert a Liqe operator to a QueryKit operator
+   */
+  private convertLiqeOperator(operator: string): ComparisonOperator {
+    // Handle the case where operator is part of the value for comparison operators
+    if (operator === ':') {
+      return '==';
+    }
+
+    // Check if the operator is prefixed with a colon
+    const actualOperator = operator.startsWith(':') ? operator.substring(1) : operator;
+
+    // Map Liqe operators to QueryKit operators
+    const operatorMap: Record<string, ComparisonOperator> = {
+      '=': '==',
+      '!=': '!=',
+      '>': '>',
+      '>=': '>=',
+      '<': '<',
+      '<=': '<=',
+      'in': 'IN',
+      'not in': 'NOT IN'
+    };
+
+    const queryKitOperator = operatorMap[actualOperator.toLowerCase()];
+    if (!queryKitOperator) {
+      throw new QueryParseError(`Unsupported operator: ${operator}`);
+    }
+
+    return queryKitOperator;
+  }
+
+  /**
+   * Convert a Liqe value to a QueryKit value
+   * Security: Strict type checking to prevent NoSQL injection via objects
+   */
+  private convertLiqeValue(value: unknown): QueryValue {
+    // Security fix: Strict type checking to prevent object injection
+    if (value === null) {
+      return null;
+    }
+    
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      return value as QueryValue;
+    }
+    
+    if (Array.isArray(value)) {
+      // Security fix: Recursively validate array elements
+      const validatedArray = value.map(item => {
+        if (typeof item === 'object' && item !== null) {
+          throw new QueryParseError('Object values are not allowed in arrays');
+        }
+        return this.convertLiqeValue(item);
+      });
+      return validatedArray as QueryValue;
+    }
+    
+    // Security fix: Reject all object types to prevent NoSQL injection
+    if (typeof value === 'object') {
+      throw new QueryParseError('Object values are not supported for security reasons');
+    }
+
+    throw new QueryParseError(`Unsupported value type: ${typeof value}`);
+  }
+
+  /**
+   * Normalize a field name based on parser options
+   */
+  private normalizeFieldName(field: string): string {
+    const normalizedField = this.options.caseInsensitiveFields
+      ? field.toLowerCase()
+      : field;
+
+    return this.options.fieldMappings[normalizedField] ?? normalizedField;
+  }
+} 

package/src/parser/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Core AST types for QueryKit's parser
+ */
+
+/**
+ * Represents a comparison operator in a query expression
+ */
+export type ComparisonOperator = 
+  | '==' 
+  | '!=' 
+  | '>' 
+  | '>=' 
+  | '<' 
+  | '<=' 
+  | 'IN' 
+  | 'NOT IN'
+  | 'LIKE';
+
+/**
+ * Represents a logical operator in a query expression
+ */
+export type LogicalOperator = 
+  | 'AND' 
+  | 'OR' 
+  | 'NOT';
+
+/**
+ * Represents a value that can be used in a query expression
+ */
+export type QueryValue = 
+  | string 
+  | number 
+  | boolean 
+  | null 
+  | Array<string | number | boolean | null>;
+
+/**
+ * Represents a comparison expression node in the AST
+ */
+export interface IComparisonExpression {
+  type: 'comparison';
+  field: string;
+  operator: ComparisonOperator;
+  value: QueryValue;
+}
+
+/**
+ * Represents a logical expression node in the AST
+ */
+export interface ILogicalExpression {
+  type: 'logical';
+  operator: LogicalOperator;
+  left: QueryExpression;
+  right?: QueryExpression;
+}
+
+/**
+ * Represents any valid query expression node
+ */
+export type QueryExpression = 
+  | IComparisonExpression 
+  | ILogicalExpression;
+
+/**
+ * Configuration options for the parser
+ */
+export interface IParserOptions {
+  /**
+   * Whether to allow case-insensitive field names
+   */
+  caseInsensitiveFields?: boolean;
+  
+  /**
+   * Custom field name mappings
+   */
+  fieldMappings?: Record<string, string>;
+}
+
+/**
+ * Interface for the query parser
+ */
+export interface IQueryParser {
+  /**
+   * Parse a query string into an AST
+   * @param query The query string to parse
+   * @returns The parsed AST
+   * @throws {QueryParseError} If the query is invalid
+   */
+  parse(query: string): QueryExpression;
+  
+  /**
+   * Validate a query string without fully parsing it
+   * @param query The query string to validate
+   * @returns true if the query is valid, false otherwise
+   */
+  validate(query: string): boolean;
+} 

package/src/query/builder.test.ts

@@ -0,0 +1,272 @@
+import { QueryBuilder } from './builder';
+import { ComparisonOperator } from './types';
+
+interface ITodo {
+  id: number;
+  title: string;
+  priority: number;
+  status: string;
+  dueDate: string;
+}
+
+describe('QueryBuilder', () => {
+  let builder: QueryBuilder<ITodo>;
+
+  beforeEach(() => {
+    builder = new QueryBuilder<ITodo>();
+  });
+
+  describe('where', () => {
+    it('should create a simple comparison query', () => {
+      const query = builder.where('priority', '>', 2).toString();
+
+      expect(query).toBe('priority:>2');
+    });
+
+    it('should handle string values', () => {
+      const query = builder.where('status', '==', 'active').toString();
+
+      expect(query).toBe('status:"active"');
+    });
+
+    it('should handle null values', () => {
+      const query = builder.where('dueDate', '==', null).toString();
+
+      expect(query).toBe('dueDate:null');
+    });
+
+    it('should handle array values', () => {
+      const query = builder
+        .where('status', 'IN', ['active', 'pending'])
+        .toString();
+
+      expect(query).toBe('status:in["active","pending"]');
+    });
+
+    it('should accept direct query string syntax', () => {
+      const query = builder.where('priority:>2').toString();
+
+      expect(query).toBe('priority:>2');
+    });
+
+    it('should combine direct query strings with AND', () => {
+      const query = builder
+        .where('priority:>2')
+        .andWhere('status:"active"')
+        .toString();
+
+      expect(query).toBe('(priority:>2) AND status:"active"');
+    });
+  });
+
+  describe('andWhere', () => {
+    it('should combine conditions with AND', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .andWhere('status', '==', 'active')
+        .toString();
+
+      expect(query).toBe('(priority:>2) AND status:"active"');
+    });
+
+    it('should handle multiple AND conditions', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .andWhere('status', '==', 'active')
+        .andWhere('dueDate', '!=', null)
+        .toString();
+
+      expect(query).toBe(
+        '((priority:>2) AND status:"active") AND dueDate:!=null'
+      );
+    });
+
+    it('should handle andWhere as first condition with field-operator-value', () => {
+      const query = builder.andWhere('priority', '>', 2).toString();
+
+      expect(query).toBe('priority:>2');
+    });
+
+    it('should handle andWhere as first condition with query string', () => {
+      const query = builder.andWhere('priority:>2').toString();
+
+      expect(query).toBe('priority:>2');
+    });
+  });
+
+  describe('orWhere', () => {
+    it('should combine conditions with OR', () => {
+      const query = builder
+        .where('status', '==', 'active')
+        .orWhere('status', '==', 'pending')
+        .toString();
+
+      expect(query).toBe('(status:"active") OR status:"pending"');
+    });
+
+    it('should handle multiple OR conditions', () => {
+      const query = builder
+        .where('status', '==', 'active')
+        .orWhere('status', '==', 'pending')
+        .orWhere('status', '==', 'inactive')
+        .toString();
+
+      expect(query).toBe(
+        '((status:"active") OR status:"pending") OR status:"inactive"'
+      );
+    });
+
+    it('should handle orWhere as first condition with field-operator-value', () => {
+      const query = builder.orWhere('priority', '>', 2).toString();
+
+      expect(query).toBe('priority:>2');
+    });
+
+    it('should handle orWhere as first condition with query string', () => {
+      const query = builder.orWhere('priority:>2').toString();
+
+      expect(query).toBe('priority:>2');
+    });
+  });
+
+  describe('notWhere', () => {
+    it('should create a NOT condition', () => {
+      const query = builder.notWhere('status', '==', 'inactive').toString();
+
+      expect(query).toBe('NOT status:"inactive"');
+    });
+
+    it('should combine NOT with other conditions', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .notWhere('status', '==', 'inactive')
+        .toString();
+
+      expect(query).toBe('(priority:>2) AND NOT status:"inactive"');
+    });
+
+    it('should handle notWhere as first condition with query string', () => {
+      const query = builder.notWhere('status:"inactive"').toString();
+
+      expect(query).toBe('NOT status:"inactive"');
+    });
+
+    it('should handle notWhere with query string and existing expression', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .notWhere('status:"inactive"')
+        .toString();
+
+      expect(query).toBe('(priority:>2) AND NOT status:"inactive"');
+    });
+  });
+
+  describe('orderBy', () => {
+    it('should add an ORDER BY clause', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .orderBy('title', 'asc')
+        .toString();
+
+      expect(query).toBe('priority:>2 ORDER BY title ASC');
+    });
+
+    it('should use ASC as default direction', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .orderBy('title')
+        .toString();
+
+      expect(query).toBe('priority:>2 ORDER BY title ASC');
+    });
+  });
+
+  describe('limit and offset', () => {
+    it('should add LIMIT and OFFSET clauses', () => {
+      const query = builder
+        .where('priority', '>', 2)
+        .limit(10)
+        .offset(20)
+        .toString();
+
+      expect(query).toBe('priority:>2 LIMIT 10 OFFSET 20');
+    });
+  });
+
+  describe('getExpression', () => {
+    it('should return a valid expression', () => {
+      const expression = builder
+        .where('priority', '>', 2)
+        .andWhere('status', '==', 'active')
+        .getExpression();
+
+      expect(expression).toEqual({
+        type: 'logical',
+        operator: 'AND',
+        left: {
+          type: 'comparison',
+          field: 'priority',
+          operator: '>',
+          value: 2
+        },
+        right: {
+          type: 'comparison',
+          field: 'status',
+          operator: '==',
+          value: 'active'
+        }
+      });
+    });
+  });
+
+  describe('wildcard support', () => {
+    it('should support wildcard syntax in direct query strings', () => {
+      const query = builder.where('title:Task*').toString();
+      expect(query).toBe('title:Task*'); // Preserves the wildcard in the query
+    });
+
+    it('should support wildcard syntax in field-operator-value API', () => {
+      const query = builder
+        .where('title', 'LIKE' as ComparisonOperator, 'Task*')
+        .toString();
+      expect(query).toBe('title:Task*'); // Should use the colon format for LIKE
+    });
+
+    it('should support combined wildcards', () => {
+      const query = builder.where('title:*Important*').toString();
+      expect(query).toBe('title:*Important*');
+    });
+
+    it('should support ? wildcards', () => {
+      const query = builder.where('code:ABC?').toString();
+      expect(query).toBe('code:ABC?');
+    });
+  });
+
+  describe('custom operator handling', () => {
+    it('should handle NOT IN operator properly', () => {
+      const query = builder
+        .where('status', 'NOT IN' as ComparisonOperator, [
+          'inactive',
+          'deleted'
+        ])
+        .toString();
+
+      expect(query).toBe('status:not in["inactive","deleted"]');
+    });
+  });
+
+  describe('constructor options', () => {
+    it('should initialize with custom options', () => {
+      const options = {
+        caseInsensitiveFields: true,
+        fieldMappings: { title: 'task_title' }
+      };
+
+      const customBuilder = new QueryBuilder<ITodo>(options);
+      const query = customBuilder.where('title', '==', 'Bug fix').toString();
+
+      expect(query).toBe('title:"Bug fix"');
+    });
+  });
+});