@gblikas/querykit 0.0.0

package/examples/qk-next/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+};
+
+export default config;

package/examples/qk-next/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/examples/qk-next/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/examples/qk-next/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/examples/qk-next/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/examples/qk-next/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/examples/qk-next/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ],
+    },
+    "baseUrl": "."
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    "types/**/*.d.ts",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/examples/qk-next/types/sonner.d.ts

@@ -0,0 +1,3 @@
+declare module 'sonner' {
+  export function toast(message: string): void;
+}

package/jest.config.js

@@ -0,0 +1,26 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.ts?(x)', '**/?(*.)+(spec|test).ts?(x)'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        diagnostics: {
+          ignoreCodes: [6133, 6196, 2322]
+        }
+      }
+    ]
+  },
+  verbose: true,
+  collectCoverage: true,
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/**/*.spec.ts',
+    '!src/**/index.ts',
+    '!src/types/**/*.ts'
+  ]
+}; 

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@gblikas/querykit",
+  "version": "0.0.0",
+  "description": "A comprehensive query toolkit for TypeScript that simplifies building and executing data queries across different environments",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "query",
+    "filter",
+    "typescript",
+    "orm",
+    "database",
+    "drizzle"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.30.2",
+    "liqe": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.24",
+    "@typescript-eslint/eslint-plugin": "^7.1.0",
+    "@typescript-eslint/parser": "^7.1.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0",
+    "lint-staged": "^15.5.1",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --outDir dist",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint-staged": "lint-staged"
+  }
+}

package/src/adapters/drizzle/drizzle-adapter.test.ts

@@ -0,0 +1,115 @@
+import { DrizzleAdapter, IDrizzleDatabase } from './index';
+import { QueryParser } from '../../parser';
+import { QueryExpression } from '../../parser/types';
+import { SQLWrapper, sql } from 'drizzle-orm';
+
+// Create mocks
+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: unknown[]) => T) =>
+    Promise.resolve(callback([{ id: 1, title: 'Test Todo' }]))
+});
+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
+  }
+};
+
+describe('DrizzleAdapter', () => {
+  let adapter: DrizzleAdapter;
+  let parser: QueryParser;
+
+  beforeEach(() => {
+    // Reset mocks
+    jest.clearAllMocks();
+
+    // Create fresh instances
+    adapter = new DrizzleAdapter();
+    parser = new QueryParser();
+
+    // Initialize the adapter
+    adapter.initialize({
+      db: mockDb,
+      schema: mockSchema
+    });
+  });
+
+  describe('execute', () => {
+    it('should execute a simple query', async () => {
+      const expression = parser.parse('title:"Test Todo"');
+      const result = await adapter.execute('todos', expression);
+
+      expect(mockSelect).toHaveBeenCalled();
+      expect(mockFrom).toHaveBeenCalled();
+      expect(mockWhere).toHaveBeenCalled();
+      expect(result).toEqual([{ id: 1, title: 'Test Todo' }]);
+    });
+
+    it('should support ordering', async () => {
+      const expression = parser.parse('status:"active"');
+      await adapter.execute('todos', expression, {
+        orderBy: { title: 'asc' }
+      });
+
+      expect(mockOrderBy).toHaveBeenCalled();
+    });
+
+    it('should support limit', async () => {
+      const expression = parser.parse('status:"active"');
+      await adapter.execute('todos', expression, {
+        limit: 10
+      });
+
+      expect(mockLimit).toHaveBeenCalledWith(10);
+    });
+
+    it('should support offset', async () => {
+      const expression = parser.parse('status:"active"');
+      await adapter.execute('todos', expression, {
+        offset: 20
+      });
+
+      expect(mockOffset).toHaveBeenCalledWith(20);
+    });
+
+    it('should throw error if table not found', async () => {
+      const expression = parser.parse('status:"active"');
+
+      await expect(
+        adapter.execute('unknown_table', expression)
+      ).rejects.toThrow('Table unknown_table not found in schema');
+    });
+  });
+
+  describe('canExecute', () => {
+    it('should return true for valid expressions', () => {
+      const expression = parser.parse('status:"active"');
+      expect(adapter.canExecute(expression)).toBe(true);
+    });
+
+    it('should return false for invalid expressions', () => {
+      const invalidExpression = {
+        type: 'unsupported'
+      } as unknown as QueryExpression;
+      expect(adapter.canExecute(invalidExpression)).toBe(false);
+    });
+  });
+});

package/src/adapters/drizzle/index.ts

@@ -0,0 +1,299 @@
+/**
+ * Drizzle ORM Adapter for QueryKit
+ *
+ * This adapter connects QueryKit to Drizzle ORM for database queries.
+ */
+
+import { DrizzleTranslator } from '../../translators/drizzle';
+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';
+/**
+ * Type for Drizzle ORM database instance
+ */
+export interface IDrizzleDatabase {
+  select: () => { from: (table: unknown) => IDrizzleQueryBuilder };
+}
+
+/**
+ * Type for Drizzle query builder
+ */
+export interface IDrizzleQueryBuilder {
+  where: (condition: SQL) => IDrizzleQueryBuilder;
+  orderBy: (...clauses: SQL[]) => IDrizzleQueryBuilder;
+  limit: (limit: number) => IDrizzleQueryBuilder;
+  offset: (offset: number) => IDrizzleQueryBuilder;
+  // This is already a Promise due to Drizzle's thenable implementation
+  [Symbol.toStringTag]: string;
+  then<TResult1 = unknown, TResult2 = never>(
+    onfulfilled?:
+      | ((value: unknown[]) => TResult1 | PromiseLike<TResult1>)
+      | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2>;
+}
+
+/**
+ * Options specific to the Drizzle adapter
+ */
+export interface IDrizzleAdapterOptions<
+  TSchema extends Record<string, unknown> = Record<string, unknown>
+> extends IAdapterOptions {
+  /**
+   * The Drizzle ORM database instance
+   */
+  db: IDrizzleDatabase | unknown;
+
+  /**
+   * Schema information with Drizzle table definitions
+   */
+  schema: TSchema;
+
+  /**
+   * Whether to normalize field names (e.g., lowercase them)
+   */
+  normalizeFieldNames?: boolean;
+}
+
+/**
+ * Options for Drizzle query execution
+ */
+export interface IDrizzleQueryExecutionOptions extends IQueryExecutionOptions {
+  /**
+   * Sort fields in the format: { field: 'asc' | 'desc' }
+   */
+  orderBy?: Record<string, 'asc' | 'desc'>;
+
+  /**
+   * Maximum number of records to return
+   */
+  limit?: number;
+
+  /**
+   * Number of records to skip
+   */
+  offset?: number;
+}
+
+/**
+ * Error thrown when adapter operations fail
+ */
+export class DrizzleAdapterError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DrizzleAdapterError';
+  }
+}
+
+/**
+ * Adapter for Drizzle ORM
+ */
+export class DrizzleAdapter<
+  TSchema extends Record<string, unknown> = Record<string, unknown>
+> implements IAdapter<IDrizzleAdapterOptions<TSchema>>
+{
+  private db!: unknown;
+  private schema!: TSchema;
+  private translator!: DrizzleTranslator;
+  private initialized: boolean = false;
+
+  /**
+   * Optionally initialize via constructor for convenience
+   */
+  constructor(options?: IDrizzleAdapterOptions<TSchema>) {
+    if (options) {
+      this.initialize(options);
+    }
+  }
+
+  /**
+   * Initialize the adapter with options
+   */
+  public initialize(options: IDrizzleAdapterOptions<TSchema>): void {
+    if (!options.db) {
+      throw new DrizzleAdapterError('Drizzle db instance is required');
+    }
+
+    if (!options.schema) {
+      throw new DrizzleAdapterError('Schema definition is required');
+    }
+
+    this.db = options.db;
+    this.schema = options.schema;
+    this.translator = new DrizzleTranslator({
+      normalizeFieldNames: options.normalizeFieldNames,
+      fieldMappings: options.fieldMappings,
+      schema: options.schema as unknown as Record<
+        string,
+        Record<string, unknown>
+      >
+    });
+
+    this.initialized = true;
+  }
+
+  /**
+   * Execute a QueryKit expression using Drizzle ORM
+   */
+  public async execute<TResult = unknown>(
+    tableName: string,
+    expression: QueryExpression,
+    options?: IDrizzleQueryExecutionOptions
+  ): Promise<TResult[]> {
+    this.ensureInitialized();
+
+    const table = this.getTable(tableName);
+
+    if (!table) {
+      throw new DrizzleAdapterError(`Table ${tableName} not found in schema`);
+    }
+
+    try {
+      // Start with a base query
+      let query = (this.db as IDrizzleDatabase).select().from(table);
+
+      // Add where condition if expression is provided
+      if (expression) {
+        const condition = this.translator.translate(expression);
+        query = query.where(condition);
+      }
+
+      // Add ordering if specified
+      if (options?.orderBy) {
+        const orderClauses: SQL[] = [];
+
+        Object.entries(options.orderBy).forEach(([field, direction]) => {
+          // Try to find the field in the schema
+          const schemaField = this.getSchemaField(tableName, field);
+
+          if (schemaField) {
+            // If field exists in schema, use it directly
+            orderClauses.push(
+              direction === 'asc' ? asc(schemaField) : desc(schemaField)
+            );
+          } else {
+            // Otherwise use raw SQL
+            orderClauses.push(
+              sql`${sql.identifier(field)} ${sql.raw(direction.toUpperCase())}`
+            );
+          }
+        });
+
+        if (orderClauses.length > 0) {
+          query = query.orderBy(...orderClauses);
+        }
+      }
+
+      // Add limit if specified
+      if (options?.limit !== undefined) {
+        query = query.limit(options.limit);
+      }
+
+      // Add offset if specified
+      if (options?.offset !== undefined) {
+        query = query.offset(options.offset);
+      }
+
+      // Execute the query
+      const result = await query;
+      return result as TResult[];
+    } catch (error) {
+      throw new DrizzleAdapterError(
+        `Failed to execute query: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Check if an expression can be executed by this adapter
+   */
+  public canExecute(expression: QueryExpression): boolean {
+    try {
+      this.ensureInitialized();
+      return this.translator.canTranslate(expression);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get a table from the schema
+   */
+  private getTable(tableName: string): unknown {
+    return (this.schema as Record<string, unknown>)[tableName as string];
+  }
+
+  /**
+   * Get a field from the schema
+   */
+  private getSchemaField(
+    tableName: string,
+    fieldName: string
+  ): SQLWrapper | null {
+    const schemaAsColumns = this.schema as unknown as Record<
+      string,
+      Record<string, SQLWrapper>
+    >;
+    const table = schemaAsColumns[tableName];
+    if (table && fieldName in table) {
+      return table[fieldName];
+    }
+    return null;
+  }
+
+  /**
+   * Ensure the adapter is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new DrizzleAdapterError('Adapter has not been initialized');
+    }
+  }
+}
+
+/**
+ * Convenience factory to create a pre-initialized Drizzle adapter
+ */
+export function drizzleAdapter<TSchema extends Record<string, unknown>>(
+  options: IDrizzleAdapterOptions<TSchema>
+): DrizzleAdapter<TSchema> {
+  return new DrizzleAdapter<TSchema>(options);
+}
+
+// Helper types and factory for zero-cast DX with Drizzle tables
+export type RowTypeFromDrizzleTable<TTable> = TTable extends {
+  $inferSelect: infer R;
+}
+  ? R
+  : unknown;
+
+export type RowMapFromDrizzleSchema<TSchema extends Record<string, unknown>> = {
+  [K in keyof TSchema]: RowTypeFromDrizzleTable<TSchema[K]>;
+};
+
+export function createDrizzleQueryKit<
+  TSchema extends Record<string, object>
+>(args: {
+  db: unknown;
+  schema: TSchema;
+  normalizeFieldNames?: boolean;
+  fieldMappings?: Record<string, string>;
+  security?: import('../../security').ISecurityOptions;
+}): QueryKit<TSchema, RowMapFromDrizzleSchema<TSchema>> {
+  const adapter = new DrizzleAdapter<TSchema>();
+  adapter.initialize({
+    db: args.db,
+    schema: args.schema,
+    normalizeFieldNames: args.normalizeFieldNames,
+    fieldMappings: args.fieldMappings
+  });
+
+  type RowMap = RowMapFromDrizzleSchema<TSchema>;
+
+  return createQueryKit<TSchema, RowMap>({
+    adapter,
+    schema: args.schema as unknown as TSchema,
+    security: args.security
+  });
+}

package/src/adapters/index.ts

@@ -0,0 +1,11 @@
+/**
+ * QueryKit Adapters
+ * 
+ * Exports all adapter implementations for different database systems.
+ */
+
+// Export base types
+export * from './types';
+
+// Export Drizzle adapter
+export * from './drizzle'; 

package/src/adapters/types.ts

@@ -0,0 +1,72 @@
+/**
+ * QueryKit Adapter Types
+ * 
+ * These are the core interfaces for adapters, which connect QueryKit to 
+ * external systems or libraries like Drizzle ORM.
+ */
+
+import { QueryExpression } from '../parser/types';
+
+/**
+ * Options for configuring an adapter
+ */
+export interface IAdapterOptions {
+  /**
+   * Schema information for type safety and validation
+   */
+  schema?: Record<string, unknown>;
+  
+  /**
+   * Field mappings from QueryKit fields to target database fields
+   */
+  fieldMappings?: Record<string, string>;
+}
+
+/**
+ * Options for a query execution
+ */
+export interface IQueryExecutionOptions {
+  /**
+   * Optional transaction object
+   */
+  transaction?: unknown;
+  
+  /**
+   * Additional parameters specific to the adapter
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Interface for a query adapter
+ */
+export interface IAdapter<TOptions extends IAdapterOptions = IAdapterOptions> {
+  /**
+   * Initialize the adapter with options
+   * 
+   * @param options Adapter-specific options
+   */
+  initialize(options: TOptions): void;
+  
+  /**
+   * Execute a QueryKit expression and return results
+   * 
+   * @param tableName The table/collection name to query
+   * @param expression The QueryKit expression to execute
+   * @param options Optional execution options
+   * @returns The query results
+   */
+  execute<T = unknown>(
+    tableName: string,
+    expression: QueryExpression,
+    options?: IQueryExecutionOptions
+  ): Promise<T[]>;
+  
+  /**
+   * Check if an expression can be executed by this adapter
+   * 
+   * @param expression The QueryKit expression to check
+   * @returns true if the expression can be executed, false otherwise
+   */
+  canExecute(expression: QueryExpression): boolean;
+}