feat: Create @objectql/driver-utils shared utilities package

- Created comprehensive utility package for driver development
- QueryAST normalization and parsing utilities
- FilterCondition evaluation and conversion
- Error handling with standard error codes
- ID generation (nanoid, UUID, sequential, timestamp)
- Timestamp management utilities
- Transaction state management utilities
- Comprehensive documentation and usage examples

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

Author: Copilot

packages/drivers/utils/README.md

@@ -0,0 +1,182 @@
+# @objectql/driver-utils
+
+Shared utilities for ObjectQL drivers to reduce code duplication and standardize driver implementations.
+
+## Overview
+
+This package provides common functionality used across all ObjectQL drivers:
+
+- **QueryAST normalization** - Convert between legacy and modern query formats
+- **FilterCondition evaluation** - MongoDB-style query evaluation and conversion
+- **Error handling** - Standard error codes and error creation utilities
+- **ID generation** - Multiple ID generation strategies (nanoid, UUID, sequential, timestamp)
+- **Timestamp management** - Automatic timestamp handling for create/update operations
+- **Transaction utilities** - Transaction state management and helpers
+
+## Installation
+
+```bash
+pnpm add @objectql/driver-utils
+```
+
+## Usage
+
+### QueryAST Normalization
+
+```typescript
+import { normalizeQuery, normalizeOrderBy, applySorting, applyPagination } from '@objectql/driver-utils';
+
+// Normalize query from various formats
+const normalized = normalizeQuery({
+  filters: { role: 'admin' }, // Legacy format
+  sort: [['age', 'asc']],
+  skip: 10,
+  limit: 20
+});
+// Returns: { where: {...}, orderBy: [...], offset: 10, limit: 20 }
+
+// Apply sorting to records
+const sorted = applySorting(records, [
+  { field: 'age', order: 'asc' },
+  { field: 'name', order: 'desc' }
+]);
+
+// Apply pagination
+const paginated = applyPagination(records, 10, 20); // offset: 10, limit: 20
+```
+
+### FilterCondition Evaluation
+
+```typescript
+import { evaluateFilter, filterRecords, isFilterCondition } from '@objectql/driver-utils';
+
+// Evaluate a single record against a condition
+const matches = evaluateFilter(record, {
+  age: { $gt: 18 },
+  role: 'user'
+});
+
+// Filter an array of records
+const filtered = filterRecords(records, {
+  $or: [
+    { status: 'active' },
+    { priority: { $gte: 5 } }
+  ]
+});
+
+// Check if value is a FilterCondition
+if (isFilterCondition(query.where)) {
+  // Handle MongoDB-style query
+}
+```
+
+### Error Handling
+
+```typescript
+import {
+  createRecordNotFoundError,
+  createDuplicateRecordError,
+  createValidationError,
+  wrapError,
+  DriverError
+} from '@objectql/driver-utils';
+
+// Throw standard errors
+throw createRecordNotFoundError('users', userId);
+throw createDuplicateRecordError('users', userId);
+
+// Wrap native errors
+try {
+  // ... database operation
+} catch (error) {
+  throw wrapError(error as Error, {
+    operation: 'create',
+    objectName: 'users'
+  });
+}
+```
+
+### ID Generation
+
+```typescript
+import { IDGenerator, generateNanoId, generateUUID, generateTimestampId } from '@objectql/driver-utils';
+
+// Using ID Generator
+const idGen = new IDGenerator();
+const id1 = idGen.generateSequential('users'); // "1"
+const id2 = idGen.generateSequential('users', 'usr_'); // "usr_2"
+const id3 = idGen.generateRandom(16); // Random nanoid
+
+// Direct functions
+const nanoId = generateNanoId(16);
+const uuid = generateUUID();
+const timestampId = generateTimestampId('doc');
+```
+
+### Timestamp Utilities
+
+```typescript
+import { addCreateTimestamps, addUpdateTimestamps, getCurrentTimestamp } from '@objectql/driver-utils';
+
+// Add timestamps for create
+const newRecord = addCreateTimestamps({ name: 'Alice' });
+// Returns: { name: 'Alice', created_at: '2026-02-02T...', updated_at: '2026-02-02T...' }
+
+// Add timestamps for update
+const updated = addUpdateTimestamps(
+  { email: 'new@example.com' },
+  existingRecord.created_at
+);
+// Returns: { email: '...', created_at: '<preserved>', updated_at: '2026-02-02T...' }
+```
+
+### Transaction Utilities
+
+```typescript
+import {
+  createTransaction,
+  generateTransactionId,
+  isTransactionActive,
+  markCommitted,
+  TransactionState
+} from '@objectql/driver-utils';
+
+// Create transaction
+const tx = createTransaction();
+console.log(tx.id); // "tx_1234567890_abc123"
+console.log(tx.state); // TransactionState.ACTIVE
+
+// Check state
+if (isTransactionActive(tx)) {
+  // Execute operations
+}
+
+// Update state
+markCommitted(tx);
+console.log(tx.state); // TransactionState.COMMITTED
+```
+
+## API Reference
+
+See individual module documentation for detailed API information:
+
+- [query-ast.ts](./src/query-ast.ts) - Query normalization and parsing
+- [filter-condition.ts](./src/filter-condition.ts) - Filter evaluation and conversion
+- [error-handler.ts](./src/error-handler.ts) - Error handling utilities
+- [id-generator.ts](./src/id-generator.ts) - ID generation strategies
+- [timestamp-utils.ts](./src/timestamp-utils.ts) - Timestamp management
+- [transaction-utils.ts](./src/transaction-utils.ts) - Transaction helpers
+
+## Benefits
+
+Using `@objectql/driver-utils` in your driver implementation provides:
+
+1. **Reduced Code Duplication** - Common patterns extracted and tested
+2. **Consistency** - All drivers behave the same way for core operations
+3. **Maintainability** - Bug fixes and improvements benefit all drivers
+4. **Type Safety** - Full TypeScript support with proper type definitions
+5. **Testing** - Shared utilities are thoroughly tested
+
+## License
+
+MIT

packages/drivers/utils/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@objectql/driver-utils",
+  "version": "4.0.3",
+  "description": "Shared utilities for ObjectQL drivers - QueryAST parsing, FilterCondition evaluation, error handling",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "keywords": [
+    "objectql",
+    "driver",
+    "utils",
+    "queryast",
+    "filter"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@objectql/types": "workspace:*",
+    "@objectstack/spec": "^0.8.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "jest": "^30.0.0",
+    "typescript": "^5.3.0"
+  }
+}

packages/drivers/utils/src/error-handler.ts

@@ -0,0 +1,174 @@
+/**
+ * Error Handling Utilities for Drivers
+ * 
+ * Provides standard error handling and error creation
+ */
+
+/**
+ * Base driver error class
+ */
+export class DriverError extends Error {
+    public readonly code: string;
+    public readonly details?: any;
+    
+    constructor(params: { code: string; message: string; details?: any }) {
+        super(params.message);
+        this.code = params.code;
+        this.details = params.details;
+        this.name = 'DriverError';
+        
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, DriverError);
+        }
+    }
+}
+
+/**
+ * Standard error codes for drivers
+ */
+export const DriverErrorCodes = {
+    RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
+    DUPLICATE_RECORD: 'DUPLICATE_RECORD',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    CONNECTION_ERROR: 'CONNECTION_ERROR',
+    TRANSACTION_ERROR: 'TRANSACTION_ERROR',
+    QUERY_ERROR: 'QUERY_ERROR',
+    INVALID_QUERY: 'INVALID_QUERY',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    DRIVER_ERROR: 'DRIVER_ERROR'
+} as const;
+
+export type DriverErrorCode = typeof DriverErrorCodes[keyof typeof DriverErrorCodes];
+
+/**
+ * Create a standard error for record not found
+ * 
+ * @param objectName - Name of the object
+ * @param id - ID of the record
+ * @returns DriverError instance
+ */
+export function createRecordNotFoundError(objectName: string, id: string | number): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.RECORD_NOT_FOUND,
+        message: `Record with id '${id}' not found in '${objectName}'`,
+        details: { objectName, id }
+    });
+}
+
+/**
+ * Create a standard error for duplicate record
+ * 
+ * @param objectName - Name of the object
+ * @param id - ID of the record
+ * @returns DriverError instance
+ */
+export function createDuplicateRecordError(objectName: string, id: string | number): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.DUPLICATE_RECORD,
+        message: `Record with id '${id}' already exists in '${objectName}'`,
+        details: { objectName, id }
+    });
+}
+
+/**
+ * Create a standard error for validation failure
+ * 
+ * @param message - Error message
+ * @param details - Additional details
+ * @returns DriverError instance
+ */
+export function createValidationError(message: string, details?: any): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.VALIDATION_ERROR,
+        message,
+        details
+    });
+}
+
+/**
+ * Create a standard error for connection issues
+ * 
+ * @param message - Error message
+ * @param details - Additional details
+ * @returns DriverError instance
+ */
+export function createConnectionError(message: string, details?: any): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.CONNECTION_ERROR,
+        message,
+        details
+    });
+}
+
+/**
+ * Create a standard error for transaction issues
+ * 
+ * @param message - Error message
+ * @param details - Additional details
+ * @returns DriverError instance
+ */
+export function createTransactionError(message: string, details?: any): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.TRANSACTION_ERROR,
+        message,
+        details
+    });
+}
+
+/**
+ * Create a standard error for query issues
+ * 
+ * @param message - Error message
+ * @param details - Additional details
+ * @returns DriverError instance
+ */
+export function createQueryError(message: string, details?: any): DriverError {
+    return new DriverError({
+        code: DriverErrorCodes.QUERY_ERROR,
+        message,
+        details
+    });
+}
+
+/**
+ * Wrap a native error into a DriverError
+ * 
+ * @param error - Native error to wrap
+ * @param context - Additional context information
+ * @returns DriverError instance
+ */
+export function wrapError(error: Error, context?: { operation?: string; objectName?: string; details?: any }): DriverError {
+    if (error instanceof DriverError) {
+        return error;
+    }
+    
+    return new DriverError({
+        code: DriverErrorCodes.DRIVER_ERROR,
+        message: error.message,
+        details: {
+            originalError: error.name,
+            stack: error.stack,
+            ...context
+        }
+    });
+}
+
+/**
+ * Safe error handler that ensures errors are properly formatted
+ * 
+ * @param fn - Function to wrap
+ * @returns Wrapped function that catches and formats errors
+ */
+export function withErrorHandling<T extends (...args: any[]) => Promise<any>>(
+    fn: T,
+    context?: { operation?: string; objectName?: string }
+): T {
+    return (async (...args: any[]) => {
+        try {
+            return await fn(...args);
+        } catch (error) {
+            throw wrapError(error as Error, context);
+        }
+    }) as T;
+}