From 8532be73b96799d85c43c534f71c1b61625e73a4 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Tue, 5 Dec 2023 19:53:55 +1100 Subject: [PATCH] chore(collections): complete documentation (#3896) --- collections/deep_merge.ts | 48 +++++++++++++++++++++++----------- collections/drop_last_while.ts | 2 +- collections/group_by.ts | 4 +-- collections/join_to_string.ts | 4 +-- collections/mod.ts | 25 +++++------------- collections/sample.ts | 2 +- collections/sort_by.ts | 4 +-- collections/union.ts | 2 +- 8 files changed, 47 insertions(+), 44 deletions(-) diff --git a/collections/deep_merge.ts b/collections/deep_merge.ts index a022865cffa7..7b24eb9ac8d6 100644 --- a/collections/deep_merge.ts +++ b/collections/deep_merge.ts @@ -31,7 +31,25 @@ export function deepMerge< other: Partial>, options?: Readonly, ): T; - +/** + * Merges the two given Records, recursively merging any nested Records with the + * second collection overriding the first in case of conflict + * + * For arrays, maps and sets, a merging strategy can be specified to either + * `replace` values, or `merge` them instead. Use `includeNonEnumerable` option + * to include non-enumerable properties too. + * + * @example + * ```ts + * import { deepMerge } from "https://deno.land/std@$STD_VERSION/collections/deep_merge.ts"; + * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts"; + * + * const a = { foo: true }; + * const b = { foo: { bar: true } }; + * + * assertEquals(deepMerge(a, b), { foo: { bar: true } }); + * ``` + */ export function deepMerge< T extends Record, U extends Record, @@ -279,20 +297,20 @@ export type DeepMergeOptions = { */ /** Force intellisense to expand the typing to hide merging typings */ -type ExpandRecursively = T extends Record +export type ExpandRecursively = T extends Record ? T extends infer O ? { [K in keyof O]: ExpandRecursively } : never : T; /** Filter of keys matching a given type */ -type PartialByType = { +export type PartialByType = { [K in keyof T as T[K] extends U ? K : never]: T[K]; }; /** Get set values type */ -type SetValueType = T extends Set ? V : never; +export type SetValueType = T extends Set ? V : never; /** Merge all sets types definitions from keys present in both objects */ -type MergeAllSets< +export type MergeAllSets< T, U, X = PartialByType>, @@ -303,10 +321,10 @@ type MergeAllSets< > = Z; /** Get array values type */ -type ArrayValueType = T extends Array ? V : never; +export type ArrayValueType = T extends Array ? V : never; /** Merge all sets types definitions from keys present in both objects */ -type MergeAllArrays< +export type MergeAllArrays< T, U, X = PartialByType>, @@ -319,13 +337,13 @@ type MergeAllArrays< > = Z; /** Get map values types */ -type MapKeyType = T extends Map ? K : never; +export type MapKeyType = T extends Map ? K : never; /** Get map values types */ -type MapValueType = T extends Map ? V : never; +export type MapValueType = T extends Map ? V : never; /** Merge all sets types definitions from keys present in both objects */ -type MergeAllMaps< +export type MergeAllMaps< T, U, X = PartialByType>, @@ -339,7 +357,7 @@ type MergeAllMaps< > = Z; /** Merge all records types definitions from keys present in both objects */ -type MergeAllRecords< +export type MergeAllRecords< T, U, Options, @@ -351,7 +369,7 @@ type MergeAllRecords< > = Z; /** Exclude map, sets and array from type */ -type OmitComplexes = Omit< +export type OmitComplexes = Omit< T, keyof PartialByType< T, @@ -363,7 +381,7 @@ type OmitComplexes = Omit< >; /** Object with keys in either T or U but not in both */ -type ObjectXorKeys< +export type ObjectXorKeys< T, U, X = Omit & Omit, @@ -371,14 +389,14 @@ type ObjectXorKeys< > = Y; /** Merge two objects, with left precedence */ -type MergeRightOmitComplexes< +export type MergeRightOmitComplexes< T, U, X = ObjectXorKeys & OmitComplexes<{ [K in keyof U]: U[K] }>, > = X; /** Merge two objects */ -type Merge< +export type Merge< T, U, Options, diff --git a/collections/drop_last_while.ts b/collections/drop_last_while.ts index a73f1d420b6b..7affbd7a38cb 100644 --- a/collections/drop_last_while.ts +++ b/collections/drop_last_while.ts @@ -3,7 +3,7 @@ /** * Returns a new array that drops all elements in the given collection until the - * last element that does not match the given predicate + * last element that does not match the given predicate. * * @example * ```ts diff --git a/collections/group_by.ts b/collections/group_by.ts index 259a008d184a..2cbeea6fb2f1 100644 --- a/collections/group_by.ts +++ b/collections/group_by.ts @@ -2,8 +2,6 @@ // This module is browser compatible. /** - * @deprecated (will be removed in 0.211.0) Use {@linkcode Object.groupBy} instead. - * * Applies the given selector to each element in the given array, returning a * Record containing the results as keys and all values that produced that key * as values. @@ -28,6 +26,8 @@ * }, * ); * ``` + * + * @deprecated (will be removed in 0.211.0) Use {@linkcode Object.groupBy} instead. */ export function groupBy( iterable: Iterable, diff --git a/collections/join_to_string.ts b/collections/join_to_string.ts index 3fce4cacbdf1..24ec1cf4ccc5 100644 --- a/collections/join_to_string.ts +++ b/collections/join_to_string.ts @@ -1,9 +1,7 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -/** - * Options for joinToString - */ +/** Options for {@linkcode joinToString}. */ export type JoinToStringOptions = { separator?: string; prefix?: string; diff --git a/collections/mod.ts b/collections/mod.ts index 7fcba6cab328..74afcb183b00 100644 --- a/collections/mod.ts +++ b/collections/mod.ts @@ -1,26 +1,13 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -/** Functions for specific common tasks around collection types like `Array` and - * `Record`. This module is heavily inspired by `kotlin`s stdlib. +/** + * Pure functions for common tasks around collection types like arrays and + * objects. Heavily inspired by + * [Kotlin's `kotlin.collections`]{@linkcode https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/} + * package. * - * - All provided functions are **pure**, which also means that they do **not - * mutate** your inputs, **returning a new value** instead. - * - All functions are importable on their own by referencing their snake_case - * named file (e.g. `collections/sort_by.ts`) - * - * This module re-exports several modules, and importing this module directly - * will likely include a lot of code that you might not use. - * - * Consider importing the function directly. For example to import - * {@linkcode distinctBy} import the module using the snake cased version of the - * module: - * - * ```ts - * import { distinctBy } from "https://deno.land/std@$STD_VERSION/collections/distinct_by.ts"; - * ``` - * - * @module + * @module. */ export * from "./aggregate_groups.ts"; diff --git a/collections/sample.ts b/collections/sample.ts index 8dc459726fe6..f34afd2dee8c 100644 --- a/collections/sample.ts +++ b/collections/sample.ts @@ -4,7 +4,7 @@ import { randomInteger } from "./_utils.ts"; /** - * Returns a random element from the given array + * Returns a random element from the given array. * * @example * ```ts diff --git a/collections/sort_by.ts b/collections/sort_by.ts index 198ede387161..c8f7c22c0dde 100644 --- a/collections/sort_by.ts +++ b/collections/sort_by.ts @@ -1,10 +1,10 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -/** Order */ +/** Order option for {@linkcode SortByOptions}. */ export type Order = "asc" | "desc"; -/** Options for sortBy */ +/** Options for {@linkcode sortBy}. */ export type SortByOptions = { order: Order; }; diff --git a/collections/union.ts b/collections/union.ts index e33f4561bbc7..5a1d51e1a286 100644 --- a/collections/union.ts +++ b/collections/union.ts @@ -2,7 +2,7 @@ // This module is browser compatible. /** - * Returns all distinct elements that appear in any of the given arrays + * Returns all distinct elements that appear in any of the given arrays. * * @example * ```ts