feat: 添加钩子生命周期事件和钩子定义模式，支持数据访问生命周期中的自定义逻辑

Author: hotlong

packages/objectql/src/index.ts

@@ -6,6 +6,20 @@ import { SchemaRegistry } from './registry';
 // Export Registry for consumers
 export { SchemaRegistry } from './registry';
 
+/**
+ * Hook Context
+ */
+export interface HookContext {
+  object: string;
+  driver: DriverInterface;
+  method: 'find' | 'insert' | 'update' | 'delete' | 'count';
+  args: any; // The arguments passed to the method (can be modified)
+  result?: any; // The result of the operation (for after hooks)
+  error?: any; // The error if one occurred (for error hooks)
+}
+
+export type HookHandler = (context: HookContext) => Promise<void> | void;
+
 /**
  * Host Context provided to plugins
  */
@@ -23,6 +37,14 @@ export class ObjectQL {
   private drivers = new Map<string, DriverInterface>();
   private defaultDriver: string | null = null;
 
+  // Hooks Registry
+  private hooks: Record<string, HookHandler[]> = {
+    'beforeFind': [], 'afterFind': [],
+    'beforeInsert': [], 'afterInsert': [],
+    'beforeUpdate': [], 'afterUpdate': [],
+    'beforeDelete': [], 'afterDelete': [],
+  };
+  
   // Host provided context additions (e.g. Server router)
   private hostContext: Record<string, any> = {};
 
@@ -94,6 +116,27 @@ export class ObjectQL {
     }
   }
 
+  /**
+   * Register a hook
+   * @param event The event name (e.g. 'beforeFind', 'afterInsert')
+   * @param handler The handler function
+   */
+  registerHook(event: string, handler: HookHandler) {
+    if (!this.hooks[event]) {
+        this.hooks[event] = [];
+    }
+    this.hooks[event].push(handler);
+    console.log(`[ObjectQL] Registered hook for ${event}`);
+  }
+
+  private async triggerHooks(event: string, context: HookContext) {
+    const handlers = this.hooks[event] || [];
+    for (const handler of handlers) {
+      // In a real system, we might want to catch errors here or allow them to bubble up
+      await handler(context);
+    }
+  }
+
   /**
    * Register a new storage driver
    */
@@ -189,27 +232,35 @@ export class ObjectQL {
     // Normalize QueryAST
     let ast: QueryAST;
     if (query.where || query.fields || query.orderBy || query.limit) {
-      // It's likely a QueryAST or partial QueryAST
-      // Ensure 'object' is set correctly
-      ast = {
-        object, // Force object name to match the call
-        ...query
-      } as QueryAST;
+      ast = { object, ...query } as QueryAST;
     } else {
-      // It's a direct filter object (Simplified syntax)
-      // e.g. find('account', { name: 'Acme' })
-      ast = {
-        object,
-        where: query 
-      } as QueryAST;
+      ast = { object, where: query } as QueryAST;
     }
 
-    // Default limit protection
-    if (ast.limit === undefined) {
-       ast.limit = 100;
-    }
+    if (ast.limit === undefined) ast.limit = 100;
 
-    return driver.find(object, ast, options);
+    // Trigger Before Hook
+    const hookContext: HookContext = {
+        object,
+        driver,
+        method: 'find',
+        args: { ast, options } // Hooks can modify AST here
+    };
+    await this.triggerHooks('beforeFind', hookContext);
+
+    try {
+        const result = await driver.find(object, hookContext.args.ast, hookContext.args.options);
+        
+        // Trigger After Hook
+        hookContext.result = result;
+        await this.triggerHooks('afterFind', hookContext);
+        
+        return hookContext.result;
+    } catch (e) {
+        hookContext.error = e;
+        // await this.triggerHooks('error', hookContext);
+        throw e;
+    }
   }
 
   async findOne(object: string, idOrQuery: string | any, options?: DriverOptions) {
@@ -247,21 +298,60 @@ export class ObjectQL {
        // validate(schema, data);
     }
 
-    // 2. Run "Before Insert" Triggers
+    // 2. Trigger Before Hook
+    const hookContext: HookContext = {
+        object,
+        driver,
+        method: 'insert',
+        args: { data, options }
+    };
+    await this.triggerHooks('beforeInsert', hookContext);
 
-    const result = await driver.create(object, data, options);
+    // 3. Execute Driver
+    const result = await driver.create(object, hookContext.args.data, hookContext.args.options);
 
-    // 3. Run "After Insert" Triggers
-    return result;
+    // 4. Trigger After Hook
+    hookContext.result = result;
+    await this.triggerHooks('afterInsert', hookContext);
+
+    return hookContext.result;
   }
 
   async update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions) {
     const driver = this.getDriver(object);
-    return driver.update(object, id, data, options);
+
+    const hookContext: HookContext = {
+        object,
+        driver,
+        method: 'update',
+        args: { id, data, options }
+    };
+    await this.triggerHooks('beforeUpdate', hookContext);
+
+    const result = await driver.update(object, hookContext.args.id, hookContext.args.data, hookContext.args.options);
+
+    hookContext.result = result;
+    await this.triggerHooks('afterUpdate', hookContext);
+    
+    return hookContext.result;
   }
 
   async delete(object: string, id: string | number, options?: DriverOptions) {
     const driver = this.getDriver(object);
-    return driver.delete(object, id, options);
+
+    const hookContext: HookContext = {
+        object,
+        driver,
+        method: 'delete',
+        args: { id, options }
+    };
+    await this.triggerHooks('beforeDelete', hookContext);
+
+    const result = await driver.delete(object, hookContext.args.id, hookContext.args.options);
+
+    hookContext.result = result;
+    await this.triggerHooks('afterDelete', hookContext);
+
+    return hookContext.result;
   }
 }

packages/spec/src/data/hook.zod.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+
+/**
+ * Hook Lifecycle Events
+ * Defines the interception points in the ObjectQL execution pipeline.
+ */
+export const HookEvent = z.enum([
+  // Read Operations
+  'beforeFind', 'afterFind',
+  'beforeFindOne', 'afterFindOne',
+  'beforeCount', 'afterCount',
+  'beforeAggregate', 'afterAggregate',
+
+  // Write Operations
+  'beforeInsert', 'afterInsert',
+  'beforeUpdate', 'afterUpdate',
+  'beforeDelete', 'afterDelete',
+]);
+
+/**
+ * Hook Definition Schema
+ * 
+ * Hooks serve as the "Logic Layer" in ObjectStack, allowing developers to 
+ * inject custom code during the data access lifecycle.
+ * 
+ * Use cases:
+ * - Data Enrichment (Default values, Calculated fields)
+ * - Validation (Complex business rules)
+ * - Side Effects (Sending emails, Syncing to external systems)
+ * - Security (Filtering data based on context)
+ */
+export const HookSchema = z.object({
+  /**
+   * Unique identifier for the hook
+   * Required for debugging and overriding.
+   */
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Hook unique name (snake_case)'),
+
+  /**
+   * Human readable label
+   */
+  label: z.string().optional().describe('Description of what this hook does'),
+
+  /**
+   * Target Object(s)
+   * can be:
+   * - Single object: "account"
+   * - List of objects: ["account", "contact"]
+   * - Wildcard: "*" (All objects)
+   */
+  object: z.union([z.string(), z.array(z.string())]).describe('Target object(s)'),
+
+  /**
+   * Events to subscribe to
+   * Combinations of timing (before/after) and action (find/insert/update/delete/etc)
+   */
+  events: z.array(HookEvent).describe('Lifecycle events'),
+
+  /**
+   * Handler Logic
+   * Reference to a registered function in the plugin system.
+   */
+  handler: z.string().optional().describe('Function handler name (e.g. "my_plugin.validate_account")'),
+
+  /**
+   * Inline Script (Optional)
+   * For simple logic without a full plugin.
+   * @deprecated Prefer 'handler' for better testability and type safety.
+   */
+  script: z.string().optional().describe('Inline script body'),
+
+  /**
+   * Execution Order
+   * Lower numbers run first.
+   * - System Hooks: 0-99
+   * - App Hooks: 100-999
+   * - User Hooks: 1000+
+   */
+  priority: z.number().default(100).describe('Execution priority'),
+
+  /**
+   * Async / Background Execution
+   * If true, the hook runs in the background and does not block the transaction.
+   * Only applicable for 'after*' events.
+   * Default: false (Blocking)
+   */
+  async: z.boolean().default(false).describe('Run specifically as fire-and-forget'),
+
+  /**
+   * Error Policy
+   * What to do if the hook throws an exception?
+   * - abort: Rollback transaction (if blocking)
+   * - log: Log error and continue
+   */
+  onError: z.enum(['abort', 'log']).default('abort').describe('Error handling strategy'),
+});
+
+export type Hook = z.infer<typeof HookSchema>;
+export type HookEventType = z.infer<typeof HookEvent>;

packages/spec/src/data/index.ts

@@ -3,4 +3,6 @@ export * from './filter.zod';
 export * from './object.zod';
 export * from './field.zod';
 export * from './validation.zod';
+export * from './hook.zod';
+
 export * from './dataset.zod';

packages/spec/src/permission/index.ts

@@ -9,4 +9,3 @@
 
 export * from './permission.zod';
 export * from './sharing.zod';
-export * from './trigger.zod';