@pithos/core 2.0.0

package/dist/arkhe/array/drop.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a slice of array with n elements dropped from the beginning.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to query.
+ * @param count - The number of elements to drop.
+ * @returns A new array with the first `count` elements removed.
+ * @throws {RangeError} If count is negative.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space, single slice operation.
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * drop(numbers, 2);
+ * // => [3, 4, 5]
+ *
+ * drop(numbers, 0);
+ * // => [1, 2, 3, 4, 5]
+ * ```
+ */
+export declare function drop<T>(array: readonly T[], count: number): T[];
+//# sourceMappingURL=drop.d.ts.map

package/dist/arkhe/array/drop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/drop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAM/D"}

package/dist/arkhe/array/drop.js

@@ -0,0 +1,31 @@
+/**
+ * Creates a slice of array with n elements dropped from the beginning.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to query.
+ * @param count - The number of elements to drop.
+ * @returns A new array with the first `count` elements removed.
+ * @throws {RangeError} If count is negative.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space, single slice operation.
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * drop(numbers, 2);
+ * // => [3, 4, 5]
+ *
+ * drop(numbers, 0);
+ * // => [1, 2, 3, 4, 5]
+ * ```
+ */
+export function drop(array, count) {
+    if (count < 0) {
+        // Stryker disable next-line StringLiteral: error message content is not critical
+        throw new RangeError("count must be non-negative");
+    }
+    return array.slice(count);
+}
+//# sourceMappingURL=drop.js.map

package/dist/arkhe/array/drop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop.js","sourceRoot":"","sources":["../../../src/arkhe/array/drop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,IAAI,CAAI,KAAmB,EAAE,KAAa;IACxD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,iFAAiF;QACjF,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}

package/dist/arkhe/array/fill.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fills elements of array with value from start up to, but not including, end.
+ *
+ * @info Why wrapping native?: Unlike the native `Array.fill()` which mutates the original array, this function returns a new array, preserving immutability. See [Design Philosophy](/guide/contribution/design-principles/design-philosophy/)
+ * @note For ES2023+, consider using `Array.toFilled()`.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to fill.
+ * @param value - The value to fill array with.
+ * @param start - The start position.
+ * @param end - The end position.
+ * @returns A new array with the filled values.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space — three-pass manual copy with fill range.
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * const filled = fill(numbers, 0, 1, 3);
+ * console.log(filled); // [1, 0, 0, 4, 5]
+ * console.log(numbers); // [1, 2, 3, 4, 5] (original unchanged)
+ * ```
+ */
+export declare function fill<T>(array: readonly T[], value: T, start?: number, end?: number): T[];
+//# sourceMappingURL=fill.d.ts.map

package/dist/arkhe/array/fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/fill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAClB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,CAAC,EACR,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,CAAC,EAAE,CAmBL"}

package/dist/arkhe/array/fill.js

@@ -0,0 +1,43 @@
+/**
+ * Fills elements of array with value from start up to, but not including, end.
+ *
+ * @info Why wrapping native?: Unlike the native `Array.fill()` which mutates the original array, this function returns a new array, preserving immutability. See [Design Philosophy](/guide/contribution/design-principles/design-philosophy/)
+ * @note For ES2023+, consider using `Array.toFilled()`.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to fill.
+ * @param value - The value to fill array with.
+ * @param start - The start position.
+ * @param end - The end position.
+ * @returns A new array with the filled values.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space — three-pass manual copy with fill range.
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * const filled = fill(numbers, 0, 1, 3);
+ * console.log(filled); // [1, 0, 0, 4, 5]
+ * console.log(numbers); // [1, 2, 3, 4, 5] (original unchanged)
+ * ```
+ */
+export function fill(array, value, start, end) {
+    const length = array.length;
+    const s = start !== undefined ? (start >= 0 ? Math.min(start, length) : Math.max(length + start, 0)) : 0;
+    const e = end !== undefined ? (end >= 0 ? Math.min(end, length) : Math.max(length + end, 0)) : length;
+    // Stryker disable next-line ArrayDeclaration: Preallocation optimization — all indices are assigned in the loops below
+    const result = new Array(length);
+    for (let i = 0; i < s; i++) {
+        result[i] = array[i];
+    }
+    for (let i = s; i < e; i++) {
+        result[i] = value;
+    }
+    for (let i = e; i < length; i++) {
+        result[i] = array[i];
+    }
+    return result;
+}
+//# sourceMappingURL=fill.js.map

package/dist/arkhe/array/fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fill.js","sourceRoot":"","sources":["../../../src/arkhe/array/fill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,IAAI,CAChB,KAAmB,EACnB,KAAQ,EACR,KAAc,EACd,GAAY;IAEZ,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,CAAC,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzG,MAAM,CAAC,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEtG,uHAAuH;IACvH,MAAM,MAAM,GAAG,IAAI,KAAK,CAAI,MAAM,CAAC,CAAC;IAEpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/arkhe/array/find-best.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Finds the element that produces the extreme value according to a comparator.
+ *
+ * @template T - The type of elements in the array.
+ * @template Criterion - The type of the comparison criterion.
+ * @param array - The array to search.
+ * @param iteratee - A function that returns the comparison value for each element.
+ * @param compareFn - Returns true if the first criterion should replace the current extreme.
+ * @returns The element with the extreme value, or `undefined` if array is empty.
+ * @since 2.0.0
+ *
+ * @performance O(n) time, O(1) space, uses `for` loop with early return for empty arrays.
+ *
+ * @example
+ * ```typescript
+ * findBest(
+ *   [{ name: 'John', age: 25 }, { name: 'Bob', age: 20 }],
+ *   (u) => u.age,
+ *   (a, b) => a < b
+ * );
+ * // => { name: 'Bob', age: 20 }
+ *
+ * findBest(['hi', 'hello', 'hey'], (s) => s.length, (a, b) => a > b);
+ * // => 'hello'
+ * ```
+ */
+export declare function findBest<T, Criterion>(array: readonly T[], iteratee: (value: T) => Criterion, compareFn: (a: Criterion, b: Criterion) => boolean): T | undefined;
+//# sourceMappingURL=find-best.d.ts.map

package/dist/arkhe/array/find-best.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-best.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/find-best.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EACnC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,SAAS,EACjC,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,KAAK,OAAO,GACjD,CAAC,GAAG,SAAS,CAgBf"}

package/dist/arkhe/array/find-best.js

@@ -0,0 +1,41 @@
+/**
+ * Finds the element that produces the extreme value according to a comparator.
+ *
+ * @template T - The type of elements in the array.
+ * @template Criterion - The type of the comparison criterion.
+ * @param array - The array to search.
+ * @param iteratee - A function that returns the comparison value for each element.
+ * @param compareFn - Returns true if the first criterion should replace the current extreme.
+ * @returns The element with the extreme value, or `undefined` if array is empty.
+ * @since 2.0.0
+ *
+ * @performance O(n) time, O(1) space, uses `for` loop with early return for empty arrays.
+ *
+ * @example
+ * ```typescript
+ * findBest(
+ *   [{ name: 'John', age: 25 }, { name: 'Bob', age: 20 }],
+ *   (u) => u.age,
+ *   (a, b) => a < b
+ * );
+ * // => { name: 'Bob', age: 20 }
+ *
+ * findBest(['hi', 'hello', 'hey'], (s) => s.length, (a, b) => a > b);
+ * // => 'hello'
+ * ```
+ */
+export function findBest(array, iteratee, compareFn) {
+    if (array.length === 0)
+        return undefined;
+    let extremeValue = array[0];
+    let extremeCriterion = iteratee(extremeValue);
+    for (let i = 1; i < array.length; i++) {
+        const currentCriterion = iteratee(array[i]);
+        if (compareFn(currentCriterion, extremeCriterion)) {
+            extremeValue = array[i];
+            extremeCriterion = currentCriterion;
+        }
+    }
+    return extremeValue;
+}
+//# sourceMappingURL=find-best.js.map

package/dist/arkhe/array/find-best.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-best.js","sourceRoot":"","sources":["../../../src/arkhe/array/find-best.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAmB,EACnB,QAAiC,EACjC,SAAkD;IAElD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,IAAI,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,gBAAgB,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAE9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAE5C,IAAI,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,CAAC;YAClD,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACxB,gBAAgB,GAAG,gBAAgB,CAAC;QACtC,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/arkhe/array/find-last-index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns the index of the last element that satisfies the predicate, or -1 if none found.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The source array to inspect.
+ * @param predicate - The function invoked per iteration.
+ * @returns The index of the found element, else -1.
+ * @since 2.0.0
+ *
+ * @note Prefer this over native `Array.findLastIndex()` for ES2020 compatibility.
+ *
+ * @performance O(n) time, O(1) space, reverse iteration with early return on match.
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex | Array.findLastIndex()}
+ *
+ * @example
+ * ```typescript
+ * findLastIndex([1, 2, 3, 4, 3, 2, 1], (v) => v > 2);
+ * // => 4
+ *
+ * findLastIndex(
+ *   [{ name: 'Bob', age: 30 }, { name: 'Alice', age: 30 }],
+ *   (u) => u.age === 30
+ * );
+ * // => 1
+ * ```
+ */
+export declare function findLastIndex<T>(array: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): number;
+//# sourceMappingURL=find-last-index.d.ts.map

package/dist/arkhe/array/find-last-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-last-index.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/find-last-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,OAAO,GACnE,MAAM,CAQR"}

package/dist/arkhe/array/find-last-index.js

@@ -0,0 +1,36 @@
+/**
+ * Returns the index of the last element that satisfies the predicate, or -1 if none found.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The source array to inspect.
+ * @param predicate - The function invoked per iteration.
+ * @returns The index of the found element, else -1.
+ * @since 2.0.0
+ *
+ * @note Prefer this over native `Array.findLastIndex()` for ES2020 compatibility.
+ *
+ * @performance O(n) time, O(1) space, reverse iteration with early return on match.
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex | Array.findLastIndex()}
+ *
+ * @example
+ * ```typescript
+ * findLastIndex([1, 2, 3, 4, 3, 2, 1], (v) => v > 2);
+ * // => 4
+ *
+ * findLastIndex(
+ *   [{ name: 'Bob', age: 30 }, { name: 'Alice', age: 30 }],
+ *   (u) => u.age === 30
+ * );
+ * // => 1
+ * ```
+ */
+export function findLastIndex(array, predicate) {
+    for (let index = array.length - 1; index >= 0; index--) {
+        if (predicate(array[index], index, array)) {
+            return index;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=find-last-index.js.map

package/dist/arkhe/array/find-last-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-last-index.js","sourceRoot":"","sources":["../../../src/arkhe/array/find-last-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAmB,EACnB,SAAoE;IAEpE,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACvD,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC"}

package/dist/arkhe/array/find-last.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Iterates over elements from right to left, returning the first element predicate returns truthy for.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to inspect.
+ * @param predicate - The function invoked per iteration.
+ * @returns The matched element, or `undefined` if not found.
+ * @since 2.0.0
+ *
+ * @note This is a polyfill for Array.prototype.findLast (ES2023).
+ *
+ * @performance O(n) time, stops at first match from the end.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { user: 'barney', active: true },
+ *   { user: 'fred', active: false },
+ *   { user: 'pebbles', active: true }
+ * ];
+ *
+ * findLast(users, u => u.active);
+ * // => { user: 'pebbles', active: true }
+ *
+ * findLast([1, 2, 3, 4, 5], n => n % 2 === 0);
+ * // => 4
+ * ```
+ */
+export declare function findLast<T>(array: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): T | undefined;
+//# sourceMappingURL=find-last.d.ts.map

package/dist/arkhe/array/find-last.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-last.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/find-last.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,OAAO,GACnE,CAAC,GAAG,SAAS,CAOf"}

package/dist/arkhe/array/find-last.js

@@ -0,0 +1,37 @@
+/**
+ * Iterates over elements from right to left, returning the first element predicate returns truthy for.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to inspect.
+ * @param predicate - The function invoked per iteration.
+ * @returns The matched element, or `undefined` if not found.
+ * @since 2.0.0
+ *
+ * @note This is a polyfill for Array.prototype.findLast (ES2023).
+ *
+ * @performance O(n) time, stops at first match from the end.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { user: 'barney', active: true },
+ *   { user: 'fred', active: false },
+ *   { user: 'pebbles', active: true }
+ * ];
+ *
+ * findLast(users, u => u.active);
+ * // => { user: 'pebbles', active: true }
+ *
+ * findLast([1, 2, 3, 4, 5], n => n % 2 === 0);
+ * // => 4
+ * ```
+ */
+export function findLast(array, predicate) {
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (predicate(array[i], i, array)) {
+            return array[i];
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=find-last.js.map

package/dist/arkhe/array/find-last.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-last.js","sourceRoot":"","sources":["../../../src/arkhe/array/find-last.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAmB,EACnB,SAAoE;IAEpE,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * Groups array elements by a key derived from each element.
+ *
+ * @template T - The type of elements in the array.
+ * @template K - The type of the grouping key.
+ * @param array - The array to group.
+ * @param iteratee - A function that returns the grouping key for each element.
+ * @returns An object with keys mapping to arrays of elements.
+ * @since 2.0.0
+ *
+ * @note Prefer native `Object.groupBy()` when targeting ES2024+.
+ *
+ * @performance O(n) time & space.
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy | Object.groupBy()}
+ *
+ * @example
+ * ```typescript
+ * const byAge = groupBy(
+ *   [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }, { name: 'Bob', age: 25 }],
+ *   (u) => u.age
+ * );
+ * // => { '25': [...], '30': [...] }
+ *
+ * byAge[25];   // => [{ name: 'John', age: 25 }, { name: 'Bob', age: 25 }]
+ * byAge['25']; // => same — object keys are coerced to strings at runtime
+ *
+ * groupBy(['one', 'two', 'three'], (s) => s.length);
+ * // => { '3': ['one', 'two'], '5': ['three'] }
+ * ```
+ */
+export declare function groupBy<T, K extends PropertyKey>(array: readonly T[], iteratee: (value: T) => K): Partial<Record<K, T[]>>;
+//# sourceMappingURL=group-by.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"group-by.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/group-by.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAC9C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CASzB"}

package/dist/arkhe/array/group-by.js

@@ -0,0 +1,40 @@
+/**
+ * Groups array elements by a key derived from each element.
+ *
+ * @template T - The type of elements in the array.
+ * @template K - The type of the grouping key.
+ * @param array - The array to group.
+ * @param iteratee - A function that returns the grouping key for each element.
+ * @returns An object with keys mapping to arrays of elements.
+ * @since 2.0.0
+ *
+ * @note Prefer native `Object.groupBy()` when targeting ES2024+.
+ *
+ * @performance O(n) time & space.
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy | Object.groupBy()}
+ *
+ * @example
+ * ```typescript
+ * const byAge = groupBy(
+ *   [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }, { name: 'Bob', age: 25 }],
+ *   (u) => u.age
+ * );
+ * // => { '25': [...], '30': [...] }
+ *
+ * byAge[25];   // => [{ name: 'John', age: 25 }, { name: 'Bob', age: 25 }]
+ * byAge['25']; // => same — object keys are coerced to strings at runtime
+ *
+ * groupBy(['one', 'two', 'three'], (s) => s.length);
+ * // => { '3': ['one', 'two'], '5': ['three'] }
+ * ```
+ */
+export function groupBy(array, iteratee) {
+    const result = {};
+    for (let i = 0; i < array.length; i++) {
+        const key = iteratee(array[i]);
+        (result[key] ?? (result[key] = [])).push(array[i]);
+    }
+    return result;
+}
+//# sourceMappingURL=group-by.js.map

package/dist/arkhe/array/group-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by.js","sourceRoot":"","sources":["../../../src/arkhe/array/group-by.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,OAAO,CACrB,KAAmB,EACnB,QAAyB;IAEzB,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC,MAAM,CAAC,GAAG,MAAV,MAAM,CAAC,GAAG,IAAM,EAAE,EAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/arkhe/array/group-with.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Groups adjacent elements that satisfy a predicate function.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The input array to group.
+ * @param predicate - A function that returns true if two adjacent elements should be grouped.
+ * @returns An array of arrays, where each inner array contains consecutive elements that satisfy the predicate.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space, single pass with early returns for empty/single-element arrays.
+ *
+ * @example
+ * ```typescript
+ * groupWith([0, 1, 2, 4, 5], (a, b) => a + 1 === b);
+ * // => [[0, 1, 2], [4, 5]]
+ *
+ * groupWith(['a', 'a', 'b', 'c', 'c'], (a, b) => a === b);
+ * // => [['a', 'a'], ['b'], ['c', 'c']]
+ *
+ * groupWith([20, 21, 22, 15, 16], (a, b) => Math.abs(a - b) <= 2);
+ * // => [[20, 21, 22], [15, 16]]
+ * ```
+ */
+export declare function groupWith<T>(array: readonly T[], predicate: (a: T, b: T) => boolean): T[][];
+//# sourceMappingURL=group-with.d.ts.map

package/dist/arkhe/array/group-with.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-with.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/group-with.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GACjC,CAAC,EAAE,EAAE,CAoBP"}

package/dist/arkhe/array/group-with.js

@@ -0,0 +1,44 @@
+/**
+ * Groups adjacent elements that satisfy a predicate function.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The input array to group.
+ * @param predicate - A function that returns true if two adjacent elements should be grouped.
+ * @returns An array of arrays, where each inner array contains consecutive elements that satisfy the predicate.
+ * @since 2.0.0
+ *
+ * @performance O(n) time & space, single pass with early returns for empty/single-element arrays.
+ *
+ * @example
+ * ```typescript
+ * groupWith([0, 1, 2, 4, 5], (a, b) => a + 1 === b);
+ * // => [[0, 1, 2], [4, 5]]
+ *
+ * groupWith(['a', 'a', 'b', 'c', 'c'], (a, b) => a === b);
+ * // => [['a', 'a'], ['b'], ['c', 'c']]
+ *
+ * groupWith([20, 21, 22, 15, 16], (a, b) => Math.abs(a - b) <= 2);
+ * // => [[20, 21, 22], [15, 16]]
+ * ```
+ */
+export function groupWith(array, predicate) {
+    if (array.length === 0)
+        return [];
+    // Stryker disable next-line ConditionalExpression: equivalent mutant, loop naturally handles length=1
+    if (array.length === 1)
+        return [[array[0]]];
+    const result = [];
+    let currentGroup = [array[0]];
+    for (let i = 1; i < array.length; i++) {
+        if (predicate(array[i - 1], array[i])) {
+            currentGroup.push(array[i]);
+        }
+        else {
+            result.push(currentGroup);
+            currentGroup = [array[i]];
+        }
+    }
+    result.push(currentGroup);
+    return result;
+}
+//# sourceMappingURL=group-with.js.map

package/dist/arkhe/array/group-with.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-with.js","sourceRoot":"","sources":["../../../src/arkhe/array/group-with.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CACvB,KAAmB,EACnB,SAAkC;IAElC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,sGAAsG;IACtG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAU,EAAE,CAAC;IACzB,IAAI,YAAY,GAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC1B,YAAY,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAE1B,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,25 @@
+/**
+ * Creates an array of unique values present in all arrays, using an iteratee for comparison.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param arrays - An array of arrays to inspect.
+ * @param iteratee - A function that returns the comparison value for each element.
+ * @returns A new array containing elements present in all input arrays.
+ * @since 2.0.0
+ *
+ * @performance O(n × m) — builds Sets directly (no intermediate arrays), uses delete for dedup.
+ *
+ * @example
+ * ```typescript
+ * intersectionBy(
+ *   [[{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }]],
+ *   (item) => item.id
+ * );
+ * // => [{ id: 2 }]
+ *
+ * intersectionBy([[1.2, 2.4], [2.5, 3.1]], Math.floor);
+ * // => [2.4]
+ * ```
+ */
+export declare function intersectionBy<T>(arrays: readonly (readonly T[])[], iteratee: (item: T) => unknown): T[];
+//# sourceMappingURL=intersection-by.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intersection-by.d.ts","sourceRoot":"","sources":["../../../src/arkhe/array/intersection-by.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAC7B,CAAC,EAAE,CA2DL"}

package/dist/arkhe/array/intersection-by.js

@@ -0,0 +1,78 @@
+/**
+ * Creates an array of unique values present in all arrays, using an iteratee for comparison.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param arrays - An array of arrays to inspect.
+ * @param iteratee - A function that returns the comparison value for each element.
+ * @returns A new array containing elements present in all input arrays.
+ * @since 2.0.0
+ *
+ * @performance O(n × m) — builds Sets directly (no intermediate arrays), uses delete for dedup.
+ *
+ * @example
+ * ```typescript
+ * intersectionBy(
+ *   [[{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }]],
+ *   (item) => item.id
+ * );
+ * // => [{ id: 2 }]
+ *
+ * intersectionBy([[1.2, 2.4], [2.5, 3.1]], Math.floor);
+ * // => [2.4]
+ * ```
+ */
+export function intersectionBy(arrays, iteratee) {
+    const arrCount = arrays.length;
+    if (arrCount === 0)
+        return [];
+    const first = arrays[0];
+    const fLen = first.length;
+    // Stryker disable next-line ConditionalExpression,EqualityOperator: Early return optimization — main loop produces identical empty result when fLen === 0
+    if (fLen === 0)
+        return [];
+    // Build Sets directly without intermediate .map() arrays
+    const sets = [];
+    for (let a = 1; a < arrCount; a++) {
+        const arr = arrays[a];
+        const s = new Set();
+        for (let j = 0; j < arr.length; j++) {
+            s.add(iteratee(arr[j]));
+        }
+        sets.push(s);
+    }
+    const setCount = sets.length;
+    // Single array: return deduplicated version
+    if (setCount === 0) {
+        const seen = new Set();
+        const result = [];
+        for (let i = 0; i < fLen; i++) {
+            const value = iteratee(first[i]);
+            if (!seen.has(value)) {
+                seen.add(value);
+                result.push(first[i]);
+            }
+        }
+        return result;
+    }
+    const result = [];
+    const firstSet = sets[0];
+    for (let i = 0; i < fLen; i++) {
+        const item = first[i];
+        const value = iteratee(item);
+        if (!firstSet.has(value))
+            continue;
+        let inAll = true;
+        for (let s = 1; s < setCount; s++) {
+            if (!sets[s].has(value)) {
+                inAll = false;
+                break;
+            }
+        }
+        if (inAll) {
+            firstSet.delete(value);
+            result.push(item);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=intersection-by.js.map

package/dist/arkhe/array/intersection-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersection-by.js","sourceRoot":"","sources":["../../../src/arkhe/array/intersection-by.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAiC,EACjC,QAA8B;IAE9B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,0JAA0J;IAC1J,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1B,yDAAyD;IACzD,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,IAAI,GAAG,EAAW,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IAE7B,4CAA4C;IAC5C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;QAChC,MAAM,MAAM,GAAQ,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAChB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAEnC,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,KAAK,GAAG,KAAK,CAAC;gBACd,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}