@axi-engine/utils 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,158 @@
+/**
+ * Represents a path that can be provided as a single string
+ * or an array of segments.
+ * @example
+ * 'player/stats/health'
+ * ['player', 'stats', 'health']
+ */
+type PathType = string | string[];
+
+/**
+ * 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]
+ */
+declare function genArray(length: number): number[];
+/**
+ * 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.
+ */
+declare function shuffleArray<T>(array: T[]): T[];
+/**
+ * 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
+ */
+declare function isSequentialStart<T>(arr1: T[], arr2: T[]): boolean;
+/**
+ * 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
+ */
+declare function haveSameElements<T>(arr1?: T[], arr2?: T[]): boolean;
+/**
+ * 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
+ */
+declare function areArraysEqual<T>(arr1?: T[], arr2?: T[]): boolean;
+/**
+ * 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.
+ */
+declare function last<T>(array: T[]): T | undefined;
+/**
+ * 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.
+ */
+declare function unique<T>(array: T[]): T[];
+/**
+ * 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.
+ */
+declare function getRandomElement<T>(array: T[]): T | undefined;
+
+/**
+ * Throws an error if the condition is true.
+ * @param conditionForThrow - If true, an error will be thrown.
+ * @param exceptionMessage - The message for the error.
+ */
+declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+
+interface AxiEngineConfig {
+    pathSeparator: string;
+}
+declare const axiSettings: AxiEngineConfig;
+/**
+ * set up global configuration for axi-engine.
+ * @param newConfig - configuration object
+ */
+declare function configure(newConfig: Partial<AxiEngineConfig>): void;
+
+declare function isNullOrUndefined(val: unknown): val is null | undefined;
+declare function isUndefined(val: unknown): val is undefined;
+declare function isNumber(val: unknown): val is number;
+declare function isBoolean(val: unknown): val is boolean;
+declare function isString(val: unknown): val is 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.
+ */
+declare function isPercentageString(val: unknown): val is string;
+
+/**
+ * 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.
+ */
+declare function clampNumber(val: number, min?: number | null, max?: number | null): number;
+/**
+ * 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
+ */
+declare function getPercentOf(val: number, percents: 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.
+ */
+declare function firstKeyOf(obj: any): string;
+
+/**
+ * Ensures that the given path is returned as an array of segments.
+ */
+declare function ensurePathArray(path: PathType, separator?: string): string[];
+/**
+ * Ensures that the given path is returned as a single string.
+ */
+declare function ensurePathString(path: PathType, separator?: string): string;
+
+/**
+ * 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
+ */
+declare function randInt(min: number, max: number): number;
+/**
+ * Generates a unique identifier using uuidv4.
+ * @returns A unique string ID.
+ */
+declare function randId(): string;
+
+export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, unique };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Represents a path that can be provided as a single string
+ * or an array of segments.
+ * @example
+ * 'player/stats/health'
+ * ['player', 'stats', 'health']
+ */
+type PathType = string | string[];
+
+/**
+ * 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]
+ */
+declare function genArray(length: number): number[];
+/**
+ * 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.
+ */
+declare function shuffleArray<T>(array: T[]): T[];
+/**
+ * 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
+ */
+declare function isSequentialStart<T>(arr1: T[], arr2: T[]): boolean;
+/**
+ * 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
+ */
+declare function haveSameElements<T>(arr1?: T[], arr2?: T[]): boolean;
+/**
+ * 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
+ */
+declare function areArraysEqual<T>(arr1?: T[], arr2?: T[]): boolean;
+/**
+ * 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.
+ */
+declare function last<T>(array: T[]): T | undefined;
+/**
+ * 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.
+ */
+declare function unique<T>(array: T[]): T[];
+/**
+ * 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.
+ */
+declare function getRandomElement<T>(array: T[]): T | undefined;
+
+/**
+ * Throws an error if the condition is true.
+ * @param conditionForThrow - If true, an error will be thrown.
+ * @param exceptionMessage - The message for the error.
+ */
+declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+
+interface AxiEngineConfig {
+    pathSeparator: string;
+}
+declare const axiSettings: AxiEngineConfig;
+/**
+ * set up global configuration for axi-engine.
+ * @param newConfig - configuration object
+ */
+declare function configure(newConfig: Partial<AxiEngineConfig>): void;
+
+declare function isNullOrUndefined(val: unknown): val is null | undefined;
+declare function isUndefined(val: unknown): val is undefined;
+declare function isNumber(val: unknown): val is number;
+declare function isBoolean(val: unknown): val is boolean;
+declare function isString(val: unknown): val is 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.
+ */
+declare function isPercentageString(val: unknown): val is string;
+
+/**
+ * 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.
+ */
+declare function clampNumber(val: number, min?: number | null, max?: number | null): number;
+/**
+ * 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
+ */
+declare function getPercentOf(val: number, percents: 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.
+ */
+declare function firstKeyOf(obj: any): string;
+
+/**
+ * Ensures that the given path is returned as an array of segments.
+ */
+declare function ensurePathArray(path: PathType, separator?: string): string[];
+/**
+ * Ensures that the given path is returned as a single string.
+ */
+declare function ensurePathString(path: PathType, separator?: string): string;
+
+/**
+ * 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
+ */
+declare function randInt(min: number, max: number): number;
+/**
+ * Generates a unique identifier using uuidv4.
+ * @returns A unique string ID.
+ */
+declare function randId(): string;
+
+export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, unique };

package/dist/index.js

@@ -0,0 +1,191 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  areArraysEqual: () => areArraysEqual,
+  axiSettings: () => axiSettings,
+  clampNumber: () => clampNumber,
+  configure: () => configure,
+  ensurePathArray: () => ensurePathArray,
+  ensurePathString: () => ensurePathString,
+  firstKeyOf: () => firstKeyOf,
+  genArray: () => genArray,
+  getPercentOf: () => getPercentOf,
+  getRandomElement: () => getRandomElement,
+  haveSameElements: () => haveSameElements,
+  isBoolean: () => isBoolean,
+  isNullOrUndefined: () => isNullOrUndefined,
+  isNumber: () => isNumber,
+  isPercentageString: () => isPercentageString,
+  isSequentialStart: () => isSequentialStart,
+  isString: () => isString,
+  isUndefined: () => isUndefined,
+  last: () => last,
+  randId: () => randId,
+  randInt: () => randInt,
+  shuffleArray: () => shuffleArray,
+  throwIf: () => throwIf,
+  unique: () => unique
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/arrays.ts
+function genArray(length) {
+  return Array.from({ length }, (_v, i) => i);
+}
+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;
+}
+function isSequentialStart(arr1, arr2) {
+  if (arr1.length > arr2.length) {
+    return false;
+  }
+  return arr1.every((element, index) => element === arr2[index]);
+}
+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]);
+}
+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]);
+}
+function last(array) {
+  return array[array.length - 1];
+}
+function unique(array) {
+  return [...new Set(array)];
+}
+function getRandomElement(array) {
+  if (array.length === 0) {
+    return void 0;
+  }
+  const index = Math.floor(Math.random() * array.length);
+  return array[index];
+}
+
+// src/assertion.ts
+function throwIf(conditionForThrow, exceptionMessage) {
+  if (conditionForThrow) {
+    throw new Error(exceptionMessage);
+  }
+}
+
+// src/config.ts
+var defaultConfig = {
+  pathSeparator: "/"
+};
+var axiSettings = { ...defaultConfig };
+function configure(newConfig) {
+  Object.assign(axiSettings, newConfig);
+}
+
+// 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";
+}
+function isPercentageString(val) {
+  return typeof val === "string" && val.endsWith("%");
+}
+
+// src/math.ts
+function clampNumber(val, min, max) {
+  if (!isNullOrUndefined(min)) val = Math.max(val, min);
+  if (!isNullOrUndefined(max)) val = Math.min(val, max);
+  return val;
+}
+function getPercentOf(val, percents) {
+  return percents / 100 * val;
+}
+
+// src/misc.ts
+function firstKeyOf(obj) {
+  return Object.keys(obj)[0];
+}
+
+// src/path.ts
+function ensurePathArray(path, separator = axiSettings.pathSeparator) {
+  return Array.isArray(path) ? [...path] : path.split(separator);
+}
+function ensurePathString(path, separator = axiSettings.pathSeparator) {
+  return !Array.isArray(path) ? path : path.join(separator);
+}
+
+// src/random.ts
+var import_uuid = require("uuid");
+function randInt(min, max) {
+  min = Math.ceil(min);
+  max = Math.floor(max);
+  return Math.floor(Math.random() * (max - min) + min);
+}
+function randId() {
+  return (0, import_uuid.v4)();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  areArraysEqual,
+  axiSettings,
+  clampNumber,
+  configure,
+  ensurePathArray,
+  ensurePathString,
+  firstKeyOf,
+  genArray,
+  getPercentOf,
+  getRandomElement,
+  haveSameElements,
+  isBoolean,
+  isNullOrUndefined,
+  isNumber,
+  isPercentageString,
+  isSequentialStart,
+  isString,
+  isUndefined,
+  last,
+  randId,
+  randInt,
+  shuffleArray,
+  throwIf,
+  unique
+});

package/dist/index.mjs

@@ -0,0 +1,141 @@
+// src/arrays.ts
+function genArray(length) {
+  return Array.from({ length }, (_v, i) => i);
+}
+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;
+}
+function isSequentialStart(arr1, arr2) {
+  if (arr1.length > arr2.length) {
+    return false;
+  }
+  return arr1.every((element, index) => element === arr2[index]);
+}
+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]);
+}
+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]);
+}
+function last(array) {
+  return array[array.length - 1];
+}
+function unique(array) {
+  return [...new Set(array)];
+}
+function getRandomElement(array) {
+  if (array.length === 0) {
+    return void 0;
+  }
+  const index = Math.floor(Math.random() * array.length);
+  return array[index];
+}
+
+// src/assertion.ts
+function throwIf(conditionForThrow, exceptionMessage) {
+  if (conditionForThrow) {
+    throw new Error(exceptionMessage);
+  }
+}
+
+// src/config.ts
+var defaultConfig = {
+  pathSeparator: "/"
+};
+var axiSettings = { ...defaultConfig };
+function configure(newConfig) {
+  Object.assign(axiSettings, newConfig);
+}
+
+// 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";
+}
+function isPercentageString(val) {
+  return typeof val === "string" && val.endsWith("%");
+}
+
+// src/math.ts
+function clampNumber(val, min, max) {
+  if (!isNullOrUndefined(min)) val = Math.max(val, min);
+  if (!isNullOrUndefined(max)) val = Math.min(val, max);
+  return val;
+}
+function getPercentOf(val, percents) {
+  return percents / 100 * val;
+}
+
+// src/misc.ts
+function firstKeyOf(obj) {
+  return Object.keys(obj)[0];
+}
+
+// src/path.ts
+function ensurePathArray(path, separator = axiSettings.pathSeparator) {
+  return Array.isArray(path) ? [...path] : path.split(separator);
+}
+function ensurePathString(path, separator = axiSettings.pathSeparator) {
+  return !Array.isArray(path) ? path : path.join(separator);
+}
+
+// src/random.ts
+import { v4 as uuidv4 } from "uuid";
+function randInt(min, max) {
+  min = Math.ceil(min);
+  max = Math.floor(max);
+  return Math.floor(Math.random() * (max - min) + min);
+}
+function randId() {
+  return uuidv4();
+}
+export {
+  areArraysEqual,
+  axiSettings,
+  clampNumber,
+  configure,
+  ensurePathArray,
+  ensurePathString,
+  firstKeyOf,
+  genArray,
+  getPercentOf,
+  getRandomElement,
+  haveSameElements,
+  isBoolean,
+  isNullOrUndefined,
+  isNumber,
+  isPercentageString,
+  isSequentialStart,
+  isString,
+  isUndefined,
+  last,
+  randId,
+  randInt,
+  shuffleArray,
+  throwIf,
+  unique
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@axi-engine/utils",
+  "version": "0.1.0",
+  "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"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "echo 'No tests yet for @axi-engine/utils'"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "uuid": "^13.0.0"
+  }
+}