diff --git a/collections/max_by.ts b/collections/max_by.ts index 911118e372bc..ccfbe38dcd57 100644 --- a/collections/max_by.ts +++ b/collections/max_by.ts @@ -23,7 +23,81 @@ */ export function maxBy( array: Iterable, - 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( + array: Iterable, + 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( + array: Iterable, + 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( + array: Iterable, + selector: (el: T) => Date, +): T | undefined; +export function maxBy( + array: Iterable, + selector: + | ((el: T) => number) + | ((el: T) => string) + | ((el: T) => bigint) + | ((el: T) => Date), ): T | undefined { let max: T | undefined = undefined; let maxValue: ReturnType | undefined = undefined; diff --git a/collections/max_of.ts b/collections/max_of.ts index 70ddab9c688f..3ce8d1943218 100644 --- a/collections/max_of.ts +++ b/collections/max_of.ts @@ -22,7 +22,36 @@ * assertEquals(maxCount, 32); * ``` */ -export function maxOf number | bigint>( +export function maxOf( + array: Iterable, + 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( + array: Iterable, + selector: (el: T) => bigint, +): bigint | undefined; +export function maxOf number) | ((el: T) => bigint)>( array: Iterable, selector: S, ): ReturnType | undefined { diff --git a/collections/min_by.ts b/collections/min_by.ts index 4d44d6932f12..557839b7dfa3 100644 --- a/collections/min_by.ts +++ b/collections/min_by.ts @@ -23,7 +23,81 @@ */ export function minBy( array: Iterable, - 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( + array: Iterable, + 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( + array: Iterable, + 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( + array: Iterable, + selector: (el: T) => Date, +): T | undefined; +export function minBy( + array: Iterable, + selector: + | ((el: T) => number) + | ((el: T) => string) + | ((el: T) => bigint) + | ((el: T) => Date), ): T | undefined { let min: T | undefined = undefined; let minValue: ReturnType | undefined = undefined; diff --git a/collections/min_of.ts b/collections/min_of.ts index dfde5e850c86..362d091146b8 100644 --- a/collections/min_of.ts +++ b/collections/min_of.ts @@ -21,7 +21,35 @@ * assertEquals(minCount, 2); * ``` */ -export function minOf number | bigint>( +export function minOf( + array: Iterable, + 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( + array: Iterable, + selector: (el: T) => bigint, +): bigint | undefined; +export function minOf number) | ((el: T) => bigint)>( array: Iterable, selector: S, ): ReturnType | undefined { diff --git a/collections/partition.ts b/collections/partition.ts index 7745a150b18a..75c468acdce1 100644 --- a/collections/partition.ts +++ b/collections/partition.ts @@ -21,9 +21,34 @@ export function partition( array: Iterable, 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( + array: Iterable, + predicate: (el: T) => el is U, +): [U[], Exclude[]]; +export function partition( + array: Iterable, + predicate: (el: unknown) => boolean, +): [unknown[], unknown[]] { + const matches: Array = []; + const rest: Array = []; for (const element of array) { if (predicate(element)) { diff --git a/collections/sort_by.ts b/collections/sort_by.ts index 3cc682877f6b..198ede387161 100644 --- a/collections/sort_by.ts +++ b/collections/sort_by.ts @@ -43,7 +43,82 @@ export type SortByOptions = { */ export function sortBy( 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( + 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( + 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( + array: readonly T[], + selector: (el: T) => Date, + options?: SortByOptions, +): T[]; +export function sortBy( + array: readonly T[], + selector: + | ((el: T) => number) + | ((el: T) => string) + | ((el: T) => bigint) + | ((el: T) => Date), options?: SortByOptions, ): T[] { const len = array.length;