@gblikas/querykit 0.3.0 → 0.5.0

package/dist/parser/types.d.ts

@@ -31,10 +31,26 @@ export interface ILogicalExpression {
     left: QueryExpression;
     right?: QueryExpression;
 }
+/**
+ * Represents a raw SQL expression node in the AST.
+ * Used by virtual fields to inject database-specific SQL operations.
+ */
+export interface IRawSqlExpression {
+    type: 'raw';
+    /**
+     * Function that generates the raw SQL for the adapter.
+     * For Drizzle, this should return a SQL template result.
+     */
+    toSql: (context: {
+        adapter: string;
+        tableName: string;
+        schema: Record<string, unknown>;
+    }) => unknown;
+}
 /**
  * Represents any valid query expression node
  */
-export type QueryExpression = IComparisonExpression | ILogicalExpression;
+export type QueryExpression = IComparisonExpression | ILogicalExpression | IRawSqlExpression;
 /**
  * Configuration options for the parser
  */

package/dist/security/validator.js

@@ -219,13 +219,14 @@ class QuerySecurityValidator {
                     `Found "${field}" - use a simple field name without dots instead.`);
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             // Recursively validate logical expressions
             this.validateNoDotNotation(expression.left);
             if (expression.right) {
                 this.validateNoDotNotation(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own field access
     }
     /**
      * Validate that query values are not in the denied values list for their field
@@ -263,13 +264,14 @@ class QuerySecurityValidator {
                 }
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             // Recursively validate logical expressions
             this.validateDenyValues(expression.left);
             if (expression.right) {
                 this.validateDenyValues(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own values
     }
     /**
      * Check if a value is in the denied values list
@@ -317,6 +319,7 @@ class QuerySecurityValidator {
                 this.validateQueryDepth(expression.right, currentDepth + 1);
             }
         }
+        // Raw and comparison expressions don't add depth
     }
     /**
      * Validate that the number of clauses does not exceed the maximum
@@ -341,6 +344,9 @@ class QuerySecurityValidator {
         if (expression.type === 'comparison') {
             return 1;
         }
+        if (expression.type === 'raw') {
+            return 1; // Raw expressions count as one clause
+        }
         let count = 0;
         count += this.countClauses(expression.left);
         if (expression.right) {
@@ -387,12 +393,13 @@ class QuerySecurityValidator {
                 throw new QuerySecurityError('Object values are not allowed');
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             this.validateValueLengths(expression.left);
             if (expression.right) {
                 this.validateValueLengths(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own values
     }
     /**
      * Sanitize wildcard patterns in LIKE queries to prevent regex DoS
@@ -423,12 +430,13 @@ class QuerySecurityValidator {
                 expression.value = sanitized;
             }
         }
-        else {
+        else if (expression.type === 'logical') {
             this.sanitizeWildcards(expression.left);
             if (expression.right) {
                 this.sanitizeWildcards(expression.right);
             }
         }
+        // Raw expressions are skipped - they handle their own wildcards
     }
     /**
      * Collect all field names used in the query
@@ -441,12 +449,13 @@ class QuerySecurityValidator {
         if (expression.type === 'comparison') {
             fieldSet.add(expression.field);
         }
-        else {
+        else if (expression.type === 'logical') {
             this.collectFields(expression.left, fieldSet);
             if (expression.right) {
                 this.collectFields(expression.right, fieldSet);
             }
         }
+        // Raw expressions don't expose field names for collection
     }
 }
 exports.QuerySecurityValidator = QuerySecurityValidator;

package/dist/translators/drizzle/index.js

@@ -64,6 +64,17 @@ class DrizzleTranslator {
                 return this.translateComparisonExpression(expression);
             case 'logical':
                 return this.translateLogicalExpression(expression);
+            case 'raw': {
+                const rawExpr = expression;
+                return rawExpr.toSql({
+                    adapter: 'drizzle',
+                    // tableName is empty because raw SQL expressions in virtual fields
+                    // are resolved before translation and don't need table context at this stage.
+                    // The schema is provided for field lookups if needed.
+                    tableName: '',
+                    schema: this.options.schema
+                });
+            }
             default:
                 throw new DrizzleTranslationError(`Unsupported expression type: ${expression.type}`);
         }

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

@@ -0,0 +1,32 @@
+/**
+ * Helper utilities for creating raw SQL expressions in virtual fields
+ */
+import { IRawSqlExpression } from '../parser/types';
+/**
+ * Create a JSONB array contains expression (PostgreSQL).
+ * Checks if the JSONB array field contains the given value.
+ *
+ * @param field - The JSONB field name (e.g., 'assigned_to')
+ * @param value - The value to check for in the array
+ * @returns A raw SQL expression for JSONB contains check
+ *
+ * @example
+ * // Check if assignedTo contains the current user ID
+ * jsonbContains('assigned_to', ctx.currentUserId)
+ * // Generates: assigned_to @> '["user123"]'::jsonb
+ */
+export declare function jsonbContains(field: string, value: unknown): IRawSqlExpression;
+/**
+ * Create a date range expression.
+ * Checks if a timestamp field is within the specified number of days from now.
+ *
+ * @param field - The timestamp field name (e.g., 'created_at')
+ * @param days - Number of days from now (must be a positive finite number)
+ * @returns A raw SQL expression for date range check
+ *
+ * @example
+ * // Check if created within last day
+ * dateWithinDays('created_at', 1)
+ * // Generates: created_at >= NOW() - INTERVAL '1 days'
+ */
+export declare function dateWithinDays(field: string, days: number): IRawSqlExpression;

package/dist/virtual-fields/helpers.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Helper utilities for creating raw SQL expressions in virtual fields
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonbContains = jsonbContains;
+exports.dateWithinDays = dateWithinDays;
+const drizzle_orm_1 = require("drizzle-orm");
+/**
+ * Validates field name to prevent SQL injection.
+ * Only allows alphanumeric characters, dots, and underscores.
+ * @private
+ */
+function validateFieldName(field) {
+    if (!/^[a-zA-Z][a-zA-Z0-9._]*$/.test(field)) {
+        throw new Error(`Invalid field name: ${field}`);
+    }
+    if (field.length > 64) {
+        throw new Error(`Field name too long: ${field}`);
+    }
+}
+/**
+ * Create a JSONB array contains expression (PostgreSQL).
+ * Checks if the JSONB array field contains the given value.
+ *
+ * @param field - The JSONB field name (e.g., 'assigned_to')
+ * @param value - The value to check for in the array
+ * @returns A raw SQL expression for JSONB contains check
+ *
+ * @example
+ * // Check if assignedTo contains the current user ID
+ * jsonbContains('assigned_to', ctx.currentUserId)
+ * // Generates: assigned_to @> '["user123"]'::jsonb
+ */
+function jsonbContains(field, value) {
+    validateFieldName(field);
+    return {
+        type: 'raw',
+        toSql: () => (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(field)} @> ${drizzle_orm_1.sql.raw("'" + JSON.stringify(Array.isArray(value) ? value : [value]).replace(/'/g, "''") + "'::jsonb")}`
+    };
+}
+/**
+ * Validates days parameter to ensure it's a positive finite number.
+ * @private
+ */
+function validateDaysParameter(days) {
+    if (!Number.isFinite(days)) {
+        throw new Error(`Invalid days parameter: ${days}. Must be a finite number.`);
+    }
+    if (days <= 0) {
+        throw new Error(`Invalid days parameter: ${days}. Must be a positive number.`);
+    }
+}
+/**
+ * Create a date range expression.
+ * Checks if a timestamp field is within the specified number of days from now.
+ *
+ * @param field - The timestamp field name (e.g., 'created_at')
+ * @param days - Number of days from now (must be a positive finite number)
+ * @returns A raw SQL expression for date range check
+ *
+ * @example
+ * // Check if created within last day
+ * dateWithinDays('created_at', 1)
+ * // Generates: created_at >= NOW() - INTERVAL '1 days'
+ */
+function dateWithinDays(field, days) {
+    validateFieldName(field);
+    validateDaysParameter(days);
+    return {
+        type: 'raw',
+        toSql: () => (0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(field)} >= NOW() - INTERVAL '${drizzle_orm_1.sql.raw(days.toString())} days'`
+    };
+}

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

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

package/dist/virtual-fields/index.js

@@ -0,0 +1,22 @@
+"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);
+__exportStar(require("./helpers"), 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,111 @@
+"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);
+    }
+    // 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(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
+    };
+}

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

@@ -0,0 +1,177 @@
+/**
+ * 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>;
+};
+export {};

package/dist/virtual-fields/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Virtual Fields support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });