@axi-engine/utils 0.2.6 → 0.2.8

package/dist/index.d.mts

@@ -263,6 +263,21 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      */
     clear(): void;
 }
+/**
+ * An Emitter that stores the last emitted value.
+ * New subscribers immediately receive the last value upon subscription.
+ */
+declare class StateEmitter<T extends any[]> extends Emitter<T> {
+    private _lastValue;
+    constructor(initialValue?: T);
+    /**
+     * Gets the current value synchronously without subscribing.
+     */
+    get value(): T | undefined;
+    emit(...args: T): void;
+    subscribe(listener: (...args: T) => void): () => void;
+    clear(): void;
+}
 
 /**
  * Type guard that checks if a value is a valid ScalarType.
@@ -270,12 +285,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.
@@ -338,7 +405,7 @@ declare function randId(): string;
  * @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 string, V> {
+declare class Registry<K extends PropertyKey, V> {
     protected readonly items: Map<K, V>;
     /**
      * Registers an item with a specific key.
@@ -372,4 +439,4 @@ declare class Registry<K extends string, V> {
     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, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, 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

@@ -263,6 +263,21 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      */
     clear(): void;
 }
+/**
+ * An Emitter that stores the last emitted value.
+ * New subscribers immediately receive the last value upon subscription.
+ */
+declare class StateEmitter<T extends any[]> extends Emitter<T> {
+    private _lastValue;
+    constructor(initialValue?: T);
+    /**
+     * Gets the current value synchronously without subscribing.
+     */
+    get value(): T | undefined;
+    emit(...args: T): void;
+    subscribe(listener: (...args: T) => void): () => void;
+    clear(): void;
+}
 
 /**
  * Type guard that checks if a value is a valid ScalarType.
@@ -270,12 +285,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.
@@ -338,7 +405,7 @@ declare function randId(): string;
  * @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 string, V> {
+declare class Registry<K extends PropertyKey, V> {
     protected readonly items: Map<K, V>;
     /**
      * Registers an item with a specific key.
@@ -372,4 +439,4 @@ declare class Registry<K extends string, V> {
     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, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, Registry, type ScalarType, StateEmitter, 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

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   Emitter: () => Emitter,
   Registry: () => Registry,
+  StateEmitter: () => StateEmitter,
   areArraysEqual: () => areArraysEqual,
   axiSettings: () => axiSettings,
   clampNumber: () => clampNumber,
@@ -34,10 +35,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 +108,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 +126,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("%");
@@ -188,6 +201,34 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+var StateEmitter = class extends Emitter {
+  _lastValue;
+  constructor(initialValue) {
+    super();
+    this._lastValue = initialValue ?? void 0;
+  }
+  /**
+   * Gets the current value synchronously without subscribing.
+   */
+  get value() {
+    return this._lastValue;
+  }
+  emit(...args) {
+    this._lastValue = args;
+    super.emit(...args);
+  }
+  subscribe(listener) {
+    const unsubscribe = super.subscribe(listener);
+    if (!isUndefined(this._lastValue)) {
+      listener(...this._lastValue);
+    }
+    return unsubscribe;
+  }
+  clear() {
+    super.clear();
+    this._lastValue = void 0;
+  }
+};
 
 // src/math.ts
 function clampNumber(val, min, max) {
@@ -233,7 +274,7 @@ var Registry = class {
    * @param value The item to register.
    */
   register(key, value) {
-    throwIf(this.items.has(key), `An item with the key '${key}' is already registered and will be overwritten.`);
+    throwIf(this.items.has(key), `An item with the key '${String(key)}' is already registered and will be overwritten.`);
     this.items.set(key, value);
   }
   /**
@@ -259,7 +300,7 @@ var Registry = class {
    */
   getOrThrow(key) {
     const item = this.get(key);
-    throwIfEmpty(item, `No item registered for the key '${key}'.`);
+    throwIfEmpty(item, `No item registered for the key '${String(key)}'.`);
     return item;
   }
   delete(key) {
@@ -276,6 +317,7 @@ var Registry = class {
 0 && (module.exports = {
   Emitter,
   Registry,
+  StateEmitter,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -288,10 +330,13 @@ var Registry = class {
   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("%");
@@ -133,6 +142,34 @@ var Emitter = class {
     this.listeners.clear();
   }
 };
+var StateEmitter = class extends Emitter {
+  _lastValue;
+  constructor(initialValue) {
+    super();
+    this._lastValue = initialValue ?? void 0;
+  }
+  /**
+   * Gets the current value synchronously without subscribing.
+   */
+  get value() {
+    return this._lastValue;
+  }
+  emit(...args) {
+    this._lastValue = args;
+    super.emit(...args);
+  }
+  subscribe(listener) {
+    const unsubscribe = super.subscribe(listener);
+    if (!isUndefined(this._lastValue)) {
+      listener(...this._lastValue);
+    }
+    return unsubscribe;
+  }
+  clear() {
+    super.clear();
+    this._lastValue = void 0;
+  }
+};
 
 // src/math.ts
 function clampNumber(val, min, max) {
@@ -178,7 +215,7 @@ var Registry = class {
    * @param value The item to register.
    */
   register(key, value) {
-    throwIf(this.items.has(key), `An item with the key '${key}' is already registered and will be overwritten.`);
+    throwIf(this.items.has(key), `An item with the key '${String(key)}' is already registered and will be overwritten.`);
     this.items.set(key, value);
   }
   /**
@@ -204,7 +241,7 @@ var Registry = class {
    */
   getOrThrow(key) {
     const item = this.get(key);
-    throwIfEmpty(item, `No item registered for the key '${key}'.`);
+    throwIfEmpty(item, `No item registered for the key '${String(key)}'.`);
     return item;
   }
   delete(key) {
@@ -220,6 +257,7 @@ var Registry = class {
 export {
   Emitter,
   Registry,
+  StateEmitter,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -232,10 +270,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.6",
+  "version": "0.2.8",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "repository": {