@axi-engine/utils 0.1.8 → 0.1.9

package/dist/index.d.cts

@@ -1,305 +0,0 @@
-//#region src/types.d.ts
-/**
- * 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[];
-/**
- * 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
- */
-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.
- */
-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;
-};
-//#endregion
-//#region src/arrays.d.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]
- */
-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;
-//#endregion
-//#region src/assertion.d.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
- */
-declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
-/**
- * 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]);
- */
-declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
-//#endregion
-//#region src/config.d.ts
-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;
-//#endregion
-//#region src/constructor-registry.d.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.
- */
-declare class ConstructorRegistry<T> {
-  private readonly items;
-  /**
-       * 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: string, ctor: Constructor<T>): 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: string): Constructor<T>;
-  /**
-       * 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: string): boolean;
-  /**
-       * Clears all registered constructors from the registry.
-       */
-  clear(): void;
-}
-//#endregion
-//#region src/emitter.d.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.
- */
-declare class Emitter<T extends any[]> implements Subscribable<T> {
-  private listeners;
-  /**
-       * Returns the number of listeners.
-       */
-  get listenerCount(): number;
-  /**
-       * Subscribes a listener to this event.
-       * @returns A function to unsubscribe the listener.
-       */
-  subscribe(listener: (...args: T) => void): () => void;
-  /**
-       * Manually unsubscribe by listener
-       * @returns returns true if an listener has been removed, or false if the listener does not exist.
-       */
-  unsubscribe(listener: (...args: T) => void): boolean;
-  /**
-       * Dispatches the event to all subscribed listeners.
-       */
-  emit(...args: T): void;
-  /**
-       * Clears all listeners.
-       */
-  clear(): void;
-}
-//#endregion
-//#region src/guards.d.ts
-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;
-//#endregion
-//#region src/math.d.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.
- */
-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;
-//#endregion
-//#region src/misc.d.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.
- */
-declare function firstKeyOf(obj: any): string;
-//#endregion
-//#region src/path.d.ts
-/**
- * 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;
-//#endregion
-//#region src/random.d.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
- */
-declare function randInt(min: number, max: number): number;
-/**
- * Generates a unique identifier using uuidv4.
- * @returns A unique string ID.
- */
-declare function randId(): string;
-//#endregion
-export { AxiEngineConfig, Constructor, ConstructorRegistry, Emitter, PathType, Subscribable, 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.d.cts.map

package/dist/index.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/arrays.ts","../src/assertion.ts","../src/config.ts","../src/constructor-registry.ts","../src/emitter.ts","../src/guards.ts","../src/math.ts","../src/misc.ts","../src/path.ts","../src/random.ts"],"mappings":"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"}

package/dist/index.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/arrays.ts","../src/assertion.ts","../src/config.ts","../src/constructor-registry.ts","../src/emitter.ts","../src/guards.ts","../src/math.ts","../src/misc.ts","../src/path.ts","../src/random.ts"],"mappings":"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"}

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"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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"}