goaded.utils 1.0.0 → 1.0.1

package/events.js

@@ -1,20 +1,52 @@
+/**
+ * A simple event emitter class that manages event subscriptions and emissions.
+ * Supports synchronous and asynchronous execution, one-time events, and repeated emissions.
+ */
 class emitter {
+    /**
+     * Internal storage for event listeners.
+     * @type {Array<{event: string, callback: Function}>}
+     */
     listeners = [];
-    
+
+    /**
+     * Creates a new instance of the emitter.
+     */
     constructor() {}
-    
+
+    /**
+     * Subscribes a callback function to a specific event.
+     * 
+     * @param {string} event - The name of the event to subscribe to.
+     * @param {Function} callback - The function to execute when the event is emitted.
+     * @returns {emitter} The current instance for chaining.
+     */
     on(event, callback) {
         this.listeners.push({event, callback});
         return this;
     }
-    
+
+    /**
+     * Unsubscribes a specific callback from an event.
+     * 
+     * @param {string} event - The name of the event.
+     * @param {Function} callback - The specific callback function to remove.
+     * @returns {emitter} The current instance for chaining.
+     */
     off(event, callback) {
         this.listeners = this.listeners.filter(
             listener => listener.event !== event || listener.callback !== callback
         );
         return this;
     }
-    
+
+    /**
+     * Subscribes to an event only once. The callback is removed after the first execution.
+     * 
+     * @param {string} event - The name of the event.
+     * @param {Function} callback - The function to execute once.
+     * @returns {emitter} The current instance for chaining.
+     */
     once(event, callback) {
         const wrappedCallback = (...args) => {
             callback(...args);
@@ -23,7 +55,15 @@ class emitter {
         this.on(event, wrappedCallback);
         return this;
     }
-    
+
+    /**
+     * Synchronously calls all listeners registered for the specified event.
+     * Errors in listeners are caught and logged, preventing the loop from breaking.
+     * 
+     * @param {string} event - The name of the event to emit.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {void}
+     */
     emit(event, ...args) {
         this.listeners.forEach(listener => {
             if(listener.event === event) {
@@ -35,7 +75,16 @@ class emitter {
             }
         });
     }
-    
+
+    /**
+     * Asynchronously calls all listeners registered for the specified event.
+     * Waits for all promises returned by listeners to resolve.
+     * 
+     * @async
+     * @param {string} event - The name of the event to emit.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {Promise<void>} A promise that resolves when all listeners have completed.
+     */
     async emitAsync(event, ...args) {
         const promises = this.listeners
             .filter(listener => listener.event === event)
@@ -43,7 +92,15 @@ class emitter {
         
         await Promise.all(promises);
     }
-    
+
+    /**
+     * Synchronously calls all listeners for an event and then immediately removes them.
+     * This effectively "flushes" the listeners for that specific event.
+     * 
+     * @param {string} event - The name of the event.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {void}
+     */
     emitOnce(event, ...args) {
         this.listeners = this.listeners.filter(listener => {
             if(listener.event === event) {
@@ -52,12 +109,20 @@ class emitter {
                 } catch(error) {
                     console.error(`Error in event listener for "${event}":`, error);
                 }
-                return false;
+                return false; // Remove listener
             }
-            return true;
+            return true; // Keep listener
         });
     }
-    
+
+    /**
+     * Asynchronously calls all listeners for an event and then removes them.
+     * 
+     * @async
+     * @param {string} event - The name of the event.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {Promise<void>} A promise that resolves when all listeners have completed.
+     */
     async emitOnceAsync(event, ...args) {
         const matchingListeners = this.listeners.filter(
             listener => listener.event === event
@@ -73,7 +138,15 @@ class emitter {
             )
         );
     }
-    
+
+    /**
+     * Synchronously triggers listeners for an event a specific number of times.
+     * 
+     * @param {string} event - The name of the event.
+     * @param {number} times - The number of times to trigger the listeners.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {void}
+     */
     emitRepeat(event, times, ...args) {
         this.listeners.forEach(listener => {
             if(listener.event === event) {
@@ -87,7 +160,17 @@ class emitter {
             }
         });
     }
-    
+
+    /**
+     * Asynchronously triggers listeners for an event a specific number of times.
+     * It waits for all listeners to complete one round before starting the next iteration.
+     * 
+     * @async
+     * @param {string} event - The name of the event.
+     * @param {number} times - The number of times to trigger the listeners.
+     * @param {...*} args - Arguments to pass to the callback functions.
+     * @returns {Promise<void>} A promise that resolves when all repetitions are complete.
+     */
     async emitRepeatAsync(event, times, ...args) {
         const matchingListeners = this.listeners.filter(
             listener => listener.event === event

package/package.json

@@ -3,7 +3,7 @@
     "sqlite3": "^5.1.7"
   },
   "name": "goaded.utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "services.js",
   "devDependencies": {},