@gblikas/querykit 0.0.0

package/src/query/builder.ts

@@ -0,0 +1,274 @@
+import { QueryParser } from '../parser';
+import { QueryExpression } from '../parser/types';
+import {
+  ComparisonOperator,
+  IQueryBuilder,
+  IQueryBuilderOptions,
+  QueryField,
+  QueryValue,
+  SortDirection
+} from './types';
+
+/**
+ * Implementation of the type-safe query builder
+ */
+export class QueryBuilder<T> implements IQueryBuilder<T> {
+  private parser: QueryParser;
+  private expression: string = '';
+  private orderByClause: string = '';
+  private limitClause: string = '';
+  private offsetClause: string = '';
+
+  constructor(options: IQueryBuilderOptions<T> = {}) {
+    this.parser = new QueryParser({
+      caseInsensitiveFields: options.caseInsensitiveFields,
+      fieldMappings: options.fieldMappings as Record<string, string>
+    });
+  }
+
+  /**
+   * Add a where clause to the query
+   */
+  public where(queryString: string): IQueryBuilder<T>;
+  public where(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  public where(
+    fieldOrQueryString: QueryField<T> | string,
+    operator?: ComparisonOperator,
+    value?: QueryValue
+  ): IQueryBuilder<T> {
+    if (operator === undefined || value === undefined) {
+      // Handle direct query string format
+      this.expression = fieldOrQueryString as string;
+    } else {
+      // Handle field, operator, value format
+      this.expression = this.buildComparison(
+        fieldOrQueryString as QueryField<T>,
+        operator,
+        value
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Add an AND where clause to the query
+   */
+  public andWhere(queryString: string): IQueryBuilder<T>;
+  public andWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  public andWhere(
+    fieldOrQueryString: QueryField<T> | string,
+    operator?: ComparisonOperator,
+    value?: QueryValue
+  ): IQueryBuilder<T> {
+    if (!this.expression) {
+      if (typeof fieldOrQueryString === 'string' && (operator === undefined || value === undefined)) {
+        // Handle direct query string
+        return this.where(fieldOrQueryString);
+      } else {
+        // Handle field, operator, value format
+        return this.where(
+          fieldOrQueryString as QueryField<T>,
+          operator as ComparisonOperator,
+          value as QueryValue
+        );
+      }
+    }
+
+    if (operator === undefined || value === undefined) {
+      // Handle direct query string format
+      this.expression = `(${this.expression}) AND ${fieldOrQueryString}`;
+    } else {
+      // Handle field, operator, value format
+      this.expression = `(${this.expression}) AND ${this.buildComparison(
+        fieldOrQueryString as QueryField<T>,
+        operator,
+        value
+      )}`;
+    }
+    return this;
+  }
+
+  /**
+   * Add an OR where clause to the query
+   */
+  public orWhere(queryString: string): IQueryBuilder<T>;
+  public orWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  public orWhere(
+    fieldOrQueryString: QueryField<T> | string,
+    operator?: ComparisonOperator,
+    value?: QueryValue
+  ): IQueryBuilder<T> {
+    if (!this.expression) {
+      if (typeof fieldOrQueryString === 'string' && (operator === undefined || value === undefined)) {
+        // Handle direct query string
+        return this.where(fieldOrQueryString);
+      } else {
+        // Handle field, operator, value format
+        return this.where(
+          fieldOrQueryString as QueryField<T>,
+          operator as ComparisonOperator,
+          value as QueryValue
+        );
+      }
+    }
+
+    if (operator === undefined || value === undefined) {
+      // Handle direct query string format
+      this.expression = `(${this.expression}) OR ${fieldOrQueryString}`;
+    } else {
+      // Handle field, operator, value format
+      this.expression = `(${this.expression}) OR ${this.buildComparison(
+        fieldOrQueryString as QueryField<T>,
+        operator,
+        value
+      )}`;
+    }
+    return this;
+  }
+
+  /**
+   * Add a NOT where clause to the query
+   */
+  public notWhere(queryString: string): IQueryBuilder<T>;
+  public notWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  public notWhere(
+    fieldOrQueryString: QueryField<T> | string,
+    operator?: ComparisonOperator,
+    value?: QueryValue
+  ): IQueryBuilder<T> {
+    if (!this.expression) {
+      if (operator === undefined || value === undefined) {
+        // Handle direct query string format
+        this.expression = `NOT ${fieldOrQueryString}`;
+      } else {
+        // Handle field, operator, value format
+        this.expression = `NOT ${this.buildComparison(
+          fieldOrQueryString as QueryField<T>,
+          operator,
+          value
+        )}`;
+      }
+    } else {
+      if (operator === undefined || value === undefined) {
+        // Handle direct query string format
+        this.expression = `(${this.expression}) AND NOT ${fieldOrQueryString}`;
+      } else {
+        // Handle field, operator, value format
+        this.expression = `(${this.expression}) AND NOT ${this.buildComparison(
+          fieldOrQueryString as QueryField<T>,
+          operator,
+          value
+        )}`;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Add an order by clause to the query
+   */
+  public orderBy(field: QueryField<T>, direction: SortDirection = 'asc'): IQueryBuilder<T> {
+    this.orderByClause = `ORDER BY ${field} ${direction.toUpperCase()}`;
+    return this;
+  }
+
+  /**
+   * Add a limit to the query
+   */
+  public limit(count: number): IQueryBuilder<T> {
+    this.limitClause = `LIMIT ${count}`;
+    return this;
+  }
+
+  /**
+   * Add an offset to the query
+   */
+  public offset(count: number): IQueryBuilder<T> {
+    this.offsetClause = `OFFSET ${count}`;
+    return this;
+  }
+
+  /**
+   * Get the current query expression
+   */
+  public getExpression(): QueryExpression {
+    return this.parser.parse(this.expression);
+  }
+
+  /**
+   * Get the current query as a string
+   */
+  public toString(): string {
+    const clauses = [
+      this.expression,
+      this.orderByClause,
+      this.limitClause,
+      this.offsetClause
+    ].filter(Boolean);
+
+    return clauses.join(' ');
+  }
+
+  /**
+   * Build a comparison expression
+   */
+  private buildComparison(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): string {
+    // Map QueryKit operators to Liqe operators
+    const operatorMap: Record<ComparisonOperator, string> = {
+      '==': ':',
+      '!=': '!=',
+      '>': '>',
+      '>=': '>=',
+      '<': '<',
+      '<=': '<=',
+      'IN': 'in',
+      'NOT IN': 'not in',
+      'LIKE': ':'
+    };
+
+    const liqeOperator = operatorMap[operator];
+    const formattedValue = this.formatValue(value, operator);
+
+    // For equality and LIKE operators, use field:value format (simple colon)
+    if (operator === '==' || operator === 'LIKE') {
+      return `${field}${liqeOperator}${formattedValue}`;
+    }
+
+    // Based on Liqe docs, comparison operators are prefixed with colon
+    // e.g., 'height:>100', 'height:<100'
+    if (operator === '>' || operator === '>=' || operator === '<' || operator === '<=' || operator === '!=') {
+      return `${field}:${liqeOperator}${formattedValue}`;
+    }
+
+    // For array operators (IN, NOT IN), use the format field:operator[values]
+    if (operator === 'IN' || operator === 'NOT IN') {
+      return `${field}:${liqeOperator}${formattedValue}`;
+    }
+
+    // For other operators, use field:operator value format
+    return `${field}:${liqeOperator} ${formattedValue}`;
+  }
+
+  /**
+   * Format a value for use in a query
+   */
+  private formatValue(value: QueryValue, operator?: ComparisonOperator): string {
+    if (value === null) {
+      return 'null';
+    }
+
+    if (Array.isArray(value)) {
+      return `[${value.map(v => this.formatValue(v)).join(',')}]`;
+    }
+
+    if (typeof value === 'string') {
+      // For LIKE operator with wildcard patterns, don't add quotes to allow pattern matching
+      if (operator === 'LIKE' && (value.includes('*') || value.includes('?'))) {
+        return value;
+      }
+      return `"${value}"`;
+    }
+
+    return String(value);
+  }
+} 

package/src/query/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './builder'; 

package/src/query/types.ts

@@ -0,0 +1,107 @@
+import { QueryExpression } from '../parser/types';
+
+/**
+ * Represents a field in a query
+ */
+export type QueryField<T> = keyof T & string;
+
+/**
+ * Represents a value that can be used in a query
+ */
+export type QueryValue = string | number | boolean | null | Array<string | number | boolean | null>;
+
+/**
+ * Represents a comparison operator in a query
+ */
+export type ComparisonOperator = 
+  | '==' 
+  | '!=' 
+  | '>' 
+  | '>=' 
+  | '<' 
+  | '<=' 
+  | 'IN' 
+  | 'NOT IN'
+  | 'LIKE';
+
+/**
+ * Represents a logical operator in a query
+ */
+export type LogicalOperator = 
+  | 'AND' 
+  | 'OR' 
+  | 'NOT';
+
+/**
+ * Represents a sort direction
+ */
+export type SortDirection = 'asc' | 'desc';
+
+/**
+ * Configuration options for the query builder
+ */
+export interface IQueryBuilderOptions<T> {
+  /**
+   * Whether to allow case-insensitive field names
+   */
+  caseInsensitiveFields?: boolean;
+  
+  /**
+   * Custom field name mappings
+   */
+  fieldMappings?: Partial<Record<QueryField<T>, string>>;
+}
+
+/**
+ * Interface for a query builder
+ */
+export interface IQueryBuilder<T> {
+  /**
+   * Add a where clause to the query
+   */
+  where(queryString: string): IQueryBuilder<T>;
+  where(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  
+  /**
+   * Add an AND where clause to the query
+   */
+  andWhere(queryString: string): IQueryBuilder<T>;
+  andWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  
+  /**
+   * Add an OR where clause to the query
+   */
+  orWhere(queryString: string): IQueryBuilder<T>;
+  orWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  
+  /**
+   * Add a NOT where clause to the query
+   */
+  notWhere(queryString: string): IQueryBuilder<T>;
+  notWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+  
+  /**
+   * Add an order by clause to the query
+   */
+  orderBy(field: QueryField<T>, direction?: SortDirection): IQueryBuilder<T>;
+  
+  /**
+   * Add a limit to the query
+   */
+  limit(count: number): IQueryBuilder<T>;
+  
+  /**
+   * Add an offset to the query
+   */
+  offset(count: number): IQueryBuilder<T>;
+  
+  /**
+   * Get the current query expression
+   */
+  getExpression(): QueryExpression;
+  
+  /**
+   * Get the current query as a string
+   */
+  toString(): string;
+} 

package/src/security/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './validator'; 

package/src/security/types.ts

@@ -0,0 +1,210 @@
+/**
+ * Security configuration types for QueryKit
+ *
+ * This module defines the security configuration interface and default values
+ * used throughout QueryKit to enforce security boundaries and prevent abuse.
+ */
+
+/**
+ * @interface ISecurityOptions
+ * @description Comprehensive security configuration options for QueryKit
+ *
+ * These options help protect your application from potential security issues,
+ * resource exhaustion, and performance problems when exposing QueryKit to users.
+ *
+ * @example
+ * ```typescript
+ * import { createQueryKit, type ISecurityOptions } from 'querykit';
+ *
+ * // Configure security options
+ * const securityOptions: ISecurityOptions = {
+ *   allowedFields: ['id', 'name', 'createdAt'],
+ *   denyFields: ['password', 'secretKey'],
+ *   maxQueryDepth: 5,
+ *   maxClauseCount: 20
+ * };
+ *
+ * // Create QueryKit instance with security options
+ * const queryKit = createQueryKit({
+ *   // ...other options
+ *   security: securityOptions
+ * });
+ * ```
+ */
+export interface ISecurityOptions {
+  /**
+   * List of fields that are allowed to be queried.
+   * If empty, all fields in the schema are allowed by default.
+   *
+   * @example
+   * ```typescript
+   * // Only allow specific fields to be queried
+   * allowedFields: ['id', 'name', 'email', 'createdAt']
+   * ```
+   */
+  allowedFields?: string[];
+
+  /**
+   * List of fields that are explicitly denied from being queried.
+   * These fields will be blocked even if they appear in allowedFields.
+   * Use this to protect sensitive data fields.
+   *
+   * @example
+   * ```typescript
+   * // Prevent querying of sensitive fields
+   * denyFields: ['password', 'secretToken', 'ssn']
+   * ```
+   */
+  denyFields?: string[];
+
+  /**
+   * Maximum nesting depth of query expressions.
+   * Prevents deeply nested queries that could impact performance.
+   *
+   * @default 10
+   *
+   * @example
+   * ```typescript
+   * // Allow only simple queries with limited nesting
+   * maxQueryDepth: 3
+   *
+   * // This would allow queries like:
+   * // title:"Meeting notes" && (priority > 2 || completed == true)
+   * // But would reject more deeply nested expressions
+   * ```
+   */
+  maxQueryDepth?: number;
+
+  /**
+   * Maximum number of clauses (AND/OR operations) in a query.
+   * Prevents overly complex queries that could impact performance.
+   *
+   * @default 50
+   *
+   * @example
+   * ```typescript
+   * // Limit query complexity
+   * maxClauseCount: 20
+   *
+   * // This would allow queries with up to 20 conditions joined by AND/OR
+   * ```
+   */
+  maxClauseCount?: number;
+
+  /**
+   * Default limit for query results if none is specified by the client.
+   * Prevents unintentionally large result sets.
+   *
+   * @default 100
+   *
+   * @example
+   * ```typescript
+   * // Set conservative default limit
+   * defaultLimit: 50
+   * ```
+   */
+  defaultLimit?: number;
+
+  /**
+   * Maximum allowed limit for pagination.
+   * Prevents clients from requesting excessively large result sets.
+   *
+   * @default 1000
+   *
+   * @example
+   * ```typescript
+   * // Restrict maximum page size
+   * maxLimit: 500
+   *
+   * // Even if a client requests limit=10000, it will be capped at 500
+   * ```
+   */
+  maxLimit?: number;
+
+  /**
+   * Maximum string length for query values.
+   * Prevents memory exhaustion from extremely large string values.
+   *
+   * @default 1000
+   *
+   * @example
+   * ```typescript
+   * // Limit string length in query values
+   * maxValueLength: 500
+   *
+   * // Prevents attacks using extremely long strings in filters
+   * ```
+   */
+  maxValueLength?: number;
+
+  /**
+   * Whether to sanitize wildcard patterns in LIKE queries to prevent regex DoS.
+   * When enabled, excessive wildcard patterns are sanitized or rejected.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // Enable wildcard sanitization
+   * sanitizeWildcards: true
+   *
+   * // Prevents regex DoS attacks like: name LIKE "%a%a%a%a%a%a%a%a%..."
+   * ```
+   */
+  sanitizeWildcards?: boolean;
+
+  /**
+   * Timeout in milliseconds for query execution.
+   * Prevents long-running queries from consuming excessive resources.
+   *
+   * @default 30000 (30 seconds)
+   *
+   * @example
+   * ```typescript
+   * // Set shorter timeout for API endpoints
+   * queryTimeout: 5000 // 5 seconds
+   *
+   * // Queries taking longer than 5 seconds will be terminated
+   * ```
+   */
+  queryTimeout?: number;
+}
+
+/**
+ * Default security configuration values
+ *
+ * These defaults provide a reasonable balance between functionality and security.
+ * It's recommended to review and adjust these settings based on your specific use case.
+ *
+ * @example
+ * ```typescript
+ * import { DEFAULT_SECURITY_OPTIONS } from 'querykit';
+ *
+ * // Use defaults but override specific options
+ * const securityOptions = {
+ *   ...DEFAULT_SECURITY_OPTIONS,
+ *   maxLimit: 500,
+ *   queryTimeout: 10000
+ * };
+ * ```
+ */
+export const DEFAULT_SECURITY_OPTIONS: Required<ISecurityOptions> = {
+  // Field restrictions - by default, all schema fields are allowed
+  allowedFields: [], // Empty means "use schema fields"
+  denyFields: [], // Empty means no denied fields
+
+  // Query complexity limits
+  maxQueryDepth: 10, // Maximum nesting level of expressions
+  maxClauseCount: 50, // Maximum number of clauses (AND/OR operations)
+
+  // Resource protection
+  defaultLimit: 100, // Default result limit if none specified
+  maxLimit: 1000, // Maximum allowed limit for pagination
+
+  // Value sanitization
+  maxValueLength: 1000, // Maximum string length for query values
+  sanitizeWildcards: true, // Prevent regex DoS with wildcards in LIKE queries
+
+  // Performance safeguards
+  queryTimeout: 30000 // 30 second timeout by default
+};