@axi-engine/utils 0.2.5 → 0.2.7

package/dist/index.d.mts

@@ -171,45 +171,6 @@ declare const axiSettings: AxiEngineConfig;
  */
 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.
  */
@@ -309,12 +270,64 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
  * @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;
+/**
+* Type guard that checks if a value is `null`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is `null`, otherwise `false`.
+*/
+declare function isNull(val: unknown): val is null;
+/**
+* Type guard that checks if a value is `undefined`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is `undefined`, otherwise `false`.
+*/
 declare function isUndefined(val: unknown): val is undefined;
+/**
+ * Type guard that checks if a value is either `null` or `undefined`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is `null` or `undefined`, otherwise `false`.
+ */
+declare function isNullOrUndefined(val: unknown): val is null | undefined;
+/**
+* Type guard that checks if a value is a `number`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is a `number`, otherwise `false`.
+*/
 declare function isNumber(val: unknown): val is number;
+/**
+ * Type guard that checks if a value is a `boolean`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `boolean`, otherwise `false`.
+ */
 declare function isBoolean(val: unknown): val is boolean;
+/**
+ * Type guard that checks if a value is a `string`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `string`, otherwise `false`.
+ */
 declare function isString(val: unknown): val is string;
-declare function isNull(val: unknown): val is null;
+/**
+ * Check if a value is a plain object.
+ * Correctly handles `null` and arrays, returning `false` for them.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value is a non-null, non-array object.
+ */
+declare function isObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * Type guard that checks if a value is a function.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value is a function.
+ */
+declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/**
+ * Type guard that checks if a value is a Promise-like object.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value has a `then` function.
+ */
+declare function isPromise(value: unknown): value is Promise<unknown>;
 /**
  * Type guard to check if a value is a string that ends with '%'.
  * @param val The value to check.
@@ -369,4 +382,46 @@ declare function randInt(min: number, max: number): number;
  */
 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, throwError, throwIf, throwIfEmpty, unique };
+/**
+ * A generic, type-safe wrapper around a Map for managing collections of items by key.
+ * This class provides a consistent API for registering, retrieving, and checking for
+ * the existence of items.
+ *
+ * @template K - The type of the key (must be a string).
+ * @template V - The type of the value being stored.
+ */
+declare class Registry<K extends PropertyKey, V> {
+    protected readonly items: Map<K, V>;
+    /**
+     * Registers an item with a specific key.
+     * Warns if an item with the same key is already registered.
+     * @param key The key to associate with the item.
+     * @param value The item to register.
+     */
+    register(key: K, value: V): void;
+    /**
+     * Checks if an item with the given key is registered.
+     * @param key The key to check.
+     */
+    has(key: K): boolean;
+    /**
+     * Retrieves an item by its key.
+     * @param key The key of the item to retrieve.
+     * @returns The item, or `undefined` if not found.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Retrieves an item by its key, throwing an error if it's not found.
+     * @param key The key of the item to retrieve.
+     * @returns The item.
+     * @throws {Error} if no item is found for the given key.
+     */
+    getOrThrow(key: K): V;
+    delete(key: K): boolean;
+    /**
+     * Clears all registered items from the registry.
+     */
+    clear(): void;
+}
+
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -171,45 +171,6 @@ declare const axiSettings: AxiEngineConfig;
  */
 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.
  */
@@ -309,12 +270,64 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
  * @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;
+/**
+* Type guard that checks if a value is `null`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is `null`, otherwise `false`.
+*/
+declare function isNull(val: unknown): val is null;
+/**
+* Type guard that checks if a value is `undefined`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is `undefined`, otherwise `false`.
+*/
 declare function isUndefined(val: unknown): val is undefined;
+/**
+ * Type guard that checks if a value is either `null` or `undefined`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is `null` or `undefined`, otherwise `false`.
+ */
+declare function isNullOrUndefined(val: unknown): val is null | undefined;
+/**
+* Type guard that checks if a value is a `number`.
+* @param val The value to check.
+* @returns {boolean} `true` if the value is a `number`, otherwise `false`.
+*/
 declare function isNumber(val: unknown): val is number;
+/**
+ * Type guard that checks if a value is a `boolean`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `boolean`, otherwise `false`.
+ */
 declare function isBoolean(val: unknown): val is boolean;
+/**
+ * Type guard that checks if a value is a `string`.
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `string`, otherwise `false`.
+ */
 declare function isString(val: unknown): val is string;
-declare function isNull(val: unknown): val is null;
+/**
+ * Check if a value is a plain object.
+ * Correctly handles `null` and arrays, returning `false` for them.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value is a non-null, non-array object.
+ */
+declare function isObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * Type guard that checks if a value is a function.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value is a function.
+ */
+declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/**
+ * Type guard that checks if a value is a Promise-like object.
+ *
+ * @param value The value to check.
+ * @returns {boolean} `true` if the value has a `then` function.
+ */
+declare function isPromise(value: unknown): value is Promise<unknown>;
 /**
  * Type guard to check if a value is a string that ends with '%'.
  * @param val The value to check.
@@ -369,4 +382,46 @@ declare function randInt(min: number, max: number): number;
  */
 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, throwError, throwIf, throwIfEmpty, unique };
+/**
+ * A generic, type-safe wrapper around a Map for managing collections of items by key.
+ * This class provides a consistent API for registering, retrieving, and checking for
+ * the existence of items.
+ *
+ * @template K - The type of the key (must be a string).
+ * @template V - The type of the value being stored.
+ */
+declare class Registry<K extends PropertyKey, V> {
+    protected readonly items: Map<K, V>;
+    /**
+     * Registers an item with a specific key.
+     * Warns if an item with the same key is already registered.
+     * @param key The key to associate with the item.
+     * @param value The item to register.
+     */
+    register(key: K, value: V): void;
+    /**
+     * Checks if an item with the given key is registered.
+     * @param key The key to check.
+     */
+    has(key: K): boolean;
+    /**
+     * Retrieves an item by its key.
+     * @param key The key of the item to retrieve.
+     * @returns The item, or `undefined` if not found.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Retrieves an item by its key, throwing an error if it's not found.
+     * @param key The key of the item to retrieve.
+     * @returns The item.
+     * @throws {Error} if no item is found for the given key.
+     */
+    getOrThrow(key: K): V;
+    delete(key: K): boolean;
+    /**
+     * Clears all registered items from the registry.
+     */
+    clear(): void;
+}
+
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isFunction, isNull, isNullOrUndefined, isNumber, isObject, isPercentageString, isPromise, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.js

@@ -20,8 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  ConstructorRegistry: () => ConstructorRegistry,
   Emitter: () => Emitter,
+  Registry: () => Registry,
   areArraysEqual: () => areArraysEqual,
   axiSettings: () => axiSettings,
   clampNumber: () => clampNumber,
@@ -34,10 +34,13 @@ __export(index_exports, {
   getRandomElement: () => getRandomElement,
   haveSameElements: () => haveSameElements,
   isBoolean: () => isBoolean,
+  isFunction: () => isFunction,
   isNull: () => isNull,
   isNullOrUndefined: () => isNullOrUndefined,
   isNumber: () => isNumber,
+  isObject: () => isObject,
   isPercentageString: () => isPercentageString,
+  isPromise: () => isPromise,
   isScalar: () => isScalar,
   isSequentialStart: () => isSequentialStart,
   isString: () => isString,
@@ -104,11 +107,14 @@ function isScalar(value) {
   const type = typeof value;
   return type === "string" || type === "number" || type === "boolean";
 }
-function isNullOrUndefined(val) {
-  return val === void 0 || val === null;
+function isNull(val) {
+  return val === null;
 }
 function isUndefined(val) {
-  return typeof val === "undefined";
+  return val === void 0;
+}
+function isNullOrUndefined(val) {
+  return val === null || val === void 0;
 }
 function isNumber(val) {
   return typeof val === "number";
@@ -119,8 +125,14 @@ function isBoolean(val) {
 function isString(val) {
   return typeof val === "string";
 }
-function isNull(val) {
-  return val === null;
+function isObject(value) {
+  return value !== null && !Array.isArray(value) && typeof value === "object";
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isPromise(value) {
+  return value != null && typeof value.then === "function";
 }
 function isPercentageString(val) {
   return typeof val === "string" && val.endsWith("%");
@@ -151,50 +163,6 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
-// src/constructor-registry.ts
-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();
-  }
-};
-
 // src/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -266,10 +234,60 @@ function randInt(min, max) {
 function randId() {
   return (0, import_uuid.v4)();
 }
+
+// src/registry.ts
+var Registry = class {
+  items = /* @__PURE__ */ new Map();
+  /**
+   * Registers an item with a specific key.
+   * Warns if an item with the same key is already registered.
+   * @param key The key to associate with the item.
+   * @param value The item to register.
+   */
+  register(key, value) {
+    throwIf(this.items.has(key), `An item with the key '${String(key)}' is already registered and will be overwritten.`);
+    this.items.set(key, value);
+  }
+  /**
+   * Checks if an item with the given key is registered.
+   * @param key The key to check.
+   */
+  has(key) {
+    return this.items.has(key);
+  }
+  /**
+   * Retrieves an item by its key.
+   * @param key The key of the item to retrieve.
+   * @returns The item, or `undefined` if not found.
+   */
+  get(key) {
+    return this.items.get(key);
+  }
+  /**
+   * Retrieves an item by its key, throwing an error if it's not found.
+   * @param key The key of the item to retrieve.
+   * @returns The item.
+   * @throws {Error} if no item is found for the given key.
+   */
+  getOrThrow(key) {
+    const item = this.get(key);
+    throwIfEmpty(item, `No item registered for the key '${String(key)}'.`);
+    return item;
+  }
+  delete(key) {
+    return this.items.delete(key);
+  }
+  /**
+   * Clears all registered items from the registry.
+   */
+  clear() {
+    this.items.clear();
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ConstructorRegistry,
   Emitter,
+  Registry,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -282,10 +300,13 @@ function randId() {
   getRandomElement,
   haveSameElements,
   isBoolean,
+  isFunction,
   isNull,
   isNullOrUndefined,
   isNumber,
+  isObject,
   isPercentageString,
+  isPromise,
   isScalar,
   isSequentialStart,
   isString,

package/dist/index.mjs

@@ -49,11 +49,14 @@ function isScalar(value) {
   const type = typeof value;
   return type === "string" || type === "number" || type === "boolean";
 }
-function isNullOrUndefined(val) {
-  return val === void 0 || val === null;
+function isNull(val) {
+  return val === null;
 }
 function isUndefined(val) {
-  return typeof val === "undefined";
+  return val === void 0;
+}
+function isNullOrUndefined(val) {
+  return val === null || val === void 0;
 }
 function isNumber(val) {
   return typeof val === "number";
@@ -64,8 +67,14 @@ function isBoolean(val) {
 function isString(val) {
   return typeof val === "string";
 }
-function isNull(val) {
-  return val === null;
+function isObject(value) {
+  return value !== null && !Array.isArray(value) && typeof value === "object";
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isPromise(value) {
+  return value != null && typeof value.then === "function";
 }
 function isPercentageString(val) {
   return typeof val === "string" && val.endsWith("%");
@@ -96,50 +105,6 @@ function configure(newConfig) {
   Object.assign(axiSettings, newConfig);
 }
 
-// src/constructor-registry.ts
-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();
-  }
-};
-
 // src/emitter.ts
 var Emitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -211,9 +176,59 @@ function randInt(min, max) {
 function randId() {
   return uuidv4();
 }
+
+// src/registry.ts
+var Registry = class {
+  items = /* @__PURE__ */ new Map();
+  /**
+   * Registers an item with a specific key.
+   * Warns if an item with the same key is already registered.
+   * @param key The key to associate with the item.
+   * @param value The item to register.
+   */
+  register(key, value) {
+    throwIf(this.items.has(key), `An item with the key '${String(key)}' is already registered and will be overwritten.`);
+    this.items.set(key, value);
+  }
+  /**
+   * Checks if an item with the given key is registered.
+   * @param key The key to check.
+   */
+  has(key) {
+    return this.items.has(key);
+  }
+  /**
+   * Retrieves an item by its key.
+   * @param key The key of the item to retrieve.
+   * @returns The item, or `undefined` if not found.
+   */
+  get(key) {
+    return this.items.get(key);
+  }
+  /**
+   * Retrieves an item by its key, throwing an error if it's not found.
+   * @param key The key of the item to retrieve.
+   * @returns The item.
+   * @throws {Error} if no item is found for the given key.
+   */
+  getOrThrow(key) {
+    const item = this.get(key);
+    throwIfEmpty(item, `No item registered for the key '${String(key)}'.`);
+    return item;
+  }
+  delete(key) {
+    return this.items.delete(key);
+  }
+  /**
+   * Clears all registered items from the registry.
+   */
+  clear() {
+    this.items.clear();
+  }
+};
 export {
-  ConstructorRegistry,
   Emitter,
+  Registry,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -226,10 +241,13 @@ export {
   getRandomElement,
   haveSameElements,
   isBoolean,
+  isFunction,
   isNull,
   isNullOrUndefined,
   isNumber,
+  isObject,
   isPercentageString,
+  isPromise,
   isScalar,
   isSequentialStart,
   isString,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/utils",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "repository": {