@axi-engine/utils 0.1.7 → 0.1.8

package/dist/index.mjs

@@ -1,232 +1,355 @@
-// src/arrays.ts
+import { v4 } from "uuid";
+
+//#region src/arrays.ts
+/**
+* Generates an array of numbers from 0 to length-1.
+* @param length The desired length of the array.
+* @returns An array of sequential numbers.
+* @example genArray(3); // returns [0, 1, 2]
+*/
 function genArray(length) {
-  return Array.from({ length }, (_v, i) => i);
+	return Array.from({ length }, (_v, i) => i);
 }
+/**
+* Creates a new array with its elements shuffled in a random order.
+* This function does not mutate the original array.
+* @template T The type of elements in the array.
+* @param array The array to shuffle.
+* @returns A new, shuffled array.
+*/
 function shuffleArray(array) {
-  const result = [...array];
-  for (let i = result.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [result[i], result[j]] = [result[j], result[i]];
-  }
-  return result;
+	const result = [...array];
+	for (let i = result.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[result[i], result[j]] = [result[j], result[i]];
+	}
+	return result;
 }
+/**
+* Checks if the first array is a sequential starting subset of the second array.
+* @param arr1 The potential subset array.
+* @param arr2 The array to check against.
+* @returns `true` if arr1 is a sequential start of arr2, otherwise `false`.
+* @example
+* isSequentialStart([1, 2], [1, 2, 3]); // true
+* isSequentialStart([1, 3], [1, 2, 3]); // false
+*/
 function isSequentialStart(arr1, arr2) {
-  if (arr1.length > arr2.length) {
-    return false;
-  }
-  return arr1.every((element, index) => element === arr2[index]);
+	if (arr1.length > arr2.length) return false;
+	return arr1.every((element, index) => element === arr2[index]);
 }
+/**
+* Checks if two arrays contain the same elements, ignoring order.
+* Works for arrays of primitives like strings or numbers.
+* @template T The type of elements in the array.
+* @param arr1 The first array.
+* @param arr2 The second array.
+* @returns `true` if both arrays contain the same elements, otherwise `false`.
+* @example
+* haveSameElements(['a', 'b'], ['b', 'a']); // true
+* haveSameElements([1, 2, 3], [3, 1, 2]); // true
+* haveSameElements(['a', 'b'], ['a', 'c']); // false
+*/
 function haveSameElements(arr1, arr2) {
-  if (!arr1 && !arr2) return true;
-  if (!arr1 || !arr2) return false;
-  if (arr1.length !== arr2.length) return false;
-  const sortedArr1 = [...arr1].sort();
-  const sortedArr2 = [...arr2].sort();
-  return sortedArr1.every((value, index) => value === sortedArr2[index]);
+	if (!arr1 && !arr2) return true;
+	if (!arr1 || !arr2) return false;
+	if (arr1.length !== arr2.length) return false;
+	const sortedArr1 = [...arr1].sort();
+	const sortedArr2 = [...arr2].sort();
+	return sortedArr1.every((value, index) => value === sortedArr2[index]);
 }
+/**
+* Checks if two arrays are strictly equal (same elements in the same order).
+* @template T The type of elements in the array.
+* @param arr1 The first array.
+* @param arr2 The second array.
+* @returns `true` if the arrays are strictly equal, otherwise `false`.
+* @example
+* areArraysEqual(['a', 'b'], ['a', 'b']); // true
+* areArraysEqual(['a', 'b'], ['b', 'a']); // false
+* areArraysEqual([1, 2], [1, 2, 3]);    // false
+*/
 function areArraysEqual(arr1, arr2) {
-  if (!arr1 && !arr2) return true;
-  if (!arr1 || !arr2) return false;
-  if (arr1.length !== arr2.length) return false;
-  return arr1.every((value, index) => value === arr2[index]);
+	if (!arr1 && !arr2) return true;
+	if (!arr1 || !arr2) return false;
+	if (arr1.length !== arr2.length) return false;
+	return arr1.every((value, index) => value === arr2[index]);
 }
+/**
+* Gets the last element of an array.
+* @template T The type of elements in the array.
+* @param array The array to query.
+* @returns The last element of the array, or `undefined` if the array is empty.
+*/
 function last(array) {
-  return array[array.length - 1];
+	return array[array.length - 1];
 }
+/**
+* Creates a duplicate-free version of an array.
+* @template T The type of elements in the array.
+* @param array The array to process.
+* @returns A new array with only unique elements.
+*/
 function unique(array) {
-  return [...new Set(array)];
+	return [...new Set(array)];
 }
+/**
+* Gets a random element from an array.
+* @template T The type of elements in the array.
+* @param array The array to choose from.
+* @returns A random element from the array, or `undefined` if the array is empty.
+*/
 function getRandomElement(array) {
-  if (array.length === 0) {
-    return void 0;
-  }
-  const index = Math.floor(Math.random() * array.length);
-  return array[index];
+	if (array.length === 0) return;
+	return array[Math.floor(Math.random() * array.length)];
 }
 
-// src/guards.ts
+//#endregion
+//#region src/guards.ts
 function isNullOrUndefined(val) {
-  return val === void 0 || val === null;
+	return val === void 0 || val === null;
 }
 function isUndefined(val) {
-  return typeof val === "undefined";
+	return typeof val === "undefined";
 }
 function isNumber(val) {
-  return typeof val === "number";
+	return typeof val === "number";
 }
 function isBoolean(val) {
-  return typeof val === "boolean";
+	return typeof val === "boolean";
 }
 function isString(val) {
-  return typeof val === "string";
+	return typeof val === "string";
 }
+/**
+* Type guard to check if a value is a string that ends with '%'.
+* @param val The value to check.
+* @returns `true` if the value is a percentage string.
+*/
 function isPercentageString(val) {
-  return typeof val === "string" && val.endsWith("%");
+	return typeof val === "string" && val.endsWith("%");
 }
 
-// src/assertion.ts
+//#endregion
+//#region src/assertion.ts
+/**
+* Throws an error if the condition is true.
+* @param conditionForThrow - If true, an error will be thrown.
+* @param exceptionMessage - The message for the error.
+* @throws {Error} if the value is true
+*/
 function throwIf(conditionForThrow, exceptionMessage) {
-  if (conditionForThrow) {
-    throw new Error(exceptionMessage);
-  }
+	if (conditionForThrow) throw new Error(exceptionMessage);
 }
+/**
+* Throws an error if the value is null, undefined, or an empty array.
+*
+* @template T The type of the value being checked.
+* @param value The value to check.
+* @param exceptionMessage The message for the error.
+* @throws {Error} if the value is null, undefined, or an empty array.
+*
+* @example
+* // Example with a potentially undefined variable
+* const user: { name: string } | undefined = findUser();
+* throwIfEmpty(user, 'User not found');
+* // From here, TypeScript knows `user` is not undefined.
+* console.log(user.name);
+*
+* @example
+* // Example with an array
+* const items: string[] = getItems();
+* throwIfEmpty(items, 'Items array cannot be empty');
+* // From here, you can safely access items[0] without checking for an empty array again.
+* console.log('First item:', items[0]);
+*/
 function throwIfEmpty(value, exceptionMessage) {
-  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
-  if (isNullOrUndefined(value) || isArrayAndEmpty) {
-    throw new Error(exceptionMessage);
-  }
+	const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
+	if (isNullOrUndefined(value) || isArrayAndEmpty) throw new Error(exceptionMessage);
 }
 
-// src/config.ts
-var defaultConfig = {
-  pathSeparator: "/"
-};
-var axiSettings = { ...defaultConfig };
+//#endregion
+//#region src/config.ts
+const defaultConfig = { pathSeparator: "/" };
+const axiSettings = { ...defaultConfig };
+/**
+* set up global configuration for axi-engine.
+* @param newConfig - configuration object
+*/
 function configure(newConfig) {
-  Object.assign(axiSettings, newConfig);
+	Object.assign(axiSettings, newConfig);
 }
 
-// src/constructor-registry.ts
+//#endregion
+//#region src/constructor-registry.ts
+/**
+* A generic registry for mapping string identifiers to class constructors.
+*
+* This utility is fundamental for building extensible systems like dependency injection containers,
+* factories, and serialization engines where types need to be dynamically resolved.
+*
+* @template T - A base type that all registered constructors must produce an instance of.
+*/
 var ConstructorRegistry = class {
-  items = /* @__PURE__ */ new Map();
-  /**
-   * Registers a constructor with a unique string identifier.
-   *
-   * @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
-   * @param ctor - The class constructor to register.
-   * @returns The registry instance for chainable calls.
-   * @throws If a constructor with the same `typeId` is already registered.
-   */
-  register(typeId, ctor) {
-    throwIf(this.items.has(typeId), `A constructor with typeId '${typeId}' is already registered.`);
-    this.items.set(typeId, ctor);
-    return this;
-  }
-  /**
-   * Retrieves a constructor by its identifier.
-   *
-   * @param typeId - The identifier of the constructor to retrieve.
-   * @returns The found class constructor.
-   * @throws If no constructor is found for the given `typeId`.
-   */
-  get(typeId) {
-    const Ctor = this.items.get(typeId);
-    throwIfEmpty(Ctor, `No constructor found for typeId '${typeId}'`);
-    return Ctor;
-  }
-  /**
-   * Checks if a constructor for a given identifier is registered.
-   * @param typeId - The identifier to check.
-   * @returns `true` if a constructor is registered, otherwise `false`.
-   */
-  has(typeId) {
-    return this.items.has(typeId);
-  }
-  /**
-   * Clears all registered constructors from the registry.
-   */
-  clear() {
-    this.items.clear();
-  }
+	items = /* @__PURE__ */ new Map();
+	/**
+	* Registers a constructor with a unique string identifier.
+	*
+	* @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
+	* @param ctor - The class constructor to register.
+	* @returns The registry instance for chainable calls.
+	* @throws If a constructor with the same `typeId` is already registered.
+	*/
+	register(typeId, ctor) {
+		throwIf(this.items.has(typeId), `A constructor with typeId '${typeId}' is already registered.`);
+		this.items.set(typeId, ctor);
+		return this;
+	}
+	/**
+	* Retrieves a constructor by its identifier.
+	*
+	* @param typeId - The identifier of the constructor to retrieve.
+	* @returns The found class constructor.
+	* @throws If no constructor is found for the given `typeId`.
+	*/
+	get(typeId) {
+		const Ctor = this.items.get(typeId);
+		throwIfEmpty(Ctor, `No constructor found for typeId '${typeId}'`);
+		return Ctor;
+	}
+	/**
+	* Checks if a constructor for a given identifier is registered.
+	* @param typeId - The identifier to check.
+	* @returns `true` if a constructor is registered, otherwise `false`.
+	*/
+	has(typeId) {
+		return this.items.has(typeId);
+	}
+	/**
+	* Clears all registered constructors from the registry.
+	*/
+	clear() {
+		this.items.clear();
+	}
 };
 
-// src/emitter.ts
+//#endregion
+//#region src/emitter.ts
+/**
+* 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.
+*/
 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();
-  }
+	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
+//#endregion
+//#region src/math.ts
+/**
+* Clamps a number between an optional minimum and maximum value.
+* @param val The number to clamp.
+* @param min The minimum value. If null or undefined, it's ignored.
+* @param max The maximum value. If null or undefined, it's ignored.
+* @returns The clamped number.
+*/
 function clampNumber(val, min, max) {
-  if (!isNullOrUndefined(min)) val = Math.max(val, min);
-  if (!isNullOrUndefined(max)) val = Math.min(val, max);
-  return val;
+	if (!isNullOrUndefined(min)) val = Math.max(val, min);
+	if (!isNullOrUndefined(max)) val = Math.min(val, max);
+	return val;
 }
+/**
+* Calculates a percentage of a given value.
+* @param val The base value.
+* @param percents The percentage to get.
+* @returns The calculated percentage of the value.
+* @example getPercentOf(200, 10); // returns 20
+*/
 function getPercentOf(val, percents) {
-  return percents / 100 * val;
+	return percents / 100 * val;
 }
 
-// src/misc.ts
+//#endregion
+//#region src/misc.ts
+/**
+* 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.
+*/
 function firstKeyOf(obj) {
-  return Object.keys(obj)[0];
+	return Object.keys(obj)[0];
 }
 
-// src/path.ts
+//#endregion
+//#region src/path.ts
+/**
+* Ensures that the given path is returned as an array of segments.
+*/
 function ensurePathArray(path, separator = axiSettings.pathSeparator) {
-  return Array.isArray(path) ? [...path] : path.split(separator);
+	return Array.isArray(path) ? [...path] : path.split(separator);
 }
+/**
+* Ensures that the given path is returned as a single string.
+*/
 function ensurePathString(path, separator = axiSettings.pathSeparator) {
-  return !Array.isArray(path) ? path : path.join(separator);
+	return !Array.isArray(path) ? path : path.join(separator);
 }
 
-// src/random.ts
-import { v4 as uuidv4 } from "uuid";
+//#endregion
+//#region src/random.ts
+/**
+* Returns a random integer between min (inclusive) and max (exclusive).
+* @param min The minimum integer (inclusive).
+* @param max The maximum integer (exclusive).
+* @returns A random integer.
+* @example randInt(1, 5); // returns 1, 2, 3, or 4
+*/
 function randInt(min, max) {
-  min = Math.ceil(min);
-  max = Math.floor(max);
-  return Math.floor(Math.random() * (max - min) + min);
+	min = Math.ceil(min);
+	max = Math.floor(max);
+	return Math.floor(Math.random() * (max - min) + min);
 }
+/**
+* Generates a unique identifier using uuidv4.
+* @returns A unique string ID.
+*/
 function randId() {
-  return uuidv4();
-}
-export {
-  ConstructorRegistry,
-  Emitter,
-  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
-};
+	return v4();
+}
+
+//#endregion
+export { ConstructorRegistry, Emitter, 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 };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["uuidv4"],"sources":["../src/arrays.ts","../src/guards.ts","../src/assertion.ts","../src/config.ts","../src/constructor-registry.ts","../src/emitter.ts","../src/math.ts","../src/misc.ts","../src/path.ts","../src/random.ts"],"sourcesContent":["/**\r\n * Generates an array of numbers from 0 to length-1.\r\n * @param length The desired length of the array.\r\n * @returns An array of sequential numbers.\r\n * @example genArray(3); // returns [0, 1, 2]\r\n */\r\nexport function genArray(length: number) {\r\n  return Array.from({length}, (_v, i) => i);\r\n}\r\n\r\n/**\r\n * Creates a new array with its elements shuffled in a random order.\r\n * This function does not mutate the original array.\r\n * @template T The type of elements in the array.\r\n * @param array The array to shuffle.\r\n * @returns A new, shuffled array.\r\n */\r\nexport function shuffleArray<T>(array: T[]): T[] {\r\n  const result = [...array];\r\n  for (let i = result.length - 1; i > 0; i--) {\r\n    const j = Math.floor(Math.random() * (i + 1));\r\n    [result[i], result[j]] = [result[j], result[i]];\r\n  }\r\n  return result;\r\n}\r\n\r\n/**\r\n * Checks if the first array is a sequential starting subset of the second array.\r\n * @param arr1 The potential subset array.\r\n * @param arr2 The array to check against.\r\n * @returns `true` if arr1 is a sequential start of arr2, otherwise `false`.\r\n * @example\r\n * isSequentialStart([1, 2], [1, 2, 3]); // true\r\n * isSequentialStart([1, 3], [1, 2, 3]); // false\r\n */\r\nexport function isSequentialStart<T>(arr1: T[], arr2: T[]): boolean {\r\n  if (arr1.length > arr2.length) {\r\n    return false;\r\n  }\r\n  return arr1.every((element, index) => element === arr2[index]);\r\n}\r\n\r\n/**\r\n * Checks if two arrays contain the same elements, ignoring order.\r\n * Works for arrays of primitives like strings or numbers.\r\n * @template T The type of elements in the array.\r\n * @param arr1 The first array.\r\n * @param arr2 The second array.\r\n * @returns `true` if both arrays contain the same elements, otherwise `false`.\r\n * @example\r\n * haveSameElements(['a', 'b'], ['b', 'a']); // true\r\n * haveSameElements([1, 2, 3], [3, 1, 2]); // true\r\n * haveSameElements(['a', 'b'], ['a', 'c']); // false\r\n */\r\nexport function haveSameElements<T>(arr1?: T[], arr2?: T[]): boolean {\r\n  if (!arr1 && !arr2) return true;\r\n  if (!arr1 || !arr2) return false;\r\n  if (arr1.length !== arr2.length) return false;\r\n\r\n  // Create sorted copies to compare\r\n  const sortedArr1 = [...arr1].sort();\r\n  const sortedArr2 = [...arr2].sort();\r\n\r\n  return sortedArr1.every((value, index) => value === sortedArr2[index]);\r\n}\r\n\r\n/**\r\n * Checks if two arrays are strictly equal (same elements in the same order).\r\n * @template T The type of elements in the array.\r\n * @param arr1 The first array.\r\n * @param arr2 The second array.\r\n * @returns `true` if the arrays are strictly equal, otherwise `false`.\r\n * @example\r\n * areArraysEqual(['a', 'b'], ['a', 'b']); // true\r\n * areArraysEqual(['a', 'b'], ['b', 'a']); // false\r\n * areArraysEqual([1, 2], [1, 2, 3]);    // false\r\n */\r\nexport function areArraysEqual<T>(arr1?: T[], arr2?: T[]): boolean {\r\n  if (!arr1 && !arr2) return true;\r\n  if (!arr1 || !arr2) return false;\r\n  if (arr1.length !== arr2.length) return false;\r\n\r\n  return arr1.every((value, index) => value === arr2[index]);\r\n}\r\n\r\n/**\r\n * Gets the last element of an array.\r\n * @template T The type of elements in the array.\r\n * @param array The array to query.\r\n * @returns The last element of the array, or `undefined` if the array is empty.\r\n */\r\nexport function last<T>(array: T[]): T | undefined {\r\n  return array[array.length - 1];\r\n}\r\n\r\n/**\r\n * Creates a duplicate-free version of an array.\r\n * @template T The type of elements in the array.\r\n * @param array The array to process.\r\n * @returns A new array with only unique elements.\r\n */\r\nexport function unique<T>(array: T[]): T[] {\r\n  return [...new Set(array)];\r\n}\r\n\r\n/**\r\n * Gets a random element from an array.\r\n * @template T The type of elements in the array.\r\n * @param array The array to choose from.\r\n * @returns A random element from the array, or `undefined` if the array is empty.\r\n */\r\nexport function getRandomElement<T>(array: T[]): T | undefined {\r\n  if (array.length === 0) {\r\n    return undefined;\r\n  }\r\n  const index = Math.floor(Math.random() * array.length);\r\n  return array[index];\r\n}\r\n","export function isNullOrUndefined(val: unknown): val is null | undefined {\r\n  return val === undefined || val === null;\r\n}\r\n\r\nexport function isUndefined(val: unknown): val is undefined {\r\n  return typeof val === 'undefined';\r\n}\r\n\r\nexport function isNumber(val: unknown): val is number {\r\n  return typeof val === \"number\";\r\n}\r\n\r\nexport function isBoolean(val: unknown): val is boolean {\r\n  return typeof val === \"boolean\";\r\n}\r\n\r\nexport function isString(val: unknown): val is string {\r\n  return typeof val === \"string\";\r\n}\r\n\r\n/**\r\n * Type guard to check if a value is a string that ends with '%'.\r\n * @param val The value to check.\r\n * @returns `true` if the value is a percentage string.\r\n */\r\nexport function isPercentageString(val: unknown): val is string {\r\n  return typeof val === \"string\" && val.endsWith(\"%\");\r\n}\r\n","import {isNullOrUndefined} from './guards';\r\n\r\n/**\r\n * Throws an error if the condition is true.\r\n * @param conditionForThrow - If true, an error will be thrown.\r\n * @param exceptionMessage - The message for the error.\r\n * @throws {Error} if the value is true\r\n */\r\nexport function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never {\r\n  if (conditionForThrow) {\r\n    throw new Error(exceptionMessage);\r\n  }\r\n}\r\n\r\n/**\r\n * Throws an error if the value is null, undefined, or an empty array.\r\n *\r\n * @template T The type of the value being checked.\r\n * @param value The value to check.\r\n * @param exceptionMessage The message for the error.\r\n * @throws {Error} if the value is null, undefined, or an empty array.\r\n *\r\n * @example\r\n * // Example with a potentially undefined variable\r\n * const user: { name: string } | undefined = findUser();\r\n * throwIfEmpty(user, 'User not found');\r\n * // From here, TypeScript knows `user` is not undefined.\r\n * console.log(user.name);\r\n *\r\n * @example\r\n * // Example with an array\r\n * const items: string[] = getItems();\r\n * throwIfEmpty(items, 'Items array cannot be empty');\r\n * // From here, you can safely access items[0] without checking for an empty array again.\r\n * console.log('First item:', items[0]);\r\n */\r\nexport function throwIfEmpty<T>(\r\n  value: T,\r\n  exceptionMessage: string\r\n): asserts value is NonNullable<T> {\r\n  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;\r\n\r\n  if (isNullOrUndefined(value) || isArrayAndEmpty) {\r\n    throw new Error(exceptionMessage);\r\n  }\r\n}\r\n","export interface AxiEngineConfig {\r\n  pathSeparator: string;\r\n\r\n  /** logging and debugging logic in future */\r\n  // logLevel: 'debug' | 'info' | 'warn' | 'error';\r\n  // defaultLocale: string;\r\n}\r\n\r\nconst defaultConfig: AxiEngineConfig = {\r\n  pathSeparator: '/'\r\n};\r\n\r\nexport const axiSettings: AxiEngineConfig = { ...defaultConfig };\r\n\r\n/**\r\n * set up global configuration for axi-engine.\r\n * @param newConfig - configuration object\r\n */\r\nexport function configure(newConfig: Partial<AxiEngineConfig>): void {\r\n  Object.assign(axiSettings, newConfig);\r\n}\r\n","import {Constructor, throwIf, throwIfEmpty} from '@axi-engine/utils';\r\n\r\n/**\r\n * A generic registry for mapping string identifiers to class constructors.\r\n *\r\n * This utility is fundamental for building extensible systems like dependency injection containers,\r\n * factories, and serialization engines where types need to be dynamically resolved.\r\n *\r\n * @template T - A base type that all registered constructors must produce an instance of.\r\n */\r\nexport class ConstructorRegistry<T> {\r\n  private readonly items = new Map<string, Constructor<T>>();\r\n\r\n  /**\r\n   * Registers a constructor with a unique string identifier.\r\n   *\r\n   * @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).\r\n   * @param ctor - The class constructor to register.\r\n   * @returns The registry instance for chainable calls.\r\n   * @throws If a constructor with the same `typeId` is already registered.\r\n   */\r\n  register(typeId: string, ctor: Constructor<T>): this {\r\n    throwIf(this.items.has(typeId), `A constructor with typeId '${typeId}' is already registered.`);\r\n    this.items.set(typeId, ctor);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Retrieves a constructor by its identifier.\r\n   *\r\n   * @param typeId - The identifier of the constructor to retrieve.\r\n   * @returns The found class constructor.\r\n   * @throws If no constructor is found for the given `typeId`.\r\n   */\r\n  get(typeId: string): Constructor<T> {\r\n    const Ctor = this.items.get(typeId);\r\n    throwIfEmpty(Ctor, `No constructor found for typeId '${typeId}'`);\r\n    return Ctor!;\r\n  }\r\n\r\n  /**\r\n   * Checks if a constructor for a given identifier is registered.\r\n   * @param typeId - The identifier to check.\r\n   * @returns `true` if a constructor is registered, otherwise `false`.\r\n   */\r\n  has(typeId: string): boolean {\r\n    return this.items.has(typeId);\r\n  }\r\n\r\n  /**\r\n   * Clears all registered constructors from the registry.\r\n   */\r\n  clear(): void {\r\n    this.items.clear();\r\n  }\r\n}\r\n","// file: packages/utils/src/emitter.ts\r\n\r\nimport {Subscribable} from './types';\r\n\r\n/**\r\n * A minimal, type-safe event emitter for a single event.\r\n * It does not manage state, it only manages subscribers and event dispatching.\r\n * @template T A tuple representing the types of the event arguments.\r\n */\r\nexport class Emitter<T extends any[]> implements Subscribable<T>{\r\n  private listeners: Set<(...args: T) => void> = new Set();\r\n\r\n  /**\r\n   * Returns the number of listeners.\r\n   */\r\n  get listenerCount(): number {\r\n    return this.listeners.size;\r\n  }\r\n\r\n  /**\r\n   * Subscribes a listener to this event.\r\n   * @returns A function to unsubscribe the listener.\r\n   */\r\n  subscribe(listener: (...args: T) => void): () => void {\r\n    this.listeners.add(listener);\r\n    return () => this.listeners.delete(listener);\r\n  }\r\n\r\n  /**\r\n   * Manually unsubscribe by listener\r\n   * @returns returns true if an listener has been removed, or false if the listener does not exist.\r\n   */\r\n  unsubscribe(listener: (...args: T) => void) {\r\n    return this.listeners.delete(listener);\r\n  }\r\n\r\n  /**\r\n   * Dispatches the event to all subscribed listeners.\r\n   */\r\n  emit(...args: T): void {\r\n    this.listeners.forEach(listener => listener(...args));\r\n  }\r\n\r\n  /**\r\n   * Clears all listeners.\r\n   */\r\n  clear(): void {\r\n    this.listeners.clear();\r\n  }\r\n}\r\n","import {isNullOrUndefined} from './guards';\r\n\r\n\r\n/**\r\n * Clamps a number between an optional minimum and maximum value.\r\n * @param val The number to clamp.\r\n * @param min The minimum value. If null or undefined, it's ignored.\r\n * @param max The maximum value. If null or undefined, it's ignored.\r\n * @returns The clamped number.\r\n */\r\nexport function clampNumber(val: number, min?: number | null, max?: number | null): number {\r\n  if (!isNullOrUndefined(min)) val = Math.max(val, min);\r\n  if (!isNullOrUndefined(max)) val = Math.min(val, max);\r\n  return val;\r\n}\r\n\r\n/**\r\n * Calculates a percentage of a given value.\r\n * @param val The base value.\r\n * @param percents The percentage to get.\r\n * @returns The calculated percentage of the value.\r\n * @example getPercentOf(200, 10); // returns 20\r\n */\r\nexport function getPercentOf(val: number, percents: number) {\r\n  return (percents / 100) * val;\r\n}\r\n","/**\r\n * Returns the first key of an object.\r\n * @param obj The object from which to get the key.\r\n * @returns The first key of the object as a string.\r\n */\r\nexport function firstKeyOf(obj: any) {\r\n  return Object.keys(obj)[0];\r\n}\r\n","import {PathType} from \"./types\";\r\nimport {axiSettings} from './config';\r\n\r\n/**\r\n * Ensures that the given path is returned as an array of segments.\r\n */\r\nexport function ensurePathArray(path: PathType, separator = axiSettings.pathSeparator): string[] {\r\n  return Array.isArray(path) ? [...path] : path.split(separator);\r\n}\r\n\r\n/**\r\n * Ensures that the given path is returned as a single string.\r\n */\r\nexport function ensurePathString(path: PathType, separator = axiSettings.pathSeparator): string {\r\n  return !Array.isArray(path) ? path : path.join(separator);\r\n}\r\n","import { v4 as uuidv4 } from 'uuid';\r\n\r\n/**\r\n * Returns a random integer between min (inclusive) and max (exclusive).\r\n * @param min The minimum integer (inclusive).\r\n * @param max The maximum integer (exclusive).\r\n * @returns A random integer.\r\n * @example randInt(1, 5); // returns 1, 2, 3, or 4\r\n */\r\nexport function randInt(min: number, max: number): number {\r\n  min = Math.ceil(min);\r\n  max = Math.floor(max);\r\n  return Math.floor(Math.random() * (max - min) + min);\r\n}\r\n\r\n/**\r\n * Generates a unique identifier using uuidv4.\r\n * @returns A unique string ID.\r\n */\r\nexport function randId() {\r\n  return uuidv4();\r\n}\r\n"],"mappings":"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"}

package/package.json

@@ -1,33 +1,38 @@
-{
-  "name": "@axi-engine/utils",
-  "version": "0.1.7",
-  "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
-  "license": "MIT",
-  "keywords": [
-    "axi-engine",
-    "typescript",
-    "gamedev",
-    "utils"
-  ],
-  "types": "./dist/index.d.ts",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
-    "test": "echo 'No tests yet for @axi-engine/utils'"
-  },
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "uuid": "^13.0.0"
-  }
-}
+{
+  "name": "@axi-engine/utils",
+  "version": "0.1.8",
+  "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axijs/engine.git",
+    "directory": "packages/utils"
+  },
+  "keywords": [
+    "axi-engine",
+    "typescript",
+    "gamedev",
+    "utils"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
+    "test": "echo 'No tests yet for @axi-engine/utils'"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "uuid": "^13.0.0"
+  }
+}