@zucker-framework/event 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,813 @@
+import { ClassConstructor } from 'class-transformer';
+import { OnModuleInit, OnModuleDestroy, DynamicModule } from '@nestjs/common';
+
+declare enum EntityEventType {
+    CREATE = "create",
+    /** modify */
+    MODIFY = "modify",
+    DELETE = "delete",
+    /** save */
+    SAVE = "save",
+    QUERY = "query",
+    /**
+     * @deprecated 请使用 MODIFY
+     */
+    UPDATE = "modify"
+}
+declare enum EntityEventPhase {
+    /**
+     * PREPARE 阶段 — 实体数据预处理
+     *
+     * 契约：监听器可以修改 event.entity 上的字段值，
+     * 修改后的数据会流入后续的数据库操作。
+     * 典型用途：自动填充 creatorId/createdAt、数据清洗、默认值设置。
+     */
+    PREPARE = "prepare",
+    /**
+     * BEFORE 阶段 — 操作前校验与拦截
+     *
+     * 契约：监听器可以调用 event.cancel() 取消操作，
+     * BaseService 将在此阶段后检查 cancelled 标志并抛出 OperationCancelledException。
+     * 典型用途：业务规则校验、权限检查、并发控制。
+     */
+    BEFORE = "before",
+    /**
+     * AFTER 阶段 — 操作完成后的后续处理
+     *
+     * 契约：数据已持久化，此阶段用于触发副作用。
+     * 在事务内时，建议使用 TransactionUtils.afterCommit() 确保 commit 后才执行。
+     */
+    AFTER = "after"
+}
+/**
+ * 所有事件阶段
+ *
+ * 便捷常量，包含 PREPARE、BEFORE 和 AFTER 三个阶段。
+ */
+declare const ALL_EVENT_PHASES: readonly EntityEventPhase[];
+interface EntityEvent<T = unknown> {
+    type: EntityEventType;
+    phase: EntityEventPhase;
+    entityType: string;
+    entity: T | T[];
+    timestamp: number;
+    /**
+     * 修改前的实体数据
+     *
+     * 仅在 MODIFY 类型事件中有值。
+     * before 保存旧数据，entity 保存新数据；二者均支持单条实体或实体列表。
+     */
+    readonly before?: T | T[];
+    /** 事件是否已被取消（仅 BEFORE 阶段有效） */
+    readonly cancelled: boolean;
+    /**
+     * 取消操作（仅 BEFORE 阶段有意义）
+     * 调用后 BaseService 将抛出 OperationCancelledException
+     * @param reason 取消原因，会包含在异常消息中
+     */
+    cancel(reason?: string): void;
+    /** 取消原因 */
+    readonly cancelReason?: string;
+}
+/**
+ * Create a new EntityEvent instance with cancel support.
+ * @param type - The event type (CREATE, MODIFY, DELETE, etc.)
+ * @param phase - The event phase (PREPARE, BEFORE, AFTER)
+ * @param entityType - The entity/model name
+ * @param entity - The entity data (single or batch). For MODIFY events this is the "after" data.
+ * @param before - Optional "before" data for MODIFY events
+ * @returns A new EntityEvent with cancel() capability
+ */
+declare function createEntityEvent<T>(type: EntityEventType, phase: EntityEventPhase, entityType: string, entity: T | T[], before?: T | T[]): EntityEvent<T>;
+/**
+ * 生成事件名: entity/{entityType}/{type}/{phase}
+ * 例如: entity/user/create/before
+ *
+ * 使用 `/` 分隔符以匹配 DefaultTopicEventBus 的 delimiter 配置，
+ * 使通配符订阅（如 `entity/* /create/*`）能正确匹配事件名。
+ */
+declare function getEntityEventName(entityType: string, type: EntityEventType, phase: EntityEventPhase): string;
+
+interface EntityEventListener<T = unknown> {
+    onEvent(event: EntityEvent<T>): void | Promise<void>;
+    /**
+     * 监听器优先级，数值越小优先级越高
+     * 默认 0
+     */
+    readonly order?: number;
+}
+/**
+ * 当前用户信息
+ */
+interface CurrentUser {
+    id: string;
+    name?: string;
+}
+/**
+ * 创建者监听器 - Prepare 阶段自动填充创建人/修改人信息
+ *
+ * - CREATE/SAVE: 填充 creatorId, creatorName, createdAt, modifierId, modifierName, updatedAt
+ * - MODIFY/UPDATE: 仅填充 modifierId, modifierName, updatedAt
+ *
+ * 填充规则：
+ * - 使用 ??= 确保不覆盖已有的 creatorId（用户可提前设置）
+ * - modifierId/modifierName 始终覆盖
+ * - order 为最高优先级（HIGHEST_PRECEDENCE）
+ */
+declare class CreatorEventListener implements EntityEventListener {
+    private readonly getCurrentUser;
+    readonly order: number;
+    constructor(getCurrentUser: () => CurrentUser | undefined);
+    onEvent(event: EntityEvent): Promise<void>;
+}
+/**
+ * 组合事件监听器
+ *
+ * 聚合多个 EntityEventListener 并按 order 排序执行。
+ * 数值越小优先级越高。
+ */
+declare class CompositeEventListener<T = unknown> implements EntityEventListener<T> {
+    private listeners;
+    addListener(listener: EntityEventListener<T>): void;
+    removeListener(listener: EntityEventListener<T>): void;
+    onEvent(event: EntityEvent<T>): Promise<void>;
+    getListeners(): readonly EntityEventListener<T>[];
+}
+
+declare const SUBSCRIBE_KEY = "zucker:event:subscribe";
+declare const SUBSCRIBE_METHODS_KEY = "zucker:event:subscribeMethods";
+/**
+ * Subscription feature — controls message scope.
+ * Mirrors jetlinks Subscription.Feature enum.
+ */
+declare enum SubscribeFeature {
+    /** Only subscribe to local process messages */
+    LOCAL = "local",
+    /** Subscribe to messages from the entire cluster */
+    CLUSTER = "cluster",
+    /** Subscribe to shared messages (load-balanced across instances) */
+    SHARED = "shared",
+    /**
+     * Broker mode — 参考 jetlinks Subscription.Feature.broker
+     * Subscribe to messages forwarded by the event broker (cross-node communication).
+     * In jetlinks, broker mode enables EventConnection-based inter-cluster event forwarding.
+     */
+    BROKER = "broker"
+}
+interface SubscribeOptions {
+    /** Topic patterns to subscribe to (supports * and ** wildcards) */
+    topics: string[];
+    /** Subscriber ID — defaults to method name */
+    id?: string;
+    /** Subscription features — defaults to [LOCAL] */
+    features?: SubscribeFeature[];
+    /** Priority — lower value = higher priority. Defaults to Infinity */
+    priority?: number;
+}
+/**
+ * @Subscribe decorator — 参考 jetlinks @Subscribe 注解
+ *
+ * 用于方法上，声明式订阅 TopicEventBus 的消息。
+ * 框架通过扫描带有此装饰器的方法，自动注册订阅。
+ *
+ * 用法：
+ * ```typescript
+ * @Subscribe({ topics: ['/device/ * / * /message'] })
+ * async handleDeviceMessage(payload: DeviceMessage): Promise<void> { ... }
+ *
+ * // 简写：单个 topic
+ * @Subscribe('/device/** ')
+ * async handleAllDevice(payload: unknown): Promise<void> { ... }
+ * ```
+ */
+declare function Subscribe(topicsOrOptions: string | string[] | SubscribeOptions): MethodDecorator;
+/**
+ * Get all @Subscribe method entries from a class.
+ */
+declare function getSubscriptions(target: Function): Array<{
+    propertyKey: string;
+    options: SubscribeOptions;
+}>;
+
+/**
+ * Event handler function that receives a TopicPayload.
+ * @param payload - The topic payload containing topic, data, and headers
+ */
+type EventHandler = (payload: TopicPayload) => void | Promise<void>;
+/**
+ * Legacy handler signature for backward compatibility.
+ * Accepts raw payload and topic string.
+ */
+type LegacyEventHandler = (payload: unknown, topic: string) => void | Promise<void>;
+/**
+ * TopicPayload — 参考 jetlinks TopicPayload
+ *
+ * 封装事件的 topic、payload 和 headers。
+ * jetlinks 的 TopicPayload 包含 topic + Payload(ByteBuf) + headers，
+ * 在 TypeScript 中简化为泛型 payload + Map headers。
+ */
+interface TopicPayload<T = unknown> {
+    /** The topic this event was published to */
+    readonly topic: string;
+    /** The event payload */
+    readonly payload: T;
+    /**
+     * Optional headers — 参考 jetlinks TopicPayload headers
+     * Used for metadata propagation (tracing, source info, etc.)
+     */
+    readonly headers: ReadonlyMap<string, unknown>;
+}
+/**
+ * Create a TopicPayload instance.
+ */
+declare function createTopicPayload<T = unknown>(topic: string, payload: T, headers?: Record<string, unknown> | Map<string, unknown>): TopicPayload<T>;
+/**
+ * Handle returned by subscribe() — call unsubscribe() to stop receiving events.
+ */
+interface Subscription {
+    /** Remove this subscription and stop receiving events */
+    unsubscribe: () => void;
+}
+/**
+ * SubscriptionInfo — 参考 jetlinks Subscription (org.jetlinks.core.event.Subscription)
+ *
+ * 结构化订阅信息，包含：
+ * - subscriberId: 订阅者标识
+ * - topics: 订阅的 topic 模式列表
+ * - features: 订阅特性（local/shared/broker/cluster）
+ * - priority: 优先级（值越小优先级越高，与 jetlinks 一致）
+ */
+interface SubscriptionInfo {
+    /** Unique subscriber ID — 参考 jetlinks Subscription.subscriberId */
+    subscriberId: string;
+    /** Topic patterns to subscribe to (supports *, **, and comma-separated segments) */
+    topics: string[];
+    /** Subscription features — defaults to [LOCAL] */
+    features?: SubscribeFeature[];
+    /** Priority — lower value = higher priority (jetlinks convention) */
+    priority?: number;
+}
+/**
+ * Subscription builder chain — 参考 jetlinks Subscription.builder()
+ */
+interface SubscriptionInfoBuilder {
+    subscriberId(id: string): SubscriptionInfoBuilder;
+    topics(...topics: string[]): SubscriptionInfoBuilder;
+    features(...features: SubscribeFeature[]): SubscriptionInfoBuilder;
+    priority(p: number): SubscriptionInfoBuilder;
+    build(): SubscriptionInfo;
+}
+/**
+ * SubscriptionInfo factory — 参考 jetlinks Subscription.builder() / Subscription.of()
+ */
+declare const SubscriptionBuilder: {
+    /**
+     * Quick factory — 参考 jetlinks Subscription.of(subscriberId, topic, ...features)
+     */
+    of(subscriberId: string, topics: string | string[], ...features: SubscribeFeature[]): SubscriptionInfo;
+    /**
+     * Builder pattern — 参考 jetlinks Subscription.builder()
+     */
+    builder(): SubscriptionInfoBuilder;
+};
+interface TopicEventBus {
+    /**
+     * Publish an event to a topic.
+     * @param topic The topic path
+     * @param payload The event data
+     * @param headers Optional headers for metadata propagation
+     */
+    publish(topic: string, payload: unknown, headers?: Record<string, unknown>): Promise<void>;
+    /**
+     * Subscribe using a structured SubscriptionInfo — 参考 jetlinks EventBus.subscribe(Subscription)
+     */
+    subscribe(subscription: SubscriptionInfo, handler: EventHandler): Subscription;
+    /**
+     * Subscribe with simple arguments (backward compatible).
+     * @param topicPattern Topic pattern with wildcards
+     * @param handler Event handler
+     * @param priority Priority (lower = higher priority, default Infinity)
+     */
+    subscribe(topicPattern: string, handler: EventHandler | LegacyEventHandler, priority?: number): Subscription;
+}
+/**
+ * 基于自定义 Topic 匹配的 EventBus 实现
+ *
+ * 支持：
+ * - * (单级) 和 ** (多级) 通配符
+ * - 逗号分隔的多值匹配: /device/p1/d1,d2/online
+ * - MQTT 通配符自动转换: # -> **, + -> *
+ * - TopicPayload 结构化消息
+ * - 监听器优先级排序（值越小优先级越高，与 jetlinks 一致）
+ *
+ * 参考 jetlinks DefaultEventBus
+ */
+declare class DefaultTopicEventBus implements TopicEventBus {
+    private readonly logger;
+    private handlersByPattern;
+    publish(topic: string, payload: unknown, headers?: Record<string, unknown>): Promise<void>;
+    subscribe(subscriptionOrPattern: SubscriptionInfo | string, handler: EventHandler | LegacyEventHandler, priority?: number): Subscription;
+    private _subscribeSingle;
+    /**
+     * Remove all handlers — used during module shutdown to prevent leaks.
+     */
+    removeAllListeners(): void;
+}
+/**
+ * 通配符匹配：支持 * (单级)、** (多级) 和逗号分隔的多值段
+ *
+ * 逗号分隔支持参考 jetlinks TopicUtils:
+ * /device/p1/d1,d2/online 匹配 /device/p1/d1/online 和 /device/p1/d2/online
+ */
+declare function matchesTopic(pattern: string, topic: string): boolean;
+
+/**
+ * 异步事件接口
+ *
+ * 支持两级异步任务链：
+ * - first: 优先异步任务（在 commit 前先执行）
+ * - async: 普通异步任务
+ *
+ * 执行顺序：first 任务全部完成后，再执行 async 任务。
+ * 错误会沿链传播。
+ */
+interface AsyncEvent<T = unknown> {
+    payload: T;
+    timestamp: number;
+    handled: boolean;
+    markHandled(): void;
+    /** 注册优先异步任务（在普通异步任务之前执行） */
+    first(fn: () => Promise<void>): void;
+    /** 注册普通异步任务 */
+    async(fn: () => Promise<void>): void;
+    /**
+     * 对 first 链进行变换
+     *
+     * 回调接收当前的 first 链 Promise，返回新的 Promise。
+     * 可用于包装事务边界、添加日志等横切逻辑。
+     */
+    transformFirst(mapper: (current: Promise<void>) => Promise<void>): void;
+    /**
+     * 对 async 链进行变换
+     *
+     * 回调接收当前的 async 链 Promise，返回新的 Promise。
+     */
+    transform(mapper: (current: Promise<void>) => Promise<void>): void;
+    /** 执行所有已注册任务：first 先于 async */
+    getAsync(): Promise<void>;
+    /** 是否有监听器注册了异步任务 */
+    readonly hasListener: boolean;
+}
+/**
+ * Create a new AsyncEvent with two-level async task chain support.
+ * First tasks execute before async tasks; errors propagate along the chain.
+ * @param payload - The event payload data
+ * @returns A new AsyncEvent instance
+ *
+ * @example
+ * ```ts
+ * const event = createAsyncEvent({ userId: '123' });
+ * event.first(async () => { /* pre-commit work *\/ });
+ * event.async(async () => { /* post-commit work *\/ });
+ * await event.getAsync(); // executes first, then async tasks
+ * ```
+ */
+declare function createAsyncEvent<T>(payload: T): AsyncEvent<T>;
+
+/**
+ * 验证分组
+ *
+ * 使用 class-validator 的 groups 功能区分创建和更新时的不同校验规则。
+ *
+ * @example
+ * ```ts
+ * class User {
+ *   @IsNotEmpty({ groups: [CREATE_GROUP] })
+ *   name: string;
+ *
+ *   @IsEmail({}, { groups: [CREATE_GROUP, UPDATE_GROUP] })
+ *   email: string;
+ * }
+ * ```
+ */
+declare const CREATE_GROUP = "create";
+declare const UPDATE_GROUP = "update";
+declare const SAVE_GROUP = "save";
+/**
+ * PREPARE 阶段的自动校验监听器
+ *
+ * 在 PREPARE 阶段使用 class-validator 校验实体数据。
+ * 校验失败时，取消操作（event.cancel）。
+ *
+ * 验证规则：
+ * - CREATE/SAVE 操作使用 CreateGroup
+ * - UPDATE/MODIFY 操作使用 UpdateGroup
+ * - 用户可通过 options.groups 覆盖默认分组
+ *
+ * 用法：
+ *   new ValidateEventListener(UserEntity)
+ *   注册到 entity.user.create.prepare 和 entity.user.update.prepare
+ */
+declare class ValidateEventListener<T extends object> implements EntityEventListener<T> {
+    private readonly entityClass;
+    private readonly options?;
+    constructor(entityClass: ClassConstructor<T>, options?: {
+        /** 跳过校验的事件类型 */
+        skipTypes?: EntityEventType[];
+        /** class-validator 的 groups（覆盖默认分组策略） */
+        groups?: string[];
+        /** 是否跳过缺失属性（适用于 partial update） */
+        skipMissingProperties?: boolean;
+    } | undefined);
+    onEvent(event: EntityEvent<T>): Promise<void>;
+    /**
+     * 根据事件类型解析默认的校验分组
+     */
+    private resolveGroups;
+}
+
+/**
+ * 实体事件配置元数据 key
+ */
+declare const ENTITY_EVENT_CONFIG_KEY = "zucker:event:entityEventConfig";
+/**
+ * 实体事件配置
+ */
+interface EntityEventConfig {
+    [EntityEventType.CREATE]?: boolean;
+    [EntityEventType.MODIFY]?: boolean;
+    [EntityEventType.DELETE]?: boolean;
+    [EntityEventType.SAVE]?: boolean;
+    [EntityEventType.QUERY]?: boolean;
+}
+/**
+ * @EnableEntityEvent() 装饰器
+ *
+ * 用于 Service 类，控制哪些实体事件需要发出。
+ * 默认启用 create/modify/delete/save，禁用 query。
+ *
+ * @example
+ * ```ts
+ * @EnableEntityEvent({ query: true })
+ * class UserService extends BaseService<User> { ... }
+ *
+ * @EnableEntityEvent({ delete: false })
+ * class LogService extends BaseService<Log> { ... }
+ * ```
+ */
+declare function EnableEntityEvent(config?: Partial<EntityEventConfig>): ClassDecorator;
+/**
+ * 获取实体事件配置
+ * 如果没有装饰器，返回默认配置（全部启用除 query）
+ */
+declare function getEntityEventConfig(target: Function): EntityEventConfig;
+/**
+ * 检查指定事件类型是否启用
+ */
+declare function isEntityEventEnabled(target: Function, type: EntityEventType): boolean;
+
+/**
+ * 运行时实体事件开关配置
+ *
+ * 支持三个粒度级别的控制（从粗到细）：
+ * 1. 实体级别：enable('user') / disable('user')
+ * 2. 事件类型级别：enable('user', EntityEventType.CREATE)
+ * 3. 事件阶段级别：enable('user', EntityEventType.CREATE, EntityEventPhase.BEFORE)
+ *
+ * 优先级（从高到低）：
+ * 1. 运行时 disable 配置（精确匹配优先）
+ * 2. 运行时 enable 配置（精确匹配优先）
+ * 3. @EnableEntityEvent 装饰器
+ * 4. 默认全部启用
+ *
+ * enable 和 disable 互斥，enable 某个阶段会自动从 disabled 集合中移除，反之亦然。
+ *
+ * 并发安全改进：
+ * 在初次 CRUD 操作并发执行时，多个请求可能同时尝试初始化同一实体类型的事件配置。
+ * 初始化过程同步执行，不跨异步边界。
+ * 使用已初始化标志确保初始化逻辑只执行一次。
+ */
+declare class EntityEventListenerConfigure {
+    private readonly enabled;
+    private readonly disabled;
+    /**
+     * 启用整个实体的事件
+     */
+    enable(entityType: string): void;
+    /**
+     * 启用指定实体的指定事件类型
+     */
+    enable(entityType: string, eventType: EntityEventType): void;
+    /**
+     * 启用指定实体的指定事件类型的指定阶段
+     */
+    enable(entityType: string, eventType: EntityEventType, ...phases: EntityEventPhase[]): void;
+    /**
+     * 禁用整个实体的事件
+     */
+    disable(entityType: string): void;
+    /**
+     * 禁用指定实体的指定事件类型
+     */
+    disable(entityType: string, eventType: EntityEventType): void;
+    /**
+     * 禁用指定实体的指定事件类型的指定阶段
+     */
+    disable(entityType: string, eventType: EntityEventType, ...phases: EntityEventPhase[]): void;
+    /**
+     * 检查某个实体是否启用了事件（实体级别）
+     */
+    isEnabled(entityType: string): boolean;
+    /**
+     * 检查某个实体的某种事件在某个阶段是否启用
+     */
+    isEnabled(entityType: string, eventType: EntityEventType, phase?: EntityEventPhase): boolean;
+    /**
+     * 清除指定实体的运行时覆盖配置
+     */
+    reset(entityType: string, eventType?: EntityEventType, phase?: EntityEventPhase): void;
+    /**
+     * 清除所有运行时覆盖配置
+     */
+    resetAll(): void;
+}
+
+/**
+ * 实体事件监听器自定义接口
+ *
+ * 实现此接口可在应用启动时对 EntityEventListenerConfigure 进行编程式配置。
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyCustomizer implements EntityEventListenerCustomizer {
+ *   customize(configure: EntityEventListenerConfigure): void {
+ *     // 禁用 audit_log 实体的 QUERY 事件
+ *     configure.disable('audit_log', EntityEventType.QUERY);
+ *     // 仅禁用 user 实体的 DELETE.BEFORE 阶段
+ *     configure.disable('user', EntityEventType.DELETE, EntityEventPhase.BEFORE);
+ *   }
+ * }
+ * ```
+ */
+interface EntityEventListenerCustomizer {
+    customize(configure: EntityEventListenerConfigure): void;
+}
+declare const ENTITY_EVENT_LISTENER_CUSTOMIZER = "ENTITY_EVENT_LISTENER_CUSTOMIZER";
+
+/**
+ * 检查当前上下文是否应该触发事件
+ * @param defaultIfEmpty 未设置时的默认值（默认 true）
+ */
+declare function isDoFireEvent(defaultIfEmpty?: boolean): boolean;
+/**
+ * 在回调范围内禁用事件触发
+ *
+ * @example
+ * ```ts
+ * await withoutFireEvent(async () => {
+ *   await service.save(entity); // 不会触发实体事件
+ * });
+ * ```
+ */
+declare function withoutFireEvent<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * 在回调范围内启用事件触发（用于嵌套恢复）
+ */
+declare function withFireEvent<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * 尝试触发事件 — 如果当前上下文禁用了事件则跳过
+ */
+declare function tryFireEvent(task: () => Promise<void>): Promise<void>;
+/**
+ * 创建并返回一个 EntityEvent，便捷方法
+ */
+declare function createSingleEntityEvent<T>(type: EntityEventType, phase: EntityEventPhase, entityType: string, entity: T): EntityEvent<T>;
+/**
+ * 创建并返回一个批量 EntityEvent
+ */
+declare function createBatchEntityEvent<T>(type: EntityEventType, phase: EntityEventPhase, entityType: string, entities: T[]): EntityEvent<T>;
+/**
+ * 创建批量修改事件（带 before/after）
+ *
+ * 修改事件同时包含修改前（before）和修改后（after）的数据列表，
+ * 供监听器对比差异或进行审计日志记录。
+ *
+ * @param phase - 事件阶段
+ * @param entityType - 实体类型名称
+ * @param before - 修改前的实体列表
+ * @param after - 修改后的实体列表
+ */
+declare function createModifyEntityEvent<T>(phase: EntityEventPhase, entityType: string, before: T[], after: T[]): EntityEvent<T> | null;
+/**
+ * 创建批量创建事件
+ */
+declare function createCreatedEntityEvent<T>(phase: EntityEventPhase, entityType: string, entities: T[]): EntityEvent<T>;
+/**
+ * 创建批量删除事件
+ */
+declare function createDeletedEntityEvent<T>(phase: EntityEventPhase, entityType: string, entities: T[]): EntityEvent<T>;
+/**
+ * 创建批量保存事件
+ */
+declare function createSavedEntityEvent<T>(phase: EntityEventPhase, entityType: string, entities: T[]): EntityEvent<T>;
+
+declare const TOPIC_EVENT_BUS = "TOPIC_EVENT_BUS";
+declare class ZuckerEventModule implements OnModuleInit, OnModuleDestroy {
+    private readonly listenerConfigure;
+    private readonly eventBus;
+    private readonly customizers?;
+    constructor(listenerConfigure: EntityEventListenerConfigure, eventBus: TopicEventBus, customizers?: EntityEventListenerCustomizer[] | undefined);
+    /**
+     * 模块初始化时执行所有 EntityEventListenerCustomizer
+     * 通过 EntityEventListenerCustomizer 进行运行时配置
+     */
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    static forRoot(): DynamicModule;
+}
+
+/**
+ * 事件持久化存储接口。
+ * 支持事件溯源和重放。
+ *
+ * 默认无实现（事件只在内存中传播）。
+ * 生产环境可注入数据库实现以支持事件审计和重放。
+ */
+interface EventStore {
+    /** 持久化一个事件 */
+    save(event: StoredEvent): Promise<void>;
+    /** 按主题查询事件 */
+    findByTopic(topic: string, options?: EventQueryOptions): Promise<StoredEvent[]>;
+    /** 按聚合根查询事件 */
+    findByAggregateId(aggregateId: string, options?: EventQueryOptions): Promise<StoredEvent[]>;
+    /** 重放事件（按时间顺序） */
+    replay(topic: string, fromTimestamp?: number): AsyncIterable<StoredEvent>;
+    /** 统计事件数 */
+    count(topic?: string): Promise<number>;
+}
+interface StoredEvent {
+    id?: string;
+    topic: string;
+    aggregateId?: string;
+    aggregateType?: string;
+    payload: unknown;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+    version?: number;
+}
+interface EventQueryOptions {
+    fromTimestamp?: number;
+    toTimestamp?: number;
+    limit?: number;
+    offset?: number;
+}
+declare const EVENT_STORE = "EVENT_STORE";
+
+/**
+ * 集群事件传输接口
+ *
+ * 用于跨进程/跨节点的事件分发。
+ * 本地事件走 TopicEventBus，远程事件走此接口。
+ */
+interface ClusterTransport {
+    /** 将事件广播到集群其他节点 */
+    broadcast(topic: string, payload: unknown): Promise<void>;
+    /** 订阅来自集群其他节点的事件 */
+    onRemoteEvent(handler: (topic: string, payload: unknown) => void): void;
+}
+declare const CLUSTER_TRANSPORT: unique symbol;
+/**
+ * 统一事件总线
+ *
+ * 对标 Claude Code 的 Hook Registry 模式：
+ * 所有事件走同一个管道，通过 topic 模式匹配做路由。
+ *
+ * 整合了:
+ * - TopicEventBus（本地发布/订阅，带 wildcard 匹配）
+ * - EventEmitter2（NestJS 内置，访问日志等）
+ * - ClusterTransport（可选，跨节点广播）
+ *
+ * 用法:
+ * ```ts
+ * // 发布事件（本地 + 集群）
+ * await eventBus.publish('entity/user/create/after', { user });
+ *
+ * // 只发布到本地
+ * await eventBus.publishLocal('access.log', { path, method });
+ *
+ * // 订阅
+ * const sub = eventBus.subscribe('entity/user/**', handler);
+ * sub.unsubscribe();
+ * ```
+ */
+declare class UnifiedEventBus {
+    private readonly cluster?;
+    private readonly logger;
+    private readonly localBus;
+    constructor(localBus: TopicEventBus, cluster?: ClusterTransport | undefined);
+    /**
+     * 发布事件（本地 + 集群）
+     * @param topic 事件主题
+     * @param payload 事件负载
+     */
+    publish(topic: string, payload: unknown): Promise<void>;
+    /**
+     * 仅发布到本地（不广播到集群）
+     * 适用于访问日志等高频、无需跨节点的事件
+     */
+    publishLocal(topic: string, payload: unknown): Promise<void>;
+    /**
+     * 订阅事件（支持 wildcard 模式）
+     * @param pattern 主题匹配模式（支持 * 和 **）
+     * @param handler 事件处理函数
+     */
+    subscribe(pattern: string, handler: EventHandler): Subscription;
+    /**
+     * 发布并等待所有处理完成
+     * 用于需要确保所有 listener 执行完毕的场景（如事务内事件）
+     */
+    publishAndWait(topic: string, payload: unknown): Promise<void>;
+}
+
+/**
+ * 通用操作 Hook 系统
+ *
+ * 对标 Claude Code 的 PreToolUse / PostToolUse hook:
+ * 允许在任意操作前后注入逻辑（审批、记录、拦截），而不限于 CRUD 事件。
+ *
+ * 用法:
+ * ```ts
+ * const hooks = new OperationHookRegistry();
+ *
+ * // 注册 hook: 在 storage.upload 之前执行
+ * hooks.register('storage.upload', 'before', async (ctx) => {
+ *   if (ctx.data.size > MAX_SIZE) ctx.cancel('文件超过大小限制');
+ * });
+ *
+ * // 执行 hook
+ * const ctx = hooks.createContext('storage.upload', { file });
+ * await hooks.executeBefore(ctx);
+ * if (ctx.cancelled) throw new Error(ctx.cancelReason);
+ * // ... 执行实际操作 ...
+ * await hooks.executeAfter(ctx);
+ * ```
+ */
+type HookPhase = 'before' | 'after';
+interface OperationContext {
+    /** 操作名称（如 'storage.upload', 'config.update'） */
+    readonly operation: string;
+    /** 操作数据 */
+    data: unknown;
+    /** 操作是否被取消 */
+    cancelled: boolean;
+    /** 取消原因 */
+    cancelReason?: string;
+    /** 操作结果（仅在 after 阶段可用） */
+    result?: unknown;
+    /** 自定义属性 */
+    readonly attributes: Map<string, unknown>;
+    /** 取消操作 */
+    cancel(reason: string): void;
+}
+type HookHandler = (ctx: OperationContext) => void | Promise<void>;
+declare class OperationHookRegistry {
+    private readonly logger;
+    private readonly hooks;
+    /**
+     * 注册操作 hook
+     * @param operation 操作名称模式（支持 * 和 ** 通配符）
+     * @param phase 执行阶段
+     * @param handler hook 处理函数
+     * @param options 可选配置
+     * @returns 取消注册的函数
+     */
+    register(operation: string, phase: HookPhase, handler: HookHandler, options?: {
+        priority?: number;
+        name?: string;
+    }): () => void;
+    /**
+     * 创建操作上下文
+     */
+    createContext(operation: string, data: unknown): OperationContext;
+    /**
+     * 执行 before 阶段的所有 hook
+     * 如果任意 hook 取消了操作，后续 hook 不再执行
+     */
+    executeBefore(ctx: OperationContext): Promise<void>;
+    /**
+     * 执行 after 阶段的所有 hook
+     */
+    executeAfter(ctx: OperationContext): Promise<void>;
+    private executePhase;
+    /**
+     * 获取已注册的 hook 数量
+     */
+    get size(): number;
+    /**
+     * 清除所有 hook
+     */
+    clear(): void;
+}
+
+export { ALL_EVENT_PHASES, type AsyncEvent, CLUSTER_TRANSPORT, CREATE_GROUP, type ClusterTransport, CompositeEventListener, CreatorEventListener, type CurrentUser, DefaultTopicEventBus, ENTITY_EVENT_CONFIG_KEY, ENTITY_EVENT_LISTENER_CUSTOMIZER, EVENT_STORE, EnableEntityEvent, type EntityEvent, type EntityEventConfig, type EntityEventListener, EntityEventListenerConfigure, type EntityEventListenerCustomizer, EntityEventPhase, EntityEventType, type EventHandler, type EventQueryOptions, type EventStore, type HookHandler, type HookPhase, type LegacyEventHandler, type OperationContext, OperationHookRegistry, SAVE_GROUP, SUBSCRIBE_KEY, SUBSCRIBE_METHODS_KEY, type StoredEvent, Subscribe, SubscribeFeature, type SubscribeOptions, type Subscription, SubscriptionBuilder, type SubscriptionInfo, type SubscriptionInfoBuilder, TOPIC_EVENT_BUS, type TopicEventBus, type TopicPayload, UPDATE_GROUP, UnifiedEventBus, ValidateEventListener, ZuckerEventModule, createAsyncEvent, createBatchEntityEvent, createCreatedEntityEvent, createDeletedEntityEvent, createEntityEvent, createModifyEntityEvent, createSavedEntityEvent, createSingleEntityEvent, createTopicPayload, getEntityEventConfig, getEntityEventName, getSubscriptions, isDoFireEvent, isEntityEventEnabled, matchesTopic, tryFireEvent, withFireEvent, withoutFireEvent };