@pawells/typescript-common 2.0.0 → 2.1.6

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

@@ -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

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

@@ -8,7 +8,7 @@ import type { TPredicate } from './types.js';
  * @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.js

@@ -7,7 +7,7 @@
  * @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
@@ -17,9 +17,8 @@
  */
 export function ArrayContains(array, predicate) {
     // Predicate functions use array.some() / array.every() for consistency
-    if (!array || array.length === 0) {
+    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

@@ -8,7 +8,7 @@ import type { TTransform } from './types.js';
  * @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/{build → dist}/array/array-count-by.js

@@ -7,7 +7,7 @@
  * @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
@@ -20,7 +20,7 @@
  */
 export function ArrayCountBy(array, keyFn) {
     // Consistent null-check: early return for null/undefined arrays
-    if (!array)
+    if (array === null || array === undefined)
         return {};
     const result = {};
     for (const item of array) {
@@ -29,4 +29,3 @@ export function ArrayCountBy(array, keyFn) {
     }
     return result;
 }
-//# sourceMappingURL=array-count-by.js.map

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

@@ -2,15 +2,16 @@ 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.
+ * 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
+ * @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 instead of custom comparator (optional)
- * @returns Array of elements in `array1` that are not in `array2`
+ * @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
@@ -28,9 +29,15 @@ import type { TArrayComparisonOptions } from './types.js';
  *   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) when a comparator or deep equality is provided
+ * @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

@@ -7,7 +7,7 @@ import type { TPredicate } from './types.js';
  *
  * @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.js

@@ -39,7 +39,7 @@ function matchesValue(value, filterValue) {
  *
  * @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
@@ -83,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

@@ -8,7 +8,7 @@ import type { TTransform } from './types.js';
  * @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/{build → dist}/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;;;;;;;;;;;;;;;;;;;;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"}
+{"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

@@ -7,7 +7,7 @@
  * @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
@@ -21,16 +21,17 @@
  */
 export function ArrayGroupBy(array, keyFn) {
     // Consistent null-check: early return for null/undefined arrays
-    if (!array) {
+    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/{build → dist}/array/array-intersection.d.ts

@@ -2,15 +2,16 @@ 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, or deep equality checking.
+ * 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
+ * @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 instead of custom comparator (optional)
- * @returns Array containing elements present in both arrays
+ * @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
@@ -28,9 +29,15 @@ import type { TArrayComparisonOptions } from './types.js';
  *   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
+ * @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

@@ -7,7 +7,7 @@ import type { TPredicate } from './types.js';
  * @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.js

@@ -6,7 +6,7 @@
  * @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
@@ -18,7 +18,7 @@
  */
 export function ArrayPartition(array, predicate) {
     // Consistent null-check: early return for null/undefined arrays
-    if (!array)
+    if (array === null || array === undefined)
         return [[], []];
     const matches = [];
     const rest = [];
@@ -32,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,7 +4,7 @@
  * @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
@@ -21,7 +21,7 @@ export declare function ArraySample<T>(array: readonly T[]): T | undefined;
  * @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/{build → dist}/array/array-sample.js

@@ -1,15 +1,14 @@
 export function ArraySample(array, n, random) {
-    const sampleCount = n;
     const rng = random ?? Math.random;
     if (!array || array.length === 0) {
-        return sampleCount !== undefined ? [] : undefined;
+        return n !== undefined ? [] : undefined;
     }
-    if (sampleCount === undefined) {
+    if (n === undefined) {
         return array[Math.floor(rng() * array.length)];
     }
     // Fisher-Yates partial shuffle for O(n) sampling
     const copy = [...array];
-    const count = Math.min(sampleCount, copy.length);
+    const count = Math.min(n, copy.length);
     for (let i = 0; i < count; i++) {
         const j = i + Math.floor(rng() * (copy.length - i));
         const tmp = copy[j];
@@ -18,4 +17,3 @@ export function ArraySample(array, n, random) {
     }
     return copy.slice(0, count);
 }
-//# sourceMappingURL=array-sample.js.map

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

@@ -4,7 +4,7 @@
  * @template T - The type of array elements
  * @param array - The array to shuffle
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns A new shuffled array (original is not mutated)
+ * @returns A new shuffled array (original is not mutated). Returns `[]` if `array` is `null` or `undefined`.
  *
  * @remarks Uses `Math.random()` by default — not cryptographically secure. Do not use for
  * security-sensitive operations.

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

@@ -4,7 +4,7 @@
  * @template T - The type of array elements
  * @param array - The array to shuffle
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns A new shuffled array (original is not mutated)
+ * @returns A new shuffled array (original is not mutated). Returns `[]` if `array` is `null` or `undefined`.
  *
  * @remarks Uses `Math.random()` by default — not cryptographically secure. Do not use for
  * security-sensitive operations.
@@ -28,4 +28,3 @@ export function ArrayShuffle(array, random) {
     }
     return result;
 }
-//# sourceMappingURL=array-shuffle.js.map

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

@@ -6,7 +6,7 @@ import type { TTransform } from './types.js';
  * @param array - The array to sort
  * @param keyFn - Function that extracts the sort key from each element
  * @param direction - Sort direction: `'asc'` (default) or `'desc'`
- * @returns A sorted copy of the array
+ * @returns A sorted copy of the array. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript

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

@@ -5,7 +5,7 @@
  * @param array - The array to sort
  * @param keyFn - Function that extracts the sort key from each element
  * @param direction - Sort direction: `'asc'` (default) or `'desc'`
- * @returns A sorted copy of the array
+ * @returns A sorted copy of the array. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -28,4 +28,3 @@ export function ArraySortBy(array, keyFn, direction = 'asc') {
         return 0;
     });
 }
-//# sourceMappingURL=array-sort-by.js.map

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

@@ -3,7 +3,7 @@
  * The result length is capped at the shortest input array.
  *
  * @param arrays - Two or more arrays to zip
- * @returns Array of tuples — one tuple per index position
+ * @returns Array of tuples — one tuple per index position. Returns `[]` if `arrays` is empty or if any input array is `null` or `undefined`.
  *
  * @example
  * ```typescript