@pawells/typescript-common 1.4.1 → 2.1.5

package/{build → dist}/array/array-chunk.js

@@ -4,7 +4,7 @@
  * @template T - The type of array elements
  * @param array - The array to split
  * @param size - Size of each chunk (last chunk may be smaller)
- * @returns Array of arrays, each of the specified size
+ * @returns Array of arrays, each of the specified size. Returns `[]` if `array` is `null`, `undefined`, or `size` is not positive.
  *
  * @example
  * ```typescript
@@ -13,7 +13,7 @@
  * ```
  */
 export function ArrayChunk(array, size) {
-    if (array === null || array === undefined || !(size > 0)) {
+    if (array == null || !(size > 0)) {
         return [];
     }
     const result = [];
@@ -22,4 +22,3 @@ export function ArrayChunk(array, size) {
     }
     return result;
 }
-//# sourceMappingURL=array-chunk.js.map

package/{build → dist}/array/array-compact.d.ts

@@ -3,7 +3,7 @@
  *
  * @template T - The non-nullish element type
  * @param array - The array to compact
- * @returns A new array with `null`/`undefined` entries removed
+ * @returns A new array with `null`/`undefined` entries removed. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript

package/{build → dist}/array/array-compact.js

@@ -3,7 +3,7 @@
  *
  * @template T - The non-nullish element type
  * @param array - The array to compact
- * @returns A new array with `null`/`undefined` entries removed
+ * @returns A new array with `null`/`undefined` entries removed. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -19,4 +19,3 @@ export function ArrayCompact(array) {
         return [];
     return array.filter((item) => item !== null && item !== undefined);
 }
-//# sourceMappingURL=array-compact.js.map

package/{build → dist}/array/array-contains.d.ts

@@ -2,10 +2,13 @@ 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
- * @returns `true` if at least one element passes the test, `false` otherwise
+ * @returns `true` if at least one element passes the test, `false` if no element passes, the array is `null`, `undefined`, or empty
  *
  * @example
  * ```typescript

package/{build → dist}/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,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAMvF"}
+{"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 → dist}/array/array-contains.js

@@ -1,10 +1,13 @@
 /**
  * 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
- * @returns `true` if at least one element passes the test, `false` otherwise
+ * @returns `true` if at least one element passes the test, `false` if no element passes, the array is `null`, `undefined`, or empty
  *
  * @example
  * ```typescript
@@ -13,9 +16,9 @@
  * ```
  */
 export function ArrayContains(array, predicate) {
-    if (!array || array.length === 0) {
+    // Predicate functions use array.some() / array.every() for consistency
+    if (array === null || array === undefined || array.length === 0) {
         return false;
     }
     return array.some(predicate);
 }
-//# sourceMappingURL=array-contains.js.map

package/{build → dist}/array/array-count-by.d.ts

@@ -2,11 +2,13 @@ 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
  * @param keyFn - Function that assigns each element to a group key
- * @returns A record where keys are group identifiers and values are occurrence counts
+ * @returns A record where keys are group identifiers and values are occurrence counts. Returns `{}` if `array` is `null`, `undefined`, or an empty array.
  *
  * @example
  * ```typescript

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;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 → dist}/array/array-count-by.js

@@ -1,11 +1,13 @@
 /**
  * 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
  * @param keyFn - Function that assigns each element to a group key
- * @returns A record where keys are group identifiers and values are occurrence counts
+ * @returns A record where keys are group identifiers and values are occurrence counts. Returns `{}` if `array` is `null`, `undefined`, or an empty array.
  *
  * @example
  * ```typescript
@@ -17,6 +19,7 @@
  * ```
  */
 export function ArrayCountBy(array, keyFn) {
+    // Consistent null-check: early return for null/undefined arrays
     if (array === null || array === undefined)
         return {};
     const result = {};
@@ -26,4 +29,3 @@ export function ArrayCountBy(array, keyFn) {
     }
     return result;
 }
-//# sourceMappingURL=array-count-by.js.map

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

@@ -0,0 +1,43 @@
+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, deep equality checking, or key extraction.
+ *
+ * @template T - The type of array elements
+ * @param array1 - The source array
+ * @param array2 - Elements to exclude
+ * @param options - Optional configuration. Choose one strategy: `comparator`, `useDeepEqual`, or `keyFn`.
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison (optional)
+ * @param options.keyFn - Optional function to extract a primitive key for O(n+m) Set-based lookup. When provided, enables efficient comparison by mapping each item to a key that can be stored in a Set. Example: `{ keyFn: item => item.id }` for objects with a unique id field.
+ * @returns Array of elements in `array1` that are not in `array2`. Returns `[]` if `array1` is `null`, `undefined`, or an empty array.
+ *
+ * @example
+ * ```typescript
+ * // Basic difference with primitives
+ * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
+ *
+ * // 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' }]
+ *
+ * // Key function for O(n+m) lookup
+ * ArrayDifference(arr1, arr2, {
+ *   keyFn: item => item.id
+ * });
+ * // [{ id: 1, name: 'Alice' }]
+ * ```
+ *
+ * @complexity O(n+m) for primitive values, O(n+m) with keyFn, O(n*m) when a comparator or deep equality is provided
+ */
+export declare function ArrayDifference<T>(array1: readonly T[], array2: readonly T[], options?: TArrayComparisonOptions<T>): T[];
+//# sourceMappingURL=array-difference.d.ts.map

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

@@ -0,0 +1 @@
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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,CA+BL"}

package/dist/array/array-difference.js

@@ -0,0 +1,70 @@
+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, deep equality checking, or key extraction.
+ *
+ * @template T - The type of array elements
+ * @param array1 - The source array
+ * @param array2 - Elements to exclude
+ * @param options - Optional configuration. Choose one strategy: `comparator`, `useDeepEqual`, or `keyFn`.
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison (optional)
+ * @param options.keyFn - Optional function to extract a primitive key for O(n+m) Set-based lookup. When provided, enables efficient comparison by mapping each item to a key that can be stored in a Set. Example: `{ keyFn: item => item.id }` for objects with a unique id field.
+ * @returns Array of elements in `array1` that are not in `array2`. Returns `[]` if `array1` is `null`, `undefined`, or an empty array.
+ *
+ * @example
+ * ```typescript
+ * // Basic difference with primitives
+ * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
+ *
+ * // 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' }]
+ *
+ * // Key function for O(n+m) lookup
+ * ArrayDifference(arr1, arr2, {
+ *   keyFn: item => item.id
+ * });
+ * // [{ id: 1, name: 'Alice' }]
+ * ```
+ *
+ * @complexity O(n+m) for primitive values, O(n+m) with keyFn, O(n*m) when a comparator or deep equality is provided
+ */
+export function ArrayDifference(array1, array2, options) {
+    if (!array1)
+        return [];
+    if (!array2 || array2.length === 0)
+        return [...array1];
+    // Type narrowing: determine which strategy to use
+    if (!options) {
+        // No options: use reference equality (===)
+        const set2 = new Set(array2);
+        return array1.filter((item) => !set2.has(item));
+    }
+    if ('keyFn' in options && options.keyFn !== undefined) {
+        // Use key function for O(n+m) Set-based lookup
+        const keyFn = options.keyFn;
+        const set2 = new Set(array2.map(keyFn));
+        return array1.filter((item) => !set2.has(keyFn(item)));
+    }
+    if ('comparator' in options && options.comparator !== undefined) {
+        // Use custom comparator
+        return array1.filter((item) => !array2.some((other) => options.comparator(item, other)));
+    }
+    if (options.useDeepEqual) {
+        // Use deep equality
+        return array1.filter((item) => !array2.some((other) => ObjectEquals(item, other)));
+    }
+    // Fallback (should not reach here with proper type narrowing)
+    const set2 = new Set(array2);
+    return array1.filter((item) => !set2.has(item));
+}

package/dist/array/array-element.js

@@ -0,0 +1 @@
+export {};

package/{build → dist}/array/array-filter.d.ts

@@ -3,9 +3,11 @@ 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
+ * @returns A new array containing only items that match the criteria. Returns `[]` if `array` is `null`, `undefined`, or empty.
  *
  * @example
  * // Simple property filtering

package/{build → dist}/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,SAAS,CAAC,EAAE,EACnB,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 → dist}/array/array-filter.js

@@ -35,9 +35,11 @@ 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
+ * @returns A new array containing only items that match the criteria. Returns `[]` if `array` is `null`, `undefined`, or empty.
  *
  * @example
  * // Simple property filtering
@@ -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') {
@@ -80,4 +83,3 @@ export function ArrayFilter(array, criteria) {
         });
     });
 }
-//# sourceMappingURL=array-filter.js.map

package/{build → dist}/array/array-flatten.d.ts

@@ -4,7 +4,7 @@
  * @template T - The leaf element type
  * @param array - The nested array to flatten
  * @param depth - How many levels deep to flatten (default: `Infinity`)
- * @returns Flattened array of `T`
+ * @returns Flattened array of `T`. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -12,5 +12,5 @@
  * ArrayFlatten([1, [2, [3]]], 1);   // [1, 2, [3]]
  * ```
  */
-export declare function ArrayFlatten<T = unknown>(array: readonly any[], depth?: number): T[];
+export declare function ArrayFlatten<T = unknown>(array: readonly unknown[], depth?: number): T[];
 //# sourceMappingURL=array-flatten.d.ts.map

package/{build → dist}/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,SAAS,GAAG,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAGpF"}
+{"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,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAGxF"}

package/{build → dist}/array/array-flatten.js

@@ -4,7 +4,7 @@
  * @template T - The leaf element type
  * @param array - The nested array to flatten
  * @param depth - How many levels deep to flatten (default: `Infinity`)
- * @returns Flattened array of `T`
+ * @returns Flattened array of `T`. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -17,4 +17,3 @@ export function ArrayFlatten(array, depth) {
         return [];
     return array.flat(depth ?? Infinity);
 }
-//# sourceMappingURL=array-flatten.js.map

package/{build → dist}/array/array-group-by.d.ts

@@ -2,11 +2,13 @@ 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
  * @param keyFn - Function that returns the grouping key for each element
- * @returns A record where each key maps to an array of matching elements
+ * @returns A record where each key maps to an array of matching elements. Returns `{}` if `array` is `null`, `undefined`, or an empty array.
  *
  * @example
  * ```typescript

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;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,CAgBhI"}

package/{build → dist}/array/array-group-by.js

@@ -1,11 +1,13 @@
 /**
  * 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
  * @param keyFn - Function that returns the grouping key for each element
- * @returns A record where each key maps to an array of matching elements
+ * @returns A record where each key maps to an array of matching elements. Returns `{}` if `array` is `null`, `undefined`, or an empty array.
  *
  * @example
  * ```typescript
@@ -18,16 +20,18 @@
  * ```
  */
 export function ArrayGroupBy(array, keyFn) {
+    // Consistent null-check: early return for null/undefined arrays
     if (array === null || array === undefined) {
         return {};
     }
-    return array.reduce((acc, item) => {
+    // Use imperative loop instead of reduce for slightly better performance on large arrays
+    const result = {};
+    for (const item of array) {
         const key = keyFn(item);
-        if (!acc[key]) {
-            acc[key] = [];
+        if (!result[key]) {
+            result[key] = [];
         }
-        acc[key].push(item);
-        return acc;
-    }, {});
+        result[key].push(item);
+    }
+    return result;
 }
-//# sourceMappingURL=array-group-by.js.map

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

@@ -0,0 +1,43 @@
+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.
+ * Supports custom comparators for advanced comparison logic, deep equality checking, or key extraction.
+ *
+ * @template T - The type of array elements
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param options - Optional configuration. Choose one strategy: `comparator`, `useDeepEqual`, or `keyFn`.
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison (optional)
+ * @param options.keyFn - Optional function to extract a primitive key for O(n+m) Set-based lookup. When provided, enables efficient comparison by mapping each item to a key that can be stored in a Set. Example: `{ keyFn: item => item.id }` for objects with a unique id field.
+ * @returns Array containing elements present in both arrays. Returns `[]` if either `array1` or `array2` is `null`, `undefined`, or an empty array.
+ *
+ * @example
+ * ```typescript
+ * // Basic intersection with primitives
+ * ArrayIntersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+ *
+ * // 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' }]
+ *
+ * // Key function for O(n+m) lookup
+ * ArrayIntersection(arr1, arr2, {
+ *   keyFn: item => item.id
+ * });
+ * // [{ id: 2, name: 'Bob' }]
+ * ```
+ *
+ * @complexity O(n+m) where n and m are array lengths (O(n*m) with custom comparator or deep equality)
+ */
+export declare function ArrayIntersection<T>(array1: readonly T[], array2: readonly T[], options?: TArrayComparisonOptions<T>): T[];
+//# sourceMappingURL=array-intersection.d.ts.map

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

@@ -0,0 +1 @@
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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,CA8CL"}

package/dist/array/array-intersection.js

@@ -0,0 +1,79 @@
+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.
+ * Supports custom comparators for advanced comparison logic, deep equality checking, or key extraction.
+ *
+ * @template T - The type of array elements
+ * @param array1 - First array
+ * @param array2 - Second array
+ * @param options - Optional configuration. Choose one strategy: `comparator`, `useDeepEqual`, or `keyFn`.
+ * @param options.comparator - Custom function to determine if elements are equal (optional)
+ * @param options.useDeepEqual - Use deep equality for comparison (optional)
+ * @param options.keyFn - Optional function to extract a primitive key for O(n+m) Set-based lookup. When provided, enables efficient comparison by mapping each item to a key that can be stored in a Set. Example: `{ keyFn: item => item.id }` for objects with a unique id field.
+ * @returns Array containing elements present in both arrays. Returns `[]` if either `array1` or `array2` is `null`, `undefined`, or an empty array.
+ *
+ * @example
+ * ```typescript
+ * // Basic intersection with primitives
+ * ArrayIntersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+ *
+ * // 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' }]
+ *
+ * // Key function for O(n+m) lookup
+ * ArrayIntersection(arr1, arr2, {
+ *   keyFn: item => item.id
+ * });
+ * // [{ id: 2, name: 'Bob' }]
+ * ```
+ *
+ * @complexity O(n+m) where n and m are array lengths (O(n*m) with custom comparator or deep equality)
+ */
+export function ArrayIntersection(array1, array2, options) {
+    if (!array1 || !array2) {
+        return [];
+    }
+    // Type narrowing: determine which strategy to use
+    if (!options) {
+        // No options: use reference equality (===)
+        const set2 = new Set(array2);
+        return array1.filter(item => set2.has(item));
+    }
+    if ('keyFn' in options && options.keyFn !== undefined) {
+        // Use key function for O(n+m) Set-based lookup
+        const keyFn = options.keyFn;
+        const set2 = new Set(array2.map(keyFn));
+        return array1.filter(item => set2.has(keyFn(item)));
+    }
+    if ('comparator' in options && options.comparator !== undefined) {
+        // Use custom comparator
+        // Optimize by checking smaller array to reduce 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 => options.comparator(item, otherItem)));
+    }
+    if (options.useDeepEqual) {
+        // Use deep equality
+        // Optimize by checking smaller array
+        // PERFORMANCE NOTE: This nested .some() call is O(n*m) where n and m are array lengths.
+        // For large arrays using deep equality, this can be 100-1000x slower than necessary.
+        const [smaller, larger] = array1.length <= array2.length
+            ? [array1, array2]
+            : [array2, array1];
+        return smaller.filter(item => larger.some(otherItem => ObjectEquals(item, otherItem)));
+    }
+    // Fallback (should not reach here with proper type narrowing)
+    const set2 = new Set(array2);
+    return array1.filter(item => set2.has(item));
+}

package/{build → dist}/array/array-partition.d.ts

@@ -2,10 +2,12 @@ import type { TPredicate } from './types.js';
 /**
  * Splits an array into two groups: elements that satisfy the predicate and those that do not.
  *
+ * Returns `[[], []]` if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The array to partition
  * @param predicate - The condition to test each element against
- * @returns A tuple `[matches, rest]` where `matches` passed the predicate
+ * @returns A tuple `[matches, rest]` where `matches` passed the predicate. Returns `[[], []]` if `array` is `null`, `undefined`, or empty.
  *
  * @example
  * ```typescript

package/{build → dist}/array/array-partition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-partition.d.ts","sourceRoot":"","sources":["../../src/array/array-partition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAe3F"}
+{"version":3,"file":"array-partition.d.ts","sourceRoot":"","sources":["../../src/array/array-partition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAgB3F"}

package/{build → dist}/array/array-partition.js

@@ -1,10 +1,12 @@
 /**
  * Splits an array into two groups: elements that satisfy the predicate and those that do not.
  *
+ * Returns `[[], []]` if array is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The array to partition
  * @param predicate - The condition to test each element against
- * @returns A tuple `[matches, rest]` where `matches` passed the predicate
+ * @returns A tuple `[matches, rest]` where `matches` passed the predicate. Returns `[[], []]` if `array` is `null`, `undefined`, or empty.
  *
  * @example
  * ```typescript
@@ -15,6 +17,7 @@
  * ```
  */
 export function ArrayPartition(array, predicate) {
+    // Consistent null-check: early return for null/undefined arrays
     if (array === null || array === undefined)
         return [[], []];
     const matches = [];
@@ -29,4 +32,3 @@ export function ArrayPartition(array, predicate) {
     }
     return [matches, rest];
 }
-//# sourceMappingURL=array-partition.js.map

package/{build → dist}/array/array-range.d.ts

@@ -4,7 +4,7 @@
  * @param start - The first value in the range
  * @param end - The value to stop before (exclusive)
  * @param step - Increment between values (default: `1`; use negative for descending ranges)
- * @returns Array of numbers
+ * @returns Array of numbers. Returns `[]` if `step` is 0, or if the range is invalid (e.g., `start >= end` with positive `step`).
  *
  * @example
  * ```typescript

package/{build → dist}/array/array-range.js

@@ -4,7 +4,7 @@
  * @param start - The first value in the range
  * @param end - The value to stop before (exclusive)
  * @param step - Increment between values (default: `1`; use negative for descending ranges)
- * @returns Array of numbers
+ * @returns Array of numbers. Returns `[]` if `step` is 0, or if the range is invalid (e.g., `start >= end` with positive `step`).
  *
  * @example
  * ```typescript
@@ -29,4 +29,3 @@ export function ArrayRange(start, end, step = 1) {
     }
     return result;
 }
-//# sourceMappingURL=array-range.js.map

package/{build → dist}/array/array-sample.d.ts

@@ -4,15 +4,15 @@
  * @template T - The type of array elements
  * @param array - The array to sample from
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns A random element, or `undefined` if the array is empty
+ * @returns A random element, or `undefined` if the array is `null`, `undefined`, or empty
  *
  * @example
  * ```typescript
  * ArraySample([1, 2, 3, 4, 5]); // e.g. 3
- * ArraySample([1, 2, 3], () => 0.5); // deterministic with custom RNG
+ * ArraySample([1, 2, 3], undefined, () => 0.5); // deterministic with custom RNG
  * ```
  */
-export declare function ArraySample<T>(array: readonly T[], random?: () => number): T | undefined;
+export declare function ArraySample<T>(array: readonly T[]): T | undefined;
 /**
  * Returns `n` unique random elements from an array (without replacement).
  * If `n` exceeds the array length, all elements are returned in random order.
@@ -21,7 +21,7 @@ export declare function ArraySample<T>(array: readonly T[], random?: () => numbe
  * @param array - The array to sample from
  * @param n - How many elements to sample
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns An array of `n` randomly selected elements
+ * @returns An array of `n` randomly selected elements. Returns `[]` if `array` is `null`, `undefined`, or empty.
  *
  * @example
  * ```typescript

package/dist/array/array-sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-sample.d.ts","sourceRoot":"","sources":["../../src/array/array-sample.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,CAAC,EAAE,CAAC"}