@axi-engine/utils 0.2.8 → 0.2.9

package/dist/index.d.mts

@@ -37,6 +37,12 @@ type PathType = string | string[];
  * console.log(userInstance.timestamp); // Logs the current date
  */
 type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Describes an object that can be unsubscribed from.
+ */
+interface Unsubscribable {
+    unsubscribe(): void;
+}
 /**
  * Defines the public, read-only contract for an event emitter.
  * It allows subscribing to an event but not emitting it.
@@ -48,7 +54,7 @@ type Subscribable<T extends any[]> = {
      * Subscribes a listener to this event.
      * @returns A function to unsubscribe the listener.
      */
-    subscribe(listener: (...args: T) => void): () => void;
+    subscribe(listener: (...args: T) => void): Unsubscribable;
     unsubscribe(listener: (...args: T) => void): boolean;
     clear(): void;
 };
@@ -233,6 +239,34 @@ interface DataSink {
 interface DataStorage extends DataSource, DataSink {
 }
 
+/**
+ * Represents a disposable resource, such as the execution of an Observable or an Event Listener.
+ * Allows grouping multiple teardown logic into a single unit (Composite Subscription).
+ */
+declare class Subscription implements Unsubscribable {
+    private _closed;
+    private _teardowns;
+    /**
+     * Indicates whether this subscription has already been unsubscribed.
+     */
+    get closed(): boolean;
+    /**
+     * @param teardown Optional initial teardown logic to execute when unsubscribed.
+     */
+    constructor(teardown?: () => void);
+    /**
+     * Adds a teardown logic to this subscription.
+     * If the subscription is already closed, the teardown is executed immediately.
+     * @param teardown A function or another Unsubscribable object to be managed.
+     */
+    add(teardown: Unsubscribable | (() => void)): void;
+    /**
+     * Disposes the resources held by the subscription.
+     * Executes all attached teardown logic and clears the list.
+     */
+    unsubscribe(): void;
+}
+
 /**
  * A minimal, type-safe event emitter for a single event.
  * It does not manage state, it only manages subscribers and event dispatching.
@@ -246,9 +280,15 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
     get listenerCount(): number;
     /**
      * Subscribes a listener to this event.
-     * @returns A function to unsubscribe the listener.
+     * @returns A Subscription object to manage the unsubscription.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    /**
+     * Subscribes a listener that triggers only once and then automatically unsubscribes.
+     * @param listener The callback function to execute once.
+     * @returns A Subscription object (can be used to cancel before the event fires).
      */
-    subscribe(listener: (...args: T) => void): () => void;
+    once(listener: (...args: T) => void): Subscription;
     /**
      * Manually unsubscribe by listener
      * @returns returns true if an listener has been removed, or false if the listener does not exist.
@@ -269,13 +309,25 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
  */
 declare class StateEmitter<T extends any[]> extends Emitter<T> {
     private _lastValue;
+    /**
+     * @param initialValue Optional initial value to set.
+     */
     constructor(initialValue?: T);
     /**
      * Gets the current value synchronously without subscribing.
      */
     get value(): T | undefined;
+    /**
+     * Updates the state and notifies all listeners.
+     * @param args The new value(s).
+     */
     emit(...args: T): void;
-    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Subscribes to the event. If a value exists, the listener is called immediately.
+     * @param listener The callback function.
+     * @returns A Subscription object.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
     clear(): void;
 }
 
@@ -439,4 +491,4 @@ declare class Registry<K extends PropertyKey, V> {
     clear(): void;
 }
 
-export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, type Subscribable, Subscription, type Unsubscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -37,6 +37,12 @@ type PathType = string | string[];
  * console.log(userInstance.timestamp); // Logs the current date
  */
 type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Describes an object that can be unsubscribed from.
+ */
+interface Unsubscribable {
+    unsubscribe(): void;
+}
 /**
  * Defines the public, read-only contract for an event emitter.
  * It allows subscribing to an event but not emitting it.
@@ -48,7 +54,7 @@ type Subscribable<T extends any[]> = {
      * Subscribes a listener to this event.
      * @returns A function to unsubscribe the listener.
      */
-    subscribe(listener: (...args: T) => void): () => void;
+    subscribe(listener: (...args: T) => void): Unsubscribable;
     unsubscribe(listener: (...args: T) => void): boolean;
     clear(): void;
 };
@@ -233,6 +239,34 @@ interface DataSink {
 interface DataStorage extends DataSource, DataSink {
 }
 
+/**
+ * Represents a disposable resource, such as the execution of an Observable or an Event Listener.
+ * Allows grouping multiple teardown logic into a single unit (Composite Subscription).
+ */
+declare class Subscription implements Unsubscribable {
+    private _closed;
+    private _teardowns;
+    /**
+     * Indicates whether this subscription has already been unsubscribed.
+     */
+    get closed(): boolean;
+    /**
+     * @param teardown Optional initial teardown logic to execute when unsubscribed.
+     */
+    constructor(teardown?: () => void);
+    /**
+     * Adds a teardown logic to this subscription.
+     * If the subscription is already closed, the teardown is executed immediately.
+     * @param teardown A function or another Unsubscribable object to be managed.
+     */
+    add(teardown: Unsubscribable | (() => void)): void;
+    /**
+     * Disposes the resources held by the subscription.
+     * Executes all attached teardown logic and clears the list.
+     */
+    unsubscribe(): void;
+}
+
 /**
  * A minimal, type-safe event emitter for a single event.
  * It does not manage state, it only manages subscribers and event dispatching.
@@ -246,9 +280,15 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
     get listenerCount(): number;
     /**
      * Subscribes a listener to this event.
-     * @returns A function to unsubscribe the listener.
+     * @returns A Subscription object to manage the unsubscription.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    /**
+     * Subscribes a listener that triggers only once and then automatically unsubscribes.
+     * @param listener The callback function to execute once.
+     * @returns A Subscription object (can be used to cancel before the event fires).
      */
-    subscribe(listener: (...args: T) => void): () => void;
+    once(listener: (...args: T) => void): Subscription;
     /**
      * Manually unsubscribe by listener
      * @returns returns true if an listener has been removed, or false if the listener does not exist.
@@ -269,13 +309,25 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
  */
 declare class StateEmitter<T extends any[]> extends Emitter<T> {
     private _lastValue;
+    /**
+     * @param initialValue Optional initial value to set.
+     */
     constructor(initialValue?: T);
     /**
      * Gets the current value synchronously without subscribing.
      */
     get value(): T | undefined;
+    /**
+     * Updates the state and notifies all listeners.
+     * @param args The new value(s).
+     */
     emit(...args: T): void;
-    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Subscribes to the event. If a value exists, the listener is called immediately.
+     * @param listener The callback function.
+     * @returns A Subscription object.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
     clear(): void;
 }
 
@@ -439,4 +491,4 @@ declare class Registry<K extends PropertyKey, V> {
     clear(): void;
 }
 
-export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, type Subscribable, Subscription, type Unsubscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   Emitter: () => Emitter,
   Registry: () => Registry,
   StateEmitter: () => StateEmitter,
+  Subscription: () => Subscription,
   areArraysEqual: () => areArraysEqual,
   axiSettings: () => axiSettings,
   clampNumber: () => clampNumber,
@@ -164,6 +165,48 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
+// src/subscription.ts
+var Subscription = class {
+  _closed = false;
+  _teardowns = [];
+  /**
+   * Indicates whether this subscription has already been unsubscribed.
+   */
+  get closed() {
+    return this._closed;
+  }
+  /**
+   * @param teardown Optional initial teardown logic to execute when unsubscribed.
+   */
+  constructor(teardown) {
+    if (teardown) {
+      this._teardowns.push(teardown);
+    }
+  }
+  /**
+   * Adds a teardown logic to this subscription.
+   * If the subscription is already closed, the teardown is executed immediately.
+   * @param teardown A function or another Unsubscribable object to be managed.
+   */
+  add(teardown) {
+    if (this._closed) {
+      isFunction(teardown) ? teardown() : teardown.unsubscribe();
+      return;
+    }
+    this._teardowns.push(isFunction(teardown) ? teardown : () => teardown.unsubscribe());
+  }
+  /**
+   * Disposes the resources held by the subscription.
+   * Executes all attached teardown logic and clears the list.
+   */
+  unsubscribe() {
+    if (this._closed) return;
+    this._closed = true;
+    this._teardowns.forEach((fn) => fn());
+    this._teardowns = [];
+  }
+};
+
 // src/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -175,11 +218,23 @@ var Emitter = class {
   }
   /**
    * Subscribes a listener to this event.
-   * @returns A function to unsubscribe the listener.
+   * @returns A Subscription object to manage the unsubscription.
    */
   subscribe(listener) {
     this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+    return new Subscription(() => this.unsubscribe(listener));
+  }
+  /**
+   * Subscribes a listener that triggers only once and then automatically unsubscribes.
+   * @param listener The callback function to execute once.
+   * @returns A Subscription object (can be used to cancel before the event fires).
+   */
+  once(listener) {
+    const wrapper = (...args) => {
+      this.unsubscribe(wrapper);
+      listener(...args);
+    };
+    return this.subscribe(wrapper);
   }
   /**
    * Manually unsubscribe by listener
@@ -203,6 +258,9 @@ var Emitter = class {
 };
 var StateEmitter = class extends Emitter {
   _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
   constructor(initialValue) {
     super();
     this._lastValue = initialValue ?? void 0;
@@ -213,10 +271,19 @@ var StateEmitter = class extends Emitter {
   get value() {
     return this._lastValue;
   }
+  /**
+   * Updates the state and notifies all listeners.
+   * @param args The new value(s).
+   */
   emit(...args) {
     this._lastValue = args;
     super.emit(...args);
   }
+  /**
+   * Subscribes to the event. If a value exists, the listener is called immediately.
+   * @param listener The callback function.
+   * @returns A Subscription object.
+   */
   subscribe(listener) {
     const unsubscribe = super.subscribe(listener);
     if (!isUndefined(this._lastValue)) {
@@ -318,6 +385,7 @@ var Registry = class {
   Emitter,
   Registry,
   StateEmitter,
+  Subscription,
   areArraysEqual,
   axiSettings,
   clampNumber,

package/dist/index.mjs

@@ -105,6 +105,48 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
+// src/subscription.ts
+var Subscription = class {
+  _closed = false;
+  _teardowns = [];
+  /**
+   * Indicates whether this subscription has already been unsubscribed.
+   */
+  get closed() {
+    return this._closed;
+  }
+  /**
+   * @param teardown Optional initial teardown logic to execute when unsubscribed.
+   */
+  constructor(teardown) {
+    if (teardown) {
+      this._teardowns.push(teardown);
+    }
+  }
+  /**
+   * Adds a teardown logic to this subscription.
+   * If the subscription is already closed, the teardown is executed immediately.
+   * @param teardown A function or another Unsubscribable object to be managed.
+   */
+  add(teardown) {
+    if (this._closed) {
+      isFunction(teardown) ? teardown() : teardown.unsubscribe();
+      return;
+    }
+    this._teardowns.push(isFunction(teardown) ? teardown : () => teardown.unsubscribe());
+  }
+  /**
+   * Disposes the resources held by the subscription.
+   * Executes all attached teardown logic and clears the list.
+   */
+  unsubscribe() {
+    if (this._closed) return;
+    this._closed = true;
+    this._teardowns.forEach((fn) => fn());
+    this._teardowns = [];
+  }
+};
+
 // src/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -116,11 +158,23 @@ var Emitter = class {
   }
   /**
    * Subscribes a listener to this event.
-   * @returns A function to unsubscribe the listener.
+   * @returns A Subscription object to manage the unsubscription.
    */
   subscribe(listener) {
     this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+    return new Subscription(() => this.unsubscribe(listener));
+  }
+  /**
+   * Subscribes a listener that triggers only once and then automatically unsubscribes.
+   * @param listener The callback function to execute once.
+   * @returns A Subscription object (can be used to cancel before the event fires).
+   */
+  once(listener) {
+    const wrapper = (...args) => {
+      this.unsubscribe(wrapper);
+      listener(...args);
+    };
+    return this.subscribe(wrapper);
   }
   /**
    * Manually unsubscribe by listener
@@ -144,6 +198,9 @@ var Emitter = class {
 };
 var StateEmitter = class extends Emitter {
   _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
   constructor(initialValue) {
     super();
     this._lastValue = initialValue ?? void 0;
@@ -154,10 +211,19 @@ var StateEmitter = class extends Emitter {
   get value() {
     return this._lastValue;
   }
+  /**
+   * Updates the state and notifies all listeners.
+   * @param args The new value(s).
+   */
   emit(...args) {
     this._lastValue = args;
     super.emit(...args);
   }
+  /**
+   * Subscribes to the event. If a value exists, the listener is called immediately.
+   * @param listener The callback function.
+   * @returns A Subscription object.
+   */
   subscribe(listener) {
     const unsubscribe = super.subscribe(listener);
     if (!isUndefined(this._lastValue)) {
@@ -258,6 +324,7 @@ export {
   Emitter,
   Registry,
   StateEmitter,
+  Subscription,
   areArraysEqual,
   axiSettings,
   clampNumber,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/utils",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "repository": {