tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/jsdoc/EventEmitter.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+require('events');
+

package/dist/v1/jsdoc/EventEmitter.d.mts

@@ -0,0 +1,33 @@
+import { EventEmitter } from 'events';
+export type ICustomEventEmitter<MyEvents extends Record<string | symbol, (...args: any[]) => any>> = Omit<EventEmitter, 'on' | 'off' | 'emit' | 'once' | 'addListener' | 'removeListener' | 'removeAllListeners' | 'listeners' | 'rawListeners' | 'listenerCount' | 'prependListener' | 'prependOnceListener'> & {
+    on<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    once<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    off<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    addListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    removeListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    removeAllListeners<K extends keyof MyEvents>(event?: K): ICustomEventEmitter<MyEvents>;
+    prependListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    prependOnceListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+    emit<K extends keyof MyEvents>(event: K, ...args: Parameters<MyEvents[K]>): boolean;
+    listeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+    rawListeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+    listenerCount<K extends keyof MyEvents>(event: K, listener?: MyEvents[K]): number;
+};
+/**
+ * @template {Record<string | symbol, (...args: any[]) => any>} MyEvents
+ * @typedef {Omit<EventEmitter, 'on' | 'off' | 'emit' | 'once' | 'addListener' | 'removeListener' | 'removeAllListeners' | 'listeners' | 'rawListeners' | 'listenerCount' | 'prependListener' | 'prependOnceListener'> & {
+ *   on<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   once<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   off<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   addListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   removeListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   removeAllListeners<K extends keyof MyEvents>(event?: K): ICustomEventEmitter<MyEvents>;
+ *   prependListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   prependOnceListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   emit<K extends keyof MyEvents>(event: K, ...args: Parameters<MyEvents[K]>): boolean;
+ *   listeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+ *   rawListeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+ *   listenerCount<K extends keyof MyEvents>(event: K, listener?: MyEvents[K]): number;
+ * }} ICustomEventEmitter
+ */
+//# sourceMappingURL=EventEmitter.d.mts.map

package/dist/v1/jsdoc/EventEmitter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.d.mts","sourceRoot":"","sources":["../../../src/v1/jsdoc/EventEmitter.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAInC,YAaG,mBAAmB,CAduC,QAAQ,SAA1D,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAW,IAC3D,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,WAAW,GAAG,cAAc,GAAG,eAAe,GAAG,iBAAiB,GAAG,qBAAqB,CAAC,GAAG;IACpN,EAAE,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC7F,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC/F,GAAG,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9F,WAAW,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACtG,cAAc,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACzG,kBAAkB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvF,eAAe,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC1G,mBAAmB,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9G,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACpF,SAAS,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,YAAY,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,aAAa,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;CACnF,CAAqB;AAfzB;;;;;;;;;;;;;;;;GAgBG"}

package/dist/v1/jsdoc/EventEmitter.mjs

@@ -0,0 +1,18 @@
+import { EventEmitter } from 'events';
+/**
+ * @template {Record<string | symbol, (...args: any[]) => any>} MyEvents
+ * @typedef {Omit<EventEmitter, 'on' | 'off' | 'emit' | 'once' | 'addListener' | 'removeListener' | 'removeAllListeners' | 'listeners' | 'rawListeners' | 'listenerCount' | 'prependListener' | 'prependOnceListener'> & {
+ *   on<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   once<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   off<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   addListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   removeListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   removeAllListeners<K extends keyof MyEvents>(event?: K): ICustomEventEmitter<MyEvents>;
+ *   prependListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   prependOnceListener<K extends keyof MyEvents>(event: K, listener: MyEvents[K]): ICustomEventEmitter<MyEvents>;
+ *   emit<K extends keyof MyEvents>(event: K, ...args: Parameters<MyEvents[K]>): boolean;
+ *   listeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+ *   rawListeners<K extends keyof MyEvents>(event: K): MyEvents[K][];
+ *   listenerCount<K extends keyof MyEvents>(event: K, listener?: MyEvents[K]): number;
+ * }} ICustomEventEmitter
+ */

package/dist/v1/libs/array/TinyArrayComparator.cjs

@@ -1,38 +1,93 @@
 'use strict';
 
 /**
- * @fileoverview Array comparison utility.
+ * @fileoverview Array comparison utility with deep object diffing capabilities.
  * @module TinyArrayComparator
  */
 
 /**
- * @template {any} ArrayItem
+ * @template Item
+ * @typedef {Object} HashEntry
+ * @property {Item} item - The original item stored in the map.
+ * @property {string} hash - The calculated hash representing the item's value.
+ */
+
+// STRUCTURAL TRANSFORMATION & TYPE DERIVATION:
+// Here we remove 'any' and use 'Partial<Item>' and Mapped Types.
+// VSCode/Intellisense will now know exactly which keys exist within 'added', 'deleted', and 'modified',
+// deriving the types directly from the data structure you pass to the class.
+
+/**
+ * @template Item
+ * @typedef {Object} ObjectDiff
+ * @property {Partial<Item>} added - Properties added in the new object.
+ * @property {Partial<Item>} deleted - Properties removed from the old object.
+ * @property {Partial<{ [K in keyof Item]: { oldValue: Item[K], newValue: Item[K] } }>} modified - Properties that changed value.
+ * @property {Partial<{ [K in keyof Item]: ObjectDiff<Item[K]> }>} nested - Nested differences for nested objects.
+ */
+
+// ADVANCED PATTERN MATCHING:
+// We use a discriminated union (status) so the IDE knows that 'oldItem' and 'details'
+// only make sense (or are more relevant) in contexts where the change requires it.
+
+/**
+ * @template Item
+ * @typedef {Object} DiffResult
+ * @property {Item} item - The item that was affected.
+ * @property {Item} [oldItem] - The original item before the change (only for 'edited' status).
+ * @property {'added'|'deleted'|'edited'} status - The nature of the change.
+ * @property {ObjectDiff<Item>} [details] - Detailed property changes (only if status is 'edited' and deepComparison is enabled).
+ */
+
+/**
+ * @template Item
  * @typedef {Object} InternalState
  * Holds the internal tracking variables during the comparison process.
- * @property {Map<string, ArrayItem>} oldItemsMap - A map storing the hash as the key and the original item as the value.
- * @property {AffectedItems<ArrayItem>} affectedItems - The final array that collects added or deleted items.
+ * @property {Map<string|number, HashEntry<Item>>} oldItemsMap - A map storing the identity key as the key and the hash entry as the value.
+ * @property {Array<DiffResult<Item>>} affectedItems - The final array that collects added, deleted, or edited items.
  */
 
 /**
- * The final array that collects added or deleted items.
- * @template {any} ArrayItem
- * @typedef {Array<{item: ArrayItem, status: 'added'|'deleted'}>} AffectedItems
+ * The final array that collects added, deleted, or edited items.
+ * @template Item
+ * @typedef {Array<DiffResult<Item>>} AffectedItems
  */
 
+// ZERO-REDUNDANCY RULE:
+// If 'Item' is a known object, 'idKey' will suggest the valid keys of that object (keyof Item).
+// The '(string & {})' is an advanced trick to allow the user to type other strings if the base type is dynamic,
+// without losing autocomplete for the known keys.
+
 /**
- * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ * Options to configure the comparator.
+ * @template Item
+ * @typedef {Object} ComparatorOptions
+ * @property {keyof Item | (string & {})} [idKey='id'] - The property name used as a unique identifier for objects to detect edits.
+ * @property {boolean} [deepComparison=true] - If true, provides detailed property-level diffs for edited objects.
+ */
+
+/**
+ * Compares two arrays efficiently by hashing their items to detect additions, deletions, and edits.
  * @template {any} ArrayItem
  */
 class TinyArrayComparator {
   /**
    * Generates a simple 32-bit integer hash converted to a base36 string.
-   * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+   * @param {any} item - The item to be hashed.
    * @returns {string} The unique hash representing the item's value.
+   * @throws {TypeError} Throws a TypeError if the item cannot be stringified due to circular references.
    */
   static generateHash(item) {
-    const stringified = typeof item === 'object' ? JSON.stringify(item) : String(item);
-    let hash = 0;
+    let stringified;
+    try {
+      stringified = typeof item === 'object' && item !== null ? JSON.stringify(item) : String(item);
+    } catch (error) {
+      throw new TypeError(
+        'Failed to stringify item for hashing. Ensure the object does not have circular references.',
+      );
+    }
 
+    let hash = 0;
     for (let i = 0, len = stringified.length; i < len; i++) {
       const char = stringified.charCodeAt(i);
       hash = (hash << 5) - hash + char;
@@ -48,6 +103,55 @@ class TinyArrayComparator {
    */
   #oldArray = [];
 
+  /**
+   * The key used to track identity of an object (e.g., 'id', 'uuid').
+   * @type {string|null}
+   */
+  #idKey = null;
+
+  /**
+   * Detects whether deep comparison is enabled.
+   * @type {boolean}
+   */
+  #deepComparison = true;
+
+  /**
+   * Gets the current identity key.
+   * @returns {string|null}
+   */
+  get idKey() {
+    return this.#idKey;
+  }
+
+  /**
+   * Sets the identity key used for object comparison.
+   * @param {string|null} value - The property name to use as an identifier.
+   * @throws {TypeError} Throws a TypeError if the value is not a string.
+   */
+  set idKey(value) {
+    if (value !== null && typeof value !== 'string')
+      throw new TypeError('The idKey must be a string or null.');
+    this.#idKey = value;
+  }
+
+  /**
+   * Gets whether deep comparison is enabled.
+   * @returns {boolean}
+   */
+  get deepComparison() {
+    return this.#deepComparison;
+  }
+
+  /**
+   * Sets whether deep comparison is enabled.
+   * @param {boolean} value - The configuration value.
+   */
+  set deepComparison(value) {
+    if (typeof value !== 'boolean')
+      throw new TypeError('The deepComparison option must be a boolean.');
+    this.#deepComparison = value;
+  }
+
   /**
    * Gets the current base array used for comparisons.
    * @returns {ArrayItem[]} The current initial state of the array.
@@ -68,16 +172,25 @@ class TinyArrayComparator {
   }
 
   /**
-   * Initializes the comparator with an optional base array.
+   * Initializes the comparator with an optional base array and options.
    * @param {ArrayItem[]} [oldArray] - The initial state of the array to be stored.
+   * @param {ComparatorOptions<ArrayItem>} [options={}] - Configuration options for the comparator.
    */
-  constructor(oldArray) {
+  constructor(oldArray, options = {}) {
     if (typeof oldArray !== 'undefined') this.oldArray = oldArray;
+
+    if (typeof options.idKey === 'string') {
+      this.idKey = options.idKey;
+    }
+
+    if (typeof options.deepComparison === 'boolean') {
+      this.deepComparison = options.deepComparison;
+    }
   }
 
   /**
    * Proxy to generates a hash converted to a string.
-   * @param {ArrayItem} item - The item to be hashed (can be an object, array, string, or number).
+   * @param {ArrayItem} item - The item to be hashed.
    * @returns {string} The unique hash representing the item's value.
    * @private
    */
@@ -86,7 +199,70 @@ class TinyArrayComparator {
   }
 
   /**
-   * Compares the stored older array with a newer array and identifies missing or new items.
+   * Recursively compares two objects to find differences.
+   * @param {Object} oldObj - The original object.
+   * @param {Object} newObj - The modified object.
+   * @returns {ObjectDiff<ArrayItem>} A structured object containing the differences.
+   */
+  #getDeepDiff(oldObj, newObj) {
+    /** @type {ObjectDiff<ArrayItem>} */
+    const diff = {
+      added: {},
+      deleted: {},
+      modified: {},
+      nested: {},
+    };
+
+    const allKeys = new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+
+    for (const key of allKeys) {
+      // @ts-ignore
+      const oldVal = oldObj[key];
+      // @ts-ignore
+      const newVal = newObj[key];
+
+      if (!(key in oldObj)) {
+        // Key exists in new object but not in old
+        // @ts-ignore
+        diff.added[key] = newVal;
+      } else if (!(key in newObj)) {
+        // Key exists in old object but not in new
+        // @ts-ignore
+        diff.deleted[key] = oldVal;
+      } else if (
+        typeof oldVal === 'object' &&
+        oldVal !== null &&
+        typeof newVal === 'object' &&
+        newVal !== null &&
+        !Array.isArray(oldVal) &&
+        !Array.isArray(newObj)
+      ) {
+        // Both are objects, recurse
+        const nestedDiff = this.#getDeepDiff(oldVal, newVal);
+        // Only add nested if it actually contains differences
+        if (
+          Object.keys(nestedDiff.added).length > 0 ||
+          Object.keys(nestedDiff.deleted).length > 0 ||
+          Object.keys(nestedDiff.modified).length > 0 ||
+          Object.keys(nestedDiff.nested).length > 0
+        ) {
+          // @ts-ignore
+          diff.nested[key] = nestedDiff;
+        }
+      } else if (oldVal !== newVal) {
+        // Values are different and not objects (or one is an array)
+        // @ts-ignore
+        diff.modified[key] = {
+          oldValue: oldVal,
+          newValue: newVal,
+        };
+      }
+    }
+    return diff;
+  }
+
+  /**
+   * Compares the stored older array with a newer array and identifies added, deleted, or edited items.
    *
    * @param {ArrayItem[]} newArray - The modified state of the array.
    * @returns {AffectedItems<ArrayItem>} An array containing the affected items and their status.
@@ -104,26 +280,65 @@ class TinyArrayComparator {
 
     // Step 1: Hash and store all items from the first array
     for (const item of this.#oldArray) {
-      const hashKey = this._generateHash(item);
-      state.oldItemsMap.set(hashKey, item);
+      const hash = this._generateHash(item);
+
+      // Identity is determined by the idKey. Otherwise, it relies purely on the hash.
+      const identityKey =
+        this.#idKey !== null && item !== null && typeof item === 'object' && this.#idKey in item
+          ? // @ts-ignore
+            item[this.#idKey]
+          : hash;
+
+      state.oldItemsMap.set(identityKey, { item, hash });
     }
 
-    // Step 2: Iterate through the second array to find matches or additions
+    // Step 2: Iterate through the second array to find matches, edits or additions
     for (const item of newArray) {
-      const hashKey = this._generateHash(item);
+      const hash = this._generateHash(item);
+
+      const identityKey =
+        this.#idKey !== null && item !== null && typeof item === 'object' && this.#idKey in item
+          ? // @ts-ignore
+            item[this.#idKey]
+          : hash;
+
+      const oldData = state.oldItemsMap.get(identityKey);
+      if (oldData) {
+        if (oldData.hash === hash) {
+          // Item exists and the content is identical. Unchanged.
+          state.oldItemsMap.delete(identityKey);
+        } else {
+          // Item has the same identity but a different hash. It was edited.
+          /** @type {DiffResult<ArrayItem>} */
+          const diffResult = {
+            item: item,
+            oldItem: oldData.item,
+            status: 'edited',
+          };
+
+          // Perform deep comparison if enabled and items are objects
+          if (
+            this.#deepComparison &&
+            typeof item === 'object' &&
+            item !== null &&
+            typeof oldData.item === 'object' &&
+            oldData.item !== null
+          ) {
+            diffResult.details = this.#getDeepDiff(oldData.item, item);
+          }
 
-      if (state.oldItemsMap.has(hashKey)) {
-        // Item exists in both, so it is unchanged. Remove from map.
-        state.oldItemsMap.delete(hashKey);
+          state.affectedItems.push(diffResult);
+          state.oldItemsMap.delete(identityKey);
+        }
       } else {
-        // Item was not in the old array, so it is an addition.
+        // Item identity was not found in the old array. It is an addition.
         state.affectedItems.push({ item, status: 'added' });
       }
     }
 
     // Step 3: Any item left in the oldItemsMap was not present in the new array (deleted)
-    for (const item of state.oldItemsMap.values()) {
-      state.affectedItems.push({ item, status: 'deleted' });
+    for (const oldData of state.oldItemsMap.values()) {
+      state.affectedItems.push({ item: oldData.item, status: 'deleted' });
     }
 
     return state.affectedItems;

package/dist/v1/libs/array/TinyArrayComparator.d.mts

@@ -1,45 +1,152 @@
 /**
- * @fileoverview Array comparison utility.
+ * @fileoverview Array comparison utility with deep object diffing capabilities.
  * @module TinyArrayComparator
  */
-export type InternalState<ArrayItem extends any> = {
+export type HashEntry<Item> = {
     /**
-     * - A map storing the hash as the key and the original item as the value.
+     * - The original item stored in the map.
      */
-    oldItemsMap: Map<string, ArrayItem>;
+    item: Item;
     /**
-     * - The final array that collects added or deleted items.
+     * - The calculated hash representing the item's value.
      */
-    affectedItems: AffectedItems<ArrayItem>;
+    hash: string;
+};
+export type ObjectDiff<Item> = {
+    /**
+     * - Properties added in the new object.
+     */
+    added: Partial<Item>;
+    /**
+     * - Properties removed from the old object.
+     */
+    deleted: Partial<Item>;
+    /**
+     * - Properties that changed value.
+     */
+    modified: Partial<{ [K in keyof Item]: {
+        oldValue: Item[K];
+        newValue: Item[K];
+    }; }>;
+    /**
+     * - Nested differences for nested objects.
+     */
+    nested: Partial<{ [K in keyof Item]: ObjectDiff<Item[K]>; }>;
+};
+export type DiffResult<Item> = {
+    /**
+     * - The item that was affected.
+     */
+    item: Item;
+    /**
+     * - The original item before the change (only for 'edited' status).
+     */
+    oldItem?: Item;
+    /**
+     * - The nature of the change.
+     */
+    status: 'added' | 'deleted' | 'edited';
+    /**
+     * - Detailed property changes (only if status is 'edited' and deepComparison is enabled).
+     */
+    details?: ObjectDiff<Item>;
+};
+export type InternalState<Item> = {
+    /**
+     * - A map storing the identity key as the key and the hash entry as the value.
+     */
+    oldItemsMap: Map<string | number, HashEntry<Item>>;
+    /**
+     * - The final array that collects added, deleted, or edited items.
+     */
+    affectedItems: Array<DiffResult<Item>>;
+};
+export type AffectedItems<Item> = Array<DiffResult<Item>>;
+export type ComparatorOptions<Item> = {
+    /**
+     * - The property name used as a unique identifier for objects to detect edits.
+     */
+    idKey?: keyof Item | (string & {});
+    /**
+     * - If true, provides detailed property-level diffs for edited objects.
+     */
+    deepComparison?: boolean;
 };
-export type AffectedItems<ArrayItem extends any> = Array<{
-    item: ArrayItem;
-    status: 'added' | 'deleted';
-}>;
 /**
- * @template {any} ArrayItem
+ * @template Item
+ * @typedef {Object} HashEntry
+ * @property {Item} item - The original item stored in the map.
+ * @property {string} hash - The calculated hash representing the item's value.
+ */
+/**
+ * @template Item
+ * @typedef {Object} ObjectDiff
+ * @property {Partial<Item>} added - Properties added in the new object.
+ * @property {Partial<Item>} deleted - Properties removed from the old object.
+ * @property {Partial<{ [K in keyof Item]: { oldValue: Item[K], newValue: Item[K] } }>} modified - Properties that changed value.
+ * @property {Partial<{ [K in keyof Item]: ObjectDiff<Item[K]> }>} nested - Nested differences for nested objects.
+ */
+/**
+ * @template Item
+ * @typedef {Object} DiffResult
+ * @property {Item} item - The item that was affected.
+ * @property {Item} [oldItem] - The original item before the change (only for 'edited' status).
+ * @property {'added'|'deleted'|'edited'} status - The nature of the change.
+ * @property {ObjectDiff<Item>} [details] - Detailed property changes (only if status is 'edited' and deepComparison is enabled).
+ */
+/**
+ * @template Item
  * @typedef {Object} InternalState
  * Holds the internal tracking variables during the comparison process.
- * @property {Map<string, ArrayItem>} oldItemsMap - A map storing the hash as the key and the original item as the value.
- * @property {AffectedItems<ArrayItem>} affectedItems - The final array that collects added or deleted items.
+ * @property {Map<string|number, HashEntry<Item>>} oldItemsMap - A map storing the identity key as the key and the hash entry as the value.
+ * @property {Array<DiffResult<Item>>} affectedItems - The final array that collects added, deleted, or edited items.
  */
 /**
- * The final array that collects added or deleted items.
- * @template {any} ArrayItem
- * @typedef {Array<{item: ArrayItem, status: 'added'|'deleted'}>} AffectedItems
+ * The final array that collects added, deleted, or edited items.
+ * @template Item
+ * @typedef {Array<DiffResult<Item>>} AffectedItems
+ */
+/**
+ * Options to configure the comparator.
+ * @template Item
+ * @typedef {Object} ComparatorOptions
+ * @property {keyof Item | (string & {})} [idKey='id'] - The property name used as a unique identifier for objects to detect edits.
+ * @property {boolean} [deepComparison=true] - If true, provides detailed property-level diffs for edited objects.
  */
 /**
- * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ * Compares two arrays efficiently by hashing their items to detect additions, deletions, and edits.
  * @template {any} ArrayItem
  */
 declare class TinyArrayComparator<ArrayItem extends any> {
     #private;
     /**
      * Generates a simple 32-bit integer hash converted to a base36 string.
-     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @param {any} item - The item to be hashed.
      * @returns {string} The unique hash representing the item's value.
+     * @throws {TypeError} Throws a TypeError if the item cannot be stringified due to circular references.
      */
     static generateHash(item: any): string;
+    /**
+     * Gets the current identity key.
+     * @returns {string|null}
+     */
+    get idKey(): string | null;
+    /**
+     * Sets the identity key used for object comparison.
+     * @param {string|null} value - The property name to use as an identifier.
+     * @throws {TypeError} Throws a TypeError if the value is not a string.
+     */
+    set idKey(value: string | null);
+    /**
+     * Gets whether deep comparison is enabled.
+     * @returns {boolean}
+     */
+    get deepComparison(): boolean;
+    /**
+     * Sets whether deep comparison is enabled.
+     * @param {boolean} value - The configuration value.
+     */
+    set deepComparison(value: boolean);
     /**
      * Gets the current base array used for comparisons.
      * @returns {ArrayItem[]} The current initial state of the array.
@@ -52,19 +159,20 @@ declare class TinyArrayComparator<ArrayItem extends any> {
      */
     set oldArray(oldArray: ArrayItem[]);
     /**
-     * Initializes the comparator with an optional base array.
+     * Initializes the comparator with an optional base array and options.
      * @param {ArrayItem[]} [oldArray] - The initial state of the array to be stored.
+     * @param {ComparatorOptions<ArrayItem>} [options={}] - Configuration options for the comparator.
      */
-    constructor(oldArray?: ArrayItem[]);
+    constructor(oldArray?: ArrayItem[], options?: ComparatorOptions<ArrayItem>);
     /**
      * Proxy to generates a hash converted to a string.
-     * @param {ArrayItem} item - The item to be hashed (can be an object, array, string, or number).
+     * @param {ArrayItem} item - The item to be hashed.
      * @returns {string} The unique hash representing the item's value.
      * @private
      */
     private _generateHash;
     /**
-     * Compares the stored older array with a newer array and identifies missing or new items.
+     * Compares the stored older array with a newer array and identifies added, deleted, or edited items.
      *
      * @param {ArrayItem[]} newArray - The modified state of the array.
      * @returns {AffectedItems<ArrayItem>} An array containing the affected items and their status.

package/dist/v1/libs/array/TinyArrayComparator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"TinyArrayComparator.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/array/TinyArrayComparator.mjs"],"names":[],"mappings":"AAAA;;;GAGG;AAIA,YAAkB,aAAa,CADf,SAAS,SAAd,GAAc,IAGzB;;;;IAAmC,WAAW,EAAnC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CACjC;;;;IAAqC,aAAa,EAAvC,aAAa,CAAC,SAAS,CAAC,CACrC;CAAA,CAAA;AAKE,YAA+D,aAAa,CAD5D,SAAS,SAAd,GAAc,IACf,KAAK,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,OAAO,GAAC,SAAS,CAAA;CAAC,CAAC,CAAe;AAX/E;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;GAGG;AACH,cAAM,mBAAmB,CAFN,SAAS,SAAd,GAAc;;IAG1B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAHb,GAGa,GAFX,MAAM,CAalB;IAQD;;;OAGG;IACH,IAAI,QAAQ,IAFC,SAAS,EAAE,CAIvB;IAED;;;;OAIG;IACH,IAAI,QAAQ,CAAC,QAAQ,EAHV,SAAS,EAGC,EAIpB;IAED;;;OAGG;IACH,YAAY,QAAQ,AAFjB,CACF,EADU,SAAS,EAEA,EAEnB;IAED;;;;;OAKG;YACH,aAAa;IAIb;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAJL,SAAS,EAIJ,GAHH,aAAa,CAAC,SAAS,CAAC,CAsCpC;CACF;eAEc,mBAAmB"}
+{"version":3,"file":"TinyArrayComparator.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/array/TinyArrayComparator.mjs"],"names":[],"mappings":"AAAA;;;GAGG;AAIA,YAAkB,SAAS,CADjB,IAAI,IAEd;;;;IAAiB,IAAI,EAAV,IAAI,CACf;;;;IAAmB,IAAI,EAAZ,MAAM,CACnB;CAAA,CAAA;AASE,YAAkB,UAAU,CADlB,IAAI,IAEd;;;;IAA0B,KAAK,EAApB,OAAO,CAAC,IAAI,CAAC,CACxB;;;;IAA0B,OAAO,EAAtB,OAAO,CAAC,IAAI,CAAC,CACxB;;;;IAAqF,QAAQ,EAAlF,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,IAAI,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;KAAE,GAAE,CAAC,CACnF;;;;IAAgE,MAAM,EAA3D,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAE,CAAC,CAChE;CAAA,CAAA;AAQE,YAAkB,UAAU,CADlB,IAAI,IAEd;;;;IAAiB,IAAI,EAAV,IAAI,CACf;;;;IAAkB,OAAO,AAAzB,CACA,EADW,IAAI,CACf;;;;IAAuC,MAAM,EAAlC,OAAO,GAAC,SAAS,GAAC,QAAQ,CACrC;;;;IAA8B,OAAO,AAArC,CACF,EADa,UAAU,CAAC,IAAI,CAAC,CAC7B;CAAA,CAAA;AAIE,YAAkB,aAAa,CADrB,IAAI,IAGd;;;;IAAgD,WAAW,EAAhD,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAC9C;;;;IAAoC,aAAa,EAAtC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CACpC;CAAA,CAAA;AAKE,YAAmC,aAAa,CADtC,IAAI,IACJ,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAe;AAWhD,YAAkB,iBAAiB,CADzB,IAAI,IAEd;;;;IAAwC,KAAK,AAA7C,CACA,EADW,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CACrC;;;;IAAqB,cAAc,AAAnC,CACF,EADa,OAAO,CACpB;CAAA,CAAA;AA3DD;;;;;GAKG;AAOH;;;;;;;GAOG;AAMH;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAOH;;;;;;GAMG;AAEH;;;GAGG;AACH,cAAM,mBAAmB,CAFN,SAAS,SAAd,GAAc;;IAG1B;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAJb,GAIa,GAHX,MAAM,CAqBlB;IAoBD;;;OAGG;IACH,IAAI,KAAK,IAFI,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,IAAI,KAAK,CAAC,KAAK,EAHJ,MAAM,GAAC,IAGH,EAId;IAED;;;OAGG;IACH,IAAI,cAAc,IAFL,OAAO,CAInB;IAED;;;OAGG;IACH,IAAI,cAAc,CAAC,KAAK,EAFb,OAEa,EAIvB;IAED;;;OAGG;IACH,IAAI,QAAQ,IAFC,SAAS,EAAE,CAIvB;IAED;;;;OAIG;IACH,IAAI,QAAQ,CAAC,QAAQ,EAHV,SAAS,EAGC,EAIpB;IAED;;;;OAIG;IACH,YAAY,QAAQ,AAHjB,CACA,EADQ,SAAS,EAGA,EAAE,OAAO,AAF1B,CACF,EADU,iBAAiB,CAAC,SAAS,CAEJ,EAUjC;IAED;;;;;OAKG;YACH,aAAa;IAmEb;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAJL,SAAS,EAIJ,GAHH,aAAa,CAAC,SAAS,CAAC,CA6EpC;CACF;eAEc,mBAAmB"}