@virid/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import { Newable, Container, BindInWhenOnFluentSyntax, BindWhenOnFluentSyntax } from 'inversify';
+
+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;
+    };
+    constructor();
+}
+/**
+ * 可合并的信号基类
+ */
+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;
+    constructor(error: Error, context?: string);
+}
+/**
+ * 基础警告消息：不可合并，必须被精准捕获
+ */
+declare class WarnMessage extends EventMessage {
+    readonly context: string;
+    constructor(context: string);
+}
+/**
+ * 原子修改消息：不可合并，带上组件类型、修改逻辑和语义标签
+ */
+declare class AtomicModifyMessage<T> extends EventMessage {
+    readonly ComponentClass: Newable<T>;
+    readonly recipe: (comp: T) => void;
+    readonly label: string;
+    constructor(ComponentClass: Newable<T>, // 你要改哪个组件？
+    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;
+    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;
+    /**
+     * 标记脏数据：根据基类判断进入哪个池子
+     */
+    markDirty(message: any): void;
+    tick(interestMap: Map<any, SystemTask[]>): void;
+}
+
+/**
+ * @description: 消息注册器 - 负责将系统函数或监听器与消息类型关联
+ */
+declare class MessageRegistry {
+    interestMap: 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;
+}
+
+interface IMessagePublisher {
+    dispatch(message: BaseMessage): void;
+}
+declare function activatInstance(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 error(e: Error, context?: string): void;
+    static warn(context: string): void;
+}
+
+/**
+ * @description: 系统装饰器
+ * @param priority 优先级，数值越大越早执行
+ */
+declare function System(priority?: number): (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;
+/**
+ * @description: 标记Controller身份
+ */
+declare function Controller(): (target: any) => void;
+/**
+ * @description: 标记Component身份
+ */
+declare function Component(): (target: any) => void;
+
+interface ViridPlugin {
+    name: string;
+    install: (app: ViridApp, options?: any) => void;
+}
+
+/**
+ * 创建 virid 核心实例
+ */
+declare class ViridApp {
+    container: Container;
+    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;
+}
+
+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 };