docs(collection): document overloads (revert #3818) (#3823)

collections/max_by.ts

@@ -23,7 +23,81 @@
  */
 export function maxBy<T>(
   array: Iterable<T>,
-  selector: (el: T) => number | string | bigint | Date,
+  selector: (el: T) => number,
+): T | undefined;
+/**
+ * Returns the first element that is the largest value of the given function or
+ * undefined if there are no elements.
+ *
+ * @example
+ * ```ts
+ * import { maxBy } from "https://deno.land/std@$STD_VERSION/collections/max_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna" },
+ *   { name: "Kim" },
+ *   { name: "John" },
+ * ];
+ *
+ * const personWithMaxName = maxBy(people, (i) => i.name);
+ * ```
+ */
+export function maxBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => string,
+): T | undefined;
+/**
+ * Returns the first element that is the largest value of the given function or
+ * undefined if there are no elements.
+ *
+ * @example
+ * ```ts
+ * import { maxBy } from "https://deno.land/std@$STD_VERSION/collections/max_by.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34n },
+ *   { name: "Kim", age: 42n },
+ *   { name: "John", age: 23n },
+ * ];
+ *
+ * const personWithMaxAge = maxBy(people, (i) => i.age);
+ *
+ * assertEquals(personWithMaxAge, { name: "Kim", age: 42n });
+ * ```
+ */
+export function maxBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => bigint,
+): T | undefined;
+/**
+ * Returns the first element that is the largest value of the given function or
+ * undefined if there are no elements.
+ *
+ * @example
+ * ```ts
+ * import { maxBy } from "https://deno.land/std@$STD_VERSION/collections/max_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna", startedAt: new Date("2020-01-01") },
+ *   { name: "Kim", startedAt: new Date("2021-03-01") },
+ *   { name: "John", startedAt: new Date("2020-03-01") },
+ * ];
+ *
+ * const personWithLastStartedAt = maxBy(people, (i) => i.startedAt);
+ * ```
+ */
+export function maxBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => Date,
+): T | undefined;
+export function maxBy<T>(
+  array: Iterable<T>,
+  selector:
+    | ((el: T) => number)
+    | ((el: T) => string)
+    | ((el: T) => bigint)
+    | ((el: T) => Date),
 ): T | undefined {
   let max: T | undefined = undefined;
   let maxValue: ReturnType<typeof selector> | undefined = undefined;

collections/max_of.ts

@@ -22,7 +22,36 @@
  * assertEquals(maxCount, 32);
  * ```
  */
-export function maxOf<T, S extends (el: T) => number | bigint>(
+export function maxOf<T>(
+  array: Iterable<T>,
+  selector: (el: T) => number,
+): number | undefined;
+/**
+ * Applies the given selector to all elements of the provided collection and
+ * returns the max value of all elements. If an empty array is provided the
+ * function will return undefined
+ *
+ * @example
+ * ```ts
+ * import { maxOf } from "https://deno.land/std@$STD_VERSION/collections/max_of.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const inventory = [
+ *   { name: "mustard", count: 2n },
+ *   { name: "soy", count: 4n },
+ *   { name: "tomato", count: 32n },
+ * ];
+ *
+ * const maxCount = maxOf(inventory, (i) => i.count);
+ *
+ * assertEquals(maxCount, 32n);
+ * ```
+ */
+export function maxOf<T>(
+  array: Iterable<T>,
+  selector: (el: T) => bigint,
+): bigint | undefined;
+export function maxOf<T, S extends ((el: T) => number) | ((el: T) => bigint)>(
   array: Iterable<T>,
   selector: S,
 ): ReturnType<S> | undefined {

collections/min_by.ts

@@ -23,7 +23,81 @@
  */
 export function minBy<T>(
   array: Iterable<T>,
-  selector: (el: T) => number | string | bigint | Date,
+  selector: (el: T) => number,
+): T | undefined;
+/**
+ * Returns the first element that is the smallest value of the given function or
+ * undefined if there are no elements
+ *
+ * @example
+ * ```ts
+ * import { minBy } from "https://deno.land/std@$STD_VERSION/collections/min_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna" },
+ *   { name: "Kim" },
+ *   { name: "John" },
+ * ];
+ *
+ * const personWithMinName = minBy(people, (i) => i.name);
+ * ```
+ */
+export function minBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => string,
+): T | undefined;
+/**
+ * Returns the first element that is the smallest value of the given function or
+ * undefined if there are no elements
+ *
+ * @example
+ * ```ts
+ * import { minBy } from "https://deno.land/std@$STD_VERSION/collections/min_by.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34n },
+ *   { name: "Kim", age: 42n },
+ *   { name: "John", age: 23n },
+ * ];
+ *
+ * const personWithMinAge = minBy(people, (i) => i.age);
+ *
+ * assertEquals(personWithMinAge, { name: "John", age: 23n });
+ * ```
+ */
+export function minBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => bigint,
+): T | undefined;
+/**
+ * Returns the first element that is the smallest value of the given function or
+ * undefined if there are no elements
+ *
+ * @example
+ * ```ts
+ * import { minBy } from "https://deno.land/std@$STD_VERSION/collections/min_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna", startedAt: new Date("2020-01-01") },
+ *   { name: "Kim", startedAt: new Date("2020-03-01") },
+ *   { name: "John", startedAt: new Date("2019-01-01") },
+ * ];
+ *
+ * const personWithMinStartedAt = minBy(people, (i) => i.startedAt);
+ * ```
+ */
+export function minBy<T>(
+  array: Iterable<T>,
+  selector: (el: T) => Date,
+): T | undefined;
+export function minBy<T>(
+  array: Iterable<T>,
+  selector:
+    | ((el: T) => number)
+    | ((el: T) => string)
+    | ((el: T) => bigint)
+    | ((el: T) => Date),
 ): T | undefined {
   let min: T | undefined = undefined;
   let minValue: ReturnType<typeof selector> | undefined = undefined;

collections/min_of.ts

@@ -21,7 +21,35 @@
  * assertEquals(minCount, 2);
  * ```
  */
-export function minOf<T, S extends (el: T) => number | bigint>(
+export function minOf<T>(
+  array: Iterable<T>,
+  selector: (el: T) => number,
+): number | undefined;
+/**
+ * Applies the given selector to all elements of the given collection and
+ * returns the min value of all elements. If an empty array is provided the
+ * function will return undefined.
+ *
+ * @example
+ * ```ts
+ * import { minOf } from "https://deno.land/std@$STD_VERSION/collections/min_of.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const inventory = [
+ *   { name: "mustard", count: 2n },
+ *   { name: "soy", count: 4n },
+ *   { name: "tomato", count: 32n },
+ * ];
+ * const minCount = minOf(inventory, (i) => i.count);
+ *
+ * assertEquals(minCount, 2n);
+ * ```
+ */
+export function minOf<T>(
+  array: Iterable<T>,
+  selector: (el: T) => bigint,
+): bigint | undefined;
+export function minOf<T, S extends ((el: T) => number) | ((el: T) => bigint)>(
   array: Iterable<T>,
   selector: S,
 ): ReturnType<S> | undefined {

collections/partition.ts

@@ -21,9 +21,34 @@
 export function partition<T>(
   array: Iterable<T>,
   predicate: (el: T) => boolean,
-): [T[], T[]] {
-  const matches = [];
-  const rest = [];
+): [T[], T[]];
+/**
+ * Returns a tuple of two arrays with the first one containing all elements in
+ * the given array that match the given predicate and the second one containing
+ * all that do not.
+ *
+ * @example
+ * ```ts
+ * import { partition } from "https://deno.land/std@$STD_VERSION/collections/partition.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const numbers = [5, 6, 7, 8, 9];
+ * const [even, odd] = partition(numbers, (it) => it % 2 === 0);
+ *
+ * assertEquals(even, [6, 8]);
+ * assertEquals(odd, [5, 7, 9]);
+ * ```
+ */
+export function partition<T, U extends T>(
+  array: Iterable<T>,
+  predicate: (el: T) => el is U,
+): [U[], Exclude<T, U>[]];
+export function partition(
+  array: Iterable<unknown>,
+  predicate: (el: unknown) => boolean,
+): [unknown[], unknown[]] {
+  const matches: Array<unknown> = [];
+  const rest: Array<unknown> = [];
 
   for (const element of array) {
     if (predicate(element)) {

collections/sort_by.ts

@@ -43,7 +43,82 @@ export type SortByOptions = {
  */
 export function sortBy<T>(
   array: readonly T[],
-  selector: (el: T) => number | string | bigint | Date,
+  selector: (el: T) => number,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified.
+ *
+ * @example
+ * ```ts
+ * import { sortBy } from "https://deno.land/std@$STD_VERSION/collections/sort_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna" },
+ *   { name: "Kim" },
+ *   { name: "John" },
+ * ];
+ * const sortedByName = sortBy(people, (it) => it.name);
+ */
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => string,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified.
+ *
+ * @example
+ * ```ts
+ * import { sortBy } from "https://deno.land/std@$STD_VERSION/collections/sort_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34n },
+ *   { name: "Kim", age: 42n },
+ *   { name: "John", age: 23n },
+ * ];
+ * const sortedByAge = sortBy(people, (it) => it.age);
+ * ```
+ */
+
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => bigint,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified.
+ *
+ * @example
+ * ```ts
+ * import { sortBy } from "https://deno.land/std@$STD_VERSION/collections/sort_by.ts";
+ *
+ * const people = [
+ *   { name: "Anna", startedAt: new Date("2020-01-01") },
+ *   { name: "Kim", startedAt: new Date("2020-03-01") },
+ *   { name: "John", startedAt: new Date("2020-06-01") },
+ * ];
+ * const sortedByStartedAt = sortBy(people, (it) => it.startedAt);
+ * ```
+ */
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => Date,
+  options?: SortByOptions,
+): T[];
+export function sortBy<T>(
+  array: readonly T[],
+  selector:
+    | ((el: T) => number)
+    | ((el: T) => string)
+    | ((el: T) => bigint)
+    | ((el: T) => Date),
   options?: SortByOptions,
 ): T[] {
   const len = array.length;