@virid/core 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -1,170 +1,139 @@
 type Newable<TInstance = unknown, TArgs extends unknown[] = any[]> = new (...args: TArgs) => TInstance;
 interface AppConfig {
-    enableLog: boolean;
-}
-declare const defaultConfig: {
-    enableLog: boolean;
-};
-
-interface SystemParams {
-    priority?: number;
-    messageClass?: Newable<BaseMessage> | null;
-}
-interface MessageMetadata {
-    index: number;
-    messageClass: Newable<BaseMessage>;
-    single: boolean;
-}
-interface ObserverItem {
-    propertyKey: string;
-    callback: (oldVal: any, newVal: any) => void | BaseMessage | BaseMessage;
-}
-type ObserverMetadata = ObserverItem[];
-type SafeMetadata = Set<string>;
-
-type Middleware = (message: BaseMessage, next: () => void) => void;
-type ExecuteHook<T extends BaseMessage> = (message: [BaseMessage] extends [T] ? SingleMessage[] | EventMessage : T extends SingleMessage ? T[] : T, context: ExecuteHookContext) => void | Promise<void>;
-interface ExecuteHookContext {
-    context: SystemContext;
-    tick: number;
-    payload: {
-        [key: string]: any;
-    };
-}
-interface SystemContext {
-    params: any[];
-    targetClass: any;
-    methodName: string;
-    originalMethod: (...args: any[]) => any;
-}
-interface SystemTask {
-    fn: (...args: any[]) => any;
-    priority: number;
-}
-type MessagePayload<T> = T extends SingleMessage ? T[] : T extends EventMessage ? T : T | T[];
-type MessageIdentifier<T> = (abstract new (...args: any[]) => T) | Newable<T>;
-type TickHook = (context: TickHookContext) => void | Promise<void>;
-interface TickHookContext {
-    tick: number;
-    timestamp: number;
-    payload: {
-        [key: string]: any;
-    };
+    maxDepth?: number;
+    enableLog?: boolean;
+    manual?: boolean;
 }
+declare const defaultConfig: AppConfig;
 
 declare abstract class BaseMessage {
     static send<T extends Newable<any>>(this: T, ...args: ConstructorParameters<T>): void;
 }
-/**
- * 可合并的信号基类
- */
 declare abstract class SingleMessage extends BaseMessage {
-    private readonly __kind;
     constructor();
 }
-/**
- * 不可合并的消息基类
- */
 declare abstract class EventMessage extends BaseMessage {
-    private readonly __kind;
     constructor();
 }
-/**
- * 基础错误消息：不可合并，必须被精准捕获
- */
 declare class ErrorMessage extends EventMessage {
     readonly error: Error;
     readonly context?: string | undefined;
     constructor(error: Error, context?: string | undefined);
 }
-/**
- * 基础警告消息：不可合并，必须被精准捕获
- */
 declare class WarnMessage extends EventMessage {
     readonly context: string;
     constructor(context: string);
 }
-/**
- * 基础信息消息：不可合并，必须被精准捕获
- */
 declare class InfoMessage extends EventMessage {
     readonly context: string;
     constructor(context: string);
 }
 
-declare class MessageInternal {
-    private eventHub;
+declare class MessageEngine {
     private dispatcher;
     private registry;
     private middlewares;
-    constructor();
+    private manual;
+    constructor(maxDepth: number, manual: boolean);
     useMiddleware(mw: Middleware, front: boolean): void;
     onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: ExecuteHook<T>, front: boolean): void;
     onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: ExecuteHook<T>, front: boolean): void;
     onBeforeTick(hook: TickHook, front: boolean): void;
     onAfterTick(hook: TickHook, front: boolean): void;
-    /**
-     * 消息进入系统的唯一入口
-     */
+    tick(): void;
     dispatch(message: BaseMessage): void;
     private pipeline;
     register(messageClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
 }
 
-/**
- * @description: 消息注册器 - 负责将系统函数或监听器与消息类型关联
- */
 declare class MessageRegistry {
     systemTaskMap: Map<any, SystemTask[]>;
     /**
-     * 注册消息并返回一个卸载函数
-     * 这种模式能完美适配 Controller 的生命周期销毁
+     * Register the message and corresponding system and return an uninstallation function
      */
     register(messageClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
 }
 
-interface IMessagePublisher {
-    dispatch(message: BaseMessage): void;
-}
-declare function activateInstance(instance: MessageInternal): void;
-declare const publisher: IMessagePublisher;
+declare function activateInstance(instance: MessageEngine): void;
 declare class MessageWriter {
-    /**
-     * 核心入口：无论是类还是实例，统一交给 Internal 处理
-     */
     static write<T extends BaseMessage, K extends Newable<T>>(target: K | T, ...args: ConstructorParameters<K>): void;
-    /**
-     * 快捷方式：系统内部常用
-     */
     static error(e: Error, context?: string): void;
     static warn(context: string): void;
     static info(context: string): void;
 }
 
-declare const handleResult: (res: any) => void;
+interface SystemParams {
+    priority?: number;
+    messageClass?: Newable<BaseMessage> | null;
+}
+interface MessageMetadata {
+    index: number;
+    messageClass: Newable<BaseMessage>;
+    single: boolean;
+}
+interface ObserverItem {
+    propertyKey: string;
+    callback: (oldVal: any, newVal: any) => void | BaseMessage | BaseMessage;
+}
+type ObserverMetadata = ObserverItem[];
+type SafeMetadata = Set<string>;
+
+type Middleware = (message: BaseMessage, next: () => void) => void;
+type ExecuteHook<T extends BaseMessage> = (message: [BaseMessage] extends [T] ? SingleMessage[] | EventMessage : T extends SingleMessage ? T[] : T, context: ExecuteHookContext, success: boolean) => void | Promise<void>;
+interface ExecuteHookContext {
+    context: SystemContext;
+    tick: number;
+    payload: {
+        [key: string]: any;
+    };
+}
+interface SystemContext {
+    params: any[];
+    targetClass: any;
+    methodName: string;
+    originalMethod: (...args: any[]) => any;
+}
+interface SystemConfig {
+    priority: number;
+    messageClass: Newable<BaseMessage>;
+    messageIdx: number;
+    batchMode: boolean;
+}
+interface SystemTask {
+    fn: (...args: any[]) => any;
+    priority: number;
+}
+type MessagePayload<T> = T extends SingleMessage ? T[] : T extends EventMessage ? T : T | T[];
+type MessageIdentifier<T> = (abstract new (...args: any[]) => T) | Newable<T>;
+type TickHook = (context: TickHookContext) => void | Promise<void>;
+interface TickHookContext {
+    tick: number;
+    timestamp: number;
+    payload: {
+        [key: string]: any;
+    };
+}
+
+declare function handleResult(res: any): void;
 /**
- * @description: 系统装饰器
- * @param priority 优先级，数值越大越早执行
+ * System Decorator
+ * @param params Priority and MessageClass config
  */
 declare function System(params?: SystemParams): (target: any, key: string, descriptor: PropertyDescriptor) => void;
 /**
- * @description: 标记参数为 MessageReader 并锁定其消息类型
- */
-declare function Message<T extends BaseMessage>(messageClass: Newable<T>, single?: boolean): (target: any, key: string, index: number) => void;
-/**
- * @description: 标识controller或者组件的方法是否是安全的，可被其他controller直接调用
+ * Is the method used to identify the controller or component safe and can be directly called by other controllers
  */
 declare function Safe(): (target: any, key: string, _descriptor: PropertyDescriptor) => void;
 /**
- * @description: 标识Component里的这个属性被改了之后需要调用一个回调
+ * Observer Decorator
  */
 declare function Observer(callback: (oldVal: any, newVale: any) => void | BaseMessage | BaseMessage[]): (target: any, propertyKey: string) => void;
 /**
- * @description: 标记Controller身份
+ * Controller Decorator
  */
 declare function Controller(): (target: any) => void;
 /**
- * @description: 标记Component身份
+ * Component Decorator
  */
 declare function Component(): (target: any) => void;
 
@@ -182,53 +151,78 @@ declare const VIRID_METADATA: {
 declare class ViridContainer {
     private bindings;
     private singletonInstances;
-    bind<T>(identifier: Newable<T>): {
-        toSelf: () => {
-            inSingletonScope: () => {
-                onActivation: (fn: any) => void;
-            };
-        };
-    };
-    get<T>(identifier: Newable<T>, onActivate: (instance: T) => T): T;
+    private activationHooks;
+    /**
+     * Register an activation hook
+     * @param hook An activation hook
+     * @param front Is the hook order inserted from the front or added
+     */
+    addActivationHook(hook: (instance: any) => any, front: boolean): void;
+    /**
+     * Static binding component or controller
+     * @param identifier Constructor of components or controllers
+     */
+    bind<T>(identifier: Newable<T>): void;
+    /**
+     * Dynamically register a component
+     * @param instance Component instance
+     */
+    spawn(instance: object): void;
+    /**
+     * Obtain a Component or Controller instance
+     * @param identifier Constructor of components or controllers
+     */
+    get<T>(identifier: Newable<T>): T;
+    private handleActivation;
 }
 
-interface ViridPlugin<T = void> {
+interface ViridPlugin<T = any> {
     name: string;
     install: (app: ViridApp, options: T) => void;
 }
-/**
- * 创建 virid 核心实例
- */
 declare class ViridApp {
     container: ViridContainer;
-    private messageInternal;
-    private activationHooks;
-    addActivationHook(hook: (instance: any) => any): void;
+    engine: MessageEngine;
+    private installedPlugins;
+    constructor(maxDepth: number, manual: boolean);
+    /**
+     * Register an activation hook
+     * @param hook An activation hook
+     * @param front Is the hook order inserted from the front or added
+     */
+    onActivate(hook: (instance: any) => any, front?: boolean): void;
+    /**
+     * Opening a new tick
+     */
+    tick(): void;
+    /**
+     * Obtain a Component or Controller instance
+     * @param identifier Constructor of components or controllers
+     */
     get<T>(identifier: Newable<T>): T;
-    private handleActivation;
     /**
-     * 绑定多例 (Controller 通常是多例)
+     * Static binding component or controller
+     * @param identifier Constructor of components or controllers
      */
-    bindController<T>(identifier: Newable<T>): {
-        inSingletonScope: () => {
-            onActivation: () => void;
-        };
-    };
+    bind<T>(identifier: Newable<T>): void;
     /**
-     * 绑定单例 (Component 是单例)
+     * Dynamically register a component
+     * @param instance Component instance
      */
-    bindComponent<T>(identifier: Newable<T>): {
-        onActivation: () => void;
-    };
+    spawn(instance: object): void;
     useMiddleware(mw: Middleware, front?: boolean): void;
     onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: ExecuteHook<T>, front?: boolean): void;
     onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: ExecuteHook<T>, front?: boolean): void;
     onBeforeTick(hook: TickHook, front?: boolean): void;
     onAfterTick(hook: TickHook, front?: boolean): void;
-    register(messageClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
     use<T>(plugin: ViridPlugin<T>, options: T): this;
+    /**
+     * Register message to registrar
+     * @param systemFn System functions
+     */
+    register(systemFn: (...args: any[]) => any): () => void;
 }
 
 declare function createVirid(config?: AppConfig): ViridApp;
 
-export { type AppConfig, BaseMessage, Component, Controller, ErrorMessage, EventMessage, type ExecuteHook, type ExecuteHookContext, type IMessagePublisher, InfoMessage, Message, type MessageIdentifier, MessageInternal, type MessageMetadata, type MessagePayload, MessageRegistry, MessageWriter, type Middleware, type Newable, Observer, type ObserverItem, type ObserverMetadata, Safe, type SafeMetadata, SingleMessage, System, type SystemContext, type SystemParams, type SystemTask, type TickHook, type TickHookContext, VIRID_METADATA, ViridApp, type ViridPlugin, WarnMessage, activateInstance, bindObservers, createVirid, defaultConfig, handleResult, publisher };
+export { type AppConfig, BaseMessage, Component, Controller, ErrorMessage, EventMessage, type ExecuteHook, type ExecuteHookContext, InfoMessage, MessageEngine, type MessageIdentifier, type MessageMetadata, type MessagePayload, MessageRegistry, MessageWriter, type Middleware, type Newable, Observer, type ObserverItem, type ObserverMetadata, Safe, type SafeMetadata, SingleMessage, System, type SystemConfig, type SystemContext, type SystemParams, type SystemTask, type TickHook, type TickHookContext, VIRID_METADATA, ViridApp, type ViridPlugin, WarnMessage, activateInstance, bindObservers, createVirid, defaultConfig, handleResult };