@gblikas/querykit 0.3.0 → 0.4.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,352 @@ 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();
+```
+
 ## Roadmap
 
 ### Core Parsing Engine and DSL
@@ -459,6 +805,7 @@ function SearchBar({ value, onChange }) {
 - [x] Support for complex nested expressions
 - [ ] 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,

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

@@ -0,0 +1,5 @@
+/**
+ * Virtual Fields module exports
+ */
+export * from './types';
+export * from './resolver';

package/dist/virtual-fields/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Virtual Fields module exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./resolver"), exports);

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

@@ -0,0 +1,17 @@
+/**
+ * Virtual field resolution logic
+ */
+import { QueryExpression } from '../parser/types';
+import { IQueryContext, VirtualFieldsConfig } from './types';
+/**
+ * Resolve virtual fields in a query expression.
+ * Recursively walks the AST and replaces virtual field references with
+ * their resolved expressions based on the provided context.
+ *
+ * @param expr - The query expression to resolve
+ * @param virtualFields - Virtual field configuration
+ * @param context - Runtime context for resolution
+ * @returns The resolved query expression
+ * @throws {QueryParseError} If a virtual field value is invalid or operator is not allowed
+ */
+export declare function resolveVirtualFields<TSchema extends Record<string, object>, TContext extends IQueryContext>(expr: QueryExpression, virtualFields: VirtualFieldsConfig<TSchema, TContext>, context: TContext): QueryExpression;

package/dist/virtual-fields/resolver.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Virtual field resolution logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVirtualFields = resolveVirtualFields;
+const parser_1 = require("../parser/parser");
+/**
+ * Resolve virtual fields in a query expression.
+ * Recursively walks the AST and replaces virtual field references with
+ * their resolved expressions based on the provided context.
+ *
+ * @param expr - The query expression to resolve
+ * @param virtualFields - Virtual field configuration
+ * @param context - Runtime context for resolution
+ * @returns The resolved query expression
+ * @throws {QueryParseError} If a virtual field value is invalid or operator is not allowed
+ */
+function resolveVirtualFields(expr, virtualFields, context) {
+    // Base case: comparison expression
+    if (expr.type === 'comparison') {
+        return resolveComparisonExpression(expr, virtualFields, context);
+    }
+    // Recursive case: logical expression
+    if (expr.type === 'logical') {
+        return resolveLogicalExpression(expr, virtualFields, context);
+    }
+    // Unknown expression type, return as-is
+    return expr;
+}
+/**
+ * Resolve a comparison expression.
+ * If the field is a virtual field, resolve it using the configuration.
+ * Otherwise, return the expression unchanged.
+ */
+function resolveComparisonExpression(expr, virtualFields, context) {
+    const fieldName = expr.field;
+    const virtualFieldDef = virtualFields[fieldName];
+    // Not a virtual field, return as-is
+    if (!virtualFieldDef) {
+        return expr;
+    }
+    // Validate the value is a string (virtual fields require string values)
+    if (typeof expr.value !== 'string') {
+        const valueType = Array.isArray(expr.value)
+            ? `array (${JSON.stringify(expr.value)})`
+            : typeof expr.value === 'object'
+                ? `object (${JSON.stringify(expr.value)})`
+                : typeof expr.value;
+        throw new parser_1.QueryParseError(`Virtual field "${fieldName}" requires a string value, got ${valueType}`);
+    }
+    const value = expr.value;
+    // Validate the value is in allowedValues
+    if (!virtualFieldDef.allowedValues.includes(value)) {
+        const allowedValuesStr = virtualFieldDef.allowedValues
+            .map(v => `"${v}"`)
+            .join(', ');
+        throw new parser_1.QueryParseError(`Invalid value "${value}" for virtual field "${fieldName}". Allowed values: ${allowedValuesStr}`);
+    }
+    // Validate operator usage
+    const allowOperators = virtualFieldDef.allowOperators ?? false;
+    if (!allowOperators && expr.operator !== '==') {
+        throw new parser_1.QueryParseError(`Virtual field "${fieldName}" does not allow comparison operators. Only equality (":") is permitted.`);
+    }
+    // Create the input for the resolver
+    const input = {
+        field: fieldName,
+        operator: expr.operator,
+        value: value
+    };
+    // Create the helpers object with type-safe fields() helper
+    // The fields() method is generic at the method level, allowing TypeScript to
+    // infer TValues from the mapping object at call-time without needing type assertions
+    const helpers = {
+        fields: (mapping) => {
+            // Validate that all keys in the mapping are in the virtual field's allowed values
+            const mappingKeys = Object.keys(mapping);
+            const allowedValues = virtualFieldDef.allowedValues;
+            for (const key of mappingKeys) {
+                if (!allowedValues.includes(key)) {
+                    throw new parser_1.QueryParseError(`Invalid key "${key}" in field mapping for virtual field "${fieldName}". ` +
+                        `Allowed keys are: ${allowedValues.map(v => `"${v}"`).join(', ')}`);
+                }
+            }
+            // Runtime: this is just an identity function
+            // Compile-time: TypeScript validates the mapping structure
+            return mapping;
+        }
+    };
+    // Resolve the virtual field - no type assertions needed!
+    const resolved = virtualFieldDef.resolve(input, context, helpers);
+    return resolved;
+}
+/**
+ * Resolve a logical expression.
+ * Recursively resolve both left and right sides.
+ */
+function resolveLogicalExpression(expr, virtualFields, context) {
+    return {
+        type: 'logical',
+        operator: expr.operator,
+        left: resolveVirtualFields(expr.left, virtualFields, context),
+        right: expr.right
+            ? resolveVirtualFields(expr.right, virtualFields, context)
+            : undefined
+    };
+}