Merge pull request #1 from jhonsnow456/feat/collections

feat(collections): add groupBy, shuffle, range, difference, flatten, countBy

Author: hey-amanthakur

collections/count_by.ts

@@ -0,0 +1,44 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Counts the occurrences of each key returned by the given function.
+ *
+ * @typeParam T The type of the array elements
+ * @typeParam K The type of the keys
+ *
+ * @param array The array to count
+ * @param keyFn The function that returns the key for each element
+ *
+ * @returns An object mapping keys to their counts
+ *
+ * @example Basic usage
+ * ```ts
+ * import { countBy } from "@std/collections/count-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const pets = [
+ *   { type: "dog", name: "Fido" },
+ *   { type: "cat", name: "Whiskers" },
+ *   { type: "dog", name: "Rover" },
+ * ];
+ *
+ * const counts = countBy(pets, (pet) => pet.type);
+ * assertEquals(counts, { dog: 2, cat: 1 });
+ * ```
+ */
+export function countBy<T, K extends PropertyKey>(
+  array: readonly T[],
+  keyFn: (element: T) => K,
+): Record<K, number> {
+  const result = {} as Record<K, number>;
+  for (const element of array) {
+    const key = keyFn(element);
+    if (Object.prototype.hasOwnProperty.call(result, key)) {
+      result[key]!++;
+    } else {
+      result[key] = 1;
+    }
+  }
+  return result;
+}

collections/count_by_test.ts

@@ -0,0 +1,32 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+import { assertEquals } from "@std/assert";
+import { countBy } from "./count_by.ts";
+
+Deno.test({
+  name: "countBy() counts elements by key",
+  fn() {
+    const pets = [
+      { type: "dog", name: "Fido" },
+      { type: "cat", name: "Whiskers" },
+      { type: "dog", name: "Rover" },
+    ];
+    assertEquals(countBy(pets, (pet) => pet.type), { dog: 2, cat: 1 });
+  },
+});
+
+Deno.test({
+  name: "countBy() handles empty array",
+  fn() {
+    assertEquals(countBy([], (x: number) => x % 2), {});
+  },
+});
+
+Deno.test({
+  name: "countBy() counts numbers by parity",
+  fn() {
+    assertEquals(
+      countBy([1, 2, 3, 4, 5, 6], (n) => n % 2 === 0 ? "even" : "odd"),
+      { odd: 3, even: 3 },
+    );
+  },
+});

collections/deno.json

@@ -7,7 +7,9 @@
     "./associate-by": "./associate_by.ts",
     "./associate-with": "./associate_with.ts",
     "./chunk": "./chunk.ts",
+    "./count-by": "./count_by.ts",
     "./deep-merge": "./deep_merge.ts",
+    "./difference": "./difference.ts",
     "./distinct": "./distinct.ts",
     "./distinct-by": "./distinct_by.ts",
     "./drop-last-while": "./drop_last_while.ts",
@@ -16,6 +18,8 @@
     "./filter-keys": "./filter_keys.ts",
     "./filter-values": "./filter_values.ts",
     "./find-single": "./find_single.ts",
+    "./flatten": "./flatten.ts",
+    "./group-by": "./group_by.ts",
     "./first-not-nullish-of": "./first_not_nullish_of.ts",
     "./includes-value": "./includes_value.ts",
     "./interleave": "./interleave.ts",
@@ -38,9 +42,11 @@
     "./partition-entries": "./partition_entries.ts",
     "./permutations": "./permutations.ts",
     "./pick": "./pick.ts",
+    "./range": "./range.ts",
     "./reduce-groups": "./reduce_groups.ts",
     "./running-reduce": "./running_reduce.ts",
     "./sample": "./sample.ts",
+    "./shuffle": "./shuffle.ts",
     "./sliding-windows": "./sliding_windows.ts",
     "./sort-by": "./sort_by.ts",
     "./sum-of": "./sum_of.ts",

collections/difference.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Returns an array of elements that are in the first array but not in the
+ * second.
+ *
+ * @typeParam T The type of the array elements
+ *
+ * @param a The array to check for elements
+ * @param b The array whose elements should be excluded
+ *
+ * @returns A new array with elements from `a` not in `b`
+ *
+ * @example Basic usage
+ * ```ts
+ * import { difference } from "@std/collections/difference";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = [1, 2, 3, 4];
+ * const b = [2, 4];
+ *
+ * assertEquals(difference(a, b), [1, 3]);
+ * ```
+ */
+export function difference<T>(a: readonly T[], b: readonly T[]): T[] {
+  const exclude = new Set(b);
+  return a.filter((item) => !exclude.has(item));
+}

collections/difference_test.ts

@@ -0,0 +1,39 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+import { assertEquals } from "@std/assert";
+import { difference } from "./difference.ts";
+
+Deno.test({
+  name: "difference() returns elements in a not in b",
+  fn() {
+    assertEquals(difference([1, 2, 3, 4], [2, 4]), [1, 3]);
+  },
+});
+
+Deno.test({
+  name: "difference() returns empty array when all elements are excluded",
+  fn() {
+    assertEquals(difference([1, 2], [1, 2]), []);
+  },
+});
+
+Deno.test({
+  name: "difference() returns all elements when no overlap",
+  fn() {
+    assertEquals(difference([1, 2], [3, 4]), [1, 2]);
+  },
+});
+
+Deno.test({
+  name: "difference() handles empty arrays",
+  fn() {
+    assertEquals(difference([], [1, 2]), []);
+    assertEquals(difference([1, 2], []), [1, 2]);
+  },
+});
+
+Deno.test({
+  name: "difference() handles duplicates in input",
+  fn() {
+    assertEquals(difference([1, 1, 2, 2, 3], [2]), [1, 1, 3]);
+  },
+});

collections/flatten.ts

@@ -0,0 +1,30 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Flattens an array of arrays into a single array (one level deep).
+ *
+ * @typeParam T The type of the inner array elements
+ *
+ * @param array The array of arrays to flatten
+ *
+ * @returns A new flattened array
+ *
+ * @example Basic usage
+ * ```ts
+ * import { flatten } from "@std/collections/flatten";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const nested = [[1, 2], [3, 4], [5]];
+ * assertEquals(flatten(nested), [1, 2, 3, 4, 5]);
+ * ```
+ */
+export function flatten<T>(array: readonly (readonly T[])[]): T[] {
+  const result: T[] = [];
+  for (const inner of array) {
+    for (const element of inner) {
+      result.push(element);
+    }
+  }
+  return result;
+}

collections/flatten_test.ts

@@ -0,0 +1,35 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+import { assertEquals } from "@std/assert";
+import { flatten } from "./flatten.ts";
+
+Deno.test({
+  name: "flatten() flattens nested arrays one level",
+  fn() {
+    assertEquals(
+      flatten([[1, 2], [3, 4], [5]]),
+      [1, 2, 3, 4, 5],
+    );
+  },
+});
+
+Deno.test({
+  name: "flatten() handles empty subarrays",
+  fn() {
+    assertEquals(flatten([[1], [], [2]]), [1, 2]);
+  },
+});
+
+Deno.test({
+  name: "flatten() handles empty outer array",
+  fn() {
+    assertEquals(flatten([]), []);
+  },
+});
+
+Deno.test({
+  name: "flatten() does not deep flatten",
+  fn() {
+    const result = flatten([[[1]], [[2]]]);
+    assertEquals(result, [[1], [2]]);
+  },
+});

collections/group_by.ts

@@ -0,0 +1,47 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Groups elements of an array by a key returned by the given function.
+ *
+ * @typeParam T The type of the array elements
+ * @typeParam K The type of the group keys
+ *
+ * @param array The array to group
+ * @param keyFn The function that returns the key for each element
+ *
+ * @returns An object mapping keys to arrays of elements
+ *
+ * @example Basic usage
+ * ```ts
+ * import { groupBy } from "@std/collections/group-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const pets = [
+ *   { type: "dog", name: "Fido" },
+ *   { type: "cat", name: "Whiskers" },
+ *   { type: "dog", name: "Rover" },
+ * ];
+ *
+ * const grouped = groupBy(pets, (pet) => pet.type);
+ * assertEquals(grouped, {
+ *   dog: [{ type: "dog", name: "Fido" }, { type: "dog", name: "Rover" }],
+ *   cat: [{ type: "cat", name: "Whiskers" }],
+ * });
+ * ```
+ */
+export function groupBy<T, K extends PropertyKey>(
+  array: readonly T[],
+  keyFn: (element: T) => K,
+): Record<K, T[]> {
+  const result = {} as Record<K, T[]>;
+  for (const element of array) {
+    const key = keyFn(element);
+    if (Object.prototype.hasOwnProperty.call(result, key)) {
+      result[key]!.push(element);
+    } else {
+      result[key] = [element];
+    }
+  }
+  return result;
+}

collections/group_by_test.ts

@@ -0,0 +1,37 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+import { assertEquals } from "@std/assert";
+import { groupBy } from "./group_by.ts";
+
+Deno.test({
+  name: "groupBy() groups elements by key function",
+  fn() {
+    const pets = [
+      { type: "dog", name: "Fido" },
+      { type: "cat", name: "Whiskers" },
+      { type: "dog", name: "Rover" },
+    ];
+    const grouped = groupBy(pets, (pet) => pet.type);
+    assertEquals(grouped, {
+      dog: [
+        { type: "dog", name: "Fido" },
+        { type: "dog", name: "Rover" },
+      ],
+      cat: [{ type: "cat", name: "Whiskers" }],
+    });
+  },
+});
+
+Deno.test({
+  name: "groupBy() handles empty array",
+  fn() {
+    assertEquals(groupBy([], (x: number) => x % 2), {});
+  },
+});
+
+Deno.test({
+  name: "groupBy() groups numbers by parity",
+  fn() {
+    const result = groupBy([1, 2, 3, 4, 5, 6], (n) => n % 2 === 0 ? "even" : "odd");
+    assertEquals(result, { odd: [1, 3, 5], even: [2, 4, 6] });
+  },
+});

collections/mod.ts

@@ -32,16 +32,20 @@ export * from "./aggregate_groups.ts";
 export * from "./associate_by.ts";
 export * from "./associate_with.ts";
 export * from "./chunk.ts";
+export * from "./count_by.ts";
 export * from "./deep_merge.ts";
+export * from "./difference.ts";
 export * from "./distinct.ts";
 export * from "./distinct_by.ts";
 export * from "./drop_last_while.ts";
 export * from "./drop_while.ts";
 export * from "./filter_entries.ts";
 export * from "./filter_keys.ts";
 export * from "./filter_values.ts";
+export * from "./flatten.ts";
 export * from "./find_single.ts";
 export * from "./first_not_nullish_of.ts";
+export * from "./group_by.ts";
 export * from "./includes_value.ts";
 export * from "./interleave.ts";
 export * from "./intersect.ts";
@@ -63,9 +67,11 @@ export * from "./partition.ts";
 export * from "./partition_entries.ts";
 export * from "./permutations.ts";
 export * from "./pick.ts";
+export * from "./range.ts";
 export * from "./reduce_groups.ts";
 export * from "./running_reduce.ts";
 export * from "./sample.ts";
+export * from "./shuffle.ts";
 export * from "./sliding_windows.ts";
 export * from "./sort_by.ts";
 export * from "./sum_of.ts";