@axi-engine/utils 0.2.9 → 0.2.10

package/dist/index.d.mts

@@ -37,6 +37,16 @@ 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.
  */
@@ -167,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;
 }
@@ -231,12 +242,16 @@ 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 {
 }
 
 /**
@@ -303,6 +318,7 @@ 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.
@@ -414,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;
 
@@ -447,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.
@@ -491,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, 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 };
+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,16 @@ 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.
  */
@@ -167,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;
 }
@@ -231,12 +242,16 @@ 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 {
 }
 
 /**
@@ -303,6 +318,7 @@ 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.
@@ -414,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;
 
@@ -447,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.
@@ -491,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, 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 };
+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

@@ -48,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);
@@ -137,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
@@ -147,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);
@@ -158,7 +158,7 @@ function throwError(message) {
 
 // src/config.ts
 var defaultConfig = {
-  pathSeparator: "/"
+  pathSeparator: "."
 };
 var axiSettings = { ...defaultConfig };
 function configure(newConfig) {
@@ -207,7 +207,7 @@ var Subscription = class {
   }
 };
 
-// src/emitter.ts
+// src/emitters/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
   /**
@@ -256,6 +256,8 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+
+// src/emitters/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
   /**
@@ -303,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];
 }
 
@@ -327,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)();
 }
 
@@ -410,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,7 +98,7 @@ function throwError(message) {
 
 // src/config.ts
 var defaultConfig = {
-  pathSeparator: "/"
+  pathSeparator: "."
 };
 var axiSettings = { ...defaultConfig };
 function configure(newConfig) {
@@ -147,7 +147,7 @@ var Subscription = class {
   }
 };
 
-// src/emitter.ts
+// src/emitters/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
   /**
@@ -196,6 +196,8 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+
+// src/emitters/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
   /**
@@ -243,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];
 }
 
@@ -267,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();
 }
 
@@ -349,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.9",
+  "version": "0.2.10",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "repository": {