@gblikas/querykit 0.3.0 → 0.5.0

package/.husky/pre-commit

@@ -14,16 +14,16 @@ echo "Running pre-commit checks..."
 
 # Run lint-staged to process only changed files
 echo "🔍 Running lint-staged..."
-pnpm lint-staged || { echo "❌ Linting failed"; exit 1; }
+npx lint-staged || { echo "❌ Linting failed"; exit 1; }
 
 # Check TypeScript compilation
 echo "🔍 Checking TypeScript compilation..."
-pnpm exec tsc --noEmit || { echo "❌ TypeScript check failed"; exit 1; }
+npx tsc --noEmit || { echo "❌ TypeScript check failed"; exit 1; }
 
 # Run tests
 if [ "$RUN_TESTS" = "true" ]; then
   echo "🧪 Running tests..."
-  pnpm test || { echo "❌ Tests failed"; exit 1; }
+  npm test || { echo "❌ Tests failed"; exit 1; }
 fi
 
 # If everything passes, allow the commit

package/README.md

@@ -434,6 +434,543 @@ function SearchBar({ value, onChange }) {
 }
 ```
 
+## Virtual Fields
+
+Virtual fields enable powerful shortcuts in your queries that expand to real schema fields at query execution time based on runtime context. This allows you to support queries like `my:assigned` which expands to `assignee_id == <current_user_id>` using the currently logged-in user's ID.
+
+### Why Virtual Fields?
+
+Virtual fields are useful when:
+- You want to provide user-friendly shortcuts (e.g., `my:assigned` instead of `assignee_id:123`)
+- The query depends on runtime context (current user, permissions, tenant, etc.)
+- You want to abstract complex field mappings from end users
+- You need consistent query shortcuts across your application
+
+### Basic Usage
+
+Define virtual fields when creating your QueryKit instance:
+
+```typescript
+import { createQueryKit } from '@gblikas/querykit';
+import { drizzleAdapter } from '@gblikas/querykit/adapters/drizzle';
+
+const qk = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { tasks, users },
+
+  // Define virtual fields
+  virtualFields: {
+    my: {
+      allowedValues: ['assigned', 'created', 'watching'] as const,
+      description: 'Filter by your relationship to items',
+      
+      resolve: (input, ctx, { fields }) => {
+        // Map virtual values to real schema fields
+        const fieldMap = fields({
+          assigned: 'assignee_id',
+          created: 'creator_id',
+          watching: 'watcher_ids'
+        });
+
+        return {
+          type: 'comparison',
+          field: fieldMap[input.value],
+          operator: '==',
+          value: ctx.currentUserId
+        };
+      }
+    }
+  },
+
+  // Provide runtime context
+  createContext: async () => ({
+    currentUserId: await getCurrentUserId(),
+    currentUserTeamIds: await getUserTeamIds()
+  })
+});
+
+// Use virtual fields in queries
+const myTasks = await qk
+  .query('tasks')
+  .where('my:assigned AND status:active')
+  .execute();
+```
+
+### Configuration Options
+
+Each virtual field definition supports:
+
+```typescript
+{
+  // Required: allowed values for this virtual field
+  allowedValues: ['value1', 'value2'] as const,
+
+  // Optional: allow comparison operators (>, <, >=, <=)
+  // Default: false (only equality ":" is allowed)
+  allowOperators?: boolean,
+
+  // Required: resolver function
+  resolve: (input, context, helpers) => {
+    // Return a query expression that replaces the virtual field
+    return {
+      type: 'comparison',
+      field: 'real_field',
+      operator: '==',
+      value: context.someValue
+    };
+  },
+
+  // Optional: human-readable description
+  description?: string,
+
+  // Optional: descriptions for each value
+  valueDescriptions?: {
+    value1: 'Description of value1',
+    value2: 'Description of value2'
+  }
+}
+```
+
+### Type-Safe Field Mapping
+
+The `fields()` helper provides compile-time validation that all mapped fields exist in your schema:
+
+```typescript
+virtualFields: {
+  my: {
+    allowedValues: ['assigned', 'created'] as const,
+    resolve: (input, ctx, { fields }) => {
+      // TypeScript validates:
+      // 1. All allowedValues keys are mapped
+      // 2. All field values exist in the schema
+      const fieldMap = fields({
+        assigned: 'assignee_id',  // ✓ Valid schema field
+        created: 'creator_id'      // ✓ Valid schema field
+        // Missing 'watching' → TypeScript error!
+        // assigned: 'invalid_field' → TypeScript error!
+      });
+
+      return {
+        type: 'comparison',
+        field: fieldMap[input.value],
+        operator: '==',
+        value: ctx.currentUserId
+      };
+    }
+  }
+}
+```
+
+### Context Factory
+
+The `createContext` function is called once per query execution to provide runtime values:
+
+```typescript
+createContext: async () => {
+  const user = await getCurrentUser();
+  const permissions = await getUserPermissions(user.id);
+  
+  return {
+    currentUserId: user.id,
+    currentUserTeamIds: user.teamIds,
+    canSeeArchived: permissions.includes('view:archived')
+  };
+}
+```
+
+Context is type-safe and can include any data your resolvers need:
+
+```typescript
+interface MyQueryContext extends IQueryContext {
+  currentUserId: number;
+  currentUserTeamIds: number[];
+  canSeeArchived: boolean;
+}
+
+const qk = createQueryKit<typeof schema, MyQueryContext>({
+  // ... configuration
+});
+```
+
+### Complex Resolvers
+
+Virtual fields can return logical expressions for more complex scenarios:
+
+```typescript
+virtualFields: {
+  myItems: {
+    allowedValues: ['all'] as const,
+    resolve: (input, ctx) => ({
+      // Return a logical OR expression
+      type: 'logical',
+      operator: 'OR',
+      left: {
+        type: 'comparison',
+        field: 'assignee_id',
+        operator: '==',
+        value: ctx.currentUserId
+      },
+      right: {
+        type: 'comparison',
+        field: 'creator_id',
+        operator: '==',
+        value: ctx.currentUserId
+      }
+    })
+  }
+}
+
+// Expands to: (assignee_id == currentUserId OR creator_id == currentUserId)
+await qk.query('tasks').where('myItems:all').execute();
+```
+
+### Allowing Comparison Operators
+
+By default, only equality (`:`) is allowed. Enable other operators with `allowOperators: true`:
+
+```typescript
+virtualFields: {
+  priority: {
+    allowedValues: ['high', 'low'] as const,
+    allowOperators: true,  // Enable >, <, etc.
+    
+    resolve: (input, ctx) => {
+      const threshold = input.value === 'high' ? 7 : 3;
+      
+      return {
+        type: 'comparison',
+        field: 'priority',
+        operator: input.operator,  // Use the operator from the query
+        value: threshold
+      };
+    }
+  }
+}
+
+// Both work:
+qk.query('tasks').where('priority:high')    // priority == 7
+qk.query('tasks').where('priority:>high')  // priority > 7
+```
+
+### Error Handling
+
+QueryKit throws `QueryParseError` for invalid virtual field usage:
+
+```typescript
+// Invalid value
+qk.query('tasks').where('my:invalid')
+// Error: Invalid value "invalid" for virtual field "my". 
+//        Allowed values: "assigned", "created", "watching"
+
+// Operator not allowed (when allowOperators: false)
+qk.query('tasks').where('my:>assigned')
+// Error: Virtual field "my" does not allow comparison operators. 
+//        Only equality (":") is permitted.
+```
+
+### Complete Example
+
+Here's a full example with multiple virtual fields:
+
+```typescript
+import { createQueryKit, IQueryContext, ComparisonOperator } from '@gblikas/querykit';
+import { drizzleAdapter } from '@gblikas/querykit/adapters/drizzle';
+
+// Define your context type
+interface TaskQueryContext extends IQueryContext {
+  currentUserId: number;
+  currentUserTeamIds: number[];
+  currentTenantId: string;
+}
+
+// Create QueryKit with virtual fields
+const qk = createQueryKit<typeof schema, TaskQueryContext>({
+  adapter: drizzleAdapter,
+  schema: { tasks, users },
+
+  virtualFields: {
+    // User relationship shortcuts
+    my: {
+      allowedValues: ['assigned', 'created', 'watching'] as const,
+      description: 'Filter by your relationship to tasks',
+      valueDescriptions: {
+        assigned: 'Tasks assigned to you',
+        created: 'Tasks you created',
+        watching: 'Tasks you are watching'
+      },
+      resolve: (input, ctx, { fields }) => {
+        const fieldMap = fields({
+          assigned: 'assignee_id',
+          created: 'creator_id',
+          watching: 'watcher_ids'
+        });
+        return {
+          type: 'comparison',
+          field: fieldMap[input.value],
+          operator: '==',
+          value: ctx.currentUserId
+        };
+      }
+    },
+
+    // Team shortcuts
+    team: {
+      allowedValues: ['assigned', 'owned'] as const,
+      description: 'Filter by team relationship',
+      resolve: (input, ctx, { fields }) => {
+        const fieldMap = fields({
+          assigned: 'assignee_id',
+          owned: 'owner_id'
+        });
+        return {
+          type: 'comparison',
+          field: fieldMap[input.value],
+          operator: 'IN',
+          value: ctx.currentUserTeamIds
+        };
+      }
+    },
+
+    // Priority shortcuts with operators
+    priority: {
+      allowedValues: ['critical', 'high', 'normal', 'low'] as const,
+      allowOperators: true,
+      description: 'Filter by priority level',
+      resolve: (input) => {
+        const priorityMap = {
+          critical: 10,
+          high: 7,
+          normal: 5,
+          low: 3
+        };
+        return {
+          type: 'comparison',
+          field: 'priority',
+          operator: input.operator as ComparisonOperator,
+          value: priorityMap[input.value as keyof typeof priorityMap]
+        };
+      }
+    }
+  },
+
+  // Context factory
+  createContext: async () => {
+    const user = await getCurrentUser();
+    const teams = await getUserTeams(user.id);
+    
+    return {
+      currentUserId: user.id,
+      currentUserTeamIds: teams.map(t => t.id),
+      currentTenantId: user.tenantId
+    };
+  }
+});
+
+// Example queries using virtual fields
+// "my:assigned AND status:active"
+// "team:assigned OR my:created"
+// "priority:>high AND my:watching"
+// "(my:assigned OR team:assigned) AND status:active"
+
+const results = await qk
+  .query('tasks')
+  .where('my:assigned AND priority:>high')
+  .orderBy('created_at', 'desc')
+  .limit(10)
+  .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
@@ -457,8 +994,10 @@ function SearchBar({ value, onChange }) {
 - [ ] 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
 
 ### Ecosystem Expansion
 - [x] Frontend query builder components (input parser)

package/dist/index.d.ts

@@ -10,9 +10,11 @@ import { QueryParser, IParserOptions } from './parser';
 import { SqlTranslator } from './translators/sql';
 import { ISecurityOptions } from './security';
 import { IAdapter, IAdapterOptions } from './adapters';
+import { IQueryContext, VirtualFieldsConfig } from './virtual-fields';
 export { QueryParser, IParserOptions, QueryBuilder, IQueryBuilderOptions, SqlTranslator };
 export * from './translators';
 export * from './adapters';
+export * from './virtual-fields';
 /**
  * Create a new QueryBuilder instance
  */
@@ -24,7 +26,7 @@ export declare function createQueryParser(options?: IParserOptions): QueryParser
 /**
  * Options for creating a new QueryKit instance
  */
-export interface IQueryKitOptions<TSchema extends Record<string, object> = Record<string, Record<string, unknown>>> {
+export interface IQueryKitOptions<TSchema extends Record<string, object> = Record<string, Record<string, unknown>>, TContext extends IQueryContext = IQueryContext> {
     /**
      * The adapter to use for database connections
      */
@@ -43,6 +45,37 @@ export interface IQueryKitOptions<TSchema extends Record<string, object> = Recor
     adapterOptions?: IAdapterOptions & {
         [key: string]: unknown;
     };
+    /**
+     * Virtual field definitions for context-aware query expansion.
+     * Virtual fields allow shortcuts like `my:assigned` that expand to
+     * real schema fields at query execution time.
+     *
+     * @example
+     * virtualFields: {
+     *   my: {
+     *     allowedValues: ['assigned', 'created'] as const,
+     *     resolve: (input, ctx, { fields }) => ({
+     *       type: 'comparison',
+     *       field: fields({ assigned: 'assignee_id', created: 'creator_id' })[input.value],
+     *       operator: '==',
+     *       value: ctx.currentUserId
+     *     })
+     *   }
+     * }
+     */
+    virtualFields?: VirtualFieldsConfig<TSchema, TContext>;
+    /**
+     * Factory function to create query execution context.
+     * Called once per query execution to provide runtime values
+     * for virtual field resolution.
+     *
+     * @example
+     * createContext: async () => ({
+     *   currentUserId: await getCurrentUserId(),
+     *   currentUserTeamIds: await getUserTeamIds()
+     * })
+     */
+    createContext?: () => TContext | Promise<TContext>;
 }
 export interface IQueryExecutor<TResult> {
     execute(): Promise<TResult[]>;
@@ -66,10 +99,10 @@ export type QueryKit<TSchema extends Record<string, object>, TRows extends {
 /**
  * Create a new QueryKit instance
  */
-export declare function createQueryKit<TSchema extends Record<string, object>, TRows extends {
+export declare function createQueryKit<TSchema extends Record<string, object>, TContext extends IQueryContext = IQueryContext, TRows extends {
     [K in keyof TSchema & string]: unknown;
 } = {
     [K in keyof TSchema & string]: unknown;
-}>(options: IQueryKitOptions<TSchema>): QueryKit<TSchema, TRows>;
+}>(options: IQueryKitOptions<TSchema, TContext>): QueryKit<TSchema, TRows>;
 export * from './parser';
 export * from './security';

package/dist/index.js

@@ -33,9 +33,11 @@ Object.defineProperty(exports, "QueryParser", { enumerable: true, get: function
 const sql_1 = require("./translators/sql");
 Object.defineProperty(exports, "SqlTranslator", { enumerable: true, get: function () { return sql_1.SqlTranslator; } });
 const security_1 = require("./security");
+const virtual_fields_1 = require("./virtual-fields");
 // Re-export from modules
 __exportStar(require("./translators"), exports);
 __exportStar(require("./adapters"), exports);
+__exportStar(require("./virtual-fields"), exports);
 /**
  * Create a new QueryBuilder instance
  */
@@ -75,9 +77,8 @@ function createQueryKit(options) {
         query: (table) => {
             return {
                 where: (queryString) => {
-                    // Parse and validate the query
+                    // Parse the query
                     const expressionAst = parser.parse(queryString);
-                    securityValidator.validate(expressionAst, options.schema);
                     // Execution state accumulated via fluent calls
                     let orderByState = {};
                     let limitState;
@@ -96,8 +97,24 @@ function createQueryKit(options) {
                             return executor;
                         },
                         execute: async () => {
+                            // Validate that if virtual fields are configured, createContext must also be provided
+                            if (options.virtualFields && !options.createContext) {
+                                throw new Error('createContext must be provided when virtualFields is configured');
+                            }
+                            // Get context if virtual fields are configured
+                            let context;
+                            if (options.virtualFields && options.createContext) {
+                                context = await options.createContext();
+                            }
+                            // Resolve virtual fields if configured and context is available
+                            let resolvedExpression = expressionAst;
+                            if (options.virtualFields && context) {
+                                resolvedExpression = (0, virtual_fields_1.resolveVirtualFields)(expressionAst, options.virtualFields, context);
+                            }
+                            // Validate the resolved query
+                            securityValidator.validate(resolvedExpression, options.schema);
                             // Delegate to adapter
-                            const results = await options.adapter.execute(table, expressionAst, {
+                            const results = await options.adapter.execute(table, resolvedExpression, {
                                 orderBy: Object.keys(orderByState).length > 0
                                     ? orderByState
                                     : undefined,