es-toolkit 0.0.1 → 1.0.0-dev.24

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# es-toolkit Changelog
+
+## Version v1.0.0
+
+Initial release. Released on May 31th, 2024.

package/README.md

@@ -0,0 +1,31 @@
+![](./docs/public/og.png)
+
+# es-toolkit · [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/toss/slash/blob/main/LICENSE)
+
+English | [한국어](./README-ko_kr.md)
+
+es-toolkit is a state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.
+
+- es-toolkit offers a variety of everyday utility functions with modern implementations, such as [debounce](https://es-toolkit.slash.page/reference/function/debounce.html), [delay](https://es-toolkit.slash.page/reference/promise/delay.html), [chunk](https://es-toolkit.slash.page/reference/array/chunk.html), [sum](https://es-toolkit.slash.page/reference/math/sum.html), and [pick](https://es-toolkit.slash.page/reference/object/pick.html).
+- Designed with performance in mind, es-toolkit achieves [2-3× better performance](https://es-toolkit.slash.page/performance.html) in modern JavaScript environments.
+- es-toolkit supports tree shaking out of the box, and [reduces JavaScript code by up to 97%](https://es-toolkit.slash.page/bundle-size.html) compared to other libraries.
+- es-toolkit includes built-in TypeScript support, with straightforward yet robust types. It also provides useful type guards such as [isNotNil](https://es-toolkit.slash.page/reference/predicate/isNotNil.html).
+- es-toolkit is battle-tested with 100% test coverage, ensuring reliability and robustness.
+
+
+## Contributing
+
+We welcome contribution from everyone in the community. Read below for detailed contribution guide.
+
+[CONTRIBUTING](./.github/CONTRIBUTING.md)
+
+## License
+
+MIT © Viva Republica, Inc. See [LICENSE](./LICENSE) for details.
+
+<a title="Toss" href="https://toss.im">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://static.toss.im/logos/png/4x/logo-toss-reverse.png">
+    <img alt="Toss" src="https://static.toss.im/logos/png/4x/logo-toss.png" width="100">
+  </picture>
+</a>

package/dist/array/chunk.d.ts

@@ -1,8 +1,24 @@
 /**
- * @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']]
  */
 export declare function chunk<T>(arr: T[], size: number): T[][];

package/dist/array/difference.d.ts

@@ -1,7 +1,23 @@
 /**
- * @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.
  */
 export declare function difference<T>(firstArr: T[], secondArr: T[]): T[];

package/dist/array/differenceBy.d.ts

@@ -1,8 +1,26 @@
 /**
- * @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.
  */
 export declare function differenceBy<T, U>(firstArr: T[], secondArr: T[], mapper: (value: T) => U): T[];

package/dist/array/differenceWith.d.ts

@@ -1,8 +1,22 @@
 /**
- * @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.
  */
 export declare function differenceWith<T>(firstArr: T[], secondArr: T[], areItemsEqual: (x: T, y: T) => boolean): T[];

package/dist/array/drop.d.ts

@@ -1,7 +1,16 @@
 /**
- * @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.
  */
 export declare function drop<T>(arr: T[], itemsCount: number): T[];

package/dist/array/dropRight.d.ts

@@ -1,7 +1,16 @@
 /**
- * @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.
  */
 export declare function dropRight<T>(arr: T[], itemsCount: number): T[];

package/dist/array/dropRightWhile.d.ts

@@ -1,7 +1,18 @@
 /**
- * @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.
  */
 export declare function dropRightWhile<T>(arr: T[], canContinueDropping: (item: T) => boolean): T[];

package/dist/array/dropWhile.d.ts

@@ -1,7 +1,18 @@
 /**
- * @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.
  */
 export declare function dropWhile<T>(arr: T[], canContinueDropping: (item: T) => boolean): T[];

package/dist/array/groupBy.d.ts

@@ -1 +1,31 @@
-export declare function groupBy(): void;
+/**
+ * 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' }
+ * //   ]
+ * // }
+ */
+export declare function groupBy<T, K extends string>(arr: T[], getKeyFromItem: (item: T) => K): Record<K, T[]>;

package/dist/array/groupBy.spec.d.ts

@@ -0,0 +1 @@
+export {};