@virid/core 0.0.1 → 0.1.1

package/dist/index.d.ts

@@ -1,14 +1,54 @@
-import { Newable, Container, BindInWhenOnFluentSyntax, BindWhenOnFluentSyntax } from 'inversify';
+type Newable<TInstance = unknown, TArgs extends unknown[] = any[]> = new (...args: TArgs) => TInstance;
 
-type AnyConstructor = abstract new (...args: any[]) => any;
-declare abstract class BaseMessage {
-    static send<T extends AnyConstructor>(this: T, ...args: ConstructorParameters<T>): void;
-    senderInfo?: {
-        fileName: string;
-        line: number;
-        timestamp: number;
+interface SystemParams {
+    priority?: number;
+    messageClass?: Newable<BaseMessage> | null;
+}
+interface MessageMetadata {
+    index: number;
+    messageClass: Newable<BaseMessage>;
+    single: boolean;
+}
+interface ObserverItem {
+    key: string;
+    callback: (oldVal: any, newVal: any) => void | BaseMessage | BaseMessage;
+}
+type ObserverMetadata = ObserverItem[];
+interface SafeMetadata extends 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;
     };
-    constructor();
+}
+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;
+    };
+}
+
+declare abstract class BaseMessage {
+    static send<T extends Newable<any>>(this: T, ...args: ConstructorParameters<T>): void;
 }
 /**
  * 可合并的信号基类
@@ -39,6 +79,13 @@ declare class WarnMessage extends EventMessage {
     readonly context: string;
     constructor(context: string);
 }
+/**
+ * 基础信息消息：不可合并，必须被精准捕获
+ */
+declare class InfoMessage extends EventMessage {
+    readonly context: string;
+    constructor(context: string);
+}
 /**
  * 原子修改消息：不可合并，带上组件类型、修改逻辑和语义标签
  */
@@ -50,138 +97,74 @@ declare class AtomicModifyMessage<T> extends EventMessage {
     recipe: (comp: T) => void, // 你打算怎么改？
     label: string);
 }
-type Middleware = (message: BaseMessage, next: () => void) => void;
-type Hook<T extends BaseMessage> = (message: [BaseMessage] extends [T] ? SingleMessage[] | EventMessage : T extends SingleMessage ? T[] : T, context: CCSSystemContext) => void | Promise<void>;
-type MessageIdentifier<T> = (abstract new (...args: any[]) => T) | (new (...args: any[]) => T);
-interface CCSSystemContext {
-    params: any[];
-    targetClass: any;
-    methodName: string;
-    originalMethod: (...args: any[]) => any;
-}
-interface SystemTask {
-    fn: (...args: any[]) => any;
-    priority: number;
-}
-/**
- * 核心逻辑：根据 T 的类型决定 Hook 接收的是数组还是单体
- */
-type MessagePayload<T> = T extends SingleMessage ? T[] : T extends EventMessage ? T : T | T[];
 
-/**
- * @description:  事件中心，存储和分发消息 - 物理隔离 SIGNAL 与 EVENT
- */
-declare class EventHub {
-    private signalActive;
-    private signalStaging;
-    private eventActive;
-    private eventStaging;
-    /**
-     * 写入逻辑：根据消息策略分流
-     */
-    push(event: any): void;
-    /**
-     * 翻转缓冲区：在 Dispatcher 的 Tick 开始时调用
-     */
-    flip(): void;
-    /**
-     * [SIGNAL专用] 批量读取某种类型的信号
-     */
-    peekSignal<T>(type: new (...args: any[]) => T): T[];
-    /**
-     * [EVENT专用] 获取当前所有待处理的事件流
-     */
-    getEventStream(): any[];
-    /**
-     * [新增] 根据索引精准读取 EVENT 里的某个数据
-     * 配合 Dispatcher 逐条分发时使用
-     */
-    peekEventAt(index: number): any;
-    /**
-     * 清理已处理的内容
-     */
-    clearSignals(types: Set<any>): void;
-    clearEvents(): void;
-    /**
-     * 重置所有池子
-     */
-    reset(): void;
-}
-
-declare class Dispatcher {
-    private dirtySignalTypes;
-    private eventQueue;
-    private isRunning;
-    private tickCount;
+declare class MessageInternal {
     private eventHub;
-    private beforeHooks;
-    private afterHooks;
-    constructor(eventHub: EventHub);
-    addBefore<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    addAfter<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    private cleanupHook;
-    setCleanupHook(hook: (types: Set<any>) => void): void;
+    private dispatcher;
+    private registry;
+    private middlewares;
+    constructor();
+    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;
     /**
-     * 标记脏数据：根据基类判断进入哪个池子
+     * 消息进入系统的唯一入口
      */
-    markDirty(message: any): void;
-    tick(interestMap: Map<any, SystemTask[]>): void;
+    dispatch(message: BaseMessage): void;
+    private pipeline;
+    register(messageClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
 }
 
 /**
  * @description: 消息注册器 - 负责将系统函数或监听器与消息类型关联
  */
 declare class MessageRegistry {
-    interestMap: Map<any, SystemTask[]>;
+    systemTaskMap: Map<any, SystemTask[]>;
     /**
      * 注册消息并返回一个卸载函数
      * 这种模式能完美适配 Controller 的生命周期销毁
      */
-    register(eventClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
-}
-
-declare class MessageInternal {
-    readonly eventHub: EventHub;
-    readonly dispatcher: Dispatcher;
-    readonly registry: MessageRegistry;
-    readonly middlewares: Middleware[];
-    constructor();
-    useMiddleware(mw: Middleware): void;
-    onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    /**
-     * 消息进入系统的唯一入口
-     */
-    dispatch(message: BaseMessage): void;
-    private pipeline;
+    register(messageClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
 }
 
 interface IMessagePublisher {
     dispatch(message: BaseMessage): void;
 }
-declare function activatInstance(instance: MessageInternal): void;
+declare function activateInstance(instance: MessageInternal): void;
 declare const publisher: IMessagePublisher;
 declare class MessageWriter {
     /**
      * 核心入口：无论是类还是实例，统一交给 Internal 处理
      */
-    static write<T extends BaseMessage, K extends new (...args: any[]) => T>(target: K | T, ...args: ConstructorParameters<K>): void;
+    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;
 /**
  * @description: 系统装饰器
  * @param priority 优先级，数值越大越早执行
  */
-declare function System(priority?: number): (target: any, key: string, descriptor: PropertyDescriptor) => void;
+declare function System(params?: SystemParams): (target: any, key: string, descriptor: PropertyDescriptor) => void;
 /**
  * @description: 标记参数为 MessageReader 并锁定其消息类型
  */
-declare function Message<T extends BaseMessage>(eventClass: new (...args: any[]) => T, single?: boolean): (target: any, key: string, index: number) => void;
+declare function Message<T extends BaseMessage>(messageClass: Newable<T>, single?: boolean): (target: any, key: string, index: number) => void;
+/**
+ * @description: 标识controller或者组件的方法是否是安全的，可被其他controller直接调用
+ */
+declare function Safe(): (target: any, key: string, _descriptor: PropertyDescriptor) => void;
+/**
+ * @description: 标识Component里的这个属性被改了之后需要调用一个回调
+ */
+declare function Observer(callback: (oldVal: any, newVale: any) => void | BaseMessage | BaseMessage, []: Iterable<any, void, undefined>): (target: any, key: string) => void;
 /**
  * @description: 标记Controller身份
  */
@@ -191,28 +174,67 @@ declare function Controller(): (target: any) => void;
  */
 declare function Component(): (target: any) => void;
 
-interface ViridPlugin {
-    name: string;
-    install: (app: ViridApp, options?: any) => void;
+declare function bindObservers(instance: any): any;
+
+declare const VIRID_METADATA: {
+    readonly SYSTEM: "virid:core:system";
+    readonly MESSAGE: "virid:core:message";
+    readonly CONTROLLER: "virid:core:controller";
+    readonly COMPONENT: "virid:core:component";
+    readonly SAFE: "virid:core:safe";
+    readonly OBSERVER: "virid:core:observer";
+};
+
+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;
 }
 
+interface ViridPlugin<T = any> {
+    name: string;
+    install: (app: ViridApp, options?: T) => void;
+}
 /**
  * 创建 virid 核心实例
  */
 declare class ViridApp {
-    container: Container;
+    container: ViridContainer;
     private messageInternal;
-    private bindBase;
-    get(identifier: any): unknown;
-    bindController<T>(identifier: new (...args: any[]) => T): BindInWhenOnFluentSyntax<T>;
-    bindComponent<T>(identifier: new (...args: any[]) => T): BindWhenOnFluentSyntax<T>;
-    useMiddleware(mw: Middleware): void;
-    onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
-    register(eventClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
-    use(plugin: ViridPlugin, options: any): this;
+    private activationHooks;
+    addActivationHook(hook: (instance: any) => any): void;
+    get<T>(identifier: Newable<T>): T;
+    private handleActivation;
+    /**
+     * 绑定多例 (Controller 通常是多例)
+     */
+    bindController<T>(identifier: Newable<T>): {
+        inSingletonScope: () => {
+            onActivation: () => void;
+        };
+    };
+    /**
+     * 绑定单例 (Component 是单例)
+     */
+    bindComponent<T>(identifier: Newable<T>): {
+        onActivation: () => 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;
 }
 
 declare function createVirid(): ViridApp;
 
-export { AtomicModifyMessage, BaseMessage, type CCSSystemContext, Component, Controller, ErrorMessage, EventMessage, type Hook, type IMessagePublisher, Message, type MessageIdentifier, MessageInternal, type MessagePayload, MessageWriter, type Middleware, SingleMessage, System, type SystemTask, ViridApp, type ViridPlugin, WarnMessage, activatInstance, createVirid, publisher };
+export { AtomicModifyMessage, 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, handleResult, publisher };