@xiacg/exia-event 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiachenggang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# exia-event
+
+轻量级事件系统，提供全局事件管理和模块间通信。
+
+## 简介
+
+`exia-event` 是一个轻量级、高性能的事件系统，提供全局事件管理和模块间松耦合通信能力。支持事件的添加、移除、发送、批量管理等操作，适用于游戏各系统之间的解耦通信。
+
+**核心特性**：
+
+- 🚀 零依赖，轻量级实现
+- 📡 全局事件管理器
+- 🎯 支持按 ID、名称、目标对象移除事件
+- 🔥 支持一次性事件（addOnce）
+- 🎨 完整的 TypeScript 类型定义
+- ⚡ 高性能事件分发机制
+
+## 安装
+
+```bash
+npm install @xiacg/exia-event
+```
+
+## 使用说明
+
+### 全局事件 (GlobalEvent)
+
+全局单例事件管理器，用于模块间通信。
+
+**添加事件**：
+
+- `add(name, callback, target?)` - 添加事件监听，返回事件 ID
+- `addOnce(name, callback, target?)` - 添加一次性事件监听（触发后自动移除）
+
+**发送事件**：
+
+- `send(name, ...args)` - 发送事件给所有监听者
+- `sendToTarget(name, target, ...args)` - 发送事件给指定目标
+
+**移除事件**：
+
+- `remove(eventId)` - 按 ID 移除事件
+- `removeByName(name)` - 移除指定名称的所有事件
+- `removeByTarget(target)` - 移除指定目标的所有事件
+- `removeByNameAndTarget(name, target)` - 移除指定名称和目标的事件
+- `clearAll()` - 清空所有事件
+
+**参数说明**：
+
+- `name` - 事件名称（建议使用常量管理）
+- `callback` - 回调函数 `(...args: any[]) => void`
+- `target` - 目标对象（用于批量移除）
+- `eventId` - 事件 ID（add 方法返回）
+
+### 事件管理器 (EventManager)
+
+可创建独立的事件管理器实例，用于特定模块或系统。
+
+**使用方式**：
+
+- `new EventManager()` - 创建独立的事件管理器
+- API 与 `GlobalEvent` 完全相同
+
+**适用场景**：
+
+- 需要隔离的事件系统
+- 模块内部事件管理
+- 可以整体清空的事件组
+
+### 最佳实践
+
+1. **使用事件名称常量** - 避免字符串拼写错误
+
+2. **及时移除事件** - 在对象销毁时移除监听，避免内存泄漏
+
+3. **使用 target 参数** - 方便批量移除事件
+
+4. **避免事件循环** - 不要在事件 A 中触发事件 B，再在事件 B 中触发事件 A
+
+5. **事件分组管理** - 对于复杂系统，使用独立的 EventManager 实例
+
+详细 API 请查看 `exia-event.d.ts` 类型定义文件。
+
+## 依赖
+
+无外部依赖
+
+## 许可证
+
+MIT License
+
+## 作者
+
+**xiacg** (xiacg)  
+**邮箱**: <xiacg@163.com>
+
+## 源码仓库
+
+- [GitHub](https://github.com/xiachenggang/exia-framework.git)
+- [npm](https://www.npmjs.com/package/@xiacg/exia-event)

package/dist/exia-event.cjs

@@ -0,0 +1,565 @@
+'use strict';
+
+/**
+ * @Description: 命令
+ */
+var CommandType;
+(function (CommandType) {
+    CommandType[CommandType["Add"] = 1] = "Add";
+    CommandType[CommandType["RemoveById"] = 2] = "RemoveById";
+    CommandType[CommandType["RemoveByName"] = 3] = "RemoveByName";
+    CommandType[CommandType["RemoveByTarget"] = 4] = "RemoveByTarget";
+    CommandType[CommandType["RemoveByNameAndTarget"] = 5] = "RemoveByNameAndTarget";
+    CommandType[CommandType["ClearAll"] = 6] = "ClearAll";
+})(CommandType || (CommandType = {}));
+/**
+ * 命令
+ * @internal
+ */
+class Command {
+    constructor() {
+        this.type = CommandType.Add;
+    }
+    reset() {
+        this.type = CommandType.Add;
+        this.eventId = 0;
+        this.event = null;
+        this.name = null;
+        this.target = null;
+    }
+}
+/**
+ * 命令管理器
+ * @internal
+ */
+class CommandManager {
+    constructor() {
+        this.commands = [];
+        this.index = 0;
+        this.length = 0;
+        this.clearAll = false;
+    }
+    /**
+     * 添加一个添加事件的命令
+     * @param event 事件
+     */
+    addEvent(event) {
+        if (this.index == this.length) {
+            let command = new Command();
+            command.type = CommandType.Add;
+            command.event = event;
+            this.commands.push(command);
+            this.length++;
+            this.index++;
+        }
+        else {
+            let command = this.commands[this.index++];
+            command.type = CommandType.Add;
+            command.event = event;
+        }
+    }
+    /**
+     * 添加一个删除事件或者清理所有的命令
+     */
+    add(type, eventId, name, target) {
+        if (type == CommandType.ClearAll) {
+            this.clearAll = true;
+            return;
+        }
+        if (this.index == this.length) {
+            let command = new Command();
+            command.type = type;
+            command.eventId = eventId;
+            command.name = name;
+            command.target = target;
+            this.commands.push(command);
+            this.length++;
+            this.index++;
+        }
+        else {
+            let command = this.commands[this.index++];
+            command.type = type;
+            command.eventId = eventId;
+            command.name = name;
+            command.target = target;
+        }
+    }
+    forEach(callback) {
+        if (this.clearAll) {
+            callback({
+                type: CommandType.ClearAll,
+                eventId: 0,
+                event: null,
+                name: null,
+                target: null,
+                reset: null,
+            });
+            return;
+        }
+        for (let i = 0; i < this.index; i++) {
+            let command = this.commands[i];
+            callback(command);
+            command.reset();
+        }
+        this.index = 0;
+    }
+    clear() {
+        this.commands.length = 0;
+        this.index = 0;
+        this.clearAll = false;
+        this.length = 0;
+    }
+}
+
+/** @internal */
+class Event {
+    constructor() {
+        this.once = false;
+    }
+}
+
+/** @internal */
+class EventFactory {
+    constructor(capacity, objectClass) {
+        this._id = 0;
+        this._stack = [];
+        this._maxCapacity = 64;
+        this._maxCapacity = capacity;
+        this._msgClass = objectClass;
+    }
+    allocate() {
+        if (this._stack.length == 0) {
+            const ret = new this._msgClass();
+            ret.id = ++this._id;
+            return ret;
+        }
+        const ret = this._stack.pop();
+        // 分配新ID，避免ID重用导致误删
+        ret.id = ++this._id;
+        return ret;
+    }
+    recycle(ret) {
+        if (this._maxCapacity > 0 && this._stack.length < this._maxCapacity) {
+            this._stack.push(ret);
+            return true;
+        }
+        return false;
+    }
+}
+
+/**
+ * @Description: 事件管理器 - 支持递归保护
+ */
+/**
+ * 最大递归深度常量
+ */
+const MAX_RECURSION_DEPTH = 20;
+/**
+ * 事件管理器 - 防止递归调用栈溢出
+ *
+ * 功能特性：
+ * - 递归深度限制防止栈溢出
+ * - 完全向后兼容现有API
+ */
+class EventManager {
+    constructor() {
+        /**
+         * 当前递归发送深度
+         * 0 表示没有在发送，> 0 表示正在发送事件
+         * @internal
+         */
+        this.sending_depth = 0;
+        /**
+         * 注册的所有事件 事件ID -> 事件
+         * @internal
+         */
+        this.events = new Map();
+        /**
+         * 事件名称 -> 事件ID集合
+         * @internal
+         */
+        this.nameToIds = new Map();
+        /**
+         * 事件目标 -> 事件ID集合
+         * @internal
+         */
+        this.targetToIds = new Map();
+        /**
+         * 事件工厂
+         * @internal
+         */
+        this.factory = new EventFactory(64, Event);
+        /**
+         * 命令管理器
+         * @internal
+         */
+        this.commandManager = new CommandManager();
+    }
+    /**
+     * 添加事件监听器
+     * @param name - 事件名称
+     * @param callback - 回调函数，当事件触发时执行
+     * @param target - 可选参数，指定事件监听的目标对象
+     * @returns 返回事件ID，可用于移除事件
+     */
+    add(name, callback, target) {
+        if (!name) {
+            throw new Error("事件名称不能为空");
+        }
+        if (!callback) {
+            throw new Error("回调函数不能为空");
+        }
+        let event = this.factory.allocate();
+        event.name = name;
+        event.callback = callback;
+        event.target = target;
+        event.once = false;
+        if (this.sending_depth > 0) {
+            this.commandManager.addEvent(event);
+            return event.id;
+        }
+        this._addEvent(event);
+        return event.id;
+    }
+    /**
+     * 添加一个只触发一次的事件监听器
+     * @param name - 事件名称
+     * @param callback - 事件触发时要执行的回调函数
+     * @param target - 可选参数，指定事件监听器的目标对象
+     * @returns 返回事件ID，可用于移除事件
+     */
+    addOnce(name, callback, target) {
+        if (!name) {
+            throw new Error("事件名称不能为空");
+        }
+        if (!callback) {
+            throw new Error("回调函数不能为空");
+        }
+        let event = this.factory.allocate();
+        event.name = name;
+        event.callback = callback;
+        event.target = target;
+        event.once = true;
+        if (this.sending_depth > 0) {
+            this.commandManager.addEvent(event);
+            return event.id;
+        }
+        this._addEvent(event);
+        return event.id;
+    }
+    /**
+     * 添加事件内部方法
+     * @param event 事件对象
+     * @internal
+     */
+    _addEvent(event) {
+        this.events.set(event.id, event);
+        if (!this.nameToIds.has(event.name)) {
+            this.nameToIds.set(event.name, new Set());
+        }
+        const ids = this.nameToIds.get(event.name);
+        ids.add(event.id);
+        let target = event.target;
+        if (target) {
+            if (!this.targetToIds.has(target)) {
+                this.targetToIds.set(target, new Set());
+            }
+            this.targetToIds.get(target).add(event.id);
+        }
+    }
+    /**
+     * 发送事件给所有注册的监听器（带递归保护）
+     * @param name - 事件名称
+     * @param target - 可选参数，指定目标对象，只有目标对象匹配时才会触发监听器
+     * @param args - 传递给监听器回调函数的参数
+     */
+    send(name, target, ...args) {
+        // 递归深度保护：阻止超过限制的执行并报告错误
+        if (this.sending_depth >= MAX_RECURSION_DEPTH) {
+            console.error(`[EventManager] 递归深度超出限制！`);
+            console.error(`  事件名称: "${name}"`);
+            console.error(`  当前深度: ${this.sending_depth}`);
+            console.error(`  最大深度: ${MAX_RECURSION_DEPTH}`);
+            console.error(`  为防止栈溢出，事件执行已被阻止`);
+            return;
+        }
+        if (!this.nameToIds.has(name)) {
+            return;
+        }
+        const eventIds = this.nameToIds.get(name);
+        if (eventIds.size === 0) {
+            return;
+        }
+        // 使用局部变量，避免嵌套调用时互相污染
+        const needRemoveIds = [];
+        const triggerList = [];
+        // 增加递归深度
+        this.sending_depth++;
+        // 构建触发列表
+        for (const eventId of eventIds.values()) {
+            if (!this.events.has(eventId)) {
+                needRemoveIds.push(eventId);
+                continue;
+            }
+            let event = this.events.get(eventId);
+            if (!target || target === event.target) {
+                triggerList.push(event);
+                if (event.once) {
+                    needRemoveIds.push(eventId);
+                }
+            }
+        }
+        // 同步触发事件
+        for (const event of triggerList) {
+            event.callback(...args);
+        }
+        // 减少递归深度
+        this.sending_depth--;
+        // 只在最外层执行清理工作
+        if (this.sending_depth === 0) {
+            // 清理 once 事件
+            if (needRemoveIds.length > 0) {
+                for (const id of needRemoveIds) {
+                    this.remove(id);
+                }
+            }
+            // 处理命令队列
+            this.commandManager.forEach((command) => {
+                switch (command.type) {
+                    case CommandType.Add:
+                        this._addEvent(command.event);
+                        break;
+                    case CommandType.RemoveById:
+                        this.remove(command.eventId);
+                        break;
+                    case CommandType.RemoveByName:
+                        this.removeByName(command.name);
+                        break;
+                    case CommandType.RemoveByTarget:
+                        this.removeByTarget(command.target);
+                        break;
+                    case CommandType.RemoveByNameAndTarget:
+                        this.removeByNameAndTarget(command.name, command.target);
+                        break;
+                    case CommandType.ClearAll:
+                        this.clearAll();
+                        break;
+                }
+            });
+        }
+    }
+    /**
+     * 通过事件ID移除事件
+     * @param eventId 事件ID
+     */
+    remove(eventId) {
+        if (!this.events.has(eventId)) {
+            return;
+        }
+        if (this.sending_depth > 0) {
+            this.commandManager.add(CommandType.RemoveById, eventId, null, null);
+            return;
+        }
+        let event = this.events.get(eventId);
+        let name = event.name;
+        let target = event.target;
+        this.events.delete(eventId);
+        this.factory.recycle(event);
+        if (this.nameToIds.has(name)) {
+            this.nameToIds.get(name).delete(eventId);
+        }
+        if (target && this.targetToIds.has(target)) {
+            this.targetToIds.get(target).delete(eventId);
+        }
+    }
+    /**
+     * 移除指定名称的所有事件
+     * @param name 事件名称
+     */
+    removeByName(name) {
+        if (!this.nameToIds.has(name)) {
+            return;
+        }
+        let eventIds = this.nameToIds.get(name);
+        if (eventIds.size === 0) {
+            return;
+        }
+        if (this.sending_depth > 0) {
+            this.commandManager.add(CommandType.RemoveByName, null, name, null);
+            return;
+        }
+        eventIds.forEach((eventId) => {
+            if (this.events.has(eventId)) {
+                let event = this.events.get(eventId);
+                if (event.target && this.targetToIds.has(event.target)) {
+                    this.targetToIds.get(event.target).delete(eventId);
+                }
+                this.events.delete(eventId);
+                this.factory.recycle(event);
+            }
+        });
+        this.nameToIds.delete(name);
+    }
+    /**
+     * 移除指定目标的所有事件
+     * @param target 目标对象
+     */
+    removeByTarget(target) {
+        if (!this.targetToIds.has(target)) {
+            return;
+        }
+        let eventIds = this.targetToIds.get(target);
+        if (eventIds.size === 0) {
+            return;
+        }
+        if (this.sending_depth > 0) {
+            this.commandManager.add(CommandType.RemoveByTarget, null, null, target);
+            return;
+        }
+        eventIds.forEach((eventId) => {
+            if (this.events.has(eventId)) {
+                let event = this.events.get(eventId);
+                if (this.nameToIds.has(event.name)) {
+                    this.nameToIds.get(event.name).delete(eventId);
+                }
+                this.events.delete(eventId);
+                this.factory.recycle(event);
+            }
+        });
+        this.targetToIds.delete(target);
+    }
+    /**
+     * 移除指定名称和指定目标的事件
+     * @param name 事件名称
+     * @param target 绑定的目标对象
+     */
+    removeByNameAndTarget(name, target) {
+        if (!this.nameToIds.has(name)) {
+            return;
+        }
+        let nameIds = this.nameToIds.get(name);
+        let targetIds = this.targetToIds.get(target);
+        // 检查targetIds是否存在，避免NPE
+        if (nameIds.size === 0 || !targetIds || targetIds.size === 0) {
+            return;
+        }
+        if (this.sending_depth > 0) {
+            this.commandManager.add(CommandType.RemoveByNameAndTarget, null, name, target);
+            return;
+        }
+        // 使用局部变量
+        const needRemoveIds = [];
+        if (nameIds.size < targetIds.size) {
+            nameIds.forEach((eventId) => {
+                let event = this.events.get(eventId);
+                if (event.target === target) {
+                    needRemoveIds.push(eventId);
+                }
+            });
+        }
+        else {
+            targetIds.forEach((eventId) => {
+                let event = this.events.get(eventId);
+                if (event.name === name) {
+                    needRemoveIds.push(eventId);
+                }
+            });
+        }
+        if (needRemoveIds.length > 0) {
+            for (const id of needRemoveIds) {
+                this.remove(id);
+            }
+        }
+    }
+    /**
+     * 清空所有注册的事件
+     */
+    clearAll() {
+        if (this.sending_depth > 0) {
+            this.commandManager.add(CommandType.ClearAll, null, null, null);
+            return;
+        }
+        for (const event of this.events.values()) {
+            this.factory.recycle(event);
+        }
+        this.events.clear();
+        this.nameToIds.clear();
+        this.targetToIds.clear();
+        this.commandManager.clear();
+        // 清理递归保护相关状态
+        this.sending_depth = 0;
+    }
+}
+
+/**
+ * @Description: 全局事件
+ */
+class GlobalEvent {
+    /**
+     * 添加一个事件
+     * @param name 事件名称
+     * @param callback 事件回调
+     * @param target 事件目标
+     */
+    static add(name, callback, target) {
+        return this.event.add(name, callback, target);
+    }
+    /**
+     * 添加一个只触发一次的事件
+     */
+    static addOnce(name, callback, target) {
+        return this.event.addOnce(name, callback, target);
+    }
+    /**
+     * 发送一个事件
+     * @param name 事件名称
+     * @param args 事件参数
+     */
+    static send(name, ...args) {
+        this.event.send(name, null, ...args);
+    }
+    /**
+     * 发送一个事件给指定目标
+     * @param name 事件名称
+     * @param target 事件目标
+     * @param args 事件参数
+     */
+    static sendToTarget(name, target, ...args) {
+        this.event.send(name, target, ...args);
+    }
+    /**
+     * 移除一个指定ID的事件
+     * @param eventId 事件ID
+     */
+    static remove(eventId) {
+        this.event.remove(eventId);
+    }
+    static removeByName(name) {
+        this.event.removeByName(name);
+    }
+    static removeByTarget(target) {
+        this.event.removeByTarget(target);
+    }
+    /**
+     * 通过目标和事件名称批量移除事件
+     * @param name 事件名称
+     * @param target 事件目标
+     */
+    static removeByNameAndTarget(name, target) {
+        this.event.removeByNameAndTarget(name, target);
+    }
+    /**
+     * 清空所有事件
+     */
+    static clearAll() {
+        this.event.clearAll();
+    }
+}
+/**
+ * 事件管理器
+ * @internal
+ */
+GlobalEvent.event = new EventManager();
+
+exports.EventManager = EventManager;
+exports.GlobalEvent = GlobalEvent;