@axi-engine/utils 0.1.8 → 0.2.0

package/dist/arrays.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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]
+ */
+export 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.
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function getRandomElement<T>(array: T[]): T | undefined;
+//# sourceMappingURL=arrays.d.ts.map

package/dist/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../src/arrays.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,YAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAO/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,CAUnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,CAMjE;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAM7D"}

package/dist/arrays.js

@@ -0,0 +1,115 @@
+/**
+ * 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]
+ */
+export 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.
+ */
+export 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
+ */
+export 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
+ */
+export function haveSameElements(arr1, arr2) {
+    if (!arr1 && !arr2)
+        return true;
+    if (!arr1 || !arr2)
+        return false;
+    if (arr1.length !== arr2.length)
+        return false;
+    // Create sorted copies to compare
+    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
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function getRandomElement(array) {
+    if (array.length === 0) {
+        return undefined;
+    }
+    const index = Math.floor(Math.random() * array.length);
+    return array[index];
+}
+//# sourceMappingURL=arrays.js.map

package/dist/arrays.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.js","sourceRoot":"","sources":["../src/arrays.ts"],"names":[],"mappings":"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"}

package/dist/assertion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+export 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]);
+ */
+export declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
+//# sourceMappingURL=assertion.d.ts.map

package/dist/assertion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../src/assertion.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,iBAAiB,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAI1F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EACR,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAMjC"}

package/dist/assertion.js

@@ -0,0 +1,41 @@
+import { isNullOrUndefined } from './guards';
+/**
+ * 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
+ */
+export 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]);
+ */
+export function throwIfEmpty(value, exceptionMessage) {
+    const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
+    if (isNullOrUndefined(value) || isArrayAndEmpty) {
+        throw new Error(exceptionMessage);
+    }
+}
+//# sourceMappingURL=assertion.js.map

package/dist/assertion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion.js","sourceRoot":"","sources":["../src/assertion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,UAAU,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,iBAA0B,EAAE,gBAAwB;IAC1E,IAAI,iBAAiB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAQ,EACR,gBAAwB;IAExB,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IAEnE,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,eAAe,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface AxiEngineConfig {
+    pathSeparator: string;
+}
+export declare const axiSettings: AxiEngineConfig;
+/**
+ * set up global configuration for axi-engine.
+ * @param newConfig - configuration object
+ */
+export declare function configure(newConfig: Partial<AxiEngineConfig>): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;CAKvB;AAMD,eAAO,MAAM,WAAW,EAAE,eAAsC,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAEnE"}

package/dist/config.js

@@ -0,0 +1,12 @@
+const defaultConfig = {
+    pathSeparator: '/'
+};
+export const axiSettings = { ...defaultConfig };
+/**
+ * set up global configuration for axi-engine.
+ * @param newConfig - configuration object
+ */
+export function configure(newConfig) {
+    Object.assign(axiSettings, newConfig);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,aAAa,GAAoB;IACrC,aAAa,EAAE,GAAG;CACnB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAoB,EAAE,GAAG,aAAa,EAAE,CAAC;AAEjE;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,SAAmC;IAC3D,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACxC,CAAC"}

package/dist/constructor-registry.d.ts

@@ -0,0 +1,40 @@
+import { Constructor } from './types';
+/**
+ * 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.
+ */
+export 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;
+}
+//# sourceMappingURL=constructor-registry.d.ts.map

package/dist/constructor-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constructor-registry.d.ts","sourceRoot":"","sources":["../src/constructor-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAGpC;;;;;;;GAOG;AACH,qBAAa,mBAAmB,CAAC,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAE3D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI;IAMpD;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;IAMnC;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/constructor-registry.js

@@ -0,0 +1,52 @@
+import { throwIf, throwIfEmpty } from './assertion';
+/**
+ * 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.
+ */
+export class ConstructorRegistry {
+    items = 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();
+    }
+}
+//# sourceMappingURL=constructor-registry.js.map

package/dist/constructor-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constructor-registry.js","sourceRoot":"","sources":["../src/constructor-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,EAAE,YAAY,EAAC,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAmB;IACb,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE3D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAc,EAAE,IAAoB;QAC3C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,8BAA8B,MAAM,0BAA0B,CAAC,CAAC;QAChG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,MAAc;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,YAAY,CAAC,IAAI,EAAE,oCAAoC,MAAM,GAAG,CAAC,CAAC;QAClE,OAAO,IAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/emitter.d.ts

@@ -0,0 +1,32 @@
+import { Subscribable } from './types';
+/**
+ * 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.
+ */
+export 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;
+}
+//# sourceMappingURL=emitter.d.ts.map

package/dist/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,YAAY,EAAC,MAAM,SAAS,CAAC;AAErC;;;;GAIG;AACH,qBAAa,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,CAAC,SAAS,CAAwC;IAEzD;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI;IAI1C;;OAEG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/emitter.js

@@ -0,0 +1,43 @@
+// file: packages/utils/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.
+ */
+export class Emitter {
+    listeners = 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();
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/dist/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAItC;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACV,SAAS,GAA8B,IAAI,GAAG,EAAE,CAAC;IAEzD;;OAEG;IACH,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,QAA8B;QACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,QAA8B;QACxC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,GAAG,IAAO;QACb,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/guards.d.ts

@@ -0,0 +1,12 @@
+export declare function isNullOrUndefined(val: unknown): val is null | undefined;
+export declare function isUndefined(val: unknown): val is undefined;
+export declare function isNumber(val: unknown): val is number;
+export declare function isBoolean(val: unknown): val is boolean;
+export 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.
+ */
+export declare function isPercentageString(val: unknown): val is string;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,IAAI,GAAG,SAAS,CAEvE;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,SAAS,CAE1D;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAEpD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CAEtD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAE9D"}

package/dist/guards.js

@@ -0,0 +1,24 @@
+export function isNullOrUndefined(val) {
+    return val === undefined || val === null;
+}
+export function isUndefined(val) {
+    return typeof val === 'undefined';
+}
+export function isNumber(val) {
+    return typeof val === "number";
+}
+export function isBoolean(val) {
+    return typeof val === "boolean";
+}
+export 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.
+ */
+export function isPercentageString(val) {
+    return typeof val === "string" && val.endsWith("%");
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,OAAO,GAAG,KAAK,WAAW,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,OAAO,OAAO,GAAG,KAAK,SAAS,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC"}