es-toolkit 0.0.1

package/dist/array/intersection.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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
+ * @example
+ * intersection([1, 2], [1, 3]) === [1]
+ * intersection([1, 2, 3], [2, 3, 4]) === [2, 3]
+ */
+export declare function intersection<T>(firstArr: T[], secondArr: T[]): T[];

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

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

package/dist/array/intersectionBy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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
+ * @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 }]
+ */
+export declare function intersectionBy<T, U>(firstArr: T[], secondArr: T[], mapper: (item: T) => U): T[];

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

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

package/dist/array/intersectionWith.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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
+ * @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 }]
+ */
+export declare function intersectionWith<T>(firstArr: T[], secondArr: T[], areItemsEqual: (x: T, y: T) => boolean): T[];

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

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

package/dist/array/partition.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @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
+ */
+export declare function partition<T>(arr: T[], isInTruthy: (value: T) => boolean): [truthy: T[], falsy: T[]];

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

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

package/dist/array/sample.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @name sample
+ * @description
+ * Returns a random element from an array.
+ * @param arr The element to get a random element
+ */
+export declare function sample<T>(arr: T[]): T;

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

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

package/dist/array/shuffle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @name shuffle
+ * @description
+ * Randomize the order of an array.
+ * @param arr The array to shuffle
+ */
+export declare function shuffle<T>(arr: T[]): T[];

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

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

package/dist/array/take.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns a new array containing the first `count` elements from the input array `arr`.
+ * If `count` is greater than the length of `arr`, the entire array is returned.
+ *
+ * @template T - Type of elements in the input array.
+ *
+ * @param {T[]} arr - The array to take elements from.
+ * @param {number} count - The number of elements to take.
+ * @returns {T[]} A new array containing the first `count` elements from `arr`.
+ *
+ * @example
+ * // Returns [1, 2, 3]
+ * take([1, 2, 3, 4, 5], 3);
+ *
+ * @example
+ * // Returns ['a', 'b']
+ * take(['a', 'b', 'c'], 2);
+ *
+ * @example
+ * // Returns [1, 2, 3]
+ * take([1, 2, 3], 5);
+ */
+export declare function take<T>(arr: T[], count: number): T[];

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

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

package/dist/array/takeRight.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns a new array containing the last `count` elements from the input array `arr`.
+ * If `count` is greater than the length of `arr`, the entire array is returned.
+ *
+ * @template T - Type of elements in the input array.
+ *
+ * @param {T[]} arr - The array to take elements from.
+ * @param {number} count - The number of elements to take.
+ * @returns {T[]} A new array containing the last `count` elements from `arr`.
+ *
+ * @example
+ * // Returns [4, 5]
+ * takeRight([1, 2, 3, 4, 5], 2);
+ *
+ * @example
+ * // Returns ['b', 'c']
+ * takeRight(['a', 'b', 'c'], 2);
+ *
+ * @example
+ * // Returns [1, 2, 3]
+ * takeRight([1, 2, 3], 5);
+ */
+export declare function takeRight<T>(arr: T[], count: number): T[];

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

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

package/dist/array/takeRightWhile.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Takes elements from the end of the array while the predicate function returns `true`.
+ *
+ * @template T - Type of elements in the input array.
+ *
+ * @param {T[]} arr - The array to take elements from.
+ * @param {function(T): boolean} shouldContinueTaking - The function invoked per element.
+ * @returns {T[]} A new array containing the elements taken from the end while the predicate returns `true`.
+ *
+ * @example
+ * // Returns [3, 2, 1]
+ * takeRightWhile([5, 4, 3, 2, 1], n => n < 4);
+ *
+ * @example
+ * // Returns []
+ * takeRightWhile([1, 2, 3], n => n > 3);
+ */
+export declare function takeRightWhile<T>(arr: T[], shouldContinueTaking: (item: T) => boolean): T[];

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

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

package/dist/array/takeWhile.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a new array containing the leading elements of the provided array
+ * that satisfy the provided predicate function. It stops taking elements as soon
+ * as an element does not satisfy the predicate.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array to process.
+ * @param {(element: T) => boolean} shouldContinueTaking - The predicate function that is called with each element. Elements are included in the result as long as this function returns true.
+ * @returns {T[]} A new array containing the leading elements that satisfy the predicate.
+ *
+ * @example
+ * // Returns [1, 2]
+ * takeWhile([1, 2, 3, 4], x => x < 3);
+ *
+ * @example
+ * // Returns []
+ * takeWhile([1, 2, 3, 4], x => x > 3);
+ */
+export declare function takeWhile<T>(arr: T[], shouldContinueTaking: (element: T) => boolean): T[];

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

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

package/dist/array/union.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `union` function returns the union of the arrays passed as arguments.
+ *
+ * @example
+ * ```ts
+ * union([2], [1, 2]);
+ * // [2, 1]
+ * ```
+ */
+export declare function union<T>(...args: T[][]): T[];

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

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

package/dist/array/unionBy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Creates an array of unique values, in order, from all given arrays using a provided mapping function to determine equality.
+ *
+ * @template T - Type of elements in the input arrays.
+ * @template U - Type of the values returned by the mapping function.
+ *
+ * @param {T[]} arr1 - The first array.
+ * @param {T[]} arr2 - The second array.
+ * @param {function(item: T): U} mapper - The function to map array elements to comparison values.
+ * @returns {T[]} A new array containing the union of unique elements from `arr1` and `arr2`, based on the values returned by the mapping function.
+ *
+ * @example
+ * // Custom mapping function for numbers (modulo comparison)
+ * const moduloMapper = (x) => x % 3;
+ * unionBy([1, 2, 3], [4, 5, 6], moduloMapper);
+ * // Returns [1, 2, 3]
+ *
+ * @example
+ * // Custom mapping function for objects with an 'id' property
+ * const idMapper = (obj) => obj.id;
+ * unionBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], idMapper);
+ * // Returns [{ id: 1 }, { id: 2 }, { id: 3 }]
+ */
+export declare function unionBy<T, U>(arr1: T[], arr2: T[], mapper: (item: T) => U): T[];

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

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

package/dist/array/unionWith.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `unionWith` function returns the union of multiple arrays passed as arguments. During this process, it removes any duplicated elements.
+ *
+ * @example
+ * ```ts
+ * unionWith(
+ *   [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }],
+ *   [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }],
+ *   (x, y) => x === y
+ * );
+ * // [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
+ * ```
+ */
+export declare function unionWith<T>(arr1: T[], arr2: T[], areItemsEqual: (item1: T, item2: T) => boolean): T[];

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

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

package/dist/array/uniq.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @name uniq
+ * @description
+ * `uniq` removes duplicated elements from the array given as an argument.
+ *
+ * It filters out elements with the same value, so duplicates of data types like Objects are not checked.
+ *
+ * @example
+ * ```ts
+ * uniq([1, 1, 2, 3, 5, 5, 7, 'foo', 'bar', 'bar']);
+ * // [1, 2, 3, 5, 7, 'foo', 'bar']
+ * ```
+ */
+export declare function uniq<T>(arr: T[]): T[];

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

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

package/dist/array/uniqBy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `uniqBy` function takes an array as its first argument and a 'converter' function as the second. It maps the array elements using the converter function, then removes any duplicates.
+ *
+ * It filters out elements with the same value, meaning it does not check for duplicates in data types like Objects.
+ *
+ * @example
+ * ```ts
+ * uniqBy([1.2, 1.5, 2.1, 3.2, 5.7, 5.3, 7.19], Math.floor);
+ * // [1.2, 2.1, 3.3, 5.7, 7.19]
+ * ```
+ */
+export declare function uniqBy<T, U>(arr: T[], converter: (item: T) => U): T[];

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

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

package/dist/array/uniqWith.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `uniqWith` function takes an array as its first argument and a 'comparator' function as the second.
+ *
+ * It evaluates the elements of the array using the comparator function, and if true is returned, it considers those elements as duplicates and removes them.
+ *
+ * @example
+ * ```ts
+ * uniqWith([1.2, 1.5, 2.1, 3.2, 5.7, 5.3, 7.19], (a, b) => );
+ * // [1, 2, 3, 5, 7]
+ * ```
+ */
+export declare function uniqWith<T>(arr: T[], areItemsEqual: (item1: T, item2: T) => boolean): T[];

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

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

package/dist/array/xor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Computes the symmetric difference between two arrays. The symmetric difference is the set of elements
+ * which are in either of the arrays, but not in their intersection.
+ *
+ * @template T - Type of elements in the input arrays.
+ *
+ * @param {T[]} arr1 - The first array.
+ * @param {T[]} arr2 - The second array.
+ * @returns {T[]} An array containing the elements that are present in either `arr1` or `arr2` but not in both.
+ *
+ * @example
+ * // Returns [1, 2, 5, 6]
+ * xor([1, 2, 3, 4], [3, 4, 5, 6]);
+ *
+ * @example
+ * // Returns ['a', 'c']
+ * xor(['a', 'b'], ['b', 'c']);
+ */
+export declare function xor<T>(arr1: T[], arr2: T[]): T[];

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

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

package/dist/array/xorBy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Computes the symmetric difference between two arrays using a custom mapping function.
+ * The symmetric difference is the set of elements which are in either of the arrays,
+ * but not in their intersection, determined by the result of the mapping function.
+ *
+ * @template T - Type of elements in the input arrays.
+ * @template U - Type of the values returned by the mapping function.
+ *
+ * @param {T[]} arr1 - The first array.
+ * @param {T[]} arr2 - The second array.
+ * @param {function(item: T): U} mapper - The function to map array elements to comparison values.
+ * @returns {T[]} An array containing the elements that are present in either `arr1` or `arr2` but not in both, based on the values returned by the mapping function.
+ *
+ * @example
+ * // Custom mapping function for objects with an 'id' property
+ * const idMapper = obj => obj.id;
+ * xorBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], idMapper);
+ * // Returns [{ id: 1 }, { id: 3 }]
+ */
+export declare function xorBy<T, U>(arr1: T[], arr2: T[], mapper: (item: T) => U): T[];

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

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

package/dist/array/xorWith.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Computes the symmetric difference between two arrays using a custom equality function.
+ * The symmetric difference is the set of elements which are in either of the arrays,
+ * but not in their intersection.
+ *
+ * @template T - Type of elements in the input arrays.
+ *
+ * @param {T[]} arr1 - The first array.
+ * @param {T[]} arr2 - The second array.
+ * @param {(item1: T, item2: T) => boolean} areElementsEqual - The custom equality function to compare elements.
+ * @returns {T[]} An array containing the elements that are present in either `arr1` or `arr2` but not in both, based on the custom equality function.
+ *
+ * @example
+ * // Custom equality function for objects with an 'id' property
+ * const areObjectsEqual = (a, b) => a.id === b.id;
+ * xorWith([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], areObjectsEqual);
+ * // Returns [{ id: 1 }, { id: 3 }]
+ */
+export declare function xorWith<T>(arr1: T[], arr2: T[], areElementsEqual: (item1: T, item2: T) => boolean): T[];

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

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

package/dist/array/zip.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Merges multiple arrays element-wise. Returns an array where each element is an array containing
+ * elements from the input arrays at the corresponding index.
+ *
+ * @param {T[]} arr1 - The first array to be zipped.
+ * @param {T[]} arr2 - The second array to be zipped.
+ * @param {T[]} arr3 - The third array to be zipped.
+ * @param {T[]} arr4 - The fourth array to be zipped.
+ */
+export declare function zip<T>(arr1: T[]): [T][];
+export declare function zip<T, U>(arr1: T[], arr2: U[]): [T, U][];
+export declare function zip<T, U, V>(arr1: T[], arr2: U[], arr3: V[]): [T, U, V][];
+export declare function zip<T, U, V, W>(arr1: T[], arr2: U[], arr3: V[], arr4: W[]): [T, U, V, W][];

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

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

package/dist/array/zipWith.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Combines multiple arrays element-wise using a provided combining function.
+ * Returns an array where each element is the result of applying the combining function
+ * to the corresponding elements from the input arrays.
+ */
+export declare function zipWith<T, R>(arr1: T[], combine: (item: T) => R): R[];
+export declare function zipWith<T, U, R>(arr1: T[], arr2: U[], combine: (item1: T, item2: U) => R): R[];
+export declare function zipWith<T, U, V, R>(arr1: T[], arr2: U[], arr3: V[], combine: (item1: T, item2: U, item3: V) => R): R[];
+export declare function zipWith<T, U, V, W, R>(arr1: T[], arr2: U[], arr3: V[], arr4: W[], combine: (item1: T, item2: U, item3: V, item4: W) => R): R[];

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

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

package/dist/function/debounce.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Creates a debounced function that delays invoking the provided function until after `waitMs` milliseconds
+ * have elapsed since the last time the debounced function was invoked. The debounced function also has a `cancel`
+ * method to cancel any pending execution.
+ *
+ * @param {() => void} func - The function to debounce.
+ * @param {number} waitMs - The number of milliseconds to delay.
+ * @returns {{ (): void; cancel: () => void }} A new debounced function with a `cancel` method.
+ *
+ * @example
+ * const debouncedFunction = debounce(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' after 1 second if not called again in that time
+ * debouncedFunction();
+ *
+ * // Will not log anything as the previous call is canceled
+ * debouncedFunction.cancel();
+ */
+export declare function debounce(func: () => void, waitMs: number): {
+    (): void;
+    cancel(): void;
+};

package/dist/function/debounce.spec.d.ts

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

package/dist/function/index.d.ts

@@ -0,0 +1,3 @@
+export { debounce } from './debounce';
+export { once } from './once';
+export { throttle } from './throttle';

package/dist/function/index.js

@@ -0,0 +1,113 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Creates a debounced function that delays invoking the provided function until after `waitMs` milliseconds
+ * have elapsed since the last time the debounced function was invoked. The debounced function also has a `cancel`
+ * method to cancel any pending execution.
+ *
+ * @param {() => void} func - The function to debounce.
+ * @param {number} waitMs - The number of milliseconds to delay.
+ * @returns {{ (): void; cancel: () => void }} A new debounced function with a `cancel` method.
+ *
+ * @example
+ * const debouncedFunction = debounce(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' after 1 second if not called again in that time
+ * debouncedFunction();
+ * 
+ * // Will not log anything as the previous call is canceled
+ * debouncedFunction.cancel();
+ */
+function debounce(func, waitMs) {
+  var timeoutId = null;
+  var debounced = function debounced() {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(function () {
+      func();
+    }, waitMs);
+  };
+  debounced.cancel = function () {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+  };
+  return debounced;
+}
+
+/**
+ * Creates a function that is restricted to invoking the provided function `func` once.
+ * Repeated calls to the function will return the value from the first invocation.
+ *
+ * @template F - The type of the function to be invoked once.
+ * @param {F} func - The function to restrict.
+ * @returns {F} A new function that invokes `func` once and caches the result.
+ *
+ * @example
+ * const initialize = once(() => {
+ *   console.log('Initialized!');
+ *   return true;
+ * });
+ * 
+ * initialize(); // Logs: 'Initialized!' and returns true
+ * initialize(); // Returns true without logging
+ */
+function once(func) {
+  var called = false;
+  var cache;
+  return function () {
+    if (called) {
+      return cache;
+    }
+    var result = func();
+    called = true;
+    cache = result;
+    return result;
+  };
+}
+
+/**
+ * Creates a throttled function that only invokes the provided function at most once
+ * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
+ * within the wait time will not trigger the execution of the original function.
+ *
+ * @param {() => void} func - The function to throttle.
+ * @param {number} throttleMs - The number of milliseconds to throttle executions to.
+ * @returns {() => void} A new throttled function.
+ *
+ * @example
+ * const throttledFunction = throttle(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' immediately
+ * throttledFunction();
+ * 
+ * // Will not log anything as it is within the throttle time
+ * throttledFunction();
+ * 
+ * // After 1 second
+ * setTimeout(() => {
+ *   throttledFunction(); // Will log 'Function executed'
+ * }, 1000);
+ */
+function throttle(func, throttleMs) {
+  var lastCallTime;
+  var throttledFunction = function throttledFunction() {
+    var now = Date.now();
+    if (lastCallTime == null || now - lastCallTime >= throttleMs) {
+      lastCallTime = now;
+      func();
+    }
+  };
+  return throttledFunction;
+}
+
+exports.debounce = debounce;
+exports.once = once;
+exports.throttle = throttle;

package/dist/function/once.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Creates a function that is restricted to invoking the provided function `func` once.
+ * Repeated calls to the function will return the value from the first invocation.
+ *
+ * @template F - The type of the function to be invoked once.
+ * @param {F} func - The function to restrict.
+ * @returns {F} A new function that invokes `func` once and caches the result.
+ *
+ * @example
+ * const initialize = once(() => {
+ *   console.log('Initialized!');
+ *   return true;
+ * });
+ *
+ * initialize(); // Logs: 'Initialized!' and returns true
+ * initialize(); // Returns true without logging
+ */
+export declare function once<F extends () => any>(func: F): F;

package/dist/function/once.spec.d.ts

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

package/dist/function/throttle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a throttled function that only invokes the provided function at most once
+ * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
+ * within the wait time will not trigger the execution of the original function.
+ *
+ * @param {() => void} func - The function to throttle.
+ * @param {number} throttleMs - The number of milliseconds to throttle executions to.
+ * @returns {() => void} A new throttled function.
+ *
+ * @example
+ * const throttledFunction = throttle(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' immediately
+ * throttledFunction();
+ *
+ * // Will not log anything as it is within the throttle time
+ * throttledFunction();
+ *
+ * // After 1 second
+ * setTimeout(() => {
+ *   throttledFunction(); // Will log 'Function executed'
+ * }, 1000);
+ */
+export declare function throttle(func: () => void, throttleMs: number): () => void;

package/dist/function/throttle.spec.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './array';
+export * from './function';
+export * from './math';
+export * from './object';
+export * from './predicate';
+export * from './promise';