feat(partition): a new function to partition arrays into two buckets

* feat(partition): a new function to partition arrays into two buckets

see: https://lodash.com/docs/4.17.15#partition

* feat(partition): add partition to mapping page

* feat(partition): make the index test actually use the index

* feat(partition): better docs

* Apply suggestions from code review

Co-authored-by: Michal Tecza <zorza2@gmail.com>

Co-authored-by: Michal Tecza <zorza2@gmail.com>

mapping.md

@@ -7,7 +7,7 @@ behave differently from either or both. Be sure to consult each library's
 documentation when migrating._
 
 | Remeda         | Lodash         | Ramda               |
-| -------------- | -------------- | ------------------- |
+|----------------|----------------| ------------------- |
 | `addProp`      | `set`          | `set`               |
 | `allPass`      | `-`            | `allPass`           |
 | `anyPass`      | `-`            | `anyPass`           |
@@ -42,6 +42,7 @@ documentation when migrating._
 | `objOf`        | `-`            | `objOf`             |
 | `omit`         | `omit`         | `omit`              |
 | `once`         | `once`         | `once`              |
+| `partition`    | `partition`    | `partition`         |
 | `pathOr`       | `get`          | `pathOr`            |
 | `pick`         | `pick`         | `pick`              |
 | `pipe`         | `flow`         | `pipe`              |

src/partition.test.ts

@@ -0,0 +1,47 @@
+import { partition } from './partition';
+import { pipe } from './pipe';
+
+const array = [
+  { a: 1, b: 1 },
+  { a: 1, b: 2 },
+  { a: 2, b: 1 },
+  { a: 1, b: 3 },
+] as const;
+const expected = [
+  [
+    { a: 1, b: 1 },
+    { a: 1, b: 2 },
+    { a: 1, b: 3 },
+  ],
+  [{ a: 2, b: 1 }],
+];
+
+describe('data first', () => {
+  test('partition', () => {
+    expect(partition(array, x => x.a === 1)).toEqual(expected);
+  });
+  test('partition.indexed', () => {
+    expect(partition.indexed(array, (_, index) => index !== 2)).toEqual(
+      expected
+    );
+  });
+});
+
+describe('data last', () => {
+  test('partition', () => {
+    expect(
+      pipe(
+        array,
+        partition(x => x.a === 1)
+      )
+    ).toEqual(expected);
+  });
+  test('partition.indexed', () => {
+    expect(
+      pipe(
+        array,
+        partition.indexed((_, index) => index !== 2)
+      )
+    ).toEqual(expected);
+  });
+});

src/partition.ts

@@ -0,0 +1,65 @@
+import { purry } from './purry';
+import { PredIndexedOptional, PredIndexed } from './_types';
+
+/**
+ * Splits a collection into two groups, the first of which contains elements the `predicate` function matches, and the second one containing the rest.
+ * @param items the items to split
+ * @param predicate the function invoked per iteration
+ * @returns the array of grouped elements.
+ * @signature
+ *    R.partition(array, fn)
+ * @example
+ *    R.partition(['one', 'two', 'forty two'], x => x.length === 3) // => [['one', 'two'], ['forty two']]
+ * @data_first
+ * @indexed
+ * @category Array
+ */
+export function partition<T>(
+  items: readonly T[],
+  predicate: (item: T) => boolean
+): [T[], T[]];
+
+/**
+ * Splits a collection into two groups, the first of which contains elements the `predicate` function matches, and the second one containing the rest.
+ * @param predicate the grouping function
+ * @returns the array of grouped elements.
+ * @signature
+ *    R.partition(fn)(array)
+ * @example
+ *    R.pipe(['one', 'two', 'forty two'], R.partition(x => x.length === 3)) // => [['one', 'two'], ['forty two']]
+ * @data_last
+ * @indexed
+ * @category Array
+ */
+export function partition<T>(
+  predicate: (item: T) => boolean
+): (array: readonly T[]) => [T[], T[]];
+
+export function partition() {
+  return purry(_partition(false), arguments);
+}
+
+const _partition = (indexed: boolean) => <T>(
+  array: T[],
+  fn: PredIndexedOptional<T, any>
+) => {
+  const ret: [T[], T[]] = [[], []];
+  array.forEach((item, index) => {
+    const matches = indexed ? fn(item, index, array) : fn(item);
+    ret[matches ? 0 : 1].push(item);
+  });
+  return ret;
+};
+
+export namespace partition {
+  export function indexed<T, K>(
+    array: readonly T[],
+    predicate: PredIndexed<T, boolean>
+  ): [T[], T[]];
+  export function indexed<T, K>(
+    predicate: PredIndexed<T, boolean>
+  ): (array: readonly T[]) => [T[], T[]];
+  export function indexed() {
+    return purry(_partition(true), arguments);
+  }
+}