From c7688cd3f372f0cd874db98aee25e12d72113657 Mon Sep 17 00:00:00 2001 From: pnodet Date: Wed, 25 Sep 2024 10:57:01 +0200 Subject: [PATCH] chore: add docs --- src/arrays/chunk.ts | 1 - src/arrays/list.ts | 75 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 73 insertions(+), 3 deletions(-) diff --git a/src/arrays/chunk.ts b/src/arrays/chunk.ts index 015909e..57d22b1 100644 --- a/src/arrays/chunk.ts +++ b/src/arrays/chunk.ts @@ -6,7 +6,6 @@ * @param {T[]} arr - The array to be chunked into smaller arrays. * @param {number} size - The size of each smaller array. Must be a positive integer. * @returns {T[][]} A two-dimensional array where each sub-array has a maximum length of `size`. - * @throws {Error} Throws an error if `size` is not a positive integer. * @example * // Splits an array of numbers into sub-arrays of length 2 * chunk([1, 2, 3, 4, 5], 2); diff --git a/src/arrays/list.ts b/src/arrays/list.ts index 49a9ee0..24aece4 100644 --- a/src/arrays/list.ts +++ b/src/arrays/list.ts @@ -98,22 +98,63 @@ export class List extends Array { return lastIndex(this); } + /** + * Get a random value with `Math.random()` + * @template T + * @returns {T} A random element from the array. + */ pick(): T { return pick(this); } + /** + * Returns a sample element array of a specified `size`. + * + * This function takes an array and a number, and returns an array containing the sampled elements using Floyd's algorithm. + * + * {@link https://www.nowherenearithaca.com/2013/05/robert-floyds-tiny-and-beautiful.html Floyd's algoritm} + * @template T + * @param {number} size - The number of elements to sample. + * @returns {T[]} An array containing the sampled elements. + */ sample(size: number): List { return List.fromArray(sample(this, size)); } + /** + * Creates a duplicate-free version of an array. + * + * This function takes an array and returns a new array containing only the unique values from the original array, preserving the order of first occurrence. + * @template T - The type of elements in the array. + * @returns {T[]} A new array with only unique values from the original array. + */ uniq(): List { return List.fromArray(uniq(this)); } + /** + * Creates an array of unique values from all given arrays. + * + * This function takes two arrays, merges them into a single array, and returns a new array + * containing only the unique values from the merged array. + * @template T - The type of elements in the array. + * @param {List} other - The second array to merge and filter for unique values. + * @returns {List} A new array of unique values. + */ union(other: List): List { return List.fromArray(union(this, other)); } + /** + * Returns the intersection of two arrays. + * + * This function takes two arrays and returns a new array containing the elements that are + * present in both arrays. It effectively filters out any elements from the first array that + * are not found in the second array. + * @template T + * @param {T[]} others - The arrays to intersect. Each array is compared to the other arrays + * @returns {T[]} A new array containing the elements that are present in both arrays. + */ intersection(...others: Array>): List { return List.fromArray(intersection(this, ...others)); } @@ -122,8 +163,23 @@ export class List extends Array { return List.fromArray(xor(this, other)); } - difference(...others: T[][]): List { - return List.fromArray(difference(this, ...others)); + /** + * Computes the difference the current list and another array. + * + * This function takes two arrays and returns a new array containing the elements + * that are present in the current list but not in the second array. It effectively filters out any elements from the current list that also appear in the second array. + * @template T + * @param {T[]} diffs - The array containing elements to be excluded from the current list. + * Each element in this array will be checked against the current list, and if a match is found, that element will be excluded from the result. + * @returns {T[]} A new array containing the elements that are present in the current list but not in the second array. + * @example + * const list = new List(...[1, 2, 3, 4, 5]); + * const array2 = [2, 4]; + * const result = list.difference(array2); + * // result will be [1, 3, 5] since 2 and 4 are in both arrays and are excluded from the result. + */ + difference(...diffs: T[][]): List { + return List.fromArray(difference(this, ...diffs)); } select( @@ -133,6 +189,13 @@ export class List extends Array { return List.fromArray(select(this, mapper, condition)); } + /** + * Sorts a list of items into groups. The return value is a map where the keys are the group ids the given getGroupId function produced and the value is a list of each item in that group. + * @template T + * @template Key + * @param {(item: T) => Key} getGroupId - A function that returns the group id for each item. + * @returns {Partial<{ [key in Key]: T[] }>} A map where the keys are the group ids and the value is an array of each item in that group. + */ group( getGroupId: (item: T) => Key, ): Partial<{ [key in Key]: T[] }> { @@ -162,6 +225,14 @@ export class List extends Array { return countOccurrences(this, value); } + /** + * Creates an array of elements split into groups the length of size. + * If collection can’t be split evenly, the + * final chunk will be the remaining elements. + * @template T The type of elements in the array. + * @param {number} size - The size of each smaller array. Must be a positive integer. + * @returns {List} A two-dimensional array where each sub-array has a maximum length of `size`. + */ chunk(size: number): List { return List.fromArray(chunk(this, size)); }