@gesslar/toolkit 4.1.0 → 4.2.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "4.1.0",
+  "version": "4.2.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -77,9 +77,9 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^2.0.0",
-    "eslint": "^10.0.2",
-    "happy-dom": "^20.8.3",
+    "@gesslar/uglier": "^2.2.0",
+    "eslint": "^10.0.3",
+    "happy-dom": "^20.8.4",
     "typescript": "^5.9.3"
   }
 }

package/src/node/lib/Notify.js

@@ -54,6 +54,26 @@ export class Notify {
     await Util.asyncEmit(this.#emitter, type, payload)
   }
 
+  /**
+   * Fires an event asynchronously without blocking the caller.
+   * Listeners run in the background. If any listener throws and an error
+   * callback is provided, it receives the error. Otherwise errors are
+   * silently discarded.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Data to send with the event.
+   * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors.
+   * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation.
+   * @returns {undefined}
+   */
+  fire(type, payload, errorCb, signal) {
+    Valid.type(type, "String", {allowEmpty: false})
+    Valid.type(errorCb, "Undefined|Null|Function")
+    Valid.type(signal, "Undefined|Null|AbortSignal")
+
+    Util.fire(this.#emitter, type, payload, errorCb, signal)
+  }
+
   /**
    * Emits an event and returns the payload for simple request/response flows.
    * Listeners can mutate the payload object to provide responses.

package/src/node/lib/Util.js

@@ -68,7 +68,7 @@ export default class Util extends BrowserUtil {
    * @returns {Promise<undefined>} Resolves when all listeners have completed
    */
   static async #performAsyncEmit(emitter, event, ...args) {
-    const listeners = emitter.listeners(event)
+    const listeners = emitter.rawListeners(event)
 
     if(listeners.length === 0)
       return // No listeners, nothing to do
@@ -115,6 +115,48 @@ export default class Util extends BrowserUtil {
     }
   }
 
+  /**
+   * Fires an event asynchronously without blocking the caller.
+   * Listeners run in the background via asyncEmit. If any listener rejects
+   * and an error callback is provided, it receives the error. If no callback
+   * is provided, errors are silently discarded.
+   *
+   * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+   * @param {string} event - The event name to emit
+   * @param {unknown} [payload] - Data to send with the event
+   * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors
+   * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation
+   * @returns {undefined}
+   */
+  static fire(emitter, event, payload, errorCb, signal) {
+    Valid.type(errorCb, "Undefined|Null|Function")
+    Valid.type(signal, "Undefined|Null|AbortSignal")
+
+    if(signal?.aborted)
+      return
+
+    const promise = this.asyncEmit(emitter, event, payload)
+
+    if(signal) {
+      const onAbort = () => {}  // asyncEmit already in flight, nothing to cancel
+      signal.addEventListener("abort", onAbort, {once: true})
+      promise.then(
+        () => signal.removeEventListener("abort", onAbort),
+        error => {
+          signal.removeEventListener("abort", onAbort)
+
+          if(!signal.aborted && errorCb) {
+            errorCb(error)
+          }
+        }
+      )
+    } else if(errorCb) {
+      promise.catch(errorCb)
+    } else {
+      promise.catch(() => {})
+    }
+  }
+
   /**
    * Emits an event asynchronously and waits for all listeners to complete.
    * Like asyncEmit, but uses duck typing for more flexible emitter validation.
@@ -129,7 +171,7 @@ export default class Util extends BrowserUtil {
   static async asyncEmitQuack(emitter, event, ...args) {
     try {
       if(!emitter ||
-         typeof emitter.listeners !== "function" ||
+         typeof emitter.rawListeners !== "function" ||
          typeof emitter.on !== "function" ||
          typeof emitter.emit !== "function") {
         throw Sass.new("First argument must be an EventEmitter-like object")

package/types/node/lib/Notify.d.ts

@@ -28,6 +28,19 @@ export class Notify {
      * @returns {Promise<undefined>} Resolves when all listeners have completed.
      */
     asyncEmit(type: string, payload?: unknown): Promise<undefined>;
+    /**
+     * Fires an event asynchronously without blocking the caller.
+     * Listeners run in the background. If any listener throws and an error
+     * callback is provided, it receives the error. Otherwise errors are
+     * silently discarded.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Data to send with the event.
+     * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors.
+     * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation.
+     * @returns {undefined}
+     */
+    fire(type: string, payload?: unknown, errorCb?: ((error: Error) => void) | null, signal?: AbortSignal): undefined;
     /**
      * Emits an event and returns the payload for simple request/response flows.
      * Listeners can mutate the payload object to provide responses.

package/types/node/lib/Notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;GAGG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAKf;;;;;;OAMG;IACH,WAJW,MAAM,YACN,OAAO,GACL,SAAS,CAMrB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,SAAS,CAAC,CAM9B;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,YACZ,kBAAkB,GAChB,MAAM,SAAS,CAa3B;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,GACV,SAAS,CAMrB;;CACF;;;;;;;WA9Fa,OAAO;;;;aACP,WAAW;;6BARE,aAAa"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;GAGG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAKf;;;;;;OAMG;IACH,WAJW,MAAM,YACN,OAAO,GACL,SAAS,CAMrB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,SAAS,CAAC,CAM9B;IAED;;;;;;;;;;;OAWG;IACH,WANW,MAAM,YACN,OAAO,YACP,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAC,IAAI,WAC7B,WAAW,GACT,SAAS,CAQrB;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,YACZ,kBAAkB,GAChB,MAAM,SAAS,CAa3B;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,GACV,SAAS,CAMrB;;CACF;;;;;;;WAlHa,OAAO;;;;aACP,WAAW;;6BARE,aAAa"}

package/types/node/lib/Util.d.ts

@@ -59,6 +59,20 @@ export default class Util extends BrowserUtil {
      * @returns {Promise<undefined>} Resolves when all listeners have completed
      */
     static asyncEmit(emitter: EventEmitter, event: string, ...args: unknown[]): Promise<undefined>;
+    /**
+     * Fires an event asynchronously without blocking the caller.
+     * Listeners run in the background via asyncEmit. If any listener rejects
+     * and an error callback is provided, it receives the error. If no callback
+     * is provided, errors are silently discarded.
+     *
+     * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+     * @param {string} event - The event name to emit
+     * @param {unknown} [payload] - Data to send with the event
+     * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors
+     * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation
+     * @returns {undefined}
+     */
+    static fire(emitter: EventEmitter, event: string, payload?: unknown, errorCb?: ((error: Error) => void) | null, signal?: AbortSignal): undefined;
     /**
      * Emits an event asynchronously and waits for all listeners to complete.
      * Like asyncEmit, but uses duck typing for more flexible emitter validation.

package/types/node/lib/Util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Util.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAmB9B;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAgB9B;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAoB9B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBALW,MAAM,QACN,OAAO,GACL,OAAO,CAmBnB;CACF;wBA1LuB,2BAA2B;6BADxB,aAAa"}
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Util.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAmB9B;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAgB9B;IAED;;;;;;;;;;;;OAYG;IACH,qBAPW,YAAY,SACZ,MAAM,YACN,OAAO,YACP,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAC,IAAI,WAC7B,WAAW,GACT,SAAS,CA6BrB;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAoB9B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBALW,MAAM,QACN,OAAO,GACL,OAAO,CAmBnB;CACF;wBApOuB,2BAA2B;6BADxB,aAAa"}