@gesslar/toolkit 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/Data.js

@@ -1,6 +1,9 @@
 /**
- * @file Data utility functions for type checking, object manipulation, and array operations.
- * Provides comprehensive utilities for working with JavaScript data types and structures.
+ * @file Data utility functions for type checking, object manipulation, and
+ * array operations.
+ *
+ * Provides comprehensive utilities for working with JavaScript data types and
+ * structures.
  */
 
 import Sass from "./Sass.js"
@@ -54,7 +57,9 @@ export default class Data {
   ])
 
   /**
-   * Combined array of all supported data types (primitives and constructors in lowercase).
+   * Combined array of all supported data types (primitives and constructors in
+   * lowercase).
+   *
    * Used for type validation throughout the utility functions.
    *
    * @type {Array<string>}
@@ -530,4 +535,27 @@ export default class Data {
     return arr.filter((_, index) => results[index])
   }
 
+  /**
+   * Ensures a value is within a specified range.
+   *
+   * @param {number} val - The value to check.
+   * @param {number} min - The minimum value.
+   * @param {number} max - The maximum value.
+   * @returns {number} The value, constrained within the range of `min` to `max`.
+   */
+  static clamp(val, min, max) {
+    return val >= min ? val <= max ? val : max : min
+  }
+
+  /**
+   * Checks if a value is within a specified range (inclusive).
+   *
+   * @param {number} val - The value to check.
+   * @param {number} min - The minimum value (inclusive).
+   * @param {number} max - The maximum value (inclusive).
+   * @returns {boolean} True if the value is within the range, false otherwise.
+   */
+  static clamped(val, min, max) {
+    return val >= min && val <= max
+  }
 }

package/src/lib/Util.js

@@ -1,5 +1,7 @@
 import {createHash} from "node:crypto"
 import {performance} from "node:perf_hooks"
+import {EventEmitter} from "node:events"
+import Sass from "./Sass.js"
 
 /**
  * Utility class providing common helper functions for string manipulation,
@@ -131,4 +133,91 @@ export default class Util {
   static async race(promises) {
     return await Promise.race(promises)
   }
+
+  /**
+   * Private method that performs the actual async emission logic.
+   * Handles listener execution, error aggregation, and result processing.
+   *
+   * @param {object} emitter - The emitter object (already validated)
+   * @param {string} event - The event name to emit
+   * @param {...unknown} args - Arguments to pass to event listeners
+   * @returns {Promise<void>} Resolves when all listeners have completed
+   */
+  static async #performAsyncEmit(emitter, event, ...args) {
+    const listeners = emitter.listeners(event)
+
+    if(listeners.length === 0)
+      return // No listeners, nothing to do
+
+    const settled =
+      await Promise.allSettled(listeners.map(listener => listener(...args)))
+
+    const rejected = settled.filter(result => result.status === "rejected")
+
+    if(rejected.length > 0) {
+      if(rejected[0].reason instanceof Error)
+        throw rejected[0].reason
+      else
+        throw Sass.new(rejected[0].reason)
+    }
+  }
+
+  /**
+   * Emits an event asynchronously and waits for all listeners to complete.
+   * Unlike the standard EventEmitter.emit() which is synchronous, this method
+   * properly handles async event listeners by waiting for all of them to
+   * resolve or reject using Promise.allSettled().
+   *
+   * Uses strict instanceof checking to ensure the emitter is a genuine EventEmitter.
+   *
+   * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+   * @param {string} event - The event name to emit
+   * @param {...unknown} args - Arguments to pass to event listeners
+   * @returns {Promise<void>} Resolves when all listeners have completed
+   */
+  static async asyncEmit(emitter, event, ...args) {
+    try {
+      if(!(emitter instanceof EventEmitter))
+        throw Sass.new("First argument must be an EventEmitter instance")
+
+      await this.#performAsyncEmit(emitter, event, ...args)
+    } catch(error) {
+      const argsDesc = args.length > 0 ? `with arguments: ${args.map(String).join(", ")}` : "with no arguments"
+
+      throw Sass.new(
+        `Processing '${event}' event ${argsDesc}.`,
+        error
+      )
+    }
+  }
+
+  /**
+   * Emits an event asynchronously and waits for all listeners to complete.
+   * Like asyncEmit, but uses duck typing for more flexible emitter validation.
+   * Accepts any object that has the required EventEmitter-like methods.
+   *
+   * @param {object} emitter - Any object with EventEmitter-like interface
+   * @param {string} event - The event name to emit
+   * @param {...unknown} args - Arguments to pass to event listeners
+   * @returns {Promise<void>} Resolves when all listeners have completed
+   */
+  static async asyncEmitAnon(emitter, event, ...args) {
+    try {
+      if(!emitter ||
+         typeof emitter.listeners !== "function" ||
+         typeof emitter.on !== "function" ||
+         typeof emitter.emit !== "function") {
+        throw Sass.new("First argument must be an EventEmitter-like object")
+      }
+
+      await this.#performAsyncEmit(emitter, event, ...args)
+    } catch(error) {
+      const argsDesc = args.length > 0 ? `with arguments: ${args.map(String).join(", ")}` : "with no arguments"
+
+      throw Sass.new(
+        `Processing '${event}' event ${argsDesc}.`,
+        error
+      )
+    }
+  }
 }

package/src/types/Data.d.ts

@@ -94,4 +94,10 @@ export default class Data {
 
   /** Filter an array asynchronously */
   static asyncFilter<T>(arr: Array<T>, predicate: (item: T) => Promise<boolean>): Promise<Array<T>>
-}
+
+  /** Ensures a value is within a specified range */
+  static clamp(val: number, min: number, max: number): number
+
+  /** Checks if a value is within a specified range (inclusive) */
+  static clamped(val: number, min: number, max: number): boolean
+}

package/src/types/Util.d.ts

@@ -81,6 +81,33 @@ declare class Util {
    * @returns Result of the first settled promise
    */
   static race<T>(promises: Array<Promise<T>>): Promise<T>
+
+  /**
+   * Emits an event asynchronously and waits for all listeners to complete.
+   * Unlike the standard EventEmitter.emit() which is synchronous, this method
+   * properly handles async event listeners by waiting for all of them to
+   * resolve or reject using Promise.allSettled().
+   *
+   * Uses strict instanceof checking to ensure the emitter is a genuine EventEmitter.
+   *
+   * @param emitter - The EventEmitter instance to emit on
+   * @param event - The event name to emit
+   * @param args - Arguments to pass to event listeners
+   * @returns Resolves when all listeners have completed
+   */
+  static asyncEmit(emitter: import('events').EventEmitter, event: string, ...args: unknown[]): Promise<void>
+
+  /**
+   * Emits an event asynchronously and waits for all listeners to complete.
+   * Like asyncEmit, but uses duck typing for more flexible emitter validation.
+   * Accepts any object that has the required EventEmitter-like methods.
+   *
+   * @param emitter - Any object with EventEmitter-like interface
+   * @param event - The event name to emit
+   * @param args - Arguments to pass to event listeners
+   * @returns Resolves when all listeners have completed
+   */
+  static asyncEmitAnon(emitter: { listeners(event: string): Function[], on(event: string, listener: Function): any, emit(event: string, ...args: unknown[]): any }, event: string, ...args: unknown[]): Promise<void>
 }
 
 export default Util