@axi-engine/utils 0.1.8 → 0.1.9

package/dist/random.js

@@ -0,0 +1,21 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * 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
+ */
+export function randInt(min, max) {
+    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.
+ */
+export function randId() {
+    return uuidv4();
+}
+//# sourceMappingURL=random.js.map

package/dist/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,GAAW;IAC9C,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrB,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO,MAAM,EAAE,CAAC;AAClB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Represents a path that can be provided as a single string
+ * or an array of segments.
+ * @example
+ * 'player/stats/health'
+ * ['player', 'stats', 'health']
+ */
+export 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
+ */
+export 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.
+ */
+export 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;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,EAAE,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEtD,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC;IAErD,KAAK,IAAI,IAAI,CAAC;CACf,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,38 +1,38 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@axi-engine/utils",
+  "version": "0.1.9",
+  "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": "tsup",
+    "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"
+  }
+}

package/dist/index.cjs

@@ -1,380 +0,0 @@
-let uuid = require("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);
-}
-/**
-* 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;
-}
-/**
-* 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]);
-}
-/**
-* 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]);
-}
-/**
-* 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]);
-}
-/**
-* 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];
-}
-/**
-* 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)];
-}
-/**
-* 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;
-	return array[Math.floor(Math.random() * array.length)];
-}
-
-//#endregion
-//#region src/guards.ts
-function isNullOrUndefined(val) {
-	return val === void 0 || val === null;
-}
-function isUndefined(val) {
-	return typeof val === "undefined";
-}
-function isNumber(val) {
-	return typeof val === "number";
-}
-function isBoolean(val) {
-	return typeof val === "boolean";
-}
-function isString(val) {
-	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("%");
-}
-
-//#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);
-}
-/**
-* 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);
-}
-
-//#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);
-}
-
-//#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();
-	}
-};
-
-//#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();
-	}
-};
-
-//#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;
-}
-/**
-* 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;
-}
-
-//#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];
-}
-
-//#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);
-}
-/**
-* 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);
-}
-
-//#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);
-}
-/**
-* Generates a unique identifier using uuidv4.
-* @returns A unique string ID.
-*/
-function randId() {
-	return (0, uuid.v4)();
-}
-
-//#endregion
-exports.ConstructorRegistry = ConstructorRegistry;
-exports.Emitter = Emitter;
-exports.areArraysEqual = areArraysEqual;
-exports.axiSettings = axiSettings;
-exports.clampNumber = clampNumber;
-exports.configure = configure;
-exports.ensurePathArray = ensurePathArray;
-exports.ensurePathString = ensurePathString;
-exports.firstKeyOf = firstKeyOf;
-exports.genArray = genArray;
-exports.getPercentOf = getPercentOf;
-exports.getRandomElement = getRandomElement;
-exports.haveSameElements = haveSameElements;
-exports.isBoolean = isBoolean;
-exports.isNullOrUndefined = isNullOrUndefined;
-exports.isNumber = isNumber;
-exports.isPercentageString = isPercentageString;
-exports.isSequentialStart = isSequentialStart;
-exports.isString = isString;
-exports.isUndefined = isUndefined;
-exports.last = last;
-exports.randId = randId;
-exports.randInt = randInt;
-exports.shuffleArray = shuffleArray;
-exports.throwIf = throwIf;
-exports.throwIfEmpty = throwIfEmpty;
-exports.unique = unique;