mm_expand 2.3.2 → 2.3.4

package/lib/eventer.js

@@ -1203,6 +1203,53 @@ Eventer.prototype.emitRace = async function (key, ...args) {
   }
 };
 
+/**
+ * 异步触发事件，返回第一个有返回值的结果（不阻塞其他监听器）
+ * @param {string} key 事件关键字，支持namespace:key格式
+ * @param  {...any} args 事件参数
+ * @returns {Promise} - 第一个有返回值（非 undefined）的监听器结果
+ * @description 所有监听器并行执行，返回第一个有返回值（非 undefined）的结果，
+ *               返回 undefined 的监听器被跳过，其他监听器继续在后台执行不受影响
+ */
+Eventer.prototype.emitFirst = async function (key, ...args) {
+  try {
+    const parsed = this._parseKey(key);
+    const namespace = parsed.namespace;
+    const event_key = parsed.key;
+
+    const list = this._dict[namespace] && this._dict[namespace][event_key];
+    if (!list || list.length === 0) {
+      return undefined;
+    }
+
+    return await new Promise(resolve => {
+      let settled = false;
+      let pending = list.length;
+
+      for (const handler of list) {
+        Promise.resolve(handler.func(...args)).then(result => {
+          if (!settled && result !== undefined) {
+            settled = true;
+            resolve(result);
+          }
+          pending--;
+          if (pending === 0 && !settled) {
+            resolve(undefined);
+          }
+        }).catch(() => {
+          pending--;
+          if (pending === 0 && !settled) {
+            resolve(undefined);
+          }
+        });
+      }
+    });
+  } catch (error) {
+    this.log('error', `首个结果事件触发失败 [${key}]`, error);
+    return undefined;
+  }
+};
+
 /**
  * 异步触发事件，瀑布流执行
  * @param {string} key 事件关键字，支持namespace:key格式
@@ -1315,12 +1362,6 @@ Eventer.prototype.emitAllNamespaces = async function (key, ...params) {
   return results;
 };
 
-/**
- * 删除事件
- * @param {string} key 事件关键字，支持namespace:key格式
- * @param {number | string} index_or_name 事件集索引或名称
- * @returns {boolean} 删除成功返回true，否则返回false
- */
 /**
  * 删除单个事件监听器
  * @private
@@ -1352,7 +1393,7 @@ Eventer.prototype._removeSingleEvent = function (events, index_or_name) {
  * @private
  * @param {string} namespace 命名空间
  * @param {string} key 事件关键字
- * @param event_key
+ * @param {string} event_key 事件键
  * @param {string} full_key 完整事件关键字
  * @returns {boolean} 删除成功返回true
  */
@@ -1413,6 +1454,12 @@ Eventer.prototype._autoCleanEvents = function (namespace, key, events, index_or_
   }
 };
 
+/**
+ * 删除事件
+ * @param {string} key 事件关键字，支持namespace:key格式
+ * @param {number | string} index_or_name 事件集索引或名称
+ * @returns {boolean} 删除成功返回true，否则返回false
+ */
 Eventer.prototype.off = function (key, index_or_name) {
   // 入参校验
   if (!key || typeof key !== 'string') {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "mm_expand",
-	"version": "2.3.2",
-	"description": "Super Meimei Prototype Function Extension Module - Enhanced operations for string, array, object, date manipulation with error prevention and simplified business logic.",
+	"version": "2.3.4",
+	"description": "超级美眉原型函数扩展模块 - 增强的字符串、数组、对象、日期操作，具备错误预防功能并简化业务逻辑",
 	"main": "index.js",
 	"scripts": {
 		"test": "node tests/index.js",