es-toolkit 0.0.1

package/esm/array/_virtual/_rollupPluginBabelHelpers.mjs

@@ -0,0 +1,114 @@
+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);
+}
+function _unsupportedIterableToArray(o, minLen) {
+  if (!o) return;
+  if (typeof o === "string") return _arrayLikeToArray(o, minLen);
+  var n = Object.prototype.toString.call(o).slice(8, -1);
+  if (n === "Object" && o.constructor) n = o.constructor.name;
+  if (n === "Map" || n === "Set") return Array.from(o);
+  if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen);
+}
+function _arrayLikeToArray(arr, len) {
+  if (len == null || len > arr.length) len = arr.length;
+  for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i];
+  return arr2;
+}
+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) {
+    if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") {
+      if (it) o = it;
+      var i = 0;
+      var F = function () {};
+      return {
+        s: F,
+        n: function () {
+          if (i >= o.length) return {
+            done: true
+          };
+          return {
+            done: false,
+            value: o[i++]
+          };
+        },
+        e: function (e) {
+          throw e;
+        },
+        f: F
+      };
+    }
+    throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+  }
+  var normalCompletion = true,
+    didErr = false,
+    err;
+  return {
+    s: function () {
+      it = it.call(o);
+    },
+    n: function () {
+      var step = it.next();
+      normalCompletion = step.done;
+      return step;
+    },
+    e: function (e) {
+      didErr = true;
+      err = e;
+    },
+    f: function () {
+      try {
+        if (!normalCompletion && it.return != null) it.return();
+      } finally {
+        if (didErr) throw err;
+      }
+    }
+  };
+}
+
+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 };

package/esm/array/chunk.mjs

@@ -0,0 +1,35 @@
+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
+ */
+function chunk(arr, size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    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();
+  }
+  return result;
+}
+
+export { chunk };

package/esm/array/difference.mjs

@@ -0,0 +1,13 @@
+/**
+ * @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`
+ */
+function difference(firstArr, secondArr) {
+  return firstArr.filter(function (item) {
+    return !secondArr.includes(item);
+  });
+}
+
+export { difference };

package/esm/array/differenceBy.mjs

@@ -0,0 +1,17 @@
+/**
+ * @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
+ */
+function differenceBy(firstArr, secondArr, mapper) {
+  var mappedSecondArr = secondArr.map(function (item) {
+    return mapper(item);
+  });
+  return firstArr.filter(function (item) {
+    return !mappedSecondArr.includes(mapper(item));
+  });
+}
+
+export { differenceBy };

package/esm/array/differenceWith.mjs

@@ -0,0 +1,16 @@
+/**
+ * @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
+ */
+function differenceWith(firstArr, secondArr, areItemsEqual) {
+  return firstArr.filter(function (firstItem) {
+    return secondArr.every(function (secondItem) {
+      return !areItemsEqual(firstItem, secondItem);
+    });
+  });
+}
+
+export { differenceWith };

package/esm/array/drop.mjs

@@ -0,0 +1,11 @@
+/**
+ * @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
+ */
+function drop(arr, itemsCount) {
+  return arr.slice(itemsCount);
+}
+
+export { drop };

package/esm/array/dropRight.mjs

@@ -0,0 +1,11 @@
+/**
+ * @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
+ */
+function dropRight(arr, itemsCount) {
+  return arr.slice(0, -itemsCount);
+}
+
+export { dropRight };

package/esm/array/dropRightWhile.mjs

@@ -0,0 +1,15 @@
+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.
+ */
+function dropRightWhile(arr, canContinueDropping) {
+  var reversed = arr.slice().reverse();
+  var dropped = dropWhile(reversed, canContinueDropping);
+  return dropped.slice().reverse();
+}
+
+export { dropRightWhile };

package/esm/array/dropWhile.mjs

@@ -0,0 +1,14 @@
+/**
+ * @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.
+ */
+function dropWhile(arr, canContinueDropping) {
+  var dropEndIndex = arr.findIndex(function (item) {
+    return !canContinueDropping(item);
+  });
+  return arr.slice(dropEndIndex);
+}
+
+export { dropWhile };

package/esm/array/groupBy.mjs

@@ -0,0 +1,5 @@
+function groupBy() {
+  throw new Error('Not implemented');
+}
+
+export { groupBy };

package/esm/array/index.mjs

@@ -0,0 +1,30 @@
+export { chunk } from './chunk.mjs';
+export { difference } from './difference.mjs';
+export { differenceBy } from './differenceBy.mjs';
+export { differenceWith } from './differenceWith.mjs';
+export { drop } from './drop.mjs';
+export { dropRight } from './dropRight.mjs';
+export { dropRightWhile } from './dropRightWhile.mjs';
+export { dropWhile } from './dropWhile.mjs';
+export { groupBy } from './groupBy.mjs';
+export { intersection } from './intersection.mjs';
+export { intersectionBy } from './intersectionBy.mjs';
+export { intersectionWith } from './intersectionWith.mjs';
+export { partition } from './partition.mjs';
+export { sample } from './sample.mjs';
+export { shuffle } from './shuffle.mjs';
+export { take } from './take.mjs';
+export { takeRight } from './takeRight.mjs';
+export { takeRightWhile } from './takeRightWhile.mjs';
+export { takeWhile } from './takeWhile.mjs';
+export { union } from './union.mjs';
+export { unionBy } from './unionBy.mjs';
+export { unionWith } from './unionWith.mjs';
+export { uniq } from './uniq.mjs';
+export { uniqBy } from './uniqBy.mjs';
+export { uniqWith } from './uniqWith.mjs';
+export { xor } from './xor.mjs';
+export { xorBy } from './xorBy.mjs';
+export { xorWith } from './xorWith.mjs';
+export { zip } from './zip.mjs';
+export { zipWith } from './zipWith.mjs';

package/esm/array/intersection.mjs

@@ -0,0 +1,17 @@
+/**
+ * @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]
+ */
+function intersection(firstArr, secondArr) {
+  return firstArr.filter(function (item) {
+    return secondArr.includes(item);
+  });
+}
+
+export { intersection };

package/esm/array/intersectionBy.mjs

@@ -0,0 +1,21 @@
+/**
+ * @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 }]
+ */
+function intersectionBy(firstArr, secondArr, mapper) {
+  var mappedSecondArr = secondArr.map(function (x) {
+    return mapper(x);
+  });
+  return firstArr.filter(function (item) {
+    return mappedSecondArr.includes(mapper(item));
+  });
+}
+
+export { intersectionBy };

package/esm/array/intersectionWith.mjs

@@ -0,0 +1,20 @@
+/**
+ * @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 }]
+ */
+function intersectionWith(firstArr, secondArr, areItemsEqual) {
+  return firstArr.filter(function (firstItem) {
+    return secondArr.some(function (secondItem) {
+      return areItemsEqual(firstItem, secondItem);
+    });
+  });
+}
+
+export { intersectionWith };

package/esm/array/partition.mjs

@@ -0,0 +1,32 @@
+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
+ */
+function partition(arr, isInTruthy) {
+  var truthy = [];
+  var falsy = [];
+  var _iterator = _createForOfIteratorHelper(arr),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var item = _step.value;
+      if (isInTruthy(item)) {
+        truthy.push(item);
+      } else {
+        falsy.push(item);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return [truthy, falsy];
+}
+
+export { partition };

package/esm/array/sample.mjs

@@ -0,0 +1,12 @@
+/**
+ * @name sample
+ * @description
+ * Returns a random element from an array.
+ * @param arr The element to get a random element
+ */
+function sample(arr) {
+  var randomIndex = Math.floor(Math.random() * arr.length);
+  return arr[randomIndex];
+}
+
+export { sample };

package/esm/array/shuffle.mjs

@@ -0,0 +1,20 @@
+/**
+ * @name shuffle
+ * @description
+ * Randomize the order of an array.
+ * @param arr The array to shuffle
+ */
+function shuffle(arr) {
+  /**
+   * https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm
+   */
+  for (var i = arr.length - 1; i >= 1; i--) {
+    var j = Math.floor(Math.random() * i);
+    var _ref = [arr[j], arr[i]];
+    arr[i] = _ref[0];
+    arr[j] = _ref[1];
+  }
+  return arr;
+}
+
+export { shuffle };

package/esm/array/take.mjs

@@ -0,0 +1,27 @@
+/**
+ * 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);
+ */
+function take(arr, count) {
+  return arr.slice(0, count);
+}
+
+export { take };

package/esm/array/takeRight.mjs

@@ -0,0 +1,30 @@
+/**
+ * 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);
+ */
+function takeRight(arr, count) {
+  if (count === 0) {
+    return [];
+  }
+  return arr.slice(-count);
+}
+
+export { takeRight };

package/esm/array/takeRightWhile.mjs

@@ -0,0 +1,27 @@
+/**
+ * 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);
+ */
+function takeRightWhile(arr, shouldContinueTaking) {
+  for (var i = arr.length - 1; i >= 0; i--) {
+    if (!shouldContinueTaking(arr[i])) {
+      return arr.slice(i + 1);
+    }
+  }
+  return arr.slice();
+}
+
+export { takeRightWhile };

package/esm/array/takeWhile.mjs

@@ -0,0 +1,41 @@
+import { createForOfIteratorHelper as _createForOfIteratorHelper } from './_virtual/_rollupPluginBabelHelpers.mjs';
+
+/**
+ * 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);
+ */
+function takeWhile(arr, shouldContinueTaking) {
+  var result = [];
+  var _iterator = _createForOfIteratorHelper(arr),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var item = _step.value;
+      if (!shouldContinueTaking(item)) {
+        break;
+      }
+      result.push(item);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return result;
+}
+
+export { takeWhile };

package/esm/array/union.mjs

@@ -0,0 +1,19 @@
+import { uniq } from './uniq.mjs';
+
+/**
+ * `union` function returns the union of the arrays passed as arguments.
+ *
+ * @example
+ * ```ts
+ * union([2], [1, 2]);
+ * // [2, 1]
+ * ```
+ */
+function union() {
+  for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+    args[_key] = arguments[_key];
+  }
+  return uniq(args.flat());
+}
+
+export { union };

package/esm/array/unionBy.mjs

@@ -0,0 +1,38 @@
+import { toConsumableArray as _toConsumableArray } from './_virtual/_rollupPluginBabelHelpers.mjs';
+
+/**
+ * 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 }]
+ */
+function unionBy(arr1, arr2, mapper) {
+  var map = new Map();
+  for (var _i = 0, _arr = [].concat(_toConsumableArray(arr1), _toConsumableArray(arr2)); _i < _arr.length; _i++) {
+    var item = _arr[_i];
+    var key = mapper(item);
+    if (!map.has(key)) {
+      map.set(key, item);
+    }
+  }
+  return _toConsumableArray(map.values());
+}
+
+export { unionBy };

package/esm/array/unionWith.mjs

@@ -0,0 +1,21 @@
+import { toConsumableArray as _toConsumableArray } from './_virtual/_rollupPluginBabelHelpers.mjs';
+import { uniqWith } from './uniqWith.mjs';
+
+/**
+ * `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 }]
+ * ```
+ */
+function unionWith(arr1, arr2, areItemsEqual) {
+  return uniqWith([].concat(_toConsumableArray(arr1), _toConsumableArray(arr2)), areItemsEqual);
+}
+
+export { unionWith };

package/esm/array/uniq.mjs

@@ -0,0 +1,18 @@
+/**
+ * @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']
+ * ```
+ */
+function uniq(arr) {
+  return Array.from(new Set(arr));
+}
+
+export { uniq };