@axi-engine/utils 0.1.4 → 0.1.6

package/README.md

@@ -30,7 +30,7 @@ const isSame = haveSameElements(['a', 'b'], ['b', 'a']); // Returns true
 ```
 
 
-API Reference
+## API Reference
 
 Will be available when code and repository will be fully published 
 

package/dist/index.d.mts

@@ -6,6 +6,47 @@
  * ['player', 'stats', 'health']
  */
 type PathType = string | string[];
+/**
+ * Represents a generic constructor for any class.
+ *
+ * This utility type is essential for implementing higher-order patterns
+ * like mixins, where a function takes a class as an argument and returns
+ * a new, extended class.
+ *
+ * The `...args: any[]` signature allows it to represent constructors
+ * with any number and type of arguments, making it universally applicable.
+ *
+ * @template T - The type of the instance created by the constructor. Defaults to `{}`.
+ *
+ * @example
+ * // Used as a constraint for a base class in a mixin
+ * function Timestamped<TBase extends Constructor>(Base: TBase) {
+ *   return class extends Base {
+ *     timestamp = new Date();
+ *   };
+ * }
+ *
+ * class User {}
+ * const TimestampedUser = Timestamped(User);
+ * const userInstance = new TimestampedUser();
+ * console.log(userInstance.timestamp); // Logs the current date
+ */
+type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Defines the public, read-only contract for an event emitter.
+ * It allows subscribing to an event but not emitting it.
+ * @template T A tuple representing the types of the event arguments.
+ */
+type Subscribable<T extends any[]> = {
+    readonly listenerCount: number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    unsubscribe(listener: (...args: T) => void): boolean;
+    clear(): void;
+};
 
 /**
  * Generates an array of numbers from 0 to length-1.
@@ -120,6 +161,37 @@ declare const axiSettings: AxiEngineConfig;
  */
 declare function configure(newConfig: Partial<AxiEngineConfig>): void;
 
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> implements Subscribable<T> {
+    private listeners;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+}
+
 declare function isNullOrUndefined(val: unknown): val is null | undefined;
 declare function isUndefined(val: unknown): val is undefined;
 declare function isNumber(val: unknown): val is number;
@@ -179,4 +251,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, Emitter, type PathType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -6,6 +6,47 @@
  * ['player', 'stats', 'health']
  */
 type PathType = string | string[];
+/**
+ * Represents a generic constructor for any class.
+ *
+ * This utility type is essential for implementing higher-order patterns
+ * like mixins, where a function takes a class as an argument and returns
+ * a new, extended class.
+ *
+ * The `...args: any[]` signature allows it to represent constructors
+ * with any number and type of arguments, making it universally applicable.
+ *
+ * @template T - The type of the instance created by the constructor. Defaults to `{}`.
+ *
+ * @example
+ * // Used as a constraint for a base class in a mixin
+ * function Timestamped<TBase extends Constructor>(Base: TBase) {
+ *   return class extends Base {
+ *     timestamp = new Date();
+ *   };
+ * }
+ *
+ * class User {}
+ * const TimestampedUser = Timestamped(User);
+ * const userInstance = new TimestampedUser();
+ * console.log(userInstance.timestamp); // Logs the current date
+ */
+type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Defines the public, read-only contract for an event emitter.
+ * It allows subscribing to an event but not emitting it.
+ * @template T A tuple representing the types of the event arguments.
+ */
+type Subscribable<T extends any[]> = {
+    readonly listenerCount: number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    unsubscribe(listener: (...args: T) => void): boolean;
+    clear(): void;
+};
 
 /**
  * Generates an array of numbers from 0 to length-1.
@@ -120,6 +161,37 @@ declare const axiSettings: AxiEngineConfig;
  */
 declare function configure(newConfig: Partial<AxiEngineConfig>): void;
 
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> implements Subscribable<T> {
+    private listeners;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+}
+
 declare function isNullOrUndefined(val: unknown): val is null | undefined;
 declare function isUndefined(val: unknown): val is undefined;
 declare function isNumber(val: unknown): val is number;
@@ -179,4 +251,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, Emitter, type PathType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Emitter: () => Emitter,
   areArraysEqual: () => areArraysEqual,
   axiSettings: () => axiSettings,
   clampNumber: () => clampNumber,
@@ -136,6 +137,44 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -171,6 +210,7 @@ function randId() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Emitter,
   areArraysEqual,
   axiSettings,
   clampNumber,

package/dist/index.mjs

@@ -86,6 +86,44 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -120,6 +158,7 @@ function randId() {
   return uuidv4();
 }
 export {
+  Emitter,
   areArraysEqual,
   axiSettings,
   clampNumber,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/utils",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "keywords": [
@@ -9,14 +9,14 @@
     "gamedev",
     "utils"
   ],
+  "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "scripts": {