@gblikas/querykit 0.3.0 → 0.5.0

package/examples/qk-next/app/page.tsx

@@ -4,7 +4,7 @@ import { useEffect, useMemo, useState, useCallback, useRef, JSX } from 'react';
 import { drizzle } from 'drizzle-orm/pglite';
 import { usePGlite } from '@electric-sql/pglite-react';
 import { pgTable, serial, text, integer, boolean } from 'drizzle-orm/pg-core';
-import { InferSelectModel, sql, SQLWrapper } from 'drizzle-orm';
+import { InferSelectModel, sql } from 'drizzle-orm';
 import { Card, CardContent } from '@/components/ui/card';
 import {
   Table,
@@ -17,9 +17,9 @@ import {
 import {
   QueryParser,
   SqlTranslator,
-  DrizzleAdapter,
-  createQueryKit,
-  IDrizzleAdapterOptions
+  createDrizzleQueryKit,
+  ISecurityOptions,
+  IQueryStructure
 } from '@gblikas/querykit';
 import { Copy, Check, Search, ChevronUp, FileCode, X } from 'lucide-react';
 import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
@@ -75,7 +75,7 @@ const highlightQueryHtml = (input: string): string => {
     .join('');
 };
 
-const INSTALL_SNIPPET = `pnpm i @gblikas/querykit drizzle-orm`;
+const INSTALL_SNIPPET = `pnpm i @gblikas/querykit@0.3.0 drizzle-orm`;
 
 const SCHEMA_SNIPPET = `// schema.ts
 import { serial, text, pgTable } from 'drizzle-orm/pg-core';
@@ -91,25 +91,30 @@ export type SelectUser = InferSelectModel<typeof users>;
 `;
 
 const QUERYKIT_SNIPPET = `// querykit.ts
-import { createQueryKit } from 'querykit';
-import { drizzleAdapter } from 'querykit/adapters/drizzle';
+import { createDrizzleQueryKit } from '@gblikas/querykit';
+import { db } from './db';
 import { users } from './schema';
 
-export const qk = createQueryKit({
-  adapter: drizzleAdapter,
+// New 0.3.0: createDrizzleQueryKit combines adapter & security config
+export const qk = createDrizzleQueryKit({
+  db,
   schema: { users },
+  security: {
+    maxQueryDepth: 5,
+    maxClauseCount: 20,
+    sanitizeWildcards: true,
+  },
 });
 
 // example.ts
 import { qk } from './querykit';
 
-const query = qk
+const results = await qk
   .query('users')
   .where('status:done AND name:"John *"')
   .orderBy('name', 'asc')
-  .limit(10);
-
-const results = await query.execute();
+  .limit(10)
+  .execute();
 `;
 
 const tasks = pgTable('tasks', {
@@ -137,6 +142,9 @@ export default function Home(): JSX.Element {
   const [, setLastExecutionMs] = useState<number | null>(null);
   const [rowsScanned, setRowsScanned] = useState<number | null>(null);
   const [operatorsUsed, setOperatorsUsed] = useState<string[]>([]);
+  const [queryStructure, setQueryStructure] = useState<IQueryStructure | null>(
+    null
+  );
   const [usedQueryKit, setUsedQueryKit] = useState<boolean>(false);
   const [, setExplainJson] = useState<string | null>(null);
   const [, setPlanningTimeMs] = useState<number | null>(null);
@@ -314,23 +322,33 @@ export default function Home(): JSX.Element {
     void seed();
   }, [db]);
 
+  // Security configuration for QueryKit 0.3.0
+  const securityOptions: ISecurityOptions = useMemo(
+    () => ({
+      maxQueryDepth: 5,
+      maxClauseCount: 20,
+      allowDotNotation: false, // Disable dot notation for simple flat schema
+      sanitizeWildcards: true
+    }),
+    []
+  );
+
   const parser = useMemo(() => new QueryParser(), []);
   const sqlTranslator = useMemo(
     () => new SqlTranslator({ useParameters: false }),
     []
   );
-  const qk = useMemo(() => {
-    const adapter = new DrizzleAdapter();
-    const iDrizzleAdataperOptions: IDrizzleAdapterOptions = {
-      db: db as unknown as PGlite,
-      schema: { tasks } as unknown as Record<string, Record<string, SQLWrapper>>
-    };
-    adapter.initialize(iDrizzleAdataperOptions);
-    return createQueryKit({
-      adapter,
-      schema: { tasks } as unknown as Record<string, Record<string, SQLWrapper>>
-    });
-  }, [db]);
+
+  // Use the new createDrizzleQueryKit factory (0.3.0 feature)
+  const qk = useMemo(
+    () =>
+      createDrizzleQueryKit({
+        db,
+        schema: { tasks },
+        security: securityOptions
+      }),
+    [db, securityOptions]
+  );
 
   // Note: Execute via QueryKit fluent API (Drizzle adapter under the hood)
 
@@ -346,6 +364,7 @@ export default function Home(): JSX.Element {
       setIsInputFocused(false);
       inputRef.current?.blur();
       setOperatorsUsed([]);
+      setQueryStructure(null);
       setExplainJson(null);
       setPlanningTimeMs(null);
       setExecutionTimeMs(null);
@@ -407,49 +426,77 @@ export default function Home(): JSX.Element {
         if (searchQuery.trim()) {
           try {
             const parseStart = performance.now();
-            const ast = parser.parse(searchQuery);
-            const translated = sqlTranslator.translate(ast) as
-              | string
-              | { sql: string; params: unknown[] };
-            localParseTranslateMs = performance.now() - parseStart;
-            setParseTranslateMs(localParseTranslateMs);
-            whereSql =
-              typeof translated === 'string' ? translated : translated.sql;
-            mockSQL += ` WHERE ${whereSql}`;
-            // Robust operator detection with word boundaries and precedence
-            const extractOperators = (sqlText: string): string[] => {
-              const found = new Set<string>();
-              const upper = sqlText.toUpperCase();
-              // Keyword operators (use word boundaries)
-              const keywordOps: Array<[string, RegExp]> = [
-                ['ILIKE', /\bILIKE\b/i],
-                ['LIKE', /\bLIKE\b/i],
-                ['AND', /\bAND\b/i],
-                ['OR', /\bOR\b/i],
-                ['NOT', /\bNOT\b/i],
-                ['IN', /\bIN\b/i],
-                ['BETWEEN', /\bBETWEEN\b/i]
-              ];
-              for (const [name, re] of keywordOps) {
-                if (re.test(sqlText)) found.add(name);
+            // Use parseWithContext for enhanced query analysis (0.3.0 feature)
+            const parseResult = parser.parseWithContext(searchQuery, {
+              schema: {
+                title: { type: 'string', description: 'Task title' },
+                status: {
+                  type: 'string',
+                  description: 'Task status',
+                  allowedValues: ['todo', 'doing', 'done']
+                },
+                priority: { type: 'number', description: 'Priority level' },
+                completed: { type: 'boolean', description: 'Is completed' }
+              }
+            });
+
+            // Set query structure for UI display
+            setQueryStructure(parseResult.structure);
+
+            if (parseResult.success && parseResult.ast) {
+              const translated = sqlTranslator.translate(parseResult.ast) as
+                | string
+                | { sql: string; params: unknown[] };
+              localParseTranslateMs = performance.now() - parseStart;
+              setParseTranslateMs(localParseTranslateMs);
+              whereSql =
+                typeof translated === 'string' ? translated : translated.sql;
+              mockSQL += ` WHERE ${whereSql}`;
+
+              // Use referenced fields from structure (0.3.0 feature)
+              detectedOperators = [];
+              if (parseResult.structure.operatorCount > 0) {
+                // Extract operators from the SQL for display
+                const extractOperators = (sqlText: string): string[] => {
+                  const found = new Set<string>();
+                  const keywordOps: Array<[string, RegExp]> = [
+                    ['ILIKE', /\bILIKE\b/i],
+                    ['LIKE', /\bLIKE\b/i],
+                    ['AND', /\bAND\b/i],
+                    ['OR', /\bOR\b/i],
+                    ['NOT', /\bNOT\b/i],
+                    ['IN', /\bIN\b/i],
+                    ['BETWEEN', /\bBETWEEN\b/i]
+                  ];
+                  for (const [name, re] of keywordOps) {
+                    if (re.test(sqlText)) found.add(name);
+                  }
+                  let temp = sqlText.toUpperCase();
+                  const consume = (re: RegExp, label: string): void => {
+                    if (re.test(temp)) {
+                      found.add(label);
+                      temp = temp.replace(re, ' ');
+                    }
+                  };
+                  consume(/>=/g, '>=');
+                  consume(/<=/g, '<=');
+                  consume(/!=/g, '!=');
+                  consume(/=/g, '=');
+                  consume(/>/g, '>');
+                  consume(/</g, '<');
+                  return Array.from(found);
+                };
+                detectedOperators = extractOperators(whereSql);
+              } else {
+                // Simple query - just detect from SQL
+                if (/ILIKE/i.test(whereSql)) detectedOperators.push('ILIKE');
+                if (/=/i.test(whereSql) && !/!=/i.test(whereSql))
+                  detectedOperators.push('=');
               }
-              // Symbol operators: match longest first and remove before shorter matches
-              let temp = upper;
-              const consume = (re: RegExp, label: string): void => {
-                if (re.test(temp)) {
-                  found.add(label);
-                  temp = temp.replace(re, ' ');
-                }
-              };
-              consume(/>=/g, '>=');
-              consume(/<=/g, '<=');
-              consume(/!=/g, '!=');
-              consume(/=/g, '=');
-              consume(/>/g, '>');
-              consume(/</g, '<');
-              return Array.from(found);
-            };
-            detectedOperators = extractOperators(whereSql);
+            } else {
+              // Parse failed - fall back to ILIKE search
+              throw new Error(parseResult.error?.message || 'Parse failed');
+            }
           } catch (error) {
             void trackQueryKitIssue({
               errorName: (error as Error)?.name ?? 'UnknownError',
@@ -1013,25 +1060,77 @@ export default function Home(): JSX.Element {
                     )}
                   </div>
                   {!isShortViewport ? (
-                    <div className="mt-3">
-                      <div className="text-xs text-muted-foreground mb-1">
-                        Detected operators
-                      </div>
-                      {operatorsUsed.length ? (
-                        <div className="flex flex-wrap gap-2">
-                          {operatorsUsed.map(op => (
-                            <span
-                              key={op}
-                              className="inline-flex items-center rounded-full border bg-muted px-2 py-0.5 text-xs font-medium"
-                            >
-                              {op}
-                            </span>
-                          ))}
+                    <>
+                      <div className="mt-3 grid grid-cols-2 gap-3">
+                        <div>
+                          <div className="text-xs text-muted-foreground mb-1">
+                            Detected operators
+                          </div>
+                          {operatorsUsed.length ? (
+                            <div className="flex flex-wrap gap-2">
+                              {operatorsUsed.map(op => (
+                                <span
+                                  key={op}
+                                  className="inline-flex items-center rounded-full border bg-muted px-2 py-0.5 text-xs font-medium"
+                                >
+                                  {op}
+                                </span>
+                              ))}
+                            </div>
+                          ) : (
+                            <div className="text-xs text-muted-foreground">
+                              -
+                            </div>
+                          )}
                         </div>
-                      ) : (
-                        <div className="text-xs text-muted-foreground">-</div>
-                      )}
-                    </div>
+                        {queryStructure && (
+                          <div>
+                            <div className="text-xs text-muted-foreground mb-1">
+                              Query complexity (0.3.0)
+                            </div>
+                            <div className="flex flex-wrap gap-2">
+                              <span
+                                className={cn(
+                                  'inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium',
+                                  queryStructure.complexity === 'simple' &&
+                                    'bg-green-500/10 text-green-600 border-green-500/30',
+                                  queryStructure.complexity === 'moderate' &&
+                                    'bg-yellow-500/10 text-yellow-600 border-yellow-500/30',
+                                  queryStructure.complexity === 'complex' &&
+                                    'bg-red-500/10 text-red-600 border-red-500/30'
+                                )}
+                              >
+                                {queryStructure.complexity}
+                              </span>
+                              <span className="inline-flex items-center rounded-full border bg-muted px-2 py-0.5 text-xs font-medium">
+                                depth: {queryStructure.depth}
+                              </span>
+                              <span className="inline-flex items-center rounded-full border bg-muted px-2 py-0.5 text-xs font-medium">
+                                clauses: {queryStructure.clauseCount}
+                              </span>
+                            </div>
+                          </div>
+                        )}
+                      </div>
+                      {queryStructure &&
+                        queryStructure.referencedFields.length > 0 && (
+                          <div className="mt-3">
+                            <div className="text-xs text-muted-foreground mb-1">
+                              Referenced fields
+                            </div>
+                            <div className="flex flex-wrap gap-2">
+                              {queryStructure.referencedFields.map(field => (
+                                <span
+                                  key={field}
+                                  className="inline-flex items-center rounded-full border bg-blue-500/10 text-blue-600 border-blue-500/30 px-2 py-0.5 text-xs font-medium"
+                                >
+                                  {field}
+                                </span>
+                              ))}
+                            </div>
+                          </div>
+                        )}
+                    </>
                   ) : (
                     <div className="mt-3 text-xs text-muted-foreground">
                       View on larger screen for more details

package/examples/qk-next/package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "@electric-sql/pglite": "^0.3.7",
     "@electric-sql/pglite-react": "^0.2.25",
-    "@gblikas/querykit": "^0.0.0",
+    "@gblikas/querykit": "^0.3.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-hover-card": "^1.1.15",
     "@vercel/analytics": "^1.5.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gblikas/querykit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A comprehensive query toolkit for TypeScript that simplifies building and executing data queries across different environments",
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
     "lint-staged": "^15.5.1",
     "prettier": "^3.2.5",
     "ts-jest": "^29.1.2",
-    "typescript": "^5.3.3"
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc --outDir dist",

package/src/adapters/drizzle/index.ts

@@ -9,6 +9,7 @@ import { IAdapter, IAdapterOptions, IQueryExecutionOptions } from '../types';
 import { QueryExpression } from '../../parser/types';
 import { SQL, SQLWrapper, asc, desc, sql } from 'drizzle-orm';
 import { createQueryKit, QueryKit } from '../../index';
+import { IQueryContext } from '../../virtual-fields';
 /**
  * Type for Drizzle ORM database instance
  */
@@ -91,8 +92,7 @@ export class DrizzleAdapterError extends Error {
  */
 export class DrizzleAdapter<
   TSchema extends Record<string, unknown> = Record<string, unknown>
-> implements IAdapter<IDrizzleAdapterOptions<TSchema>>
-{
+> implements IAdapter<IDrizzleAdapterOptions<TSchema>> {
   private db!: unknown;
   private schema!: TSchema;
   private translator!: DrizzleTranslator;
@@ -291,7 +291,7 @@ export function createDrizzleQueryKit<
 
   type RowMap = RowMapFromDrizzleSchema<TSchema>;
 
-  return createQueryKit<TSchema, RowMap>({
+  return createQueryKit<TSchema, IQueryContext, RowMap>({
     adapter,
     schema: args.schema as unknown as TSchema,
     security: args.security

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/parser/types.ts

@@ -51,10 +51,30 @@ export interface ILogicalExpression {
   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/src/security/validator.ts

@@ -240,13 +240,14 @@ export 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
   }
 
   /**
@@ -285,13 +286,14 @@ export 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
   }
 
   /**
@@ -350,6 +352,7 @@ export class QuerySecurityValidator {
         this.validateQueryDepth(expression.right, currentDepth + 1);
       }
     }
+    // Raw and comparison expressions don't add depth
   }
 
   /**
@@ -379,6 +382,10 @@ export class QuerySecurityValidator {
       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) {
@@ -442,12 +449,13 @@ export 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
   }
 
   /**
@@ -481,12 +489,13 @@ export class QuerySecurityValidator {
           .replace(/\?{2,}/g, '?'); // Limit consecutive question marks
         (expression as IComparisonExpression).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
   }
 
   /**
@@ -502,11 +511,12 @@ export class QuerySecurityValidator {
   ): void {
     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
   }
 }