es-toolkit 0.0.1 → 1.0.0-dev.24

package/dist/predicate/isNull.d.ts

@@ -1,6 +1,21 @@
 /**
- * @name isNull
  * Checks if the given value is null.
- * @param x The value to test if it is null
+ *
+ * This function tests whether the provided value is strictly equal to `null`.
+ * It returns `true` if the value is `null`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null`.
+ *
+ * @param {unknown} x - The value to test if it is null.
+ * @returns {x is null} True if the value is null, false otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ *
+ * console.log(isNull(value1)); // true
+ * console.log(isNull(value2)); // false
+ * console.log(isNull(value3)); // false
  */
 export declare function isNull(x: unknown): x is null;

package/dist/predicate/isUndefined.d.ts

@@ -1,6 +1,21 @@
 /**
- * @name isUndefined
  * Checks if the given value is undefined.
- * @param x The value to test if it is undefined
+ *
+ * This function tests whether the provided value is strictly equal to `undefined`.
+ * It returns `true` if the value is `undefined`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `undefined`.
+ *
+ * @param {unknown} x - The value to test if it is undefined.
+ * @returns {x is undefined} true if the value is undefined, false otherwise.
+ *
+ * @example
+ *  * const value1 = undefined;
+ * const value2 = null;
+ * const value3 = 42;
+ *
+ * console.log(isUndefined(value1)); // true
+ * console.log(isUndefined(value2)); // false
+ * console.log(isUndefined(value3)); // false
  */
 export declare function isUndefined(x: unknown): x is undefined;

package/dist/promise/delay.d.ts

@@ -1,6 +1,19 @@
 /**
- * @name delay
- * Pause the execution of a function for given milliseconds.
- * @param ms The amount of time to delay the function.
+ * Delays the execution of code for a specified number of milliseconds.
+ *
+ * This function returns a Promise that resolves after the specified delay, allowing you to use it
+ * with async/await to pause execution.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @returns {Promise<void>} A Promise that resolves after the specified delay.
+ *
+ * @example
+ * async function foo() {
+ *   console.log('Start');
+ *   await delay(1000); // Delays execution for 1 second
+ *   console.log('End');
+ * }
+ *
+ * foo();
  */
-export declare function delay(ms: number): Promise<unknown>;
+export declare function delay(ms: number): Promise<void>;

package/dist/promise/index.js

@@ -3,9 +3,22 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
- * @name delay
- * Pause the execution of a function for given milliseconds.
- * @param ms The amount of time to delay the function.
+ * Delays the execution of code for a specified number of milliseconds.
+ * 
+ * This function returns a Promise that resolves after the specified delay, allowing you to use it 
+ * with async/await to pause execution.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @returns {Promise<void>} A Promise that resolves after the specified delay.
+ *
+ * @example
+ * async function foo() {
+ *   console.log('Start');
+ *   await delay(1000); // Delays execution for 1 second
+ *   console.log('End');
+ * }
+ * 
+ * foo();
  */
 function delay(ms) {
   return new Promise(function (resolve) {

package/esm/array/_virtual/_rollupPluginBabelHelpers.mjs

@@ -1,42 +1,9 @@
-function _iterableToArrayLimit(r, l) {
-  var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
-  if (null != t) {
-    var e,
-      n,
-      i,
-      u,
-      a = [],
-      f = !0,
-      o = !1;
-    try {
-      if (i = (t = t.call(r)).next, 0 === l) {
-        if (Object(t) !== t) return;
-        f = !1;
-      } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
-    } catch (r) {
-      o = !0, n = r;
-    } finally {
-      try {
-        if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return;
-      } finally {
-        if (o) throw n;
-      }
-    }
-    return a;
-  }
-}
-function _slicedToArray(arr, i) {
-  return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest();
-}
 function _toConsumableArray(arr) {
   return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread();
 }
 function _arrayWithoutHoles(arr) {
   if (Array.isArray(arr)) return _arrayLikeToArray(arr);
 }
-function _arrayWithHoles(arr) {
-  if (Array.isArray(arr)) return arr;
-}
 function _iterableToArray(iter) {
   if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
@@ -56,9 +23,6 @@ function _arrayLikeToArray(arr, len) {
 function _nonIterableSpread() {
   throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _nonIterableRest() {
-  throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
-}
 function _createForOfIteratorHelper(o, allowArrayLike) {
   var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"];
   if (!it) {
@@ -111,4 +75,4 @@ function _createForOfIteratorHelper(o, allowArrayLike) {
   };
 }
 
-export { _arrayLikeToArray as arrayLikeToArray, _arrayWithHoles as arrayWithHoles, _arrayWithoutHoles as arrayWithoutHoles, _createForOfIteratorHelper as createForOfIteratorHelper, _iterableToArray as iterableToArray, _iterableToArrayLimit as iterableToArrayLimit, _nonIterableRest as nonIterableRest, _nonIterableSpread as nonIterableSpread, _slicedToArray as slicedToArray, _toConsumableArray as toConsumableArray, _unsupportedIterableToArray as unsupportedIterableToArray };
+export { _arrayLikeToArray as arrayLikeToArray, _arrayWithoutHoles as arrayWithoutHoles, _createForOfIteratorHelper as createForOfIteratorHelper, _iterableToArray as iterableToArray, _nonIterableSpread as nonIterableSpread, _toConsumableArray as toConsumableArray, _unsupportedIterableToArray as unsupportedIterableToArray };

package/esm/array/chunk.mjs

@@ -1,33 +1,36 @@
-import { createForOfIteratorHelper as _createForOfIteratorHelper, slicedToArray as _slicedToArray } from './_virtual/_rollupPluginBabelHelpers.mjs';
-
 /**
- * @name chunk
- * Separate an array into smaller arrays of length `size`.
- * If the array cannot be separated in equal size, the final sub-array will have the remaining elements.
- * @param arr The array to chunk
- * @param size The size of smaller arrays
+ * Splits an array into smaller arrays of a specified length.
+ *
+ * This function takes an input array and divides it into multiple smaller arrays,
+ * each of a specified length. If the input array cannot be evenly divided,
+ * the final sub-array will contain the remaining elements.
+ *
+ * @template T The type of elements in the array.
+ * @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);
+ * // Returns: [[1, 2], [3, 4], [5]]
+ *
+ * @example
+ * // Splits an array of strings into sub-arrays of length 3
+ * chunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3);
+ * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]
  */
 function chunk(arr, size) {
   if (!Number.isInteger(size) || size <= 0) {
-    throw new Error("Size must be an integer greater than zero.");
+    throw new Error('Size must be an integer greater than zero.');
   }
-  var result = [];
-  var _iterator = _createForOfIteratorHelper(arr.entries()),
-    _step;
-  try {
-    for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var _step$value = _slicedToArray(_step.value, 2),
-        index = _step$value[0],
-        item = _step$value[1];
-      if (index % size === 0) {
-        result.push([]);
-      }
-      result[result.length - 1].push(item);
-    }
-  } catch (err) {
-    _iterator.e(err);
-  } finally {
-    _iterator.f();
+  var chunkLength = Math.ceil(arr.length / size);
+  var result = Array(chunkLength);
+  for (var index = 0; index < chunkLength; index++) {
+    var start = index * size;
+    var end = start + size;
+    result[index] = arr.slice(start, end);
   }
   return result;
 }

package/esm/array/difference.mjs

@@ -1,8 +1,24 @@
 /**
- * @name difference
- * Returns the difference of two arrays.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
+ * Computes the difference between two arrays.
+ * 
+ * This function takes two arrays and returns a new array containing the elements 
+ * that are present in the first array but not in the second array. It effectively 
+ * filters out any elements from the first array that also appear in the second array.
+ *
+ * @template T
+ * @param {T[]} firstArr - The array from which to derive the difference. This is the primary array 
+ * from which elements will be compared and filtered.
+ * @param {T[]} secondArr - The array containing elements to be excluded from the first array. 
+ * Each element in this array will be checked against the first array, 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 first array but not 
+ * in the second array.
+ *
+ * @example
+ *  * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [2, 4];
+ * const result = difference(array1, array2);
+ * // result will be [1, 3, 5] since 2 and 4 are in both arrays and are excluded from the result.
  */
 function difference(firstArr, secondArr) {
   return firstArr.filter(function (item) {

package/esm/array/differenceBy.mjs

@@ -1,9 +1,27 @@
 /**
- * @name differenceBy
- * Returns the difference of two arrays. The identity of two elements is calculated after the elements are mapped with `mapper`.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
- * @param mapper The function to map the elements when calculating the difference
+ * Computes the difference between two arrays after mapping their elements through a provided function.
+ * 
+ * This function takes two arrays and a mapper function. It returns a new array containing the elements 
+ * that are present in the first array but not in the second array, based on the identity calculated 
+ * by the mapper function. 
+ * 
+ * Essentially, it filters out any elements from the first array that, when 
+ * mapped, match an element in the mapped version of the second array.
+ *
+ * @template T, U
+ * @param {T[]} firstArr - The primary array from which to derive the difference. 
+ * @param {T[]} secondArr - The array containing elements to be excluded from the first array.
+ * @param {(value: T) => U} mapper - The function to map the elements of both arrays. This function 
+ * is applied to each element in both arrays, and the comparison is made based on the mapped values.
+ * @returns {T[]} A new array containing the elements from the first array that do not have a corresponding 
+ * mapped identity in the second array.
+ *
+ * @example
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const mapper = item => item.id;
+ * const result = differenceBy(array1, array2, mapper);
+ * // result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are in both arrays and are excluded from the result.
  */
 function differenceBy(firstArr, secondArr, mapper) {
   var mappedSecondArr = secondArr.map(function (item) {

package/esm/array/differenceWith.mjs

@@ -1,9 +1,23 @@
 /**
- * @name differenceWith
- * Returns the difference of two arrays. The identity of two elements is calculated with the function `areItemsEqual`.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
- * @param areItemsEqual The function to determine whether two items are equal
+ * Computes the difference between two arrays based on a custom equality function.
+ * 
+ * This function takes two arrays and a custom comparison function. It returns a new array containing 
+ * the elements that are present in the first array but not in the second array. The comparison to determine 
+ * if elements are equal is made using the provided custom function.
+ *
+ * @template T
+ * @param {T[]} firstArr - The array from which to get the difference.
+ * @param {T[]} secondArr - The array containing elements to exclude from the first array. 
+ * @param {(x: T, y: T) => boolean} areItemsEqual - A function to determine if two items are equal.
+ * @returns {T[]} A new array containing the elements from the first array that do not match any elements in the second array 
+ * according to the custom equality function.
+ *
+ * @example
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * const result = differenceWith(array1, array2, areItemsEqual);
+ * // result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are considered equal and are excluded from the result.
  */
 function differenceWith(firstArr, secondArr, areItemsEqual) {
   return firstArr.filter(function (firstItem) {

package/esm/array/drop.mjs

@@ -1,8 +1,17 @@
 /**
- * @name drop
- * Drop some elements from an array from the beginning. This function returns a new array.
- * @param arr The element to drop items from the beginning
- * @param itemsCount The amount of elements to drop
+ * Removes a specified number of elements from the beginning of an array and returns the rest.
+ * 
+ * This function takes an array and a number, and returns a new array with the specified number 
+ * of elements removed from the start.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {number} itemsCount - The number of elements to drop from the beginning of the array.
+ * @returns {T[]} A new array with the specified number of elements removed from the start.
+ * 
+ * @example
+ *  * const array = [1, 2, 3, 4, 5];
+ * const result = drop(array, 2);
+ * // result will be [3, 4, 5] since the first two elements are dropped.
  */
 function drop(arr, itemsCount) {
   return arr.slice(itemsCount);

package/esm/array/dropRight.mjs

@@ -1,8 +1,17 @@
 /**
- * @name dropRight
- * Drop some elements from an array from the end. This function returns a new array.
- * @param arr The element to drop items from the end
- * @param itemsCount The amount of elements to drop
+ * Removes a specified number of elements from the end of an array and returns the rest.
+ * 
+ * This function takes an array and a number, and returns a new array with the specified number 
+ * of elements removed from the end.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {number} itemsCount - The number of elements to drop from the end of the array.
+ * @returns {T[]} A new array with the specified number of elements removed from the end.
+ *
+ * @example
+ *  * const array = [1, 2, 3, 4, 5];
+ * const result = dropRight(array, 2);
+ * // result will be [1, 2, 3] since the last two elements are dropped.
  */
 function dropRight(arr, itemsCount) {
   return arr.slice(0, -itemsCount);

package/esm/array/dropRightWhile.mjs

@@ -1,10 +1,21 @@
 import { dropWhile } from './dropWhile.mjs';
 
 /**
- * @name dropRightWhile
- * Drop some elements from an array from the end, until `predicate` returns false.
- * @param arr The element to drop items from the end
- * @param canContinueDropping The predicate to check if the function can continue dropping elements.
+ * Removes elements from the end of an array until the predicate returns false.
+ * 
+ * This function iterates over an array from the end and drops elements until the provided 
+ * predicate function returns false. It then returns a new array with the remaining elements.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {function(item: T): boolean} canContinueDropping - A predicate function that determines 
+ * whether to continue dropping elements. The function is called with each element from the end, 
+ * and dropping continues as long as it returns true.
+ * @returns {T[]} A new array with the elements remaining after the predicate returns false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const result = dropRightWhile(array, x => x > 3);
+ * // result will be [1, 2, 3] since elements greater than 3 are dropped from the end.
  */
 function dropRightWhile(arr, canContinueDropping) {
   var reversed = arr.slice().reverse();

package/esm/array/dropWhile.mjs

@@ -1,8 +1,19 @@
 /**
- * @name dropWhile
- * Drop some elements from an array from the beginning, until `predicate` returns false.
- * @param arr The element to drop items from the beginning
- * @param canContinueDropping The predicate to check if the function can continue dropping elements.
+ * Removes elements from the beginning of an array until the predicate returns false.
+ * 
+ * This function iterates over an array and drops elements from the start until the provided 
+ * predicate function returns false. It then returns a new array with the remaining elements.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {(item: T) => boolean} canContinueDropping - A predicate function that determines 
+ * whether to continue dropping elements. The function is called with each element, and dropping 
+ * continues as long as it returns true.
+ * @returns {T[]} A new array with the elements remaining after the predicate returns false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const result = dropWhile(array, x => x < 3);
+ * // result will be [3, 4, 5] since elements less than 3 are dropped.
  */
 function dropWhile(arr, canContinueDropping) {
   var dropEndIndex = arr.findIndex(function (item) {

package/esm/array/groupBy.mjs

@@ -1,5 +1,54 @@
-function groupBy() {
-  throw new Error('Not implemented');
+import { createForOfIteratorHelper as _createForOfIteratorHelper } from './_virtual/_rollupPluginBabelHelpers.mjs';
+
+/**
+ * Groups the elements of an array based on a provided key-generating function.
+ * 
+ * This function takes an array and a function that generates a key from each element. It returns 
+ * an object where the keys are the generated keys and the values are arrays of elements that share 
+ * the same key.
+ *
+ * @param {T[]} arr - The array to group.
+ * @param {(item: T) => K} getKeyFromItem - A function that generates a key from an element.
+ * @returns {Record<K, T[]>} An object where each key is associated with an array of elements that 
+ * share that key.
+ *
+ * @example
+ * const array = [
+ *   { category: 'fruit', name: 'apple' },
+ *   { category: 'fruit', name: 'banana' },
+ *   { category: 'vegetable', name: 'carrot' }
+ * ];
+ * const result = groupBy(array, item => item.category);
+ * // result will be:
+ * // {
+ * //   fruit: [
+ * //     { category: 'fruit', name: 'apple' },
+ * //     { category: 'fruit', name: 'banana' }
+ * //   ],
+ * //   vegetable: [
+ * //     { category: 'vegetable', name: 'carrot' }
+ * //   ]
+ * // }
+ */
+function groupBy(arr, getKeyFromItem) {
+  var result = {};
+  var _iterator = _createForOfIteratorHelper(arr),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var item = _step.value;
+      var key = getKeyFromItem(item);
+      if (result[key] == null) {
+        result[key] = [];
+      }
+      result[key].push(item);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return result;
 }
 
 export { groupBy };

package/esm/array/intersection.mjs

@@ -1,12 +1,19 @@
 /**
- * @name intersection
- * @description
  * Returns the intersection of two arrays.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
+ * 
+ * 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.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @returns {T[]} A new array containing the elements that are present in both arrays.
+ *
  * @example
- * intersection([1, 2], [1, 3]) === [1]
- * intersection([1, 2, 3], [2, 3, 4]) === [2, 3]
+ * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [3, 4, 5, 6, 7];
+ * const result = intersection(array1, array2);
+ * // result will be [3, 4, 5] since these elements are in both arrays.
  */
 function intersection(firstArr, secondArr) {
   return firstArr.filter(function (item) {

package/esm/array/intersectionBy.mjs

@@ -1,13 +1,22 @@
 /**
- * @name intersectionBy
- * @description
- * Returns the intersection of two arrays. The identity of two elements is calculated after the elements are mapped with `mapper`.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
- * @param mapper The function to map the elements when calculating the intersection
+ * Returns the intersection of two arrays based on a mapping function.
+ * 
+ * This function takes two arrays and a mapping function. It returns a new array containing 
+ * the elements from the first array that, when mapped using the provided function, have matching 
+ * mapped elements in the second array. It effectively filters out any elements from the first array 
+ * that do not have corresponding mapped values in the second array.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @param {(item: T) => U} mapper - A function to map the elements of both arrays for comparison.
+ * @returns {T[]} A new array containing the elements from the first array that have corresponding mapped values in the second array.
+ *
  * @example
- * intersectionBy([1.2, 2.1], [1.4, 3.1], Math.floor) === [1.2]
- * intersectionBy([{ foo: 1 }, { foo: 2 }], [{ foo: 1 }, { foo: 3 }], x => x.foo) === [{ foo: 1 }]
+ * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const mapper = item => item.id;
+ * const result = intersectionBy(array1, array2, mapper);
+ * // result will be [{ id: 2 }] since only this element has a matching id in both arrays.
  */
 function intersectionBy(firstArr, secondArr, mapper) {
   var mappedSecondArr = secondArr.map(function (x) {

package/esm/array/intersectionWith.mjs

@@ -1,13 +1,23 @@
 /**
- * @name intersectionWith
- * @description
- * Returns the intersection of two arrays. The identity of two elements is compared with `areItemsEqual`.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
- * @param areItemsEqual The function to compare the identity of two elements
+ * Returns the intersection of two arrays based on a custom equality function.
+ * 
+ * This function takes two arrays and a custom equality function. It returns a new array containing 
+ * the elements from the first array that have matching elements in the second array, as determined 
+ * by the custom equality function. It effectively filters out any elements from the first array that 
+ * do not have corresponding matches in the second array according to the equality function.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @param {(x: T, y: T) => boolean} areItemsEqual - A custom function to determine if two elements are equal. 
+ * This function takes two arguments, one from each array, and returns `true` if the elements are considered equal, and `false` otherwise.
+ * @returns {T[]} A new array containing the elements from the first array that have corresponding matches in the second array according to the custom equality function.
+ *
  * @example
- * intersectionWith([1.2, 2.1], [1.4, 3.1], (x, y) => Math.floor(x) === Math.floor(y)) === [1.2]
- * intersectionWith([{ foo: 1 }, { foo: 2 }], [{ foo: 1 }, { foo: 3 }], (x, y) => x.foo === y.foo) === [{ foo: 1 }]
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * const result = intersectionWith(array1, array2, areItemsEqual);
+ * // result will be [{ id: 2 }] since this element has a matching id in both arrays.
  */
 function intersectionWith(firstArr, secondArr, areItemsEqual) {
   return firstArr.filter(function (firstItem) {

package/esm/array/partition.mjs

@@ -1,11 +1,25 @@
 import { createForOfIteratorHelper as _createForOfIteratorHelper } from './_virtual/_rollupPluginBabelHelpers.mjs';
 
 /**
- * @name partition
- * @description
- * Creates two arrays: the first array includes items for which isInTruthy returns true, and the second array includes items for which isInTruthy returns false.
- * @param arr The array to split into two arrays
- * @param isInTruthy The predicate to tell whether an item is included in the first array
+ * Splits an array into two groups based on a predicate function.
+ * 
+ * This function takes an array and a predicate function. It returns a tuple of two arrays: 
+ * the first array contains elements for which the predicate function returns true, and 
+ * the second array contains elements for which the predicate function returns false.
+ *
+ * @param {T[]} arr - The array to partition.
+ * @param {(value: T) => boolean} isInTruthy - A predicate function that determines 
+ * whether an element should be placed in the truthy array. The function is called with each 
+ * element of the array.
+ * @returns {[T[], T[]]} A tuple containing two arrays: the first array contains elements for 
+ * which the predicate returned true, and the second array contains elements for which the 
+ * predicate returned false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const isEven = x => x % 2 === 0;
+ * const [even, odd] = partition(array, isEven);
+ * // even will be [2, 4], and odd will be [1, 3, 5]
  */
 function partition(arr, isInTruthy) {
   var truthy = [];

package/esm/array/sample.mjs

@@ -1,8 +1,15 @@
 /**
- * @name sample
- * @description
  * Returns a random element from an array.
- * @param arr The element to get a random element
+ * 
+ * This function takes an array and returns a single element selected randomly from the array.
+ *
+ * @param {T[]} arr - The array to sample from.
+ * @returns {T} A random element from the array.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const randomElement = sample(array);
+ * // randomElement will be one of the elements from the array, selected randomly.
  */
 function sample(arr) {
   var randomIndex = Math.floor(Math.random() * arr.length);