@gesslar/toolkit 0.0.5 → 0.0.7

package/package.json

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

package/src/index.js

@@ -6,6 +6,7 @@ export {default as File} from "./lib/File.js"
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"
 export {default as Data} from "./lib/Data.js"
+export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
 export {default as Term} from "./lib/Term.js"
 export {default as Type} from "./lib/Type.js"

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/Glog.js

@@ -0,0 +1,119 @@
+import Data from "./Data.js"
+import console from "node:console"
+
+/**
+ * Global logging utility with configurable log levels and prefixes.
+ * Provides a flexible logging system that can be used as both a class and
+ * a callable function, with support for log level filtering and custom
+ * prefixes for better log organization.
+ *
+ * The Glog class uses a proxy to enable both class-style and function-style
+ * usage patterns, making it convenient for different coding preferences.
+ *
+ * @example
+ * // Set up logging configuration
+ * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
+ *
+ * // Log messages with different levels
+ * Glog(0, 'Critical error')  // Always shown
+ * Glog(2, 'Debug info')      // Shown if logLevel >= 2
+ * Glog('Simple message')     // Level 0 by default
+ */
+class Glog {
+  /** @type {number} Current log level threshold (0-5) */
+  logLevel = 0
+  /** @type {string} Prefix to prepend to all log messages */
+  logPrefix = ""
+
+  /**
+   * Sets the log prefix for all subsequent log messages.
+   * The prefix helps identify the source of log messages in complex
+   * applications with multiple components.
+   *
+   * @param {string} prefix - The prefix string to prepend to log messages
+   * @returns {typeof Glog} Returns the Glog class for method chaining
+   * @example
+   * Glog.setLogPrefix('[Database]')
+   * Glog('Connection established') // Output: [Database] Connection established
+   */
+  static setLogPrefix(prefix) {
+    this.logPrefix = prefix
+
+    return Glog
+  }
+
+  /**
+   * Sets the minimum log level for messages to be displayed.
+   * Messages with a level higher than this threshold will be filtered out.
+   * Log levels range from 0 (critical) to 5 (verbose debug).
+   *
+   * @param {number} level - The minimum log level (0-5, clamped to range)
+   * @returns {typeof Glog} Returns the Glog class for method chaining
+   * @example
+   * Glog.setLogLevel(2) // Only show messages with level 0, 1, or 2
+   * Glog(1, 'Important') // Shown
+   * Glog(3, 'Verbose')   // Hidden
+   */
+  static setLogLevel(level) {
+    this.logLevel = Data.clamp(level, 0, 5)
+
+    return Glog
+  }
+
+  /**
+   * Internal logging method that handles message formatting and level
+   * filtering.
+   *
+   * Parses arguments to determine log level and message content, then outputs
+   * the message if it meets the current log level threshold.
+   *
+   * @private
+   * @param {...unknown} args - Variable arguments: either (level, ...messages) or (...messages)
+   * @returns {void}
+   */
+  static #log(...args) {
+    let level, rest
+
+    if(args.length === 0) {
+      ;[level=0, rest=[""]] = null
+    } else if(args.length === 1) {
+      ;[rest, level=0] = [args, 0]
+    } else {
+      ;[level, ...rest] = args
+    }
+
+    if(level > this.logLevel)
+      return
+
+    if(this.logPrefix)
+      console.log(this.logPrefix, ...rest)
+    else
+      console.log(...rest)
+  }
+
+  /**
+   * Executes a log operation with the provided arguments.
+   * This method serves as the entry point for all logging operations,
+   * delegating to the private #log method for actual processing.
+   *
+   * @param {...unknown} args - Log level (optional) followed by message arguments
+   * @returns {void}
+   * @example
+   * Glog.execute(0, 'Error:', error.message)
+   * Glog.execute('Simple message') // Level 0 assumed
+   */
+  static execute(...args) {
+    this.#log(...args)
+  }
+}
+
+// Wrap the class in a proxy
+export default new Proxy(Glog, {
+  apply(target, thisArg, argumentsList) {
+    // When called as function: MyClass(things, and, stuff)
+    return target.execute(...argumentsList)
+  },
+  construct(target, argumentsList) {
+    return new target(...argumentsList)
+  }
+})

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/Glog.d.ts

@@ -0,0 +1,72 @@
+// Implementation: ../lib/Glog.js
+
+/**
+ * Global logging utility with configurable log levels and prefixes.
+ * Provides a flexible logging system that can be used as both a class and
+ * a callable function, with support for log level filtering and custom
+ * prefixes for better log organization.
+ *
+ * The Glog class uses a proxy to enable both class-style and function-style
+ * usage patterns, making it convenient for different coding preferences.
+ *
+ * @example
+ * ```typescript
+ * // Set up logging configuration
+ * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
+ *
+ * // Log messages with different levels
+ * Glog(0, 'Critical error')  // Always shown
+ * Glog(2, 'Debug info')      // Shown if logLevel >= 2
+ * Glog('Simple message')     // Level 0 by default
+ * ```
+ */
+interface GlogInterface {
+  /**
+   * Sets the log prefix for all subsequent log messages.
+   * The prefix helps identify the source of log messages in complex
+   * applications with multiple components.
+   *
+   * @param prefix - The prefix string to prepend to log messages
+   * @returns Returns the Glog class for method chaining
+   */
+  setLogPrefix(prefix: string): typeof Glog
+
+  /**
+   * Sets the minimum log level for messages to be displayed.
+   * Messages with a level higher than this threshold will be filtered out.
+   * Log levels range from 0 (critical) to 5 (verbose debug).
+   *
+   * @param level - The minimum log level (0-5, clamped to range)
+   * @returns Returns the Glog class for method chaining
+   */
+  setLogLevel(level: number): typeof Glog
+
+  /**
+   * Executes a log operation with the provided arguments.
+   * This method serves as the entry point for all logging operations.
+   *
+   * @param args - Log level (optional) followed by message arguments
+   */
+  execute(...args: any[]): void
+}
+
+/**
+ * Callable interface for the proxied Glog class.
+ * Allows the class to be used as a function.
+ */
+interface GlogCallable {
+  /**
+   * Log a message with optional level specification.
+   * 
+   * @param args - Either (level: number, ...messages) or (...messages)
+   */
+  (...args: any[]): void
+}
+
+/**
+ * The Glog class with proxy functionality for callable behavior.
+ * Can be used both as a static class and as a callable function.
+ */
+declare const Glog: GlogInterface & GlogCallable
+
+export default Glog

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

package/src/types/index.d.ts

@@ -7,6 +7,7 @@ export { default as File } from './File.js'
 // Utility classes
 export { default as Cache } from './Cache.js'
 export { default as Data } from './Data.js'
+export { default as Glog } from './Glog.js'
 export { default as Sass } from './Sass.js'
 export { default as Term } from './Term.js'
 export { default as Type } from './Type.js'