@gblikas/querykit 0.3.0 → 0.5.0

package/src/virtual-fields/resolver.ts

@@ -0,0 +1,170 @@
+/**
+ * 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);
+  }
+
+  // Pass through raw expressions
+  if (expr.type === 'raw') {
+    return expr;
+  }
+
+  // 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,223 @@
+/**
+ * Type definitions for Virtual Fields support
+ */
+
+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.
+ */
+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, logical expression with typed fields, or a raw SQL expression.
+ */
+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.
+ */
+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>;
+};

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

@@ -0,0 +1,182 @@
+/**
+ * End-to-end integration test demonstrating the user's example from the issue
+ */
+
+import { sql } from 'drizzle-orm';
+import type { SQL } from 'drizzle-orm';
+import { jsonbContains, dateWithinDays } from '../virtual-fields';
+import { QueryParser } from '../parser';
+import { resolveVirtualFields } from '../virtual-fields/resolver';
+import { IQueryContext, VirtualFieldsConfig } from '../virtual-fields/types';
+import { DrizzleTranslator } from '../translators/drizzle';
+
+// Mock schema similar to the user's example
+type UserSchema = {
+  my_table: {
+    id: number;
+    title: string;
+    description: string;
+    created_at: Date;
+    assigned_to: string[];
+    status: string;
+  };
+};
+
+interface IMyContext extends IQueryContext {
+  currentUserId: string;
+}
+
+describe('Raw SQL Expression - User Example Integration', () => {
+  it('should parse and resolve my:assigned JSONB query from user example', () => {
+    const parser = new QueryParser();
+    const translator = new DrizzleTranslator();
+
+    const virtualFields: VirtualFieldsConfig<UserSchema, IMyContext> = {
+      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}`);
+        }
+      }
+    };
+
+    const context: IMyContext = { currentUserId: 'user123' };
+
+    // Parse the query
+    const expr = parser.parse('my:assigned');
+    expect(expr.type).toBe('comparison');
+
+    // Resolve virtual fields
+    const resolved = resolveVirtualFields(expr, virtualFields, context);
+    expect(resolved.type).toBe('raw');
+
+    // Translate to SQL
+    const result = translator.translate(resolved);
+    expect(result).toBeDefined();
+
+    // Verify SQL contains expected elements
+    const sqlString = JSON.stringify(result);
+    expect(sqlString).toContain('assigned_to');
+    expect(sqlString).toContain('user123');
+  });
+
+  it('should parse and resolve priority:high computed field from user example', () => {
+    const parser = new QueryParser();
+    const translator = new DrizzleTranslator();
+
+    const virtualFields: VirtualFieldsConfig<UserSchema, IMyContext> = {
+      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);
+        }
+      }
+    };
+
+    const context: IMyContext = { currentUserId: 'user123' };
+
+    // Parse the query
+    const expr = parser.parse('priority:high');
+    expect(expr.type).toBe('comparison');
+
+    // Resolve virtual fields
+    const resolved = resolveVirtualFields(expr, virtualFields, context);
+    expect(resolved.type).toBe('raw');
+
+    // Translate to SQL
+    const result = translator.translate(resolved);
+    expect(result).toBeDefined();
+
+    // Verify SQL contains expected elements
+    const sqlString = JSON.stringify(result);
+    expect(sqlString).toContain('created_at');
+    expect(sqlString).toContain('1');
+  });
+
+  it('should handle combined query: my:assigned AND priority:high AND status:active', () => {
+    const parser = new QueryParser();
+    const translator = new DrizzleTranslator();
+
+    const virtualFields: VirtualFieldsConfig<UserSchema, IMyContext> = {
+      my: {
+        allowedValues: ['assigned'] as const,
+        resolve: (input, ctx) => jsonbContains('assigned_to', ctx.currentUserId)
+      },
+      priority: {
+        allowedValues: ['high', 'medium', 'low'] as const,
+        resolve: input => {
+          const days = { high: 1, medium: 7, low: 30 }[
+            input.value as 'high' | 'medium' | 'low'
+          ];
+          return dateWithinDays('created_at', days);
+        }
+      }
+    };
+
+    const context: IMyContext = { currentUserId: 'user123' };
+
+    // Parse the combined query
+    const expr = parser.parse(
+      'my:assigned AND priority:high AND status:active'
+    );
+    expect(expr.type).toBe('logical');
+
+    // Resolve virtual fields
+    const resolved = resolveVirtualFields(expr, virtualFields, context);
+    expect(resolved.type).toBe('logical');
+
+    // Translate to SQL
+    const result = translator.translate(resolved);
+    expect(result).toBeDefined();
+
+    // Verify SQL contains all expected elements
+    const sqlString = JSON.stringify(result);
+    expect(sqlString).toContain('assigned_to');
+    expect(sqlString).toContain('created_at');
+    expect(sqlString).toContain('status');
+    expect(sqlString).toContain('AND');
+  });
+
+  it('should support custom raw SQL as shown in user example', () => {
+    const parser = new QueryParser();
+    const translator = new DrizzleTranslator();
+
+    const virtualFields: VirtualFieldsConfig<UserSchema, IMyContext> = {
+      custom: {
+        allowedValues: ['active'] as const,
+        resolve: (_input, ctx) => ({
+          type: 'raw',
+          toSql: (): SQL =>
+            sql`status = 'active' AND owner_id = ${ctx.currentUserId}`
+        })
+      }
+    };
+
+    const context: IMyContext = { currentUserId: 'user123' };
+
+    // Parse the query
+    const expr = parser.parse('custom:active');
+    expect(expr.type).toBe('comparison');
+
+    // Resolve virtual fields
+    const resolved = resolveVirtualFields(expr, virtualFields, context);
+    expect(resolved.type).toBe('raw');
+
+    // Translate to SQL
+    const result = translator.translate(resolved);
+    expect(result).toBeDefined();
+
+    // Verify SQL contains expected elements
+    const sqlString = JSON.stringify(result);
+    expect(sqlString).toContain('status');
+    expect(sqlString).toContain('active');
+    expect(sqlString).toContain('user123');
+  });
+});