@gblikas/querykit 0.4.0 → 0.5.0

package/README.md

@@ -780,6 +780,197 @@ const results = await qk
   .execute();
 ```
 
+### Raw SQL Expressions
+
+For advanced query patterns that can't be expressed as simple field comparisons, virtual fields can return **raw SQL expressions**. This enables database-specific operations like JSONB array membership checks, date calculations, and custom SQL logic.
+
+#### Why Raw SQL Expressions?
+
+Use raw SQL expressions when you need to:
+- **Check JSONB array membership** - e.g., `my:assigned` where `assignedTo` is a JSONB array
+- **Implement computed/derived fields** - e.g., `priority:high` based on date calculations
+- **Use database-specific functions** - e.g., PostGIS functions, full-text search
+- **Combine multiple conditions** - e.g., custom business logic that requires complex SQL
+
+#### Basic Example
+
+```typescript
+import { createQueryKit } from '@gblikas/querykit';
+import { drizzleAdapter } from '@gblikas/querykit/adapters/drizzle';
+import { jsonbContains, dateWithinDays } from '@gblikas/querykit/virtual-fields';
+import { sql } from 'drizzle-orm';
+
+interface MyContext extends IQueryContext {
+  currentUserId: string;
+}
+
+const qk = createQueryKit<typeof schema, MyContext>({
+  adapter: drizzleAdapter({ db, schema }),
+  schema,
+
+  virtualFields: {
+    // JSONB array contains example
+    my: {
+      allowedValues: ['assigned'] as const,
+      description: 'Filter by your relationship to items',
+      resolve: (input, ctx) => {
+        if (input.value === 'assigned') {
+          return jsonbContains('assigned_to', ctx.currentUserId);
+        }
+        throw new Error(`Unknown value: ${input.value}`);
+      }
+    },
+
+    // Computed priority based on createdAt
+    priority: {
+      allowedValues: ['high', 'medium', 'low'] as const,
+      description: 'Filter by computed priority (based on age)',
+      resolve: (input) => {
+        const thresholds = { high: 1, medium: 7, low: 30 };
+        const days = thresholds[input.value as keyof typeof thresholds];
+        return dateWithinDays('created_at', days);
+      }
+    },
+
+    // Custom raw SQL example
+    custom: {
+      allowedValues: ['active'] as const,
+      resolve: (input, ctx) => ({
+        type: 'raw',
+        toSql: () => sql`status = 'active' AND ${sql.identifier('owner_id')} = ${ctx.currentUserId}`
+      })
+    }
+  },
+
+  createContext: async () => ({
+    currentUserId: await getCurrentUserId()
+  })
+});
+
+// Queries that now work:
+await qk.query('my_table').where('my:assigned').execute();
+await qk.query('my_table').where('priority:high AND status:active').execute();
+```
+
+#### Helper Functions
+
+QueryKit provides helper functions for common raw SQL patterns:
+
+##### `jsonbContains(field, value)` - JSONB Array Membership (PostgreSQL)
+
+Checks if a JSONB array field contains the given value:
+
+```typescript
+import { jsonbContains } from '@gblikas/querykit/virtual-fields';
+
+// Check if assignedTo contains the current user ID
+jsonbContains('assigned_to', ctx.currentUserId)
+// Generates: assigned_to @> '["user123"]'::jsonb
+
+// Works with arrays too
+jsonbContains('tags', ['urgent', 'review'])
+// Generates: tags @> '["urgent","review"]'::jsonb
+```
+
+##### `dateWithinDays(field, days)` - Date Range Check
+
+Checks if a timestamp field is within the specified number of days from now:
+
+```typescript
+import { dateWithinDays } from '@gblikas/querykit/virtual-fields';
+
+// Check if created within last day
+dateWithinDays('created_at', 1)
+// Generates: created_at >= NOW() - INTERVAL '1 days'
+
+// Check if created within last week
+dateWithinDays('created_at', 7)
+// Generates: created_at >= NOW() - INTERVAL '7 days'
+```
+
+#### Custom Raw SQL
+
+For complete control, create your own raw SQL expressions:
+
+```typescript
+virtualFields: {
+  custom: {
+    allowedValues: ['special'] as const,
+    resolve: (input, ctx) => ({
+      type: 'raw',
+      toSql: (context) => {
+        // context provides: adapter, tableName, schema
+        // Return a Drizzle SQL template
+        return sql`
+          ${sql.identifier('status')} = 'active' 
+          AND ${sql.identifier('owner_id')} = ${ctx.currentUserId}
+          AND ${sql.identifier('created_at')} >= NOW() - INTERVAL '30 days'
+        `;
+      }
+    })
+  }
+}
+```
+
+#### Schema Example with JSONB
+
+Here's a complete example with a Drizzle schema that uses JSONB:
+
+```typescript
+import { pgTable, serial, varchar, timestamp, jsonb } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+
+export const tasks = pgTable('tasks', {
+  id: serial('id').primaryKey(),
+  title: varchar('title', { length: 256 }),
+  description: varchar('description', { length: 1024 }),
+  createdAt: timestamp('created_at').defaultNow(),
+  status: varchar('status', { length: 50 }).default('open'),
+  // JSONB array of user IDs
+  assignedTo: jsonb('assigned_to')
+    .$type<string[]>()
+    .default(sql`'[]'`)
+});
+
+// QueryKit configuration
+const qk = createQueryKit({
+  adapter: drizzleAdapter({ db, schema: { tasks } }),
+  schema: { tasks },
+  
+  virtualFields: {
+    my: {
+      allowedValues: ['assigned'] as const,
+      resolve: (input, ctx) => jsonbContains('assigned_to', ctx.currentUserId)
+    }
+  },
+  
+  createContext: async () => ({
+    currentUserId: await getCurrentUserId()
+  })
+});
+
+// Query: find my assigned tasks that are high priority
+await qk.query('tasks')
+  .where('my:assigned AND priority:high')
+  .execute();
+```
+
+#### Combining with Standard Fields
+
+Raw SQL expressions work seamlessly with standard field queries:
+
+```typescript
+// Mix virtual fields (raw SQL) with standard field queries
+await qk.query('tasks')
+  .where('my:assigned AND status:active AND priority:>5')
+  .execute();
+  
+// Complex nested queries
+await qk.query('tasks')
+  .where('(my:assigned OR priority:high) AND NOT status:closed')
+  .execute();
+```
+
 ## Roadmap
 
 ### Core Parsing Engine and DSL
@@ -803,6 +994,7 @@ const results = await qk
 - [ ] CLI tools for testing and debugging
 - [x] Performance optimizations for SQL generation
 - [x] Support for complex nested expressions
+- [x] Raw SQL expressions for virtual fields (JSONB, computed fields, custom SQL)
 - [ ] Custom function support
 - [ ] Pagination helpers
 - [x] Virtual fields for context-aware query expansion

package/dist/parser/types.d.ts

@@ -31,10 +31,26 @@ export interface ILogicalExpression {
     left: QueryExpression;
     right?: QueryExpression;
 }
+/**
+ * Represents a raw SQL expression node in the AST.
+ * Used by virtual fields to inject database-specific SQL operations.
+ */
+export interface IRawSqlExpression {
+    type: 'raw';
+    /**
+     * Function that generates the raw SQL for the adapter.
+     * For Drizzle, this should return a SQL template result.
+     */
+    toSql: (context: {
+        adapter: string;
+        tableName: string;
+        schema: Record<string, unknown>;
+    }) => unknown;
+}
 /**
  * Represents any valid query expression node
  */
-export type QueryExpression = IComparisonExpression | ILogicalExpression;
+export type QueryExpression = IComparisonExpression | ILogicalExpression | IRawSqlExpression;
 /**
  * Configuration options for the parser
  */

package/dist/security/validator.js

@@ -219,13 +219,14 @@ class QuerySecurityValidator {
                     `Found "${field}" - use a simple field name without dots instead.`);
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             // Recursively validate logical expressions
             this.validateNoDotNotation(expression.left);
             if (expression.right) {
                 this.validateNoDotNotation(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own field access
     }
     /**
      * Validate that query values are not in the denied values list for their field
@@ -263,13 +264,14 @@ class QuerySecurityValidator {
                 }
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             // Recursively validate logical expressions
             this.validateDenyValues(expression.left);
             if (expression.right) {
                 this.validateDenyValues(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own values
     }
     /**
      * Check if a value is in the denied values list
@@ -317,6 +319,7 @@ class QuerySecurityValidator {
                 this.validateQueryDepth(expression.right, currentDepth + 1);
             }
         }
+        // Raw and comparison expressions don't add depth
     }
     /**
      * Validate that the number of clauses does not exceed the maximum
@@ -341,6 +344,9 @@ class QuerySecurityValidator {
         if (expression.type === 'comparison') {
             return 1;
         }
+        if (expression.type === 'raw') {
+            return 1; // Raw expressions count as one clause
+        }
         let count = 0;
         count += this.countClauses(expression.left);
         if (expression.right) {
@@ -387,12 +393,13 @@ class QuerySecurityValidator {
                 throw new QuerySecurityError('Object values are not allowed');
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             this.validateValueLengths(expression.left);
             if (expression.right) {
                 this.validateValueLengths(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own values
     }
     /**
      * Sanitize wildcard patterns in LIKE queries to prevent regex DoS
@@ -423,12 +430,13 @@ class QuerySecurityValidator {
                 expression.value = sanitized;
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             this.sanitizeWildcards(expression.left);
             if (expression.right) {
                 this.sanitizeWildcards(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own wildcards
     }
     /**
      * Collect all field names used in the query
@@ -441,12 +449,13 @@ class QuerySecurityValidator {
         if (expression.type === 'comparison') {
             fieldSet.add(expression.field);
         }
-        else {
+        else if (expression.type === 'logical') {
             this.collectFields(expression.left, fieldSet);
             if (expression.right) {
                 this.collectFields(expression.right, fieldSet);
             }
         }
+        // Raw expressions don't expose field names for collection
     }
 }
 exports.QuerySecurityValidator = QuerySecurityValidator;

package/dist/translators/drizzle/index.js

@@ -64,6 +64,17 @@ class DrizzleTranslator {
                 return this.translateComparisonExpression(expression);
             case 'logical':
                 return this.translateLogicalExpression(expression);
+            case 'raw': {
+                const rawExpr = expression;
+                return rawExpr.toSql({
+                    adapter: 'drizzle',
+                    // tableName is empty because raw SQL expressions in virtual fields
+                    // are resolved before translation and don't need table context at this stage.
+                    // The schema is provided for field lookups if needed.
+                    tableName: '',
+                    schema: this.options.schema
+                });
+            }
             default:
                 throw new DrizzleTranslationError(`Unsupported expression type: ${expression.type}`);
         }

package/dist/virtual-fields/helpers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Helper utilities for creating raw SQL expressions in virtual fields
+ */
+import { IRawSqlExpression } from '../parser/types';
+/**
+ * Create a JSONB array contains expression (PostgreSQL).
+ * Checks if the JSONB array field contains the given value.
+ *
+ * @param field - The JSONB field name (e.g., 'assigned_to')
+ * @param value - The value to check for in the array
+ * @returns A raw SQL expression for JSONB contains check
+ *
+ * @example
+ * // Check if assignedTo contains the current user ID
+ * jsonbContains('assigned_to', ctx.currentUserId)
+ * // Generates: assigned_to @> '["user123"]'::jsonb
+ */
+export declare function jsonbContains(field: string, value: unknown): IRawSqlExpression;
+/**
+ * Create a date range expression.
+ * Checks if a timestamp field is within the specified number of days from now.
+ *
+ * @param field - The timestamp field name (e.g., 'created_at')
+ * @param days - Number of days from now (must be a positive finite number)
+ * @returns A raw SQL expression for date range check
+ *
+ * @example
+ * // Check if created within last day
+ * dateWithinDays('created_at', 1)
+ * // Generates: created_at >= NOW() - INTERVAL '1 days'
+ */
+export declare function dateWithinDays(field: string, days: number): IRawSqlExpression;

package/dist/virtual-fields/helpers.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Helper utilities for creating raw SQL expressions in virtual fields
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonbContains = jsonbContains;
+exports.dateWithinDays = dateWithinDays;
+const drizzle_orm_1 = require("drizzle-orm");
+/**
+ * Validates field name to prevent SQL injection.
+ * Only allows alphanumeric characters, dots, and underscores.
+ * @private
+ */
+function validateFieldName(field) {
+    if (!/^[a-zA-Z][a-zA-Z0-9._]*$/.test(field)) {
+        throw new Error(`Invalid field name: ${field}`);
+    }
+    if (field.length > 64) {
+        throw new Error(`Field name too long: ${field}`);
+    }
+}
+/**
+ * Create a JSONB array contains expression (PostgreSQL).
+ * Checks if the JSONB array field contains the given value.
+ *
+ * @param field - The JSONB field name (e.g., 'assigned_to')
+ * @param value - The value to check for in the array
+ * @returns A raw SQL expression for JSONB contains check
+ *
+ * @example
+ * // Check if assignedTo contains the current user ID
+ * jsonbContains('assigned_to', ctx.currentUserId)
+ * // Generates: assigned_to @> '["user123"]'::jsonb
+ */
+function jsonbContains(field, value) {
+    validateFieldName(field);
+    return {
+        type: 'raw',
+        toSql: () => (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(field)} @> ${drizzle_orm_1.sql.raw("'" + JSON.stringify(Array.isArray(value) ? value : [value]).replace(/'/g, "''") + "'::jsonb")}`
+    };
+}
+/**
+ * Validates days parameter to ensure it's a positive finite number.
+ * @private
+ */
+function validateDaysParameter(days) {
+    if (!Number.isFinite(days)) {
+        throw new Error(`Invalid days parameter: ${days}. Must be a finite number.`);
+    }
+    if (days <= 0) {
+        throw new Error(`Invalid days parameter: ${days}. Must be a positive number.`);
+    }
+}
+/**
+ * Create a date range expression.
+ * Checks if a timestamp field is within the specified number of days from now.
+ *
+ * @param field - The timestamp field name (e.g., 'created_at')
+ * @param days - Number of days from now (must be a positive finite number)
+ * @returns A raw SQL expression for date range check
+ *
+ * @example
+ * // Check if created within last day
+ * dateWithinDays('created_at', 1)
+ * // Generates: created_at >= NOW() - INTERVAL '1 days'
+ */
+function dateWithinDays(field, days) {
+    validateFieldName(field);
+    validateDaysParameter(days);
+    return {
+        type: 'raw',
+        toSql: () => (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(field)} >= NOW() - INTERVAL '${drizzle_orm_1.sql.raw(days.toString())} days'`
+    };
+}

package/dist/virtual-fields/index.d.ts

@@ -3,3 +3,4 @@
  */
 export * from './types';
 export * from './resolver';
+export * from './helpers';

package/dist/virtual-fields/index.js

@@ -19,3 +19,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./resolver"), exports);
+__exportStar(require("./helpers"), exports);

package/dist/virtual-fields/resolver.js

@@ -25,6 +25,10 @@ function resolveVirtualFields(expr, virtualFields, context) {
     if (expr.type === 'logical') {
         return resolveLogicalExpression(expr, virtualFields, context);
     }
+    // Pass through raw expressions
+    if (expr.type === 'raw') {
+        return expr;
+    }
     // Unknown expression type, return as-is
     return expr;
 }

package/dist/virtual-fields/types.d.ts

@@ -1,7 +1,24 @@
 /**
  * Type definitions for Virtual Fields support
  */
-import { QueryExpression, IComparisonExpression, ComparisonOperator } from '../parser/types';
+import { QueryExpression, IComparisonExpression, ComparisonOperator, IRawSqlExpression } from '../parser/types';
+/**
+ * Context provided to raw SQL generators for adapter-specific SQL generation.
+ */
+export interface IRawSqlContext {
+    /**
+     * The database adapter identifier (e.g., 'drizzle')
+     */
+    adapter: string;
+    /**
+     * The table name being queried
+     */
+    tableName: string;
+    /**
+     * Access to the schema for field references
+     */
+    schema: Record<string, unknown>;
+}
 /**
  * Base interface for query context.
  * Users can extend this interface with their own context properties.
@@ -86,9 +103,9 @@ export interface ITypedComparisonExpression<TFields extends string = string> ext
 }
 /**
  * Schema-constrained query expression.
- * Can be a comparison or logical expression with typed fields.
+ * Can be a comparison, logical expression with typed fields, or a raw SQL expression.
  */
-export type ITypedQueryExpression<TFields extends string = string> = ITypedComparisonExpression<TFields> | QueryExpression;
+export type ITypedQueryExpression<TFields extends string = string> = ITypedComparisonExpression<TFields> | IRawSqlExpression | QueryExpression;
 /**
  * Definition for a virtual field.
  * Configures how a virtual field should be resolved at query execution time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gblikas/querykit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A comprehensive query toolkit for TypeScript that simplifies building and executing data queries across different environments",
   "repository": {
     "type": "git",

package/src/parser/types.ts

@@ -51,10 +51,30 @@ export interface ILogicalExpression {
   right?: QueryExpression;
 }
 
+/**
+ * Represents a raw SQL expression node in the AST.
+ * Used by virtual fields to inject database-specific SQL operations.
+ */
+export interface IRawSqlExpression {
+  type: 'raw';
+  /**
+   * Function that generates the raw SQL for the adapter.
+   * For Drizzle, this should return a SQL template result.
+   */
+  toSql: (context: {
+    adapter: string;
+    tableName: string;
+    schema: Record<string, unknown>;
+  }) => unknown;
+}
+
 /**
  * Represents any valid query expression node
  */
-export type QueryExpression = IComparisonExpression | ILogicalExpression;
+export type QueryExpression =
+  | IComparisonExpression
+  | ILogicalExpression
+  | IRawSqlExpression;
 
 /**
  * Configuration options for the parser

package/src/security/validator.ts

@@ -240,13 +240,14 @@ export class QuerySecurityValidator {
             `Found "${field}" - use a simple field name without dots instead.`
         );
       }
-    } else {
+    } else if (expression.type === 'logical') {
       // Recursively validate logical expressions
       this.validateNoDotNotation(expression.left);
       if (expression.right) {
         this.validateNoDotNotation(expression.right);
       }
     }
+    // Raw expressions are skipped - they handle their own field access
   }
 
   /**
@@ -285,13 +286,14 @@ export class QuerySecurityValidator {
           }
         }
       }
-    } else {
+    } else if (expression.type === 'logical') {
       // Recursively validate logical expressions
       this.validateDenyValues(expression.left);
       if (expression.right) {
         this.validateDenyValues(expression.right);
       }
     }
+    // Raw expressions are skipped - they handle their own values
   }
 
   /**
@@ -350,6 +352,7 @@ export class QuerySecurityValidator {
         this.validateQueryDepth(expression.right, currentDepth + 1);
       }
     }
+    // Raw and comparison expressions don't add depth
   }
 
   /**
@@ -379,6 +382,10 @@ export class QuerySecurityValidator {
       return 1;
     }
 
+    if (expression.type === 'raw') {
+      return 1; // Raw expressions count as one clause
+    }
+
     let count = 0;
     count += this.countClauses(expression.left);
     if (expression.right) {
@@ -442,12 +449,13 @@ export class QuerySecurityValidator {
       ) {
         throw new QuerySecurityError('Object values are not allowed');
       }
-    } else {
+    } else if (expression.type === 'logical') {
       this.validateValueLengths(expression.left);
       if (expression.right) {
         this.validateValueLengths(expression.right);
       }
     }
+    // Raw expressions are skipped - they handle their own values
   }
 
   /**
@@ -481,12 +489,13 @@ export class QuerySecurityValidator {
           .replace(/\?{2,}/g, '?'); // Limit consecutive question marks
         (expression as IComparisonExpression).value = sanitized;
       }
-    } else {
+    } else if (expression.type === 'logical') {
       this.sanitizeWildcards(expression.left);
       if (expression.right) {
         this.sanitizeWildcards(expression.right);
       }
     }
+    // Raw expressions are skipped - they handle their own wildcards
   }
 
   /**
@@ -502,11 +511,12 @@ export class QuerySecurityValidator {
   ): void {
     if (expression.type === 'comparison') {
       fieldSet.add(expression.field);
-    } else {
+    } else if (expression.type === 'logical') {
       this.collectFields(expression.left, fieldSet);
       if (expression.right) {
         this.collectFields(expression.right, fieldSet);
       }
     }
+    // Raw expressions don't expose field names for collection
   }
 }

package/src/translators/drizzle/index.ts

@@ -97,6 +97,24 @@ export class DrizzleTranslator implements ITranslator<SQL> {
         return this.translateComparisonExpression(expression);
       case 'logical':
         return this.translateLogicalExpression(expression);
+      case 'raw': {
+        const rawExpr = expression as {
+          type: 'raw';
+          toSql: (context: {
+            adapter: string;
+            tableName: string;
+            schema: Record<string, unknown>;
+          }) => unknown;
+        };
+        return rawExpr.toSql({
+          adapter: 'drizzle',
+          // tableName is empty because raw SQL expressions in virtual fields
+          // are resolved before translation and don't need table context at this stage.
+          // The schema is provided for field lookups if needed.
+          tableName: '',
+          schema: this.options.schema
+        }) as SQL;
+      }
       default:
         throw new DrizzleTranslationError(
           `Unsupported expression type: ${(expression as { type: string }).type}`