ts-data-forge 3.3.0 → 4.0.0

package/dist/array/impl/array-utils-transformation.d.mts

@@ -0,0 +1,348 @@
+import { IMap } from '../../collections/index.mjs';
+/**
+ * Creates a new array by transforming each element with a mapping function.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [1, 2, 3] as const;
+ *
+ * const doubled = Arr.map(numbers, (value) => value * 2);
+ * const indexed = Arr.map<number, string>((value, index) => `${index}:${value}`)(
+ *   numbers,
+ * );
+ *
+ * assert.deepStrictEqual(doubled, [2, 4, 6]);
+ * assert.deepStrictEqual(indexed, ['0:1', '1:2', '2:3']);
+ * ```
+ */
+export declare function map<const Ar extends readonly unknown[], B>(array: Ar, mapFn: (a: Ar[number], index: ArrayIndex<Ar>) => B): Readonly<{
+    [K in keyof Ar]: B;
+}>;
+export declare function map<A, B>(mapFn: (a: A, index: SizeType.Arr) => B): <const Ar extends readonly A[]>(array: Ar) => Readonly<{
+    [K in keyof Ar]: B;
+}>;
+/**
+ * Returns an array of successively reduced values from an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const changes = [5, -2, 3] as const;
+ *
+ * const runningTotals = Arr.scan(changes, (total, change) => total + change, 0);
+ * const runningTotalsFromCurried = Arr.scan(
+ *   (total: number, change: number) => total + change,
+ *   10,
+ * )([-5, 15]);
+ *
+ * const expectedTotals = [0, 5, 3, 6] as const;
+ * const expectedCurriedTotals = [10, 5, 20] as const;
+ *
+ * assert.deepStrictEqual(runningTotals, expectedTotals);
+ * assert.deepStrictEqual(runningTotalsFromCurried, expectedCurriedTotals);
+ * ```
+ */
+export declare function scan<const Ar extends readonly unknown[], S>(array: Ar, reducer: (accumulator: S, currentValue: Ar[number], currentIndex: ArrayIndex<Ar>) => S, init: S): NonEmptyArray<S>;
+export declare function scan<E, S>(reducer: (accumulator: S, currentValue: E, currentIndex: SizeType.Arr) => S, init: S): (array: readonly E[]) => NonEmptyArray<S>;
+/**
+ * Reverses an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const tuple = [1, 'two', true] as const;
+ *
+ * const reversed = Arr.toReversed(tuple);
+ *
+ * const expected = [true, 'two', 1] as const;
+ *
+ * assert.deepStrictEqual(reversed, expected);
+ * ```
+ */
+export declare const toReversed: <const Ar extends readonly unknown[]>(array: Ar) => List.Reverse<Ar>;
+/**
+ * Sorts an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [3, 1, 2] as const;
+ * const words = ['banana', 'apple', 'cherry'] as const;
+ *
+ * const ascendingNumbers = Arr.toSorted(numbers);
+ * const alphabetical = Arr.toSorted(words, (left, right) =>
+ *   left.localeCompare(right),
+ * );
+ *
+ * const expectedNumbers = [1, 2, 3] as const;
+ * const expectedWords = ['apple', 'banana', 'cherry'] as const;
+ *
+ * assert.deepStrictEqual(ascendingNumbers, expectedNumbers);
+ * assert.deepStrictEqual(alphabetical, expectedWords);
+ * ```
+ */
+export declare const toSorted: <const Ar extends readonly unknown[]>(...[array, comparator]: Ar extends readonly number[] ? readonly [array: Ar, comparator?: (x: Ar[number], y: Ar[number]) => number] : readonly [array: Ar, comparator: (x: Ar[number], y: Ar[number]) => number]) => IsFixedLengthList<Ar> extends true ? ArrayOfLength<Ar["length"], Ar[number]> : Ar extends NonEmptyArray<unknown> ? NonEmptyArray<Ar[number]> : readonly Ar[number][];
+/**
+ * Sorts an array by a mapped value.
+ *
+ * @example
+ *
+ * ```ts
+ * const projects = [
+ *   { name: 'compiler', issues: 7 },
+ *   { name: 'docs', issues: 2 },
+ *   { name: 'ui', issues: 5 },
+ * ] as const;
+ *
+ * const byIssueCount = Arr.toSortedBy(projects, (project) => project.issues);
+ * const byIssueCountDescending = Arr.toSortedBy(
+ *   projects,
+ *   (project) => project.issues,
+ *   (left, right) => right - left,
+ * );
+ *
+ * const expectedByIssues = [
+ *   { name: 'docs', issues: 2 },
+ *   { name: 'ui', issues: 5 },
+ *   { name: 'compiler', issues: 7 },
+ * ] as const;
+ *
+ * const expectedByIssueCountDescending = [
+ *   { name: 'compiler', issues: 7 },
+ *   { name: 'ui', issues: 5 },
+ *   { name: 'docs', issues: 2 },
+ * ] as const;
+ *
+ * assert.deepStrictEqual(byIssueCount, expectedByIssues);
+ * assert.deepStrictEqual(byIssueCountDescending, expectedByIssueCountDescending);
+ * ```
+ */
+export declare function toSortedBy<const Ar extends readonly unknown[]>(array: Ar, comparatorValueMapper: (value: Ar[number]) => number, comparator?: (x: number, y: number) => number): IsFixedLengthList<Ar> extends true ? ArrayOfLength<Ar['length'], Ar[number]> : Ar extends NonEmptyArray<unknown> ? NonEmptyArray<Ar[number]> : readonly Ar[number][];
+export declare function toSortedBy<const Ar extends readonly unknown[], const V>(array: Ar, comparatorValueMapper: (value: Ar[number]) => V, comparator: (x: V, y: V) => number): IsFixedLengthList<Ar> extends true ? ArrayOfLength<Ar['length'], Ar[number]> : Ar extends NonEmptyArray<unknown> ? NonEmptyArray<Ar[number]> : readonly Ar[number][];
+/**
+ * Filters an array based on a predicate function.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [1, 2, 3, 4] as const;
+ *
+ * const evens = Arr.filter(numbers, (value) => value % 2 === 0);
+ * const greaterThanTwo = Arr.filter<number>((value) => value > 2)(numbers);
+ *
+ * assert.deepStrictEqual(evens, [2, 4]);
+ * assert.deepStrictEqual(greaterThanTwo, [3, 4]);
+ * ```
+ */
+export declare function filter<const Ar extends readonly unknown[], S extends Ar[number]>(array: Ar, predicate: (a: Ar[number], index: ArrayIndex<Ar>) => a is S): readonly S[];
+export declare function filter<E, S extends E>(predicate: (a: E, index: SizeType.Arr) => a is S): (array: readonly E[]) => readonly S[];
+export declare function filter<const Ar extends readonly unknown[]>(array: Ar, predicate: (a: Ar[number], index: ArrayIndex<Ar>) => boolean): readonly Ar[number][];
+export declare function filter<E>(predicate: (a: E, index: SizeType.Arr) => boolean): (array: readonly E[]) => readonly E[];
+/**
+ * Filters an array by excluding elements for which the predicate returns true.
+ *
+ * @example
+ *
+ * ```ts
+ * const names = ['Ada', 'Grace', 'Linus'] as const;
+ *
+ * const notAda = Arr.filterNot(names, (name) => name === 'Ada');
+ * const notShort = Arr.filterNot<string>((name) => name.length <= 4)(names);
+ *
+ * assert.deepStrictEqual(notAda, ['Grace', 'Linus']);
+ * assert.deepStrictEqual(notShort, ['Grace', 'Linus']);
+ * ```
+ */
+export declare function filterNot<const Ar extends readonly unknown[]>(array: Ar, predicate: (a: Ar[number], index: ArrayIndex<Ar>) => boolean): readonly Ar[number][];
+export declare function filterNot<E>(predicate: (a: E, index: SizeType.Arr) => boolean): (array: readonly E[]) => readonly E[];
+/**
+ * Creates a new array with unique elements.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters = ['a', 'b', 'a', 'c', 'b'] as const;
+ *
+ * const uniqueLetters = Arr.uniq(letters);
+ *
+ * const expected = ['a', 'b', 'c'] as const;
+ *
+ * assert.deepStrictEqual(uniqueLetters, expected);
+ * ```
+ */
+export declare const uniq: <const Ar extends readonly Primitive[]>(array: Ar) => Ar extends NonEmptyArray<unknown> ? NonEmptyArray<Ar[number]> : readonly Ar[number][];
+/**
+ * Creates a new array with unique elements based on a mapped value.
+ *
+ * @example
+ *
+ * ```ts
+ * const people = [
+ *   { id: 1, name: 'Ada' },
+ *   { id: 2, name: 'Brian' },
+ *   { id: 1, name: 'Alan' },
+ *   { id: 3, name: 'Grace' },
+ * ] as const;
+ *
+ * const uniqueById = Arr.uniqBy(people, (person) => person.id);
+ *
+ * const expected = [
+ *   { id: 1, name: 'Ada' },
+ *   { id: 2, name: 'Brian' },
+ *   { id: 3, name: 'Grace' },
+ * ] as const;
+ *
+ * assert.deepStrictEqual(uniqueById, expected);
+ * ```
+ */
+export declare const uniqBy: <const Ar extends readonly unknown[], P extends Primitive>(array: Ar, mapFn: (value: Ar[number]) => P) => Ar extends NonEmptyArray<unknown> ? NonEmptyArray<Ar[number]> : readonly Ar[number][];
+/**
+ * Flattens nested arrays up to the specified depth.
+ *
+ * @example
+ *
+ * ```ts
+ * const nested = [
+ *   [1, 2],
+ *   [3, 4],
+ * ] as const;
+ *
+ * const flatOnce = Arr.flat(nested, 1);
+ * const flatCurried = Arr.flat()(nested);
+ *
+ * assert.deepStrictEqual(flatOnce, [1, 2, 3, 4]);
+ * assert.deepStrictEqual(flatCurried, [1, 2, 3, 4]);
+ * ```
+ */
+export declare function flat<const Ar extends readonly unknown[], D extends SafeUintWithSmallInt = 1>(array: Ar, depth?: D): readonly FlatArray<Ar, D>[];
+export declare function flat<D extends SafeUintWithSmallInt = 1>(depth?: number): <const Ar extends readonly unknown[]>(array: Ar) => readonly FlatArray<Ar, D>[];
+/**
+ * Maps each element and flattens the result.
+ *
+ * @example
+ *
+ * ```ts
+ * const words = ['Ada', 'AI'] as const;
+ *
+ * const characters = Arr.flatMap(words, (word) => word.split(''));
+ * const labeled = Arr.flatMap<string, string>((word, index) =>
+ *   word.split('').map((char) => `${index}-${char}`),
+ * )(words);
+ *
+ * assert.deepStrictEqual(characters, ['A', 'd', 'a', 'A', 'I']);
+ * assert.deepStrictEqual(labeled, ['0-A', '0-d', '0-a', '1-A', '1-I']);
+ * ```
+ */
+export declare function flatMap<const Ar extends readonly unknown[], B>(array: Ar, mapFn: (a: Ar[number], index: ArrayIndex<Ar>) => readonly B[]): readonly B[];
+export declare function flatMap<A, B>(mapFn: (a: A, index: SizeType.Arr) => readonly B[]): (array: readonly A[]) => readonly B[];
+/**
+ * Partitions an array into sub-arrays of a specified size.
+ *
+ * @example
+ *
+ * ```ts
+ * const values = [1, 2, 3, 4, 5] as const;
+ *
+ * const pairs = Arr.partition(values, 2);
+ * const triples = Arr.partition(3)(values);
+ *
+ * const expectedPairs = [[1, 2], [3, 4], [5]] as const;
+ *
+ * assert.deepStrictEqual(pairs, expectedPairs);
+ * assert.deepStrictEqual(triples, [
+ *   [1, 2, 3],
+ *   [4, 5],
+ * ]);
+ *
+ * const pairs2 = Arr.chunk([1, 2, 3, 4, 5, 6], 2);
+ *
+ * assert.deepStrictEqual(pairs2, [
+ *   [1, 2],
+ *   [3, 4],
+ *   [5, 6],
+ * ]);
+ * ```
+ */
+export declare function partition<N extends WithSmallInt<PositiveInt & SizeType.Arr>, E>(array: readonly E[], chunkSize: N): readonly (readonly E[])[];
+export declare function partition<N extends WithSmallInt<PositiveInt & SizeType.Arr>>(chunkSize: N): <E>(array: readonly E[]) => readonly (readonly E[])[];
+/**
+ * Concatenates two arrays.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [1, 2] as const;
+ * const words = ['three', 'four'] as const;
+ *
+ * const combined = Arr.concat(numbers, words);
+ *
+ * const expectedCombined = [1, 2, 'three', 'four'] as const;
+ *
+ * assert.deepStrictEqual(combined, expectedCombined);
+ * ```
+ */
+export declare const concat: <const Ar1 extends readonly unknown[], const Ar2 extends readonly unknown[]>(array1: Ar1, array2: Ar2) => readonly [...Ar1, ...Ar2];
+/**
+ * Groups elements by a key derived from each element.
+ *
+ * @example
+ *
+ * ```ts
+ * const animals = ['ant', 'bat', 'cat', 'dove'] as const;
+ *
+ * const groupedByLength = Arr.groupBy(animals, (animal) => animal.length);
+ * const groupedByFirstLetter = Arr.groupBy((animal: string) => animal[0])(
+ *   animals,
+ * );
+ *
+ * assert.deepStrictEqual(
+ *   groupedByLength.get(3),
+ *   Optional.some(['ant', 'bat', 'cat'] as const),
+ * );
+ * assert.deepStrictEqual(
+ *   groupedByLength.get(4),
+ *   Optional.some(['dove'] as const),
+ * );
+ * assert.deepStrictEqual(groupedByLength.get(5), Optional.none);
+ *
+ * assert.deepStrictEqual(
+ *   groupedByFirstLetter.get('a'),
+ *   Optional.some(['ant'] as const),
+ * );
+ * assert.deepStrictEqual(
+ *   groupedByFirstLetter.get('d'),
+ *   Optional.some(['dove'] as const),
+ * );
+ * ```
+ */
+export declare function groupBy<const Ar extends readonly unknown[], G extends MapSetKeyType>(array: Ar, grouper: (value: Ar[number], index: ArrayIndex<Ar>) => G): IMap<G, readonly Ar[number][]>;
+export declare function groupBy<E, G extends MapSetKeyType>(grouper: (value: E, index: SizeType.Arr) => G): (array: readonly E[]) => IMap<G, readonly E[]>;
+/**
+ * Creates an array of tuples by pairing corresponding elements from two arrays.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters = ['a', 'b', 'c'] as const;
+ * const numbers = [1, 2, 3] as const;
+ *
+ * const pairs = Arr.zip(letters, numbers);
+ *
+ * const expectedPairs = [
+ *   ['a', 1],
+ *   ['b', 2],
+ *   ['c', 3],
+ * ] as const;
+ *
+ * assert.deepStrictEqual(pairs, expectedPairs);
+ * ```
+ */
+export declare const zip: <const Ar1 extends readonly unknown[], const Ar2 extends readonly unknown[]>(array1: Ar1, array2: Ar2) => List.Zip<Ar1, Ar2>;
+/**
+ * Alias for `partition`.
+ *
+ * @see {@link partition}
+ */
+export declare const chunk: typeof partition;
+//# sourceMappingURL=array-utils-transformation.d.mts.map

package/dist/array/impl/array-utils-transformation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils-transformation.d.mts","sourceRoot":"","sources":["../../../src/array/impl/array-utils-transformation.mts"],"names":[],"mappings":"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"}

package/dist/array/impl/array-utils-transformation.mjs

@@ -0,0 +1,329 @@
+import '../../collections/imap-mapped.mjs';
+import { IMap } from '../../collections/imap.mjs';
+import '../../collections/iset-mapped.mjs';
+import '../../collections/iset.mjs';
+import { castMutable } from '../../others/cast-mutable.mjs';
+import { tp } from '../../others/tuple.mjs';
+import '../../number/branded-types/finite-number.mjs';
+import '../../number/branded-types/int.mjs';
+import '../../number/branded-types/int16.mjs';
+import '../../number/branded-types/int32.mjs';
+import '../../number/branded-types/non-negative-finite-number.mjs';
+import '../../number/branded-types/non-negative-int16.mjs';
+import '../../number/branded-types/non-negative-int32.mjs';
+import '../../number/branded-types/non-zero-finite-number.mjs';
+import '../../number/branded-types/non-zero-int.mjs';
+import '../../number/branded-types/non-zero-int16.mjs';
+import '../../number/branded-types/non-zero-int32.mjs';
+import '../../number/branded-types/non-zero-safe-int.mjs';
+import '../../number/branded-types/non-zero-uint16.mjs';
+import '../../number/branded-types/non-zero-uint32.mjs';
+import '../../number/branded-types/positive-finite-number.mjs';
+import '../../number/branded-types/positive-int.mjs';
+import '../../number/branded-types/positive-int16.mjs';
+import '../../number/branded-types/positive-int32.mjs';
+import '../../number/branded-types/positive-safe-int.mjs';
+import '../../number/branded-types/positive-uint16.mjs';
+import { asPositiveUint32 } from '../../number/branded-types/positive-uint32.mjs';
+import '../../number/branded-types/safe-int.mjs';
+import '../../number/branded-types/safe-uint.mjs';
+import '../../number/branded-types/uint.mjs';
+import '../../number/branded-types/uint16.mjs';
+import { asUint32, Uint32 } from '../../number/branded-types/uint32.mjs';
+import '../../number/enum/int8.mjs';
+import '../../number/enum/uint8.mjs';
+import '../../number/num.mjs';
+import '../../number/refined-number-utils.mjs';
+import { seq, newArray } from './array-utils-creation.mjs';
+import { size } from './array-utils-size.mjs';
+
+function map(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, mapFn] = args;
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            return array.map(mapFn);
+        }
+        case 1: {
+            const [mapFn] = args;
+            return (array) => map(array, mapFn);
+        }
+    }
+}
+function scan(...args) {
+    switch (args.length) {
+        case 3: {
+            const [array, reducer, init] = args;
+            const mut_result = castMutable(newArray(asPositiveUint32(array.length + 1), init));
+            let mut_acc = init;
+            for (const [index, value] of array.entries()) {
+                mut_acc = reducer(mut_acc, value, asUint32(index));
+                mut_result[index + 1] = mut_acc;
+            }
+            return mut_result;
+        }
+        case 2: {
+            const [reducer, init] = args;
+            return (array) => scan(array, reducer, init);
+        }
+    }
+}
+/**
+ * Reverses an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const tuple = [1, 'two', true] as const;
+ *
+ * const reversed = Arr.toReversed(tuple);
+ *
+ * const expected = [true, 'two', 1] as const;
+ *
+ * assert.deepStrictEqual(reversed, expected);
+ * ```
+ */
+const toReversed = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+array.toReversed();
+/**
+ * Sorts an array.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [3, 1, 2] as const;
+ * const words = ['banana', 'apple', 'cherry'] as const;
+ *
+ * const ascendingNumbers = Arr.toSorted(numbers);
+ * const alphabetical = Arr.toSorted(words, (left, right) =>
+ *   left.localeCompare(right),
+ * );
+ *
+ * const expectedNumbers = [1, 2, 3] as const;
+ * const expectedWords = ['apple', 'banana', 'cherry'] as const;
+ *
+ * assert.deepStrictEqual(ascendingNumbers, expectedNumbers);
+ * assert.deepStrictEqual(alphabetical, expectedWords);
+ * ```
+ */
+const toSorted = (...[array, comparator]) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+array.toSorted(
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+comparator ??
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    ((x, y) => x - y));
+function toSortedBy(array, comparatorValueMapper, comparator) {
+    return array.toSorted((x, y) => comparator === undefined
+        ? // This branch assumes V is number if comparator is undefined.
+            // The overloads should handle this, but explicit cast might be needed if V is not number.
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            comparatorValueMapper(x) -
+                // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+                comparatorValueMapper(y)
+        : comparator(comparatorValueMapper(x), comparatorValueMapper(y)));
+}
+function filter(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, predicate] = args;
+            return array.filter((a, i) => predicate(a, asUint32(i)));
+        }
+        case 1: {
+            const [predicate] = args;
+            return (array) => filter(array, predicate);
+        }
+    }
+}
+function filterNot(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, predicate] = args;
+            return array.filter((a, i) => !predicate(a, asUint32(i)));
+        }
+        case 1: {
+            const [predicate] = args;
+            return (array) => filterNot(array, predicate);
+        }
+    }
+}
+/**
+ * Creates a new array with unique elements.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters = ['a', 'b', 'a', 'c', 'b'] as const;
+ *
+ * const uniqueLetters = Arr.uniq(letters);
+ *
+ * const expected = ['a', 'b', 'c'] as const;
+ *
+ * assert.deepStrictEqual(uniqueLetters, expected);
+ * ```
+ */
+const uniq = (array) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Array.from(new Set(array));
+/**
+ * Creates a new array with unique elements based on a mapped value.
+ *
+ * @example
+ *
+ * ```ts
+ * const people = [
+ *   { id: 1, name: 'Ada' },
+ *   { id: 2, name: 'Brian' },
+ *   { id: 1, name: 'Alan' },
+ *   { id: 3, name: 'Grace' },
+ * ] as const;
+ *
+ * const uniqueById = Arr.uniqBy(people, (person) => person.id);
+ *
+ * const expected = [
+ *   { id: 1, name: 'Ada' },
+ *   { id: 2, name: 'Brian' },
+ *   { id: 3, name: 'Grace' },
+ * ] as const;
+ *
+ * assert.deepStrictEqual(uniqueById, expected);
+ * ```
+ */
+const uniqBy = (array, mapFn) => {
+    const mut_mappedValues = new Set();
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return array.filter((val) => {
+        const mappedValue = mapFn(val);
+        if (mut_mappedValues.has(mappedValue))
+            return false;
+        mut_mappedValues.add(mappedValue);
+        return true;
+    });
+};
+function flat(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, depth] = args;
+            return array.flat(depth);
+        }
+        case 1: {
+            const [arrayOrDepth] = args;
+            if (typeof arrayOrDepth === 'number') {
+                const depth = arrayOrDepth;
+                return (array) => flat(array, depth);
+            }
+            else if (arrayOrDepth === undefined) {
+                return (array) => flat(array, 1);
+            }
+            else {
+                return arrayOrDepth.flat();
+            }
+        }
+        case 0:
+            return (array) => flat(array, 1);
+    }
+}
+function flatMap(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, mapFn] = args;
+            return array.flatMap((a, i) => mapFn(a, asUint32(i)));
+        }
+        case 1: {
+            const [mapFn] = args;
+            return (array) => flatMap(array, mapFn);
+        }
+    }
+}
+function partition(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, chunkSize] = args;
+            return chunkSize < 2
+                ? []
+                : // eslint-disable-next-line total-functions/no-partial-division
+                    seq(asUint32(Math.ceil(array.length / chunkSize))).map((i) => array.slice(chunkSize * i, chunkSize * (i + 1)));
+        }
+        case 1: {
+            const [chunkSize] = args;
+            return (array) => partition(array, chunkSize);
+        }
+    }
+}
+/**
+ * Concatenates two arrays.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [1, 2] as const;
+ * const words = ['three', 'four'] as const;
+ *
+ * const combined = Arr.concat(numbers, words);
+ *
+ * const expectedCombined = [1, 2, 'three', 'four'] as const;
+ *
+ * assert.deepStrictEqual(combined, expectedCombined);
+ * ```
+ */
+const concat = (array1, array2) => [...array1, ...array2];
+function groupBy(...args) {
+    switch (args.length) {
+        case 2: {
+            const [array, grouper] = args;
+            const mut_groups = new Map(); // Store mutable arrays internally
+            for (const [index, e] of array.entries()) {
+                const key = grouper(e, asUint32(index)); // Ensure index is treated as SizeType.Arr
+                const mut_group = mut_groups.get(key);
+                if (mut_group !== undefined) {
+                    mut_group.push(e);
+                }
+                else {
+                    mut_groups.set(key, [e]);
+                }
+            }
+            // Cast to IMap<G, readonly A[]> for the public interface
+            return IMap.create(mut_groups);
+        }
+        case 1: {
+            const [grouper] = args;
+            return (array) => groupBy(array, grouper);
+        }
+    }
+}
+/**
+ * Creates an array of tuples by pairing corresponding elements from two arrays.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters = ['a', 'b', 'c'] as const;
+ * const numbers = [1, 2, 3] as const;
+ *
+ * const pairs = Arr.zip(letters, numbers);
+ *
+ * const expectedPairs = [
+ *   ['a', 1],
+ *   ['b', 2],
+ *   ['c', 3],
+ * ] as const;
+ *
+ * assert.deepStrictEqual(pairs, expectedPairs);
+ * ```
+ */
+const zip = (array1, array2) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+seq(Uint32.min(size(array1), size(array2))).map((i) => 
+// Non-null assertion is safe here because `i` is always within bounds of both arrays up to the length of the shorter one.
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+tp(array1[i], array2[i]));
+/**
+ * Alias for `partition`.
+ *
+ * @see {@link partition}
+ */
+const chunk = partition;
+
+export { chunk, concat, filter, filterNot, flat, flatMap, groupBy, map, partition, scan, toReversed, toSorted, toSortedBy, uniq, uniqBy, zip };
+//# sourceMappingURL=array-utils-transformation.mjs.map