@gblikas/querykit 0.3.0 → 0.4.0

package/src/index.ts

@@ -12,6 +12,11 @@ import { QueryParser, IParserOptions } from './parser';
 import { SqlTranslator } from './translators/sql';
 import { ISecurityOptions, QuerySecurityValidator } from './security';
 import { IAdapter, IAdapterOptions } from './adapters';
+import {
+  IQueryContext,
+  VirtualFieldsConfig,
+  resolveVirtualFields
+} from './virtual-fields';
 
 export {
   // Parser exports
@@ -29,6 +34,7 @@ export {
 // Re-export from modules
 export * from './translators';
 export * from './adapters';
+export * from './virtual-fields';
 
 /**
  * Create a new QueryBuilder instance
@@ -53,7 +59,8 @@ export interface IQueryKitOptions<
   TSchema extends Record<string, object> = Record<
     string,
     Record<string, unknown>
-  >
+  >,
+  TContext extends IQueryContext = IQueryContext
 > {
   /**
    * The adapter to use for database connections
@@ -74,6 +81,39 @@ export interface IQueryKitOptions<
    * Options to initialize the provided adapter
    */
   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>;
 }
 
 // Define interfaces for return types
@@ -105,10 +145,11 @@ export type QueryKit<
  */
 export 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> {
   const parser = new QueryParser();
   const securityValidator = new QuerySecurityValidator(options.security);
 
@@ -136,12 +177,8 @@ export function createQueryKit<
     ): IWhereClause<TRows[K]> => {
       return {
         where: (queryString: string): IQueryExecutor<TRows[K]> => {
-          // Parse and validate the query
+          // Parse the query
           const expressionAst = parser.parse(queryString);
-          securityValidator.validate(
-            expressionAst,
-            options.schema as unknown as Record<string, Record<string, unknown>>
-          );
 
           // Execution state accumulated via fluent calls
           let orderByState: Record<string, 'asc' | 'desc'> = {};
@@ -165,10 +202,42 @@ export function createQueryKit<
               return executor;
             },
             execute: async (): Promise<TRows[K][]> => {
+              // 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: TContext | undefined;
+              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 = resolveVirtualFields(
+                  expressionAst,
+                  options.virtualFields,
+                  context
+                );
+              }
+
+              // Validate the resolved query
+              securityValidator.validate(
+                resolvedExpression,
+                options.schema as unknown as Record<
+                  string,
+                  Record<string, unknown>
+                >
+              );
+
               // Delegate to adapter
               const results = await options.adapter.execute(
                 table,
-                expressionAst,
+                resolvedExpression,
                 {
                   orderBy:
                     Object.keys(orderByState).length > 0

package/src/virtual-fields/index.ts

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

package/src/virtual-fields/integration.test.ts

@@ -0,0 +1,338 @@
+/**
+ * Integration test for Virtual Fields functionality
+ * Demonstrates end-to-end usage with QueryKit
+ */
+
+import { createQueryKit } from '../index';
+import { IQueryContext } from '../virtual-fields';
+import { IAdapter, IAdapterOptions } from '../adapters/types';
+import { QueryExpression } from '../parser/types';
+
+// Mock schema for testing
+type MockSchema = {
+  tasks: {
+    id: number;
+    title: string;
+    assignee_id: number;
+    creator_id: number;
+    status: string;
+    priority: number;
+  };
+};
+
+// Mock context for testing
+interface ITaskContext extends IQueryContext {
+  currentUserId: number;
+  currentUserTeamIds: number[];
+}
+
+// Mock adapter for testing
+class MockAdapter implements IAdapter {
+  name = 'mock';
+  private lastExpression?: QueryExpression;
+  private lastTable?: string;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  initialize(_options: IAdapterOptions): void {
+    // Mock initialization
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  canExecute(_expression: QueryExpression): boolean {
+    return true;
+  }
+
+  async execute<T = unknown>(
+    table: string,
+    expression: QueryExpression
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  ): Promise<T[]> {
+    // Store for verification
+    this.lastExpression = expression;
+    this.lastTable = table;
+
+    // Return mock data
+    return [
+      { id: 1, title: 'Task 1', assignee_id: 123 },
+      { id: 2, title: 'Task 2', assignee_id: 123 }
+    ] as T[];
+  }
+
+  getLastExpression(): QueryExpression | undefined {
+    return this.lastExpression;
+  }
+
+  getLastTable(): string | undefined {
+    return this.lastTable;
+  }
+}
+
+describe('Virtual Fields Integration', () => {
+  it('should resolve virtual fields in a complete QueryKit flow', async () => {
+    const mockAdapter = new MockAdapter();
+
+    const qk = createQueryKit<MockSchema, ITaskContext>({
+      adapter: mockAdapter,
+      schema: {
+        tasks: {
+          id: 0,
+          title: '',
+          assignee_id: 0,
+          creator_id: 0,
+          status: '',
+          priority: 0
+        }
+      },
+
+      virtualFields: {
+        my: {
+          allowedValues: ['assigned', 'created'] as const,
+          resolve: (input, ctx, { fields }) => {
+            const fieldMap = fields({
+              assigned: 'assignee_id',
+              created: 'creator_id'
+            });
+            return {
+              type: 'comparison',
+              field: fieldMap[input.value as 'assigned' | 'created'],
+              operator: '==',
+              value: ctx.currentUserId
+            };
+          }
+        }
+      },
+
+      createContext: async () => ({
+        currentUserId: 123,
+        currentUserTeamIds: [1, 2, 3]
+      })
+    });
+
+    // Execute a query with a virtual field
+    const results = await qk.query('tasks').where('my:assigned').execute();
+
+    // Verify the results
+    expect(results).toHaveLength(2);
+    expect(results[0]).toHaveProperty('id', 1);
+
+    // Verify the expression was resolved correctly
+    const lastExpression = mockAdapter.getLastExpression();
+    expect(lastExpression).toBeDefined();
+    expect(lastExpression?.type).toBe('comparison');
+
+    if (lastExpression?.type === 'comparison') {
+      expect(lastExpression.field).toBe('assignee_id');
+      expect(lastExpression.operator).toBe('==');
+      expect(lastExpression.value).toBe(123);
+    }
+  });
+
+  it('should resolve virtual fields combined with regular fields', async () => {
+    const mockAdapter = new MockAdapter();
+
+    const qk = createQueryKit<MockSchema, ITaskContext>({
+      adapter: mockAdapter,
+      schema: {
+        tasks: {
+          id: 0,
+          title: '',
+          assignee_id: 0,
+          creator_id: 0,
+          status: '',
+          priority: 0
+        }
+      },
+
+      virtualFields: {
+        my: {
+          allowedValues: ['assigned'] as const,
+          resolve: (_input, ctx) => ({
+            type: 'comparison',
+            field: 'assignee_id',
+            operator: '==',
+            value: ctx.currentUserId
+          })
+        }
+      },
+
+      createContext: async () => ({
+        currentUserId: 456,
+        currentUserTeamIds: []
+      })
+    });
+
+    // Execute a query with virtual field and regular field
+    await qk.query('tasks').where('my:assigned AND status:active').execute();
+
+    // Verify the expression was resolved correctly
+    const lastExpression = mockAdapter.getLastExpression();
+    expect(lastExpression).toBeDefined();
+    expect(lastExpression?.type).toBe('logical');
+
+    if (lastExpression?.type === 'logical') {
+      expect(lastExpression.operator).toBe('AND');
+
+      // Check left side (virtual field resolved)
+      const left = lastExpression.left;
+      expect(left.type).toBe('comparison');
+      if (left.type === 'comparison') {
+        expect(left.field).toBe('assignee_id');
+        expect(left.value).toBe(456);
+      }
+
+      // Check right side (regular field unchanged)
+      const right = lastExpression.right;
+      expect(right?.type).toBe('comparison');
+      if (right?.type === 'comparison') {
+        expect(right.field).toBe('status');
+        expect(right.value).toBe('active');
+      }
+    }
+  });
+
+  it('should work without virtual fields configured', async () => {
+    const mockAdapter = new MockAdapter();
+
+    const qk = createQueryKit<MockSchema>({
+      adapter: mockAdapter,
+      schema: {
+        tasks: {
+          id: 0,
+          title: '',
+          assignee_id: 0,
+          creator_id: 0,
+          status: '',
+          priority: 0
+        }
+      }
+      // No virtualFields or createContext
+    });
+
+    // Execute a regular query
+    const results = await qk.query('tasks').where('status:active').execute();
+
+    expect(results).toHaveLength(2);
+
+    // Verify the expression was not modified
+    const lastExpression = mockAdapter.getLastExpression();
+    expect(lastExpression?.type).toBe('comparison');
+    if (lastExpression?.type === 'comparison') {
+      expect(lastExpression.field).toBe('status');
+      expect(lastExpression.value).toBe('active');
+    }
+  });
+
+  it('should support multiple virtual fields in the same query', async () => {
+    const mockAdapter = new MockAdapter();
+
+    const qk = createQueryKit<MockSchema, ITaskContext>({
+      adapter: mockAdapter,
+      schema: {
+        tasks: {
+          id: 0,
+          title: '',
+          assignee_id: 0,
+          creator_id: 0,
+          status: '',
+          priority: 0
+        }
+      },
+
+      virtualFields: {
+        my: {
+          allowedValues: ['assigned', 'created'] as const,
+          resolve: (input, ctx, { fields }) => {
+            const fieldMap = fields({
+              assigned: 'assignee_id',
+              created: 'creator_id'
+            });
+            return {
+              type: 'comparison',
+              field: fieldMap[input.value as 'assigned' | 'created'],
+              operator: '==',
+              value: ctx.currentUserId
+            };
+          }
+        }
+      },
+
+      createContext: async () => ({
+        currentUserId: 789,
+        currentUserTeamIds: []
+      })
+    });
+
+    // Execute a query with multiple uses of the same virtual field
+    await qk.query('tasks').where('my:assigned OR my:created').execute();
+
+    // Verify both were resolved
+    const lastExpression = mockAdapter.getLastExpression();
+    expect(lastExpression?.type).toBe('logical');
+
+    if (lastExpression?.type === 'logical') {
+      expect(lastExpression.operator).toBe('OR');
+
+      // Check left side (my:assigned)
+      const left = lastExpression.left;
+      expect(left.type).toBe('comparison');
+      if (left.type === 'comparison') {
+        expect(left.field).toBe('assignee_id');
+        expect(left.value).toBe(789);
+      }
+
+      // Check right side (my:created)
+      const right = lastExpression.right;
+      expect(right?.type).toBe('comparison');
+      if (right?.type === 'comparison') {
+        expect(right.field).toBe('creator_id');
+        expect(right.value).toBe(789);
+      }
+    }
+  });
+
+  it('should use fluent API methods after virtual field resolution', async () => {
+    const mockAdapter = new MockAdapter();
+
+    const qk = createQueryKit<MockSchema, ITaskContext>({
+      adapter: mockAdapter,
+      schema: {
+        tasks: {
+          id: 0,
+          title: '',
+          assignee_id: 0,
+          creator_id: 0,
+          status: '',
+          priority: 0
+        }
+      },
+
+      virtualFields: {
+        my: {
+          allowedValues: ['assigned'] as const,
+          resolve: (_input, ctx) => ({
+            type: 'comparison',
+            field: 'assignee_id',
+            operator: '==',
+            value: ctx.currentUserId
+          })
+        }
+      },
+
+      createContext: async () => ({
+        currentUserId: 111,
+        currentUserTeamIds: []
+      })
+    });
+
+    // Execute a query with virtual field and fluent API methods
+    const results = await qk
+      .query('tasks')
+      .where('my:assigned')
+      .orderBy('priority', 'desc')
+      .limit(5)
+      .execute();
+
+    expect(results).toBeDefined();
+    expect(mockAdapter.getLastTable()).toBe('tasks');
+  });
+});

package/src/virtual-fields/resolver.ts

@@ -0,0 +1,165 @@
+/**
+ * Virtual field resolution logic
+ */
+
+import {
+  QueryExpression,
+  IComparisonExpression,
+  ILogicalExpression
+} from '../parser/types';
+import { QueryParseError } from '../parser/parser';
+import {
+  IQueryContext,
+  IVirtualFieldInput,
+  VirtualFieldsConfig,
+  IResolverHelpers,
+  SchemaFieldMap
+} 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 function resolveVirtualFields<
+  TSchema extends Record<string, object>,
+  TContext extends IQueryContext
+>(
+  expr: QueryExpression,
+  virtualFields: VirtualFieldsConfig<TSchema, TContext>,
+  context: TContext
+): QueryExpression {
+  // 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<
+  TSchema extends Record<string, object>,
+  TContext extends IQueryContext
+>(
+  expr: IComparisonExpression,
+  virtualFields: VirtualFieldsConfig<TSchema, TContext>,
+  context: TContext
+): QueryExpression {
+  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 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 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 QueryParseError(
+      `Virtual field "${fieldName}" does not allow comparison operators. Only equality (":") is permitted.`
+    );
+  }
+
+  // Create the input for the resolver
+  const input: IVirtualFieldInput & { value: string } = {
+    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: IResolverHelpers<TSchema> = {
+    fields: <TValues extends string>(
+      mapping: SchemaFieldMap<TValues, TSchema>
+    ): SchemaFieldMap<TValues, TSchema> => {
+      // Validate that all keys in the mapping are in the virtual field's allowed values
+      const mappingKeys = Object.keys(mapping);
+      const allowedValues = virtualFieldDef.allowedValues as readonly string[];
+
+      for (const key of mappingKeys) {
+        if (!allowedValues.includes(key)) {
+          throw new 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 as QueryExpression;
+}
+
+/**
+ * Resolve a logical expression.
+ * Recursively resolve both left and right sides.
+ */
+function resolveLogicalExpression<
+  TSchema extends Record<string, object>,
+  TContext extends IQueryContext
+>(
+  expr: ILogicalExpression,
+  virtualFields: VirtualFieldsConfig<TSchema, TContext>,
+  context: TContext
+): ILogicalExpression {
+  return {
+    type: 'logical',
+    operator: expr.operator,
+    left: resolveVirtualFields(expr.left, virtualFields, context),
+    right: expr.right
+      ? resolveVirtualFields(expr.right, virtualFields, context)
+      : undefined
+  };
+}