Add Driver Technology Compatibility Kit (TCK) for unified driver testing

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/tools/driver-tck/README.md

@@ -0,0 +1,171 @@
+# ObjectQL Driver TCK (Technology Compatibility Kit)
+
+A comprehensive test suite to ensure all ObjectQL drivers implement consistent behavior.
+
+## Purpose
+
+The Driver TCK provides a standardized set of tests that all ObjectQL drivers must pass. This ensures:
+
+- **Consistency**: All drivers behave the same way for core operations
+- **Compatibility**: Applications can switch drivers without code changes
+- **Quality**: Drivers are thoroughly tested against a known specification
+
+## Usage
+
+### With Jest
+
+```typescript
+import { runDriverTCK } from '@objectql/driver-tck';
+import { MyDriver } from './my-driver';
+
+describe('MyDriver TCK', () => {
+  runDriverTCK(() => new MyDriver({
+    // driver config
+  }), {
+    skip: {
+      // Skip tests for unsupported features
+      aggregations: true,
+      transactions: true
+    },
+    timeout: 30000
+  });
+});
+```
+
+### With Vitest
+
+```typescript
+import { describe } from 'vitest';
+import { runDriverTCK } from '@objectql/driver-tck';
+import { MyDriver } from './my-driver';
+
+describe('MyDriver TCK', () => {
+  runDriverTCK(() => new MyDriver(), {
+    timeout: 30000
+  });
+});
+```
+
+## Test Categories
+
+### 1. Core CRUD Operations
+- Create records
+- Read records (findOne)
+- Update records
+- Delete records
+- Custom IDs
+- Timestamps
+
+### 2. Query Operations
+- Find all records
+- Filter by equality, comparison operators
+- Boolean filters
+- Sorting (ascending/descending)
+- Pagination (limit/offset)
+- Combined filters + sort + pagination
+- Count with and without filters
+
+### 3. Distinct Operations *(optional)*
+- Get distinct values for a field
+- Distinct with filters
+
+### 4. Aggregation Operations *(optional)*
+- Group by with count
+- Average, min, max
+- Complex aggregation pipelines
+
+### 5. Bulk Operations *(optional)*
+- Bulk create
+- Bulk update
+- Bulk delete
+
+### 6. Edge Cases
+- Empty queries
+- Null/undefined values
+- Special characters
+- Type conversions
+
+## Configuration
+
+### Skip Options
+
+Use the `skip` configuration to disable tests for features your driver doesn't support:
+
+```typescript
+{
+  skip: {
+    transactions: true,      // Skip transaction tests
+    joins: true,            // Skip join tests
+    fullTextSearch: true,   // Skip full-text search tests
+    aggregations: true,     // Skip aggregation tests
+    distinct: true,         // Skip distinct tests
+    bulkOperations: true    // Skip bulk operation tests
+  }
+}
+```
+
+### Timeout
+
+Set custom timeout for long-running operations:
+
+```typescript
+{
+  timeout: 60000 // 60 seconds
+}
+```
+
+### Hooks
+
+Provide custom setup/teardown logic:
+
+```typescript
+{
+  hooks: {
+    beforeAll: async () => {
+      // Setup database connection
+    },
+    afterAll: async () => {
+      // Cleanup
+    },
+    beforeEach: async () => {
+      // Clear test data
+    },
+    afterEach: async () => {
+      // Post-test cleanup
+    }
+  }
+}
+```
+
+## Driver Requirements
+
+To pass the TCK, your driver must implement:
+
+### Required Methods
+
+- `create(objectName, data)` - Create a record
+- `findOne(objectName, id)` - Find by ID
+- `find(objectName, query)` - Query records
+- `update(objectName, id, data)` - Update a record
+- `delete(objectName, id)` - Delete a record
+- `count(objectName, filters)` - Count records
+
+### Optional Methods
+
+- `distinct(objectName, field, filters)` - Get distinct values
+- `aggregate(objectName, pipeline)` - Aggregation pipeline
+- `executeCommand(command)` - Bulk operations
+- `connect()` - Initialize connection
+- `disconnect()` - Close connection
+- `clear()` - Clear all data (for testing)
+
+### Expected Behavior
+
+1. **Auto-generated IDs**: If no ID is provided, generate a unique one
+2. **Timestamps**: Automatically add `created_at` and `updated_at`
+3. **Null Safety**: Return `null` for non-existent records
+4. **QueryAST Support**: Support the standard query format
+
+## License
+
+MIT

packages/tools/driver-tck/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@objectql/driver-tck",
+  "version": "4.0.0",
+  "description": "Technology Compatibility Kit for ObjectQL drivers - Unified test suite",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "objectql",
+    "driver",
+    "tck",
+    "test",
+    "compatibility"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "jest": "^30.0.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

packages/tools/driver-tck/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Driver Technology Compatibility Kit (TCK)
+ */
+
+export interface TCKDriverFactory {
+    (): any;
+}
+
+export interface TCKConfig {
+    skip?: {
+        transactions?: boolean;
+        joins?: boolean;
+        fullTextSearch?: boolean;
+        aggregations?: boolean;
+        distinct?: boolean;
+        bulkOperations?: boolean;
+    };
+    timeout?: number;
+}
+
+export function runDriverTCK(
+    createDriver: TCKDriverFactory,
+    config: TCKConfig = {}
+) {
+    const skip = config.skip || {};
+    const timeout = config.timeout || 30000;
+    
+    describe('Driver TCK', () => {
+        let driver: any;
+        const TEST_OBJECT = 'tck_test';
+        
+        beforeEach(async () => {
+            driver = createDriver();
+        }, timeout);
+        
+        test('should create a record', async () => {
+            const result = await driver.create(TEST_OBJECT, {
+                name: 'Test',
+                email: 'test@example.com'
+            });
+            
+            expect(result).toBeDefined();
+            expect(result.id).toBeDefined();
+        }, timeout);
+    });
+}

packages/tools/driver-tck/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}