@gblikas/querykit 0.2.0 → 0.4.0

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
+  };
+}

package/src/virtual-fields/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Type definitions for Virtual Fields support
+ */
+
+import {
+  QueryExpression,
+  IComparisonExpression,
+  ComparisonOperator
+} from '../parser/types';
+
+/**
+ * Base interface for query context.
+ * Users can extend this interface with their own context properties.
+ */
+export interface IQueryContext {
+  [key: string]: unknown;
+}
+
+/**
+ * Input provided to a virtual field resolver.
+ * Contains the parsed field, operator, and value from the query.
+ */
+export interface IVirtualFieldInput {
+  /**
+   * The virtual field name (e.g., "my")
+   */
+  field: string;
+
+  /**
+   * The comparison operator used (e.g., ":", ">", "<", etc.)
+   * Maps to ComparisonOperator type
+   */
+  operator: string;
+
+  /**
+   * The value provided in the query
+   */
+  value: string;
+}
+
+/**
+ * Helper type to filter out index signatures from a type
+ */
+type KnownKeys<T> = {
+  [K in keyof T]: string extends K ? never : number extends K ? never : K;
+} extends { [_ in keyof T]: infer U }
+  ? U
+  : never;
+
+/**
+ * Utility type to extract all field names from a schema.
+ * Recursively extracts field names from nested tables, excluding index signatures.
+ */
+export type AllSchemaFields<TSchema extends Record<string, object>> = {
+  [K in KnownKeys<TSchema>]: TSchema[K] extends { [key: string]: unknown }
+    ? keyof TSchema[K] & string
+    : never;
+}[KnownKeys<TSchema>];
+
+/**
+ * Type-safe mapping from allowed values to schema fields.
+ * Ensures all keys in TKeys map to valid fields in the schema.
+ */
+export type SchemaFieldMap<
+  TKeys extends string,
+  TSchema extends Record<string, object>
+> = Record<TKeys, AllSchemaFields<TSchema>>;
+
+/**
+ * Helper functions provided to virtual field resolvers.
+ *
+ * Note: The fields() method is generic at the method level, not the interface level.
+ * This allows TypeScript to infer TValues from the mapping object passed at call-time,
+ * eliminating the need for type assertions while maintaining full type safety.
+ */
+export interface IResolverHelpers<TSchema extends Record<string, object>> {
+  /**
+   * Type-safe field mapping helper.
+   * Ensures all allowedValues are mapped to valid schema fields.
+   *
+   * The generic TValues parameter is inferred from the keys in the mapping object,
+   * providing full type safety without requiring explicit type annotations.
+   *
+   * @example
+   * const fieldMap = fields({
+   *   assigned: 'assignee_id',
+   *   created: 'creator_id'
+   * });
+   * // TypeScript infers TValues as 'assigned' | 'created'
+   */
+  fields: <TValues extends string>(
+    mapping: SchemaFieldMap<TValues, TSchema>
+  ) => SchemaFieldMap<TValues, TSchema>;
+}
+
+/**
+ * Schema-constrained comparison expression.
+ * Ensures field names are valid schema fields.
+ */
+export interface ITypedComparisonExpression<
+  TFields extends string = string
+> extends Omit<IComparisonExpression, 'field'> {
+  type: 'comparison';
+  field: TFields;
+  operator: ComparisonOperator;
+  value:
+    | string
+    | number
+    | boolean
+    | null
+    | Array<string | number | boolean | null>;
+}
+
+/**
+ * Schema-constrained query expression.
+ * Can be a comparison or logical expression with typed fields.
+ */
+export type ITypedQueryExpression<TFields extends string = string> =
+  | ITypedComparisonExpression<TFields>
+  | QueryExpression;
+
+/**
+ * Definition for a virtual field.
+ * Configures how a virtual field should be resolved at query execution time.
+ */
+export interface IVirtualFieldDefinition<
+  TSchema extends Record<string, object>,
+  TContext extends IQueryContext = IQueryContext,
+  TValues extends string = string
+> {
+  /**
+   * Allowed values for this virtual field.
+   * Use `as const` for type inference.
+   *
+   * @example
+   * allowedValues: ['assigned', 'created', 'watching'] as const
+   */
+  allowedValues: readonly TValues[];
+
+  /**
+   * Whether to allow comparison operators beyond `:` (equality).
+   * If false, only `:` is allowed. If true, `:>`, `:<`, etc. are permitted.
+   *
+   * @default false
+   */
+  allowOperators?: boolean;
+
+  /**
+   * Resolve the virtual field to a real query expression.
+   * The `fields` helper ensures type-safe field references.
+   *
+   * @param input - The parsed virtual field input (field, operator, value)
+   * @param context - Runtime context provided by createContext()
+   * @param helpers - Helper functions including type-safe fields() helper
+   * @returns A query expression that replaces the virtual field
+   *
+   * @example
+   * resolve: (input, ctx, { fields }) => {
+   *   const fieldMap = fields({
+   *     assigned: 'assignee_id',
+   *     created: 'creator_id'
+   *   });
+   *   return {
+   *     type: 'comparison',
+   *     field: fieldMap[input.value],
+   *     operator: '==',
+   *     value: ctx.currentUserId
+   *   };
+   * }
+   */
+  resolve: (
+    input: IVirtualFieldInput & { value: TValues },
+    context: TContext,
+    helpers: IResolverHelpers<TSchema>
+  ) => ITypedQueryExpression<AllSchemaFields<TSchema>>;
+
+  /**
+   * Human-readable description (for autocomplete UI).
+   * Optional metadata for documentation and tooling.
+   */
+  description?: string;
+
+  /**
+   * Descriptions for each allowed value (for autocomplete UI).
+   * Optional metadata for documentation and tooling.
+   */
+  valueDescriptions?: Partial<Record<TValues, string>>;
+}
+
+/**
+ * Configuration for all virtual fields in a QueryKit instance.
+ *
+ * Note: Uses a flexible type for the values to allow each virtual field definition
+ * to have its own specific TValues type (e.g., 'assigned' | 'created' for one field,
+ * 'high' | 'low' for another). The IResolverHelpers.fields() method infers these
+ * types at call-time, maintaining type safety without needing explicit annotations.
+ */
+export type VirtualFieldsConfig<
+  TSchema extends Record<string, object> = Record<string, object>,
+  TContext extends IQueryContext = IQueryContext
+> = {
+  [fieldName: string]: IVirtualFieldDefinition<TSchema, TContext, string>;
+};