chore: add docs

Author: pnodet

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);

src/arrays/list.ts

@@ -98,22 +98,63 @@ export class List<T> extends Array<T> {
     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<T> {
     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<T> {
     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<T>} other - The second array to merge and filter for unique values.
+   * @returns {List<T>} A new array of unique values.
+   */
   union(other: List<T>): List<T> {
     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<T>>): List<T> {
     return List.fromArray(intersection(this, ...others));
   }
@@ -122,8 +163,23 @@ export class List<T> extends Array<T> {
     return List.fromArray(xor(this, other));
   }
 
-  difference(...others: T[][]): List<T> {
-    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<T> {
+    return List.fromArray(difference(this, ...diffs));
   }
 
   select<K>(
@@ -133,6 +189,13 @@ export class List<T> extends Array<T> {
     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<Key extends string | number | symbol>(
     getGroupId: (item: T) => Key,
   ): Partial<{ [key in Key]: T[] }> {
@@ -162,6 +225,14 @@ export class List<T> extends Array<T> {
     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<T[]>} A two-dimensional array where each sub-array has a maximum length of `size`.
+   */
   chunk(size: number): List<T[]> {
     return List.fromArray(chunk(this, size));
   }