@axi-engine/utils 0.2.8 → 0.2.10

package/dist/index.d.mts

@@ -37,6 +37,22 @@ type PathType = string | string[];
  * console.log(userInstance.timestamp); // Logs the current date
  */
 type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Represents an object that has a lifecycle and requires explicit destruction.
+ */
+interface Destroyable {
+    /**
+     * Destroys the object, releasing all held resources.
+     * After calling this, the object should be considered unusable.
+     */
+    destroy(): void;
+}
+/**
+ * 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 +64,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;
 };
@@ -161,6 +177,7 @@ declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts va
  */
 declare function throwError(message: string): never;
 
+/** todo: rename to 'utils config' */
 interface AxiEngineConfig {
     pathSeparator: string;
 }
@@ -225,12 +242,44 @@ interface DataSink {
      * @param path The path to the value to be deleted.
      */
     delete(path: PathType): void;
+    /**
+     * Deletes all values
+     */
+    clear(): void;
 }
 /**
  * A full CRUD contract for systems that provide complete data management.
  * Combines both reading and writing capabilities.
  */
-interface DataStorage extends DataSource, DataSink {
+interface DataStorage extends DataSource, DataSink, Destroyable {
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -246,9 +295,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.
@@ -263,19 +318,32 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      */
     clear(): void;
 }
+
 /**
  * An Emitter that stores the last emitted value.
  * New subscribers immediately receive the last value upon subscription.
  */
 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;
 }
 
@@ -362,15 +430,18 @@ declare function clampNumber(val: number, min?: number | null, max?: number | nu
  * Calculates a percentage of a given value.
  * @param val The base value.
  * @param percents The percentage to get.
+ * @param precision Optional number of decimal places to round the result to.
  * @returns The calculated percentage of the value.
- * @example getPercentOf(200, 10); // returns 20
+ * @example getPercentOf(200, 12.5); // returns 25
+ * @example getPercentOf(100, 33.333, 2); // returns 33.33
  */
-declare function getPercentOf(val: number, percents: number): number;
+declare function getPercentOf(val: number, percents: number, precision?: number): number;
 
 /**
  * Returns the first key of an object.
  * @param obj The object from which to get the key.
  * @returns The first key of the object as a string.
+ * @throws {Error} If the argument is not a valid object.
  */
 declare function firstKeyOf(obj: any): string;
 
@@ -395,7 +466,7 @@ declare function randInt(min: number, max: number): number;
  * Generates a unique identifier using uuidv4.
  * @returns A unique string ID.
  */
-declare function randId(): string;
+declare function uid(): string;
 
 /**
  * A generic, type-safe wrapper around a Map for managing collections of items by key.
@@ -439,4 +510,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, type Destroyable, 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, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, uid, unique };

package/dist/index.d.ts

@@ -37,6 +37,22 @@ type PathType = string | string[];
  * console.log(userInstance.timestamp); // Logs the current date
  */
 type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Represents an object that has a lifecycle and requires explicit destruction.
+ */
+interface Destroyable {
+    /**
+     * Destroys the object, releasing all held resources.
+     * After calling this, the object should be considered unusable.
+     */
+    destroy(): void;
+}
+/**
+ * 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 +64,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;
 };
@@ -161,6 +177,7 @@ declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts va
  */
 declare function throwError(message: string): never;
 
+/** todo: rename to 'utils config' */
 interface AxiEngineConfig {
     pathSeparator: string;
 }
@@ -225,12 +242,44 @@ interface DataSink {
      * @param path The path to the value to be deleted.
      */
     delete(path: PathType): void;
+    /**
+     * Deletes all values
+     */
+    clear(): void;
 }
 /**
  * A full CRUD contract for systems that provide complete data management.
  * Combines both reading and writing capabilities.
  */
-interface DataStorage extends DataSource, DataSink {
+interface DataStorage extends DataSource, DataSink, Destroyable {
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -246,9 +295,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.
@@ -263,19 +318,32 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      */
     clear(): void;
 }
+
 /**
  * An Emitter that stores the last emitted value.
  * New subscribers immediately receive the last value upon subscription.
  */
 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;
 }
 
@@ -362,15 +430,18 @@ declare function clampNumber(val: number, min?: number | null, max?: number | nu
  * Calculates a percentage of a given value.
  * @param val The base value.
  * @param percents The percentage to get.
+ * @param precision Optional number of decimal places to round the result to.
  * @returns The calculated percentage of the value.
- * @example getPercentOf(200, 10); // returns 20
+ * @example getPercentOf(200, 12.5); // returns 25
+ * @example getPercentOf(100, 33.333, 2); // returns 33.33
  */
-declare function getPercentOf(val: number, percents: number): number;
+declare function getPercentOf(val: number, percents: number, precision?: number): number;
 
 /**
  * Returns the first key of an object.
  * @param obj The object from which to get the key.
  * @returns The first key of the object as a string.
+ * @throws {Error} If the argument is not a valid object.
  */
 declare function firstKeyOf(obj: any): string;
 
@@ -395,7 +466,7 @@ declare function randInt(min: number, max: number): number;
  * Generates a unique identifier using uuidv4.
  * @returns A unique string ID.
  */
-declare function randId(): string;
+declare function uid(): string;
 
 /**
  * A generic, type-safe wrapper around a Map for managing collections of items by key.
@@ -439,4 +510,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, type Destroyable, 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, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, uid, 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,
@@ -47,12 +48,12 @@ __export(index_exports, {
   isString: () => isString,
   isUndefined: () => isUndefined,
   last: () => last,
-  randId: () => randId,
   randInt: () => randInt,
   shuffleArray: () => shuffleArray,
   throwError: () => throwError,
   throwIf: () => throwIf,
   throwIfEmpty: () => throwIfEmpty,
+  uid: () => uid,
   unique: () => unique
 });
 module.exports = __toCommonJS(index_exports);
@@ -136,7 +137,7 @@ function isPromise(value) {
   return value != null && typeof value.then === "function";
 }
 function isPercentageString(val) {
-  return typeof val === "string" && val.endsWith("%");
+  return isString(val) && val.endsWith("%");
 }
 
 // src/assertion.ts
@@ -146,10 +147,10 @@ function throwIf(condition, exceptionMessage) {
   }
 }
 function throwIfEmpty(value, exceptionMessage) {
-  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
-  if (isNullOrUndefined(value) || isArrayAndEmpty) {
-    throw new Error(exceptionMessage);
-  }
+  throwIf(
+    isNullOrUndefined(value) || Array.isArray(value) && !value.length,
+    exceptionMessage
+  );
 }
 function throwError(message) {
   throw new Error(message);
@@ -157,14 +158,56 @@ function throwError(message) {
 
 // src/config.ts
 var defaultConfig = {
-  pathSeparator: "/"
+  pathSeparator: "."
 };
 var axiSettings = { ...defaultConfig };
 function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
-// src/emitter.ts
+// 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/emitters/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
@@ -201,8 +256,13 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+
+// src/emitters/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
   constructor(initialValue) {
     super();
     this._lastValue = initialValue ?? void 0;
@@ -213,10 +273,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)) {
@@ -236,12 +305,17 @@ function clampNumber(val, min, max) {
   if (!isNullOrUndefined(max)) val = Math.min(val, max);
   return val;
 }
-function getPercentOf(val, percents) {
-  return percents / 100 * val;
+function getPercentOf(val, percents, precision) {
+  const result = percents / 100 * val;
+  if (!isUndefined(precision)) {
+    return Number(result.toFixed(precision));
+  }
+  return result;
 }
 
 // src/misc.ts
 function firstKeyOf(obj) {
+  throwIf(!isObject(obj), `firstKeyOf: Expected an object, got ${typeof obj}`);
   return Object.keys(obj)[0];
 }
 
@@ -260,7 +334,7 @@ function randInt(min, max) {
   max = Math.floor(max);
   return Math.floor(Math.random() * (max - min) + min);
 }
-function randId() {
+function uid() {
   return (0, import_uuid.v4)();
 }
 
@@ -318,6 +392,7 @@ var Registry = class {
   Emitter,
   Registry,
   StateEmitter,
+  Subscription,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -342,11 +417,11 @@ var Registry = class {
   isString,
   isUndefined,
   last,
-  randId,
   randInt,
   shuffleArray,
   throwError,
   throwIf,
   throwIfEmpty,
+  uid,
   unique
 });

package/dist/index.mjs

@@ -77,7 +77,7 @@ function isPromise(value) {
   return value != null && typeof value.then === "function";
 }
 function isPercentageString(val) {
-  return typeof val === "string" && val.endsWith("%");
+  return isString(val) && val.endsWith("%");
 }
 
 // src/assertion.ts
@@ -87,10 +87,10 @@ function throwIf(condition, exceptionMessage) {
   }
 }
 function throwIfEmpty(value, exceptionMessage) {
-  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
-  if (isNullOrUndefined(value) || isArrayAndEmpty) {
-    throw new Error(exceptionMessage);
-  }
+  throwIf(
+    isNullOrUndefined(value) || Array.isArray(value) && !value.length,
+    exceptionMessage
+  );
 }
 function throwError(message) {
   throw new Error(message);
@@ -98,14 +98,56 @@ function throwError(message) {
 
 // src/config.ts
 var defaultConfig = {
-  pathSeparator: "/"
+  pathSeparator: "."
 };
 var axiSettings = { ...defaultConfig };
 function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
-// src/emitter.ts
+// 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/emitters/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
@@ -142,8 +196,13 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+
+// src/emitters/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
   constructor(initialValue) {
     super();
     this._lastValue = initialValue ?? void 0;
@@ -154,10 +213,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)) {
@@ -177,12 +245,17 @@ function clampNumber(val, min, max) {
   if (!isNullOrUndefined(max)) val = Math.min(val, max);
   return val;
 }
-function getPercentOf(val, percents) {
-  return percents / 100 * val;
+function getPercentOf(val, percents, precision) {
+  const result = percents / 100 * val;
+  if (!isUndefined(precision)) {
+    return Number(result.toFixed(precision));
+  }
+  return result;
 }
 
 // src/misc.ts
 function firstKeyOf(obj) {
+  throwIf(!isObject(obj), `firstKeyOf: Expected an object, got ${typeof obj}`);
   return Object.keys(obj)[0];
 }
 
@@ -201,7 +274,7 @@ function randInt(min, max) {
   max = Math.floor(max);
   return Math.floor(Math.random() * (max - min) + min);
 }
-function randId() {
+function uid() {
   return uuidv4();
 }
 
@@ -258,6 +331,7 @@ export {
   Emitter,
   Registry,
   StateEmitter,
+  Subscription,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -282,11 +356,11 @@ export {
   isString,
   isUndefined,
   last,
-  randId,
   randInt,
   shuffleArray,
   throwError,
   throwIf,
   throwIfEmpty,
+  uid,
   unique
 };

package/package.json

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