@pawells/typescript-common 1.3.1 → 2.0.0

package/README.md

@@ -36,7 +36,60 @@ BooleanUtils.AssertBoolean(value);       // throws if not a boolean
 NumberUtils.AssertNumber(value, { gte: 0, integer: true });
 
 // Direct named import (tree-shakeable)
-import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from '@pawells/typescript-common';
+import { ArrayChunk, ObjectPick, KebabCase, Sleep, AssertString, LRUCache } from '@pawells/typescript-common';
+```
+
+## Features & Patterns
+
+### Readonly Array Support
+
+All array utilities accept `readonly T[]` arrays, enabling zero-copy usage with frozen constants:
+
+```typescript
+const colors = Object.freeze(['red', 'green', 'blue']); // readonly string[]
+ArrayChunk(colors, 2); // Works without casting!
+ArrayFilter(colors, c => c.length > 3); // ✓ No type errors
+```
+
+### Custom RNG for Deterministic Testing
+
+`ArraySample` and `ArrayShuffle` accept an optional custom RNG function for reproducible randomization:
+
+```typescript
+const seededRng = Mulberry32(42); // Your seeded PRNG
+ArrayShuffle([1, 2, 3], seededRng); // Same output every time
+ArraySample([1, 2, 3], 2, seededRng); // Deterministic sampling
+
+// Without RNG, defaults to Math.random() for normal usage
+ArrayShuffle([1, 2, 3]); // Random shuffle
+```
+
+### Predicate Functions in ObjectFilter
+
+Filter by predicate functions in addition to equality checks:
+
+```typescript
+const user = { name: 'John', age: 30, active: true };
+
+// Basic equality filtering
+ObjectFilter(user, { name: 'John' }); // true
+
+// Predicate functions as filter values
+ObjectFilter(user, { age: (v) => v > 18 }); // true
+ObjectFilter(user, { age: (v) => v < 18 }); // false
+
+// Mix predicates and values
+ObjectFilter(user, {
+  active: true,
+  age: (v) => v >= 21
+}); // true
+
+// Supports dot notation with predicates
+const order = { user: { age: 25 }, total: 100 };
+ObjectFilter(order, {
+  'user.age': (v) => v >= 21,
+  'total': (v) => v > 50
+}); // true
 ```
 
 ## API
@@ -50,7 +103,8 @@ import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from
 | `ArrayFilter(array, predicate)` | Type-safe array filter |
 | `ArrayGroupBy(array, keyFn)` | Group array elements by a key function |
 | `ArrayIntersection(a, b)` | Return elements present in both arrays |
-| `ArrayShuffle(array)` | Return a shuffled copy of an array |
+| `ArrayShuffle(array, rng?)` | Return a shuffled copy of an array (optional custom RNG for deterministic results) |
+| `ArraySample(array, n?, rng?)` | Random element or `n` random elements (optional custom RNG for deterministic results) |
 | `Unique(array)` | Remove duplicate values |
 | `ArrayDifference(a, b)` | Elements in `a` not present in `b` |
 | `ArrayFlatten(array, depth?)` | Flatten a nested array to a given depth |
@@ -60,7 +114,6 @@ import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from
 | `ArrayRange(start, end, step?)` | Generate a numeric sequence |
 | `ArraySortBy(array, keyFn, direction?)` | Immutable sort by a computed key |
 | `ArrayCountBy(array, keyFn)` | Count elements per group key |
-| `ArraySample(array, n?)` | Random element or `n` random elements |
 | `AssertArray(value, args?, exception?)` | Assert value is an array (with optional size constraints) |
 | `AssertArray2D(value, args?, exception?)` | Assert value is a rectangular 2D array |
 | `AssertArrayNotEmpty(value, exception?)` | Assert array has at least one element |
@@ -86,14 +139,14 @@ import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from
 | `IsObject(value)` | Type-guard: returns `true` if value is a non-null, non-array object |
 | `ObjectClone(obj)` | Deep-clone an object |
 | `ObjectEquals(a, b)` | Deep equality check |
-| `ObjectFilter(obj, predicate)` | Filter object entries by predicate |
-| `ObjectFilterCached(obj, predicate)` | Cached filter for repeated operations |
+| `ObjectFilter(obj, filter, options?)` | Filter object by property values or predicate functions (supports dot notation, deep equality, case-insensitive matching, and predicate functions) |
+| `ObjectFilterCached(options?)` | Returns a cached filter function for repeated filtering operations with optional deep equality and case-insensitive matching |
 | `FilterObject(obj, keys)` | Keep only specified keys |
 | `ObjectPick(obj, keys)` | Pick a subset of keys |
 | `ObjectOmit(obj, keys)` | Omit specified keys |
 | `ObjectMerge(target, ...sources)` | Deep merge objects |
 | `MapObject(obj, fn)` | Map over object values |
-| `MapObjectCached(obj, fn)` | Cached map for repeated operations |
+| `MapObjectCached(options?)` | Returns a cached map function for repeated mapping operations with optional async support |
 | `TransformObject(obj, fn)` | Transform object entries |
 | `ObjectHash(obj)` | Compute a stable hash of an object |
 | `ObjectSortKeys(obj)` | Return object with keys sorted |
@@ -116,11 +169,11 @@ import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from
 | Export | Description |
 |--------|-------------|
 | `CamelCase(str)` | Convert a string to camelCase |
-| `CAPITALIZE(str)` | Capitalize the first letter of a string |
-| `PASCAL_CASE(str)` | Convert a string to PascalCase |
-| `KEBAB_CASE(str)` | Convert a string to kebab-case |
-| `SNAKE_CASE(str)` | Convert a string to snake_case |
-| `SCREAMING_SNAKE_CASE(str)` | Convert a string to SCREAMING_SNAKE_CASE |
+| `Capitalize(str)` | Capitalize the first letter of a string |
+| `PascalCase(str)` | Convert a string to PascalCase |
+| `KebabCase(str)` | Convert a string to kebab-case |
+| `SnakeCase(str)` | Convert a string to snake_case |
+| `ScreamingSnakeCase(str)` | Convert a string to SCREAMING_SNAKE_CASE |
 | `FormatString(template, values)` | Simple string template formatting |
 | `TruncateString(str, maxLength, ellipsis?)` | Truncate a string with ellipsis |
 | `PadString(str, length, char?, padEnd?)` | Pad a string to a specified length |
@@ -129,10 +182,11 @@ import { ArrayChunk, ObjectPick, CamelCase, Sleep, AssertString, LRUCache } from
 | `Pluralize(word, count, plural?)` | Return singular or plural form based on count |
 | `WordCount(str)` | Count the number of words in a string |
 | `CountOccurrences(str, substr)` | Count non-overlapping occurrences of a substring |
-| `REVERSE_STRING(str)` | Reverse a string |
-| `SLUGIFY(str)` | Convert a string to a URL-friendly slug |
-| `IS_BLANK_STRING(str)` | Check if a string is empty or whitespace-only |
-| `IS_HEX_STRING(str)` | Check if a string is a valid hexadecimal value |
+| `ReverseString(str)` | Reverse a string |
+| `Slugify(str)` | Convert a string to a URL-friendly slug |
+| `IsBlankString(str)` | Check if a string is empty or whitespace-only |
+| `IsHexString(str)` | Check if a string is a valid hexadecimal value |
+| `StringEquals(a, b, caseInsensitive?)` | Compare two strings with optional case-insensitive matching |
 | `AssertString(value, exception?)` | Assert value is a string primitive |
 | `AssertStringNotEmpty(value, exception?)` | Assert value is a non-empty, non-whitespace string |
 | `AssertStringMatches(value, regex, exception?)` | Assert string matches a regular expression |

package/build/array/array-chunk.d.ts

@@ -12,5 +12,5 @@
  * ArrayChunk(['a', 'b', 'c'], 2); // [['a', 'b'], ['c']]
  * ```
  */
-export declare function ArrayChunk<T>(array: T[], size: number): T[][];
+export declare function ArrayChunk<T>(array: readonly T[], size: number): T[][];
 //# sourceMappingURL=array-chunk.d.ts.map

package/build/array/array-chunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-chunk.d.ts","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAY7D"}
+{"version":3,"file":"array-chunk.d.ts","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAYtE"}

package/build/array/array-chunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-chunk.js","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAI,KAAU,EAAE,IAAY;IACrD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAU,EAAE,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}
+{"version":3,"file":"array-chunk.js","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAI,KAAmB,EAAE,IAAY;IAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAU,EAAE,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/build/array/array-contains.d.ts

@@ -2,6 +2,9 @@ import type { TPredicate } from './types.js';
 /**
  * Checks if an array contains at least one element that passes a predicate test.
  *
+ * Uses `array.some()` to check if any element satisfies the predicate condition.
+ * Returns false if the array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The array to check
  * @param predicate - A function that tests each element; returns `true` to signal a match
@@ -13,5 +16,5 @@ import type { TPredicate } from './types.js';
  * ArrayContains([1, 2, 3], (n) => n > 10);  // false
  * ```
  */
-export declare function ArrayContains<T>(array: T[], predicate: TPredicate<T>): boolean;
+export declare function ArrayContains<T>(array: readonly T[], predicate: TPredicate<T>): boolean;
 //# sourceMappingURL=array-contains.d.ts.map

package/build/array/array-contains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-contains.d.ts","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAM9E"}
+{"version":3,"file":"array-contains.d.ts","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAOvF"}

package/build/array/array-contains.js

@@ -1,6 +1,9 @@
 /**
  * Checks if an array contains at least one element that passes a predicate test.
  *
+ * Uses `array.some()` to check if any element satisfies the predicate condition.
+ * Returns false if the array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The array to check
  * @param predicate - A function that tests each element; returns `true` to signal a match
@@ -13,6 +16,7 @@
  * ```
  */
 export function ArrayContains(array, predicate) {
+    // Predicate functions use array.some() / array.every() for consistency
     if (!array || array.length === 0) {
         return false;
     }

package/build/array/array-contains.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-contains.js","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAI,KAAU,EAAE,SAAwB;IACpE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"array-contains.js","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAI,KAAmB,EAAE,SAAwB;IAC7E,uEAAuE;IACvE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC"}

package/build/array/array-count-by.d.ts

@@ -2,6 +2,8 @@ import type { TTransform } from './types.js';
 /**
  * Counts how many elements fall into each group defined by `keyFn`.
  *
+ * Returns empty object if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @template K - The key type (string, number, or symbol)
  * @param array - The array to count
@@ -17,5 +19,5 @@ import type { TTransform } from './types.js';
  * // { admin: 3, member: 12, guest: 1 }
  * ```
  */
-export declare function ArrayCountBy<T, K extends string | number | symbol>(array: T[], keyFn: TTransform<T, K>): Record<K, number>;
+export declare function ArrayCountBy<T, K extends string | number | symbol>(array: readonly T[], keyFn: TTransform<T, K>): Record<K, number>;
 //# sourceMappingURL=array-count-by.d.ts.map

package/build/array/array-count-by.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-count-by.d.ts","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EACjE,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACrB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAWnB"}
+{"version":3,"file":"array-count-by.d.ts","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EACjE,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACrB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAYnB"}

package/build/array/array-count-by.js

@@ -1,6 +1,8 @@
 /**
  * Counts how many elements fall into each group defined by `keyFn`.
  *
+ * Returns empty object if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @template K - The key type (string, number, or symbol)
  * @param array - The array to count
@@ -17,7 +19,8 @@
  * ```
  */
 export function ArrayCountBy(array, keyFn) {
-    if (array === null || array === undefined)
+    // Consistent null-check: early return for null/undefined arrays
+    if (!array)
         return {};
     const result = {};
     for (const item of array) {

package/build/array/array-count-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-count-by.js","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAU,EACV,KAAuB;IAEvB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAuB,CAAC;IAE1E,MAAM,MAAM,GAAG,EAAuB,CAAC;IAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAE,MAAM,CAAC,GAAG,CAAwB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}
+{"version":3,"file":"array-count-by.js","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAmB,EACnB,KAAuB;IAEvB,gEAAgE;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAuB,CAAC;IAE3C,MAAM,MAAM,GAAG,EAAuB,CAAC;IAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAE,MAAM,CAAC,GAAG,CAAwB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/build/array/array-difference.d.ts

@@ -1,25 +1,36 @@
-import type { TEqualityComparator } from './types.js';
+import type { TArrayComparisonOptions } from './types.js';
 /**
  * Returns elements present in the first array but not in the second (set difference).
  * Optimised O(n+m) using a Set when no custom comparator is provided.
+ * Supports custom comparators for advanced comparison logic, or deep equality checking.
  *
  * @template T - The type of array elements
  * @param array1 - The source array
  * @param array2 - Elements to exclude
- * @param comparator - Optional custom equality comparator
+ * @param options - Optional configuration
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison instead of custom comparator (optional)
  * @returns Array of elements in `array1` that are not in `array2`
  *
  * @example
  * ```typescript
+ * // Basic difference with primitives
  * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
- * ArrayDifference(
- *   [{ id: 1 }, { id: 2 }],
- *   [{ id: 2 }],
- *   (a, b) => a.id === b.id,
- * ); // [{ id: 1 }]
+ *
+ * // Deep equality comparison with objects
+ * const arr1 = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * const arr2 = [{ id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }];
+ * ArrayDifference(arr1, arr2, { useDeepEqual: true });
+ * // [{ id: 1, name: 'Alice' }]
+ *
+ * // Custom comparator
+ * ArrayDifference(arr1, arr2, {
+ *   comparator: (a, b) => a.id === b.id
+ * });
+ * // [{ id: 1, name: 'Alice' }]
  * ```
  *
- * @complexity O(n+m) for primitive values, O(n*m) when a comparator is provided
+ * @complexity O(n+m) for primitive values, O(n*m) when a comparator or deep equality is provided
  */
-export declare function ArrayDifference<T>(array1: T[], array2: T[], comparator?: TEqualityComparator<T>): T[];
+export declare function ArrayDifference<T>(array1: readonly T[], array2: readonly T[], options?: TArrayComparisonOptions<T>): T[];
 //# sourceMappingURL=array-difference.d.ts.map

package/build/array/array-difference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-difference.d.ts","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAChC,MAAM,EAAE,CAAC,EAAE,EACX,MAAM,EAAE,CAAC,EAAE,EACX,UAAU,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GACjC,CAAC,EAAE,CAUL"}
+{"version":3,"file":"array-difference.d.ts","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,OAAO,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,CAAC,EAAE,CAiBL"}

package/build/array/array-difference.js

@@ -1,33 +1,50 @@
+import { ObjectEquals } from '../object/equals.js';
 /**
  * Returns elements present in the first array but not in the second (set difference).
  * Optimised O(n+m) using a Set when no custom comparator is provided.
+ * Supports custom comparators for advanced comparison logic, or deep equality checking.
  *
  * @template T - The type of array elements
  * @param array1 - The source array
  * @param array2 - Elements to exclude
- * @param comparator - Optional custom equality comparator
+ * @param options - Optional configuration
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison instead of custom comparator (optional)
  * @returns Array of elements in `array1` that are not in `array2`
  *
  * @example
  * ```typescript
+ * // Basic difference with primitives
  * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
- * ArrayDifference(
- *   [{ id: 1 }, { id: 2 }],
- *   [{ id: 2 }],
- *   (a, b) => a.id === b.id,
- * ); // [{ id: 1 }]
+ *
+ * // Deep equality comparison with objects
+ * const arr1 = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * const arr2 = [{ id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }];
+ * ArrayDifference(arr1, arr2, { useDeepEqual: true });
+ * // [{ id: 1, name: 'Alice' }]
+ *
+ * // Custom comparator
+ * ArrayDifference(arr1, arr2, {
+ *   comparator: (a, b) => a.id === b.id
+ * });
+ * // [{ id: 1, name: 'Alice' }]
  * ```
  *
- * @complexity O(n+m) for primitive values, O(n*m) when a comparator is provided
+ * @complexity O(n+m) for primitive values, O(n*m) when a comparator or deep equality is provided
  */
-export function ArrayDifference(array1, array2, comparator) {
+export function ArrayDifference(array1, array2, options) {
     if (!array1)
         return [];
     if (!array2 || array2.length === 0)
         return [...array1];
+    const opts = options ?? {};
+    const { comparator, useDeepEqual = false } = opts;
     if (comparator) {
         return array1.filter((item) => !array2.some((other) => comparator(item, other)));
     }
+    if (useDeepEqual) {
+        return array1.filter((item) => !array2.some((other) => ObjectEquals(item, other)));
+    }
     const set2 = new Set(array2);
     return array1.filter((item) => !set2.has(item));
 }

package/build/array/array-difference.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-difference.js","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAW,EACX,MAAW,EACX,UAAmC;IAEnC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEvD,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"array-difference.js","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAoB,EACpB,MAAoB,EACpB,OAAoC;IAEpC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEvD,MAAM,IAAI,GAAI,OAAe,IAAI,EAAE,CAAC;IACpC,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IAElD,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/build/array/array-filter.d.ts

@@ -3,6 +3,8 @@ import type { TPredicate } from './types.js';
  * Filters an array based on criteria that can be an object filter or a predicate function.
  * Supports nested property filtering with dot notation and array property filtering.
  *
+ * Returns empty array if input is null, undefined, or empty.
+ *
  * @param array - The array to filter
  * @param criteria - Either an object with filter criteria or a predicate function
  * @returns A new array containing only items that match the criteria
@@ -33,5 +35,5 @@ import type { TPredicate } from './types.js';
  * const numbers = [1, 2, 3, 4, 5];
  * ArrayFilter(numbers, (n) => n > 3); // [4, 5]
  */
-export declare function ArrayFilter<T>(array: T[], criteria: Partial<Record<string, unknown>> | TPredicate<T>): T[];
+export declare function ArrayFilter<T>(array: readonly T[], criteria: Partial<Record<string, unknown>> | TPredicate<T>): T[];
 //# sourceMappingURL=array-filter.d.ts.map

package/build/array/array-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-filter.d.ts","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsC7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GACxD,CAAC,EAAE,CAeL"}
+{"version":3,"file":"array-filter.d.ts","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsC7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GACxD,CAAC,EAAE,CAgBL"}

package/build/array/array-filter.js

@@ -35,6 +35,8 @@ function matchesValue(value, filterValue) {
  * Filters an array based on criteria that can be an object filter or a predicate function.
  * Supports nested property filtering with dot notation and array property filtering.
  *
+ * Returns empty array if input is null, undefined, or empty.
+ *
  * @param array - The array to filter
  * @param criteria - Either an object with filter criteria or a predicate function
  * @returns A new array containing only items that match the criteria
@@ -66,7 +68,8 @@ function matchesValue(value, filterValue) {
  * ArrayFilter(numbers, (n) => n > 3); // [4, 5]
  */
 export function ArrayFilter(array, criteria) {
-    if (array === null || array === undefined)
+    // Consistent null-check: early return for null/undefined arrays
+    if (!array)
         return [];
     // If criteria is a function, use it as predicate
     if (typeof criteria === 'function') {

package/build/array/array-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-filter.js","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,OAAO,GAAQ,GAAG,CAAC;IAEvB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAChE,kCAAkC;QAClC,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,WAAW;YAAE,OAAO,SAAS,CAAC;QAC1F,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc,EAAE,WAAoB;IACzD,8DAA8D;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,KAAK,WAAW,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAU,EACV,QAA0D;IAE1D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAErD,iDAAiD;IACjD,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,6CAA6C;IAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE;YAC5D,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"array-filter.js","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,OAAO,GAAQ,GAAG,CAAC;IAEvB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAChE,kCAAkC;QAClC,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,WAAW;YAAE,OAAO,SAAS,CAAC;QAC1F,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc,EAAE,WAAoB;IACzD,8DAA8D;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,KAAK,WAAW,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAmB,EACnB,QAA0D;IAE1D,gEAAgE;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,iDAAiD;IACjD,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,6CAA6C;IAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE;YAC5D,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/build/array/array-flatten.d.ts

@@ -12,5 +12,5 @@
  * ArrayFlatten([1, [2, [3]]], 1);   // [1, 2, [3]]
  * ```
  */
-export declare function ArrayFlatten<T = unknown>(array: any[], depth?: number): T[];
+export declare function ArrayFlatten<T = unknown>(array: readonly any[], depth?: number): T[];
 //# sourceMappingURL=array-flatten.d.ts.map

package/build/array/array-flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-flatten.d.ts","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAG3E"}
+{"version":3,"file":"array-flatten.d.ts","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAGpF"}

package/build/array/array-flatten.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-flatten.js","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAc,KAAY,EAAE,KAAc;IACrE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAQ,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"array-flatten.js","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAc,KAAqB,EAAE,KAAc;IAC9E,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAQ,CAAC;AAC7C,CAAC"}

package/build/array/array-group-by.d.ts

@@ -2,6 +2,8 @@ import type { TTransform } from './types.js';
 /**
  * Groups array elements by a key generated by a provided function.
  *
+ * Returns empty object if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @template K - The key type (string, number, or symbol)
  * @param array - The array to group
@@ -18,5 +20,5 @@ import type { TTransform } from './types.js';
  * // { 3: ['one', 'two'], 5: ['three'] }
  * ```
  */
-export declare function ArrayGroupBy<T, K extends string | number | symbol>(array: T[], keyFn: TTransform<T, K>): Record<K, T[]>;
+export declare function ArrayGroupBy<T, K extends string | number | symbol>(array: readonly T[], keyFn: TTransform<T, K>): Record<K, T[]>;
 //# sourceMappingURL=array-group-by.d.ts.map

package/build/array/array-group-by.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-group-by.d.ts","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAavH"}
+{"version":3,"file":"array-group-by.d.ts","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAchI"}

package/build/array/array-group-by.js

@@ -1,6 +1,8 @@
 /**
  * Groups array elements by a key generated by a provided function.
  *
+ * Returns empty object if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @template K - The key type (string, number, or symbol)
  * @param array - The array to group
@@ -18,7 +20,8 @@
  * ```
  */
 export function ArrayGroupBy(array, keyFn) {
-    if (array === null || array === undefined) {
+    // Consistent null-check: early return for null/undefined arrays
+    if (!array) {
         return {};
     }
     return array.reduce((acc, item) => {

package/build/array/array-group-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-group-by.js","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAwC,KAAU,EAAE,KAAuB;IACtG,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC3C,OAAO,EAAoB,CAAC;IAC7B,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,GAAG,CAAC;IACZ,CAAC,EAAE,EAAoB,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"array-group-by.js","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAwC,KAAmB,EAAE,KAAuB;IAC/G,gEAAgE;IAChE,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAoB,CAAC;IAC7B,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,GAAG,CAAC;IACZ,CAAC,EAAE,EAAoB,CAAC,CAAC;AAC1B,CAAC"}

package/build/array/array-intersection.d.ts

@@ -1,25 +1,36 @@
-import type { TEqualityComparator } from './types.js';
+import type { TArrayComparisonOptions } from './types.js';
 /**
  * Returns the intersection of two arrays (elements present in both)
- * Optimized O(n+m) complexity using Set-based approach
+ * Optimized O(n+m) complexity using Set-based approach.
+ * Supports custom comparators for advanced comparison logic, or deep equality checking.
  *
  * @template T - The type of array elements
  * @param array1 - First array
  * @param array2 - Second array
- * @param comparator - Optional custom equality comparator
+ * @param options - Optional configuration
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison instead of custom comparator (optional)
  * @returns Array containing elements present in both arrays
  *
  * @example
  * ```typescript
+ * // Basic intersection with primitives
  * ArrayIntersection([1, 2, 3], [2, 3, 4]); // [2, 3]
- * ArrayIntersection(
- *   [{id: 1}, {id: 2}],
- *   [{id: 2}, {id: 3}],
- *   (a, b) => a.id === b.id
- * ); // [{id: 2}]
+ *
+ * // Deep equality comparison with objects
+ * const arr1 = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * const arr2 = [{ id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }];
+ * ArrayIntersection(arr1, arr2, { useDeepEqual: true });
+ * // [{ id: 2, name: 'Bob' }]
+ *
+ * // Custom comparator
+ * ArrayIntersection(arr1, arr2, {
+ *   comparator: (a, b) => a.id === b.id
+ * });
+ * // [{ id: 2, name: 'Bob' }]
  * ```
  *
  * @complexity O(n+m) where n and m are array lengths
  */
-export declare function ArrayIntersection<T>(array1: T[], array2: T[], comparator?: TEqualityComparator<T>): T[];
+export declare function ArrayIntersection<T>(array1: readonly T[], array2: readonly T[], options?: TArrayComparisonOptions<T>): T[];
 //# sourceMappingURL=array-intersection.d.ts.map

package/build/array/array-intersection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-intersection.d.ts","sourceRoot":"","sources":["../../src/array/array-intersection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,MAAM,EAAE,CAAC,EAAE,EACX,MAAM,EAAE,CAAC,EAAE,EACX,UAAU,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GACjC,CAAC,EAAE,CAoBL"}
+{"version":3,"file":"array-intersection.d.ts","sourceRoot":"","sources":["../../src/array/array-intersection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,OAAO,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,CAAC,EAAE,CA8BL"}

package/build/array/array-intersection.js

@@ -1,39 +1,57 @@
+import { ObjectEquals } from '../object/equals.js';
 /**
  * Returns the intersection of two arrays (elements present in both)
- * Optimized O(n+m) complexity using Set-based approach
+ * Optimized O(n+m) complexity using Set-based approach.
+ * Supports custom comparators for advanced comparison logic, or deep equality checking.
  *
  * @template T - The type of array elements
  * @param array1 - First array
  * @param array2 - Second array
- * @param comparator - Optional custom equality comparator
+ * @param options - Optional configuration
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison instead of custom comparator (optional)
  * @returns Array containing elements present in both arrays
  *
  * @example
  * ```typescript
+ * // Basic intersection with primitives
  * ArrayIntersection([1, 2, 3], [2, 3, 4]); // [2, 3]
- * ArrayIntersection(
- *   [{id: 1}, {id: 2}],
- *   [{id: 2}, {id: 3}],
- *   (a, b) => a.id === b.id
- * ); // [{id: 2}]
+ *
+ * // Deep equality comparison with objects
+ * const arr1 = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * const arr2 = [{ id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }];
+ * ArrayIntersection(arr1, arr2, { useDeepEqual: true });
+ * // [{ id: 2, name: 'Bob' }]
+ *
+ * // Custom comparator
+ * ArrayIntersection(arr1, arr2, {
+ *   comparator: (a, b) => a.id === b.id
+ * });
+ * // [{ id: 2, name: 'Bob' }]
  * ```
  *
  * @complexity O(n+m) where n and m are array lengths
  */
-export function ArrayIntersection(array1, array2, comparator) {
+export function ArrayIntersection(array1, array2, options) {
     if (!array1 || !array2) {
         return [];
     }
-    // If no custom comparator, use Set for O(n+m) performance
-    if (!comparator) {
+    const opts = options ?? {};
+    const { comparator, useDeepEqual = false } = opts;
+    // If no custom comparator and no deep equality, use Set for O(n+m) performance
+    if (!comparator && !useDeepEqual) {
         const set2 = new Set(array2);
         return array1.filter(item => set2.has(item));
     }
-    // With custom comparator, still optimize by checking smaller array
+    // With custom comparator or deep equality, optimize by checking smaller array
     // This reduces comparisons from n*m to min(n,m)*max(n,m)
     const [smaller, larger] = array1.length <= array2.length
         ? [array1, array2]
         : [array2, array1];
-    return smaller.filter(item => larger.some(otherItem => comparator(item, otherItem)));
+    if (comparator) {
+        return smaller.filter(item => larger.some(otherItem => comparator(item, otherItem)));
+    }
+    // Use deep equality
+    return smaller.filter(item => larger.some(otherItem => ObjectEquals(item, otherItem)));
 }
 //# sourceMappingURL=array-intersection.js.map

package/build/array/array-intersection.js.map

@@ -1 +1 @@
-{"version":3,"file":"array-intersection.js","sourceRoot":"","sources":["../../src/array/array-intersection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAChC,MAAW,EACX,MAAW,EACX,UAAmC;IAEnC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,0DAA0D;IAC1D,IAAI,CAAC,UAAU,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,mEAAmE;IACnE,yDAAyD;IACzD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACvD,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC;QAClB,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAC5B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CACrD,CAAC;AACH,CAAC"}
+{"version":3,"file":"array-intersection.js","sourceRoot":"","sources":["../../src/array/array-intersection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,iBAAiB,CAChC,MAAoB,EACpB,MAAoB,EACpB,OAAoC;IAEpC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAI,OAAe,IAAI,EAAE,CAAC;IACpC,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IAElD,+EAA+E;IAC/E,IAAI,CAAC,UAAU,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,8EAA8E;IAC9E,yDAAyD;IACzD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACvD,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC;QAClB,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpB,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAC5B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CACrD,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAC5B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CACvD,CAAC;AACH,CAAC"}