docs: enhance JSDoc and README for Redis driver v4.0

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

Author: Copilot

packages/drivers/redis/README.md

@@ -2,13 +2,20 @@
 
 > ⚠️ **Note**: This is an **example/template implementation** to demonstrate how to create custom ObjectQL drivers. It is not production-ready and serves as a reference for driver development.
 
+**Version 4.0.0** - Now compliant with DriverInterface from @objectstack/spec
+
 ## Overview
 
 The Redis Driver is a reference implementation showing how to adapt a key-value store (Redis) to work with ObjectQL's universal data protocol. While Redis is primarily designed for caching and simple key-value operations, this driver demonstrates how to map ObjectQL's rich query interface to a simpler database model.
 
+This driver implements both the legacy Driver interface from @objectql/types and the standard DriverInterface from @objectstack/spec for full compatibility with the new kernel-based plugin system.
+
 ## Features
 
 - ✅ Basic CRUD operations (Create, Read, Update, Delete)
+- ✅ **v4.0**: executeQuery() with QueryAST support
+- ✅ **v4.0**: executeCommand() with unified command interface
+- ✅ **v4.0**: Bulk operations (bulkCreate, bulkUpdate, bulkDelete) using Redis PIPELINE
 - ✅ Query filtering (in-memory)
 - ✅ Sorting (in-memory)
 - ✅ Pagination (skip/limit)
@@ -136,6 +143,7 @@ new RedisDriver(config: RedisDriverConfig)
 
 All standard Driver interface methods are implemented:
 
+**Legacy Driver Interface:**
 - `find(objectName, query, options)` - Query multiple records
 - `findOne(objectName, id, query, options)` - Get single record by ID
 - `create(objectName, data, options)` - Create new record
@@ -144,6 +152,110 @@ All standard Driver interface methods are implemented:
 - `count(objectName, filters, options)` - Count matching records
 - `disconnect()` - Close Redis connection
 
+**DriverInterface v4.0 Methods:**
+- `executeQuery(ast, options)` - Execute queries using QueryAST format
+- `executeCommand(command, options)` - Execute commands (create, update, delete, bulk operations)
+
+### executeQuery Examples
+
+The new `executeQuery` method uses the QueryAST format from @objectstack/spec:
+
+```typescript
+// Basic query
+const result = await driver.executeQuery({
+  object: 'users',
+  fields: ['name', 'email']
+});
+console.log(result.value); // Array of users
+console.log(result.count); // Number of results
+
+// Query with filters
+const result = await driver.executeQuery({
+  object: 'users',
+  filters: {
+    type: 'comparison',
+    field: 'age',
+    operator: '>',
+    value: 18
+  },
+  sort: [{ field: 'name', order: 'asc' }],
+  top: 10,
+  skip: 0
+});
+
+// Complex filters (AND/OR)
+const result = await driver.executeQuery({
+  object: 'users',
+  filters: {
+    type: 'and',
+    children: [
+      { type: 'comparison', field: 'role', operator: '=', value: 'user' },
+      { type: 'comparison', field: 'age', operator: '>', value: 30 }
+    ]
+  }
+});
+```
+
+### executeCommand Examples
+
+The new `executeCommand` method provides a unified interface for mutations:
+
+```typescript
+// Create a record
+const result = await driver.executeCommand({
+  type: 'create',
+  object: 'users',
+  data: { name: 'Alice', email: 'alice@example.com' }
+});
+console.log(result.success); // true
+console.log(result.data); // Created user object
+console.log(result.affected); // 1
+
+// Update a record
+const result = await driver.executeCommand({
+  type: 'update',
+  object: 'users',
+  id: 'user-123',
+  data: { email: 'newemail@example.com' }
+});
+
+// Delete a record
+const result = await driver.executeCommand({
+  type: 'delete',
+  object: 'users',
+  id: 'user-123'
+});
+
+// Bulk create (uses Redis PIPELINE for performance)
+const result = await driver.executeCommand({
+  type: 'bulkCreate',
+  object: 'users',
+  records: [
+    { name: 'Alice', age: 30 },
+    { name: 'Bob', age: 25 },
+    { name: 'Charlie', age: 35 }
+  ]
+});
+console.log(result.affected); // 3
+
+// Bulk update
+const result = await driver.executeCommand({
+  type: 'bulkUpdate',
+  object: 'users',
+  updates: [
+    { id: 'user-1', data: { age: 31 } },
+    { id: 'user-2', data: { age: 26 } }
+  ]
+});
+
+// Bulk delete
+const result = await driver.executeCommand({
+  type: 'bulkDelete',
+  object: 'users',
+  ids: ['user-1', 'user-2', 'user-3']
+});
+```
+
 ## Example: Using as Cache Layer
 
 Redis works great as a caching layer in front of another driver:

packages/drivers/redis/src/index.ts

@@ -36,25 +36,66 @@ import { createClient, RedisClientType } from 'redis';
 
 /**
  * Command interface for executeCommand method
+ * 
+ * This interface defines the structure for all mutation operations
+ * (create, update, delete, and their bulk variants) in the v4.0 DriverInterface.
+ * 
+ * @example
+ * // Create a single record
+ * const cmd: Command = { type: 'create', object: 'users', data: { name: 'Alice' } };
+ * 
+ * @example
+ * // Update a record
+ * const cmd: Command = { type: 'update', object: 'users', id: '123', data: { email: 'new@example.com' } };
+ * 
+ * @example
+ * // Bulk create multiple records
+ * const cmd: Command = { 
+ *   type: 'bulkCreate', 
+ *   object: 'users', 
+ *   records: [{ name: 'Alice' }, { name: 'Bob' }] 
+ * };
  */
 export interface Command {
+    /** Command type: create, update, delete, or their bulk variants */
     type: 'create' | 'update' | 'delete' | 'bulkCreate' | 'bulkUpdate' | 'bulkDelete';
+    /** Target object name */
     object: string;
+    /** Data for create/update operations */
     data?: any;
+    /** Record ID for single update/delete operations */
     id?: string | number;
+    /** Array of IDs for bulkDelete operation */
     ids?: Array<string | number>;
+    /** Array of records for bulkCreate operation */
     records?: any[];
+    /** Array of updates for bulkUpdate operation */
     updates?: Array<{id: string | number, data: any}>;
+    /** Additional command-specific options */
     options?: any;
 }
 
 /**
  * Command result interface
+ * 
+ * Standardized result format for all executeCommand operations.
+ * 
+ * @example
+ * // Successful create
+ * { success: true, data: { id: '123', name: 'Alice' }, affected: 1 }
+ * 
+ * @example
+ * // Failed operation
+ * { success: false, error: 'Record not found', affected: 0 }
  */
 export interface CommandResult {
+    /** Whether the command executed successfully */
     success: boolean;
+    /** The resulting data (for create/update operations) */
     data?: any;
+    /** Number of records affected by the operation */
     affected: number;
+    /** Error message if the command failed */
     error?: string;
 }
 
@@ -325,12 +366,41 @@ export class RedisDriver implements Driver, DriverInterface {
     /**
      * Execute a query (DriverInterface v4.0 method)
      * 
-     * This method handles all read operations using the QueryAST format.
-     * Converts QueryAST to legacy query format and delegates to find().
+     * This method handles all read operations using the QueryAST format from @objectstack/spec.
+     * It provides a standardized query interface that supports:
+     * - Field selection (projection)
+     * - Filter conditions (using FilterNode AST)
+     * - Sorting
+     * - Pagination (skip/top)
+     * - Grouping and aggregations (delegated to find)
+     * 
+     * The method converts the QueryAST format to the legacy query format and delegates
+     * to the existing find() method for backward compatibility.
      * 
-     * @param ast - The query AST
+     * @param ast - The query Abstract Syntax Tree
      * @param options - Optional execution options
-     * @returns Query results with count
+     * @returns Object containing query results and count
+     * 
+     * @example
+     * // Simple query
+     * const result = await driver.executeQuery({
+     *   object: 'users',
+     *   fields: ['name', 'email']
+     * });
+     * 
+     * @example
+     * // Query with filters and sorting
+     * const result = await driver.executeQuery({
+     *   object: 'users',
+     *   filters: {
+     *     type: 'comparison',
+     *     field: 'age',
+     *     operator: '>',
+     *     value: 18
+     *   },
+     *   sort: [{ field: 'name', order: 'asc' }],
+     *   top: 10
+     * });
      */
     async executeQuery(ast: QueryAST, options?: any): Promise<{ value: any[]; count?: number }> {
         const objectName = ast.object || '';
@@ -356,16 +426,54 @@ export class RedisDriver implements Driver, DriverInterface {
     /**
      * Execute a command (DriverInterface v4.0 method)
      * 
-     * This method handles all mutation operations (create, update, delete)
-     * using a unified command interface.
+     * This method provides a unified interface for all mutation operations (create, update, delete)
+     * using the Command pattern from @objectstack/spec.
+     * 
+     * Supports both single operations and bulk operations:
+     * - Single: create, update, delete
+     * - Bulk: bulkCreate, bulkUpdate, bulkDelete
      * 
-     * Supports both single operations and bulk operations using Redis PIPELINE
-     * for optimal performance.
+     * Bulk operations use Redis PIPELINE for optimal performance, executing multiple
+     * commands in a single round-trip to the server.
      * 
-     * @param command - The command to execute
-     * @param parameters - Optional command parameters (unused in this driver)
+     * All operations return a standardized CommandResult with:
+     * - success: boolean indicating operation success/failure
+     * - data: the resulting data (for create/update)
+     * - affected: number of records affected
+     * - error: error message if operation failed
+     * 
+     * @param command - The command to execute (see Command interface)
      * @param options - Optional execution options
-     * @returns Command execution result
+     * @returns Standardized command execution result
+     * 
+     * @example
+     * // Create a single record
+     * const result = await driver.executeCommand({
+     *   type: 'create',
+     *   object: 'users',
+     *   data: { name: 'Alice', email: 'alice@example.com' }
+     * });
+     * 
+     * @example
+     * // Bulk create multiple records
+     * const result = await driver.executeCommand({
+     *   type: 'bulkCreate',
+     *   object: 'users',
+     *   records: [
+     *     { name: 'Alice' },
+     *     { name: 'Bob' },
+     *     { name: 'Charlie' }
+     *   ]
+     * });
+     * 
+     * @example
+     * // Update a record
+     * const result = await driver.executeCommand({
+     *   type: 'update',
+     *   object: 'users',
+     *   id: 'user-123',
+     *   data: { email: 'newemail@example.com' }
+     * });
      */
     async executeCommand(command: Command, options?: any): Promise<CommandResult> {
         try {
@@ -506,9 +614,31 @@ export class RedisDriver implements Driver, DriverInterface {
 
     /**
      * Convert FilterNode (QueryAST format) to legacy filter array format
-     * This allows reuse of existing filter logic while supporting new QueryAST
      * 
+     * This method bridges the gap between the new QueryAST filter format (tree-based)
+     * and the legacy array-based filter format used internally by the driver.
+     * 
+     * QueryAST FilterNode format:
+     * - type: 'comparison' | 'and' | 'or' | 'not'
+     * - field, operator, value for comparisons
+     * - children for logical operators
+     * 
+     * Legacy format:
+     * - Array of conditions: [field, operator, value]
+     * - String separators: 'and', 'or'
+     * - Example: [['age', '>', 18], 'and', ['role', '=', 'user']]
+     * 
+     * @param node - The FilterNode to convert
+     * @returns Legacy filter array format, or undefined if no filters
      * @private
+     * 
+     * @example
+     * // Input: { type: 'comparison', field: 'age', operator: '>', value: 18 }
+     * // Output: [['age', '>', 18]]
+     * 
+     * @example
+     * // Input: { type: 'and', children: [...] }
+     * // Output: [['field1', '=', 'val1'], 'and', ['field2', '>', 10]]
      */
     private convertFilterNodeToLegacy(node?: FilterNode): any {
         if (!node) return undefined;
@@ -563,10 +693,22 @@ export class RedisDriver implements Driver, DriverInterface {
     /**
      * Generate Redis key for an object record
      * 
-     * Strategy: objectName:id
-     * Example: users:user-123
+     * This method implements the key naming strategy for storing records in Redis.
+     * The strategy uses a simple pattern: `objectName:id`
      * 
+     * This ensures:
+     * - Easy querying by pattern (e.g., `users:*` to find all user records)
+     * - Clear namespace separation between different object types
+     * - Human-readable keys for debugging
+     * 
+     * @param objectName - The object/collection name
+     * @param id - The record ID
+     * @returns Redis key in format "objectName:id"
      * @private
+     * 
+     * @example
+     * generateRedisKey('users', '123') // Returns: 'users:123'
+     * generateRedisKey('orders', 'order-456') // Returns: 'orders:order-456'
      */
     private generateRedisKey(objectName: string, id: string | number): string {
         return `${objectName}:${id}`;