@axi-engine/utils 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -1,3 +1,8 @@
+/**
+ * Simple scalar type
+ *
+ */
+type ScalarType = string | number | boolean;
 /**
  * Represents a path that can be provided as a single string
  * or an array of segments.
@@ -200,6 +205,28 @@ declare class ConstructorRegistry<T> {
     clear(): void;
 }
 
+/**
+ * A read-only contract for any system that can provide data by path.
+ */
+interface DataSource {
+    get(path: PathType): unknown;
+    has(path: PathType): boolean;
+}
+/**
+ * A write-only contract for any system that can accept data by path.
+ */
+interface DataSink {
+    set(path: PathType, value: unknown): void;
+    create(path: PathType, value: unknown): void;
+    delete(path: PathType): void;
+}
+/**
+ * A full CRUD contract for systems that provide complete data management.
+ * Combines both reading and writing capabilities.
+ */
+interface DataStorage extends DataSource, DataSink {
+}
+
 /**
  * A minimal, type-safe event emitter for a single event.
  * It does not manage state, it only manages subscribers and event dispatching.
@@ -231,11 +258,18 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
     clear(): void;
 }
 
+/**
+ * Type guard that checks if a value is a valid ScalarType.
+ * @param value The value to check.
+ * @returns True if the value is a string, number, or boolean.
+ */
+declare function isScalar(value: unknown): value is ScalarType;
 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;
+declare function isNull(val: unknown): val is null;
 /**
  * Type guard to check if a value is a string that ends with '%'.
  * @param val The value to check.
@@ -290,4 +324,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type Constructor, ConstructorRegistry, Emitter, type PathType, type 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 };
+export { type AxiEngineConfig, type Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -1,12 +1,327 @@
-export type * from './types';
-export * from './arrays';
-export * from './assertion';
-export * from './config';
-export * from './constructor-registry';
-export * from './emitter';
-export * from './guards';
-export * from './math';
-export * from './misc';
-export * from './path';
-export * from './random';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Simple scalar type
+ *
+ */
+type ScalarType = string | number | boolean;
+/**
+ * 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;
+};
+
+/**
+ * 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.
+ * @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>;
+
+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;
+
+/**
+ * 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;
+}
+
+/**
+ * A read-only contract for any system that can provide data by path.
+ */
+interface DataSource {
+    get(path: PathType): unknown;
+    has(path: PathType): boolean;
+}
+/**
+ * A write-only contract for any system that can accept data by path.
+ */
+interface DataSink {
+    set(path: PathType, value: unknown): void;
+    create(path: PathType, value: unknown): void;
+    delete(path: PathType): void;
+}
+/**
+ * A full CRUD contract for systems that provide complete data management.
+ * Combines both reading and writing capabilities.
+ */
+interface DataStorage extends DataSource, DataSink {
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Type guard that checks if a value is a valid ScalarType.
+ * @param value The value to check.
+ * @returns True if the value is a string, number, or boolean.
+ */
+declare function isScalar(value: unknown): value is ScalarType;
+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;
+declare function isNull(val: unknown): val is null;
+/**
+ * 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 Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };