@gblikas/querykit 0.0.0

package/src/index.ts

@@ -0,0 +1,194 @@
+/**
+ * QueryKit - A comprehensive query toolkit for TypeScript
+ *
+ * QueryKit simplifies how you build and execute data queries across different
+ * environments with a unified, intuitive syntax for filtering, sorting, and
+ * transforming data.
+ */
+
+// Core exports
+import { QueryBuilder, IQueryBuilderOptions } from './query';
+import { QueryParser, IParserOptions } from './parser';
+import { SqlTranslator } from './translators/sql';
+import { ISecurityOptions, QuerySecurityValidator } from './security';
+import { IAdapter, IAdapterOptions } from './adapters';
+
+export {
+  // Parser exports
+  QueryParser,
+  IParserOptions,
+
+  // Query builder exports
+  QueryBuilder,
+  IQueryBuilderOptions,
+
+  // Translator exports
+  SqlTranslator
+};
+
+// Re-export from modules
+export * from './translators';
+export * from './adapters';
+
+/**
+ * Create a new QueryBuilder instance
+ */
+export function createQueryBuilder<T>(
+  options?: IQueryBuilderOptions<T>
+): QueryBuilder<T> {
+  return new QueryBuilder<T>(options);
+}
+
+/**
+ * Create a new QueryParser instance
+ */
+export function createQueryParser(options?: IParserOptions): QueryParser {
+  return new QueryParser(options);
+}
+
+/**
+ * Options for creating a new QueryKit instance
+ */
+export interface IQueryKitOptions<
+  TSchema extends Record<string, object> = Record<
+    string,
+    Record<string, unknown>
+  >
+> {
+  /**
+   * The adapter to use for database connections
+   */
+  adapter: IAdapter;
+
+  /**
+   * The schema to use for query validation
+   */
+  schema: TSchema;
+
+  /**
+   * Security options for query validation
+   */
+  security?: ISecurityOptions;
+
+  /**
+   * Options to initialize the provided adapter
+   */
+  adapterOptions?: IAdapterOptions & { [key: string]: unknown };
+}
+
+// Define interfaces for return types
+export interface IQueryExecutor<TResult> {
+  execute(): Promise<TResult[]>;
+  orderBy(field: string, direction?: 'asc' | 'desc'): IQueryExecutor<TResult>;
+  limit(count: number): IQueryExecutor<TResult>;
+  offset(count: number): IQueryExecutor<TResult>;
+}
+
+export interface IWhereClause<TResult> {
+  where(queryString: string): IQueryExecutor<TResult>;
+}
+
+/**
+ * Public QueryKit type
+ */
+export type QueryKit<
+  TSchema extends Record<string, object>,
+  TRows extends { [K in keyof TSchema & string]: unknown } = {
+    [K in keyof TSchema & string]: unknown;
+  }
+> = {
+  query<K extends keyof TSchema & string>(table: K): IWhereClause<TRows[K]>;
+};
+
+/**
+ * Create a new QueryKit instance
+ */
+export function createQueryKit<
+  TSchema extends Record<string, object>,
+  TRows extends { [K in keyof TSchema & string]: unknown } = {
+    [K in keyof TSchema & string]: unknown;
+  }
+>(options: IQueryKitOptions<TSchema>): QueryKit<TSchema, TRows> {
+  const parser = new QueryParser();
+  const securityValidator = new QuerySecurityValidator(options.security);
+
+  // Initialize adapter if options provided. If adapter is already initialized,
+  // calling initialize again with the same options should be a no-op for most adapters.
+  if (options.adapterOptions) {
+    const mergedAdapterOptions: IAdapterOptions & { [key: string]: unknown } = {
+      // Ensure adapter receives schema information if not already provided
+      schema: options.adapterOptions.schema ?? options.schema,
+      ...options.adapterOptions
+    } as IAdapterOptions & { [key: string]: unknown };
+
+    try {
+      options.adapter.initialize(mergedAdapterOptions);
+    } catch {
+      // If initialization fails here, the adapter might already be initialized
+      // or require a different init path; we'll let execute-time errors surface.
+    }
+  }
+
+  // This function would be expanded to include all QueryKit functionality
+  return {
+    query: <K extends keyof TSchema & string>(
+      table: K
+    ): IWhereClause<TRows[K]> => {
+      return {
+        where: (queryString: string): IQueryExecutor<TRows[K]> => {
+          // Parse and validate 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'> = {};
+          let limitState: number | undefined;
+          let offsetState: number | undefined;
+
+          const executor: IQueryExecutor<TRows[K]> = {
+            orderBy: (
+              field: string,
+              direction: 'asc' | 'desc' = 'asc'
+            ): IQueryExecutor<TRows[K]> => {
+              orderByState = { ...orderByState, [field]: direction };
+              return executor;
+            },
+            limit: (count: number): IQueryExecutor<TRows[K]> => {
+              limitState = count;
+              return executor;
+            },
+            offset: (count: number): IQueryExecutor<TRows[K]> => {
+              offsetState = count;
+              return executor;
+            },
+            execute: async (): Promise<TRows[K][]> => {
+              // Delegate to adapter
+              const results = await options.adapter.execute(
+                table,
+                expressionAst,
+                {
+                  orderBy:
+                    Object.keys(orderByState).length > 0
+                      ? orderByState
+                      : undefined,
+                  limit: limitState,
+                  offset: offsetState
+                }
+              );
+              return results as TRows[K][];
+            }
+          };
+
+          return executor;
+        }
+      };
+    }
+  };
+}
+
+// Export all public APIs
+export * from './parser';
+export * from './security';

package/src/integration.test.ts

@@ -0,0 +1,202 @@
+import { QueryParser } from './parser';
+import { DrizzleTranslator } from './translators/drizzle';
+import { DrizzleAdapter, IDrizzleDatabase } from './adapters/drizzle';
+import { SQLWrapper, SQL, sql } from 'drizzle-orm';
+import { createQueryBuilder, createQueryKit } from './index';
+
+// Helper function to safely get SQL string value for testing
+function getSqlString(sqlObj: SQL): string {
+  // For testing purposes only - extract a string representation
+  // of the SQL query that we can use in our assertions
+  try {
+    return JSON.stringify(sqlObj);
+  } catch (e) {
+    return String(sqlObj);
+  }
+}
+
+// Define a user type for testing
+interface ITodo {
+  id: number;
+  title: string;
+  priority: number;
+  status: string;
+}
+
+describe('QueryKit Integration Tests', () => {
+  // Set up mocks for the Drizzle adapter
+  const mockWhere = jest.fn().mockReturnThis();
+  const mockOrderBy = jest.fn().mockReturnThis();
+  const mockLimit = jest.fn().mockReturnThis();
+  const mockOffset = jest.fn().mockReturnThis();
+  const mockFrom = jest.fn().mockReturnValue({
+    where: mockWhere,
+    orderBy: mockOrderBy,
+    limit: mockLimit,
+    offset: mockOffset,
+    then: <T>(callback: (value: ITodo[]) => T) =>
+      Promise.resolve(
+        callback([
+          { id: 1, title: 'Buy groceries', priority: 2, status: 'active' },
+          { id: 2, title: 'Fix bug', priority: 3, status: 'active' }
+        ])
+      )
+  });
+  const mockSelect = jest.fn().mockReturnValue({ from: mockFrom });
+
+  // Create a mock DB instance
+  const mockDb: IDrizzleDatabase = {
+    select: mockSelect
+  };
+
+  // Create mock schema with SQLWrapper fields
+  const mockSchema = {
+    todos: {
+      id: sql.raw('id') as unknown as SQLWrapper,
+      title: sql.raw('title') as unknown as SQLWrapper,
+      priority: sql.raw('priority') as unknown as SQLWrapper,
+      status: sql.raw('status') as unknown as SQLWrapper
+    }
+  };
+
+  // Set up the adapter
+  const adapter = new DrizzleAdapter();
+  adapter.initialize({
+    db: mockDb,
+    schema: mockSchema
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('End-to-end Query', () => {
+    it('should parse, translate and execute a query', async () => {
+      // Parse a query expression
+      const parser = new QueryParser();
+      const expression = parser.parse('priority:>1 AND status:"active"');
+
+      // Execute the query using the adapter
+      const results = await adapter.execute<ITodo>('todos', expression);
+
+      // Verify results
+      expect(results).toHaveLength(2);
+      expect(results[0].title).toBe('Buy groceries');
+      expect(results[1].title).toBe('Fix bug');
+
+      // Verify that the mocks were called correctly
+      expect(mockSelect).toHaveBeenCalled();
+      expect(mockFrom).toHaveBeenCalled();
+      expect(mockWhere).toHaveBeenCalled();
+
+      // Verify the WHERE clause reflects the parsed query
+      const whereArg = mockWhere.mock.calls[0][0] as unknown as SQL;
+      const whereStr = getSqlString(whereArg);
+      expect(whereStr).toContain('priority');
+      expect(whereStr.toLowerCase()).toContain('active');
+    });
+
+    it('should work with the query builder', async () => {
+      // Create a query builder
+      const queryBuilder = createQueryBuilder<ITodo>();
+
+      // Build a query
+      queryBuilder.where('priority', '>', 1).andWhere('status', '==', 'active');
+
+      // Get the expression from the builder
+      const expression = queryBuilder.getExpression();
+
+      // Execute the query using the adapter
+      const results = await adapter.execute<ITodo>('todos', expression);
+
+      // Verify results
+      expect(results).toHaveLength(2);
+      expect(results[0].id).toBe(1);
+      expect(results[1].id).toBe(2);
+    });
+  });
+
+  describe('Translation Pipeline', () => {
+    it('should translate expressions consistently', () => {
+      // Parse a query string
+      const parser = new QueryParser();
+      const stringExpression = parser.parse('status:"active" OR priority:>2');
+
+      // Create the same expression with the builder
+      const queryBuilder = createQueryBuilder<ITodo>();
+      const builderExpression = queryBuilder
+        .where('status', '==', 'active')
+        .orWhere('priority', '>', 2)
+        .getExpression();
+
+      // Create a translator
+      const translator = new DrizzleTranslator();
+
+      // Translate both expressions
+      const stringTranslated = translator.translate(stringExpression);
+      const builderTranslated = translator.translate(builderExpression);
+
+      // The SQL from both translations should have the same structure
+      // (We can't directly compare SQL objects)
+      const stringTranslatedStr = getSqlString(stringTranslated);
+      const builderTranslatedStr = getSqlString(builderTranslated);
+
+      expect(stringTranslatedStr).toContain('OR');
+      expect(builderTranslatedStr).toContain('OR');
+
+      // Both translations should contain similar structural elements
+      // (Avoiding exact string matches as SQL objects might differ in representation)
+      if (
+        stringTranslatedStr.includes('status') &&
+        builderTranslatedStr.includes('status')
+      ) {
+        expect(true).toBe(true); // Both contain 'status'
+      } else {
+        expect(stringTranslatedStr).toContain('status');
+        expect(builderTranslatedStr).toContain('status');
+      }
+
+      if (
+        stringTranslatedStr.includes('priority') &&
+        builderTranslatedStr.includes('priority')
+      ) {
+        expect(true).toBe(true); // Both contain 'priority'
+      } else {
+        expect(stringTranslatedStr).toContain('priority');
+        expect(builderTranslatedStr).toContain('priority');
+      }
+    });
+  });
+
+  describe('Fluent API execution', () => {
+    it('executes a fluent query via createQueryKit', async () => {
+      const adapter = new DrizzleAdapter();
+      adapter.initialize({ db: mockDb, schema: mockSchema });
+
+      const qk = createQueryKit({
+        adapter,
+        schema: { todos: { id: {}, title: {}, priority: {}, status: {} } }
+      });
+
+      const results = await qk
+        .query('todos')
+        .where('priority:>1 AND status:"active"')
+        .orderBy('priority', 'desc')
+        .limit(10)
+        .execute();
+
+      expect(results).toHaveLength(2);
+      expect(mockSelect).toHaveBeenCalled();
+      expect(mockFrom).toHaveBeenCalled();
+      expect(mockWhere).toHaveBeenCalled();
+      expect(mockOrderBy).toHaveBeenCalled();
+      expect(mockLimit).toHaveBeenCalledWith(10);
+
+      // Verify WHERE clause from fluent path
+      const whereArg = mockWhere.mock.calls[0][0] as unknown as SQL;
+      const whereStr = getSqlString(whereArg);
+      expect(whereStr).toContain('priority');
+      expect(whereStr.toLowerCase()).toContain('active');
+    });
+  });
+});

package/src/parser/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './parser';