es-toolkit 1.8.0 → 1.9.0-dev.170

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # es-toolkit Changelog
 
+## Version v1.9.0
+
+Released on July 10th, 2024.
+
+- Add support for [head](https://es-toolkit.slash.page/reference/array/head.html) and [tail](https://es-toolkit.slash.page/reference/array/tail.html). (https://github.com/toss/es-toolkit/pull/131, https://github.com/toss/es-toolkit/pull/143).
+- Add support for [unzip](https://es-toolkit.slash.page/reference/array/unzip.html). (https://github.com/toss/es-toolkit/pull/130)
+- Add support for [flatten](https://es-toolkit.slash.page/reference/array/flatten.html), which is six times faster than `Array#flat`. (https://github.com/toss/es-toolkit/pull/147)
+
+
 ## Version v1.8.0
 
 Released on July 5th, 2024.

package/dist/array/flatten.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[]} arr - The array to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>>} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flatten<T, D extends number = 1>(arr: readonly T[], depth?: D): Array<FlatArray<T[], D>>;
+
+export { flatten };

package/dist/array/flatten.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[]} arr - The array to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>>} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flatten<T, D extends number = 1>(arr: readonly T[], depth?: D): Array<FlatArray<T[], D>>;
+
+export { flatten };

package/dist/array/flatten.js

@@ -0,0 +1,45 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/array/flatten.ts
+var flatten_exports = {};
+__export(flatten_exports, {
+  flatten: () => flatten
+});
+module.exports = __toCommonJS(flatten_exports);
+function flatten(arr, depth = 1) {
+  const result = [];
+  const flooredDepth = Math.floor(depth);
+  const recursive = (arr2, currentDepth) => {
+    for (const item of arr2) {
+      if (Array.isArray(item) && currentDepth < flooredDepth) {
+        recursive(item, currentDepth + 1);
+      } else {
+        result.push(item);
+      }
+    }
+  };
+  recursive(arr, 0);
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  flatten
+});
+//# sourceMappingURL=flatten.js.map

package/dist/array/flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/array/flatten.ts"],"sourcesContent":["/**\n * Flattens an array up to the specified depth.\n *\n * @template T - The type of elements within the array.\n * @template D - The depth to which the array should be flattened.\n * @param {T[]} arr - The array to flatten.\n * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.\n * @returns {Array<FlatArray<T[], D>>} A new array that has been flattened.\n *\n * @example\n * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);\n * // Returns: [1, 2, 3, 4, [5, 6]]\n *\n * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);\n * // Returns: [1, 2, 3, 4, 5, 6]\n */\nexport function flatten<T, D extends number = 1>(arr: readonly T[], depth = 1 as D): Array<FlatArray<T[], D>> {\n  const result: Array<FlatArray<T[], D>> = [];\n  const flooredDepth = Math.floor(depth);\n\n  const recursive = (arr: readonly T[], currentDepth: number) => {\n    for (const item of arr) {\n      if (Array.isArray(item) && currentDepth < flooredDepth) {\n        recursive(item, currentDepth + 1);\n      } else {\n        result.push(item as FlatArray<T[], D>);\n      }\n    }\n  };\n\n  recursive(arr, 0);\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,SAAS,QAAiC,KAAmB,QAAQ,GAAkC;AAC5G,QAAM,SAAmC,CAAC;AAC1C,QAAM,eAAe,KAAK,MAAM,KAAK;AAErC,QAAM,YAAY,CAACA,MAAmB,iBAAyB;AAC7D,eAAW,QAAQA,MAAK;AACtB,UAAI,MAAM,QAAQ,IAAI,KAAK,eAAe,cAAc;AACtD,kBAAU,MAAM,eAAe,CAAC;AAAA,MAClC,OAAO;AACL,eAAO,KAAK,IAAyB;AAAA,MACvC;AAAA,IACF;AAAA,EACF;AAEA,YAAU,KAAK,CAAC;AAChB,SAAO;AACT;","names":["arr"]}

package/dist/array/flatten.mjs

@@ -0,0 +1,8 @@
+import {
+  flatten
+} from "../chunk-33MSBDC6.mjs";
+import "../chunk-2MM5EJJX.mjs";
+export {
+  flatten
+};
+//# sourceMappingURL=flatten.mjs.map

package/dist/array/head.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Returns the first element of an array.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
+ *
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const firstElement = head(arr);
+ * // firstElement will be 1
+ *
+ * const emptyArr: number[] = [];
+ * const noElement = head(emptyArr);
+ * // noElement will be undefined
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+declare function head<T>(arr: readonly T[]): T | undefined;
+
+export { head };

package/dist/array/head.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns the first element of an array.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
+ *
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const firstElement = head(arr);
+ * // firstElement will be 1
+ *
+ * const emptyArr: number[] = [];
+ * const noElement = head(emptyArr);
+ * // noElement will be undefined
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+declare function head<T>(arr: readonly T[]): T | undefined;
+
+export { head };

package/dist/array/head.js

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/array/head.ts
+var head_exports = {};
+__export(head_exports, {
+  head: () => head
+});
+module.exports = __toCommonJS(head_exports);
+function head(arr) {
+  return arr[0];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  head
+});
+//# sourceMappingURL=head.js.map

package/dist/array/head.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/array/head.ts"],"sourcesContent":["/**\n * Returns the first element of an array.\n *\n * This function takes an array and returns the first element of the array.\n * If the array is empty, the function returns `undefined`.\n *\n * @param {T[]} arr - The array from which to get the first element.\n * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.\n *\n * @example\n * const arr = [1, 2, 3];\n * const firstElement = head(arr);\n * // firstElement will be 1\n *\n * const emptyArr: number[] = [];\n * const noElement = head(emptyArr);\n * // noElement will be undefined\n */\nexport function head<T>(arr: readonly [T, ...T[]]): T;\nexport function head<T>(arr: readonly T[]): T | undefined;\nexport function head<T>(arr: readonly T[]): T | undefined {\n  return arr[0];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBO,SAAS,KAAQ,KAAkC;AACxD,SAAO,IAAI,CAAC;AACd;","names":[]}

package/dist/array/head.mjs

@@ -0,0 +1,8 @@
+import {
+  head
+} from "../chunk-HM2JT2RX.mjs";
+import "../chunk-2MM5EJJX.mjs";
+export {
+  head
+};
+//# sourceMappingURL=head.mjs.map

package/dist/array/head.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/array/index.d.mts

@@ -9,6 +9,7 @@ export { dropRight } from './dropRight.mjs';
 export { dropRightWhile } from './dropRightWhile.mjs';
 export { dropWhile } from './dropWhile.mjs';
 export { fill } from './fill.mjs';
+export { flatten } from './flatten.mjs';
 export { forEachRight } from './forEachRight.mjs';
 export { groupBy } from './groupBy.mjs';
 export { intersection } from './intersection.mjs';
@@ -32,6 +33,7 @@ export { unionWith } from './unionWith.mjs';
 export { uniq } from './uniq.mjs';
 export { uniqBy } from './uniqBy.mjs';
 export { uniqWith } from './uniqWith.mjs';
+export { unzip } from './unzip.mjs';
 export { unzipWith } from './unzipWith.mjs';
 export { xor } from './xor.mjs';
 export { xorBy } from './xorBy.mjs';
@@ -40,3 +42,5 @@ export { zip } from './zip.mjs';
 export { zipObject } from './zipObject.mjs';
 export { zipWith } from './zipWith.mjs';
 export { without } from './without.mjs';
+export { head } from './head.mjs';
+export { tail } from './tail.mjs';

package/dist/array/index.d.ts

@@ -9,6 +9,7 @@ export { dropRight } from './dropRight.js';
 export { dropRightWhile } from './dropRightWhile.js';
 export { dropWhile } from './dropWhile.js';
 export { fill } from './fill.js';
+export { flatten } from './flatten.js';
 export { forEachRight } from './forEachRight.js';
 export { groupBy } from './groupBy.js';
 export { intersection } from './intersection.js';
@@ -32,6 +33,7 @@ export { unionWith } from './unionWith.js';
 export { uniq } from './uniq.js';
 export { uniqBy } from './uniqBy.js';
 export { uniqWith } from './uniqWith.js';
+export { unzip } from './unzip.js';
 export { unzipWith } from './unzipWith.js';
 export { xor } from './xor.js';
 export { xorBy } from './xorBy.js';
@@ -40,3 +42,5 @@ export { zip } from './zip.js';
 export { zipObject } from './zipObject.js';
 export { zipWith } from './zipWith.js';
 export { without } from './without.js';
+export { head } from './head.js';
+export { tail } from './tail.js';

package/dist/array/index.js

@@ -31,8 +31,10 @@ __export(array_exports, {
   dropRightWhile: () => dropRightWhile,
   dropWhile: () => dropWhile,
   fill: () => fill,
+  flatten: () => flatten,
   forEachRight: () => forEachRight,
   groupBy: () => groupBy,
+  head: () => head,
   intersection: () => intersection,
   intersectionBy: () => intersectionBy,
   intersectionWith: () => intersectionWith,
@@ -44,6 +46,7 @@ __export(array_exports, {
   sample: () => sample,
   sampleSize: () => sampleSize,
   shuffle: () => shuffle,
+  tail: () => tail,
   take: () => take,
   takeRight: () => takeRight,
   takeRightWhile: () => takeRightWhile,
@@ -54,6 +57,7 @@ __export(array_exports, {
   uniq: () => uniq,
   uniqBy: () => uniqBy,
   uniqWith: () => uniqWith,
+  unzip: () => unzip,
   unzipWith: () => unzipWith,
   without: () => without,
   xor: () => xor,
@@ -161,6 +165,23 @@ function fill(arr, value, start = 0, end = arr.length) {
   return arr;
 }
 
+// src/array/flatten.ts
+function flatten(arr, depth = 1) {
+  const result = [];
+  const flooredDepth = Math.floor(depth);
+  const recursive = (arr2, currentDepth) => {
+    for (const item of arr2) {
+      if (Array.isArray(item) && currentDepth < flooredDepth) {
+        recursive(item, currentDepth + 1);
+      } else {
+        result.push(item);
+      }
+    }
+  };
+  recursive(arr, 0);
+  return result;
+}
+
 // src/array/forEachRight.ts
 function forEachRight(arr, callback) {
   for (let i = arr.length - 1; i >= 0; i--) {
@@ -419,6 +440,24 @@ function uniqBy(arr, mapper) {
   return Array.from(map.values());
 }
 
+// src/array/unzip.ts
+function unzip(zipped) {
+  let maxLen = 0;
+  for (let i = 0; i < zipped.length; i++) {
+    if (zipped[i].length > maxLen) {
+      maxLen = zipped[i].length;
+    }
+  }
+  const result = new Array(maxLen);
+  for (let i = 0; i < maxLen; i++) {
+    result[i] = new Array(zipped.length);
+    for (let j = 0; j < zipped.length; j++) {
+      result[i][j] = zipped[j][i];
+    }
+  }
+  return result;
+}
+
 // src/array/unzipWith.ts
 function unzipWith(target, iteratee) {
   const maxLength = Math.max(...target.map((innerArray) => innerArray.length));
@@ -493,6 +532,24 @@ function without(array, ...values) {
   const valuesSet = new Set(values);
   return array.filter((item) => !valuesSet.has(item));
 }
+
+// src/array/head.ts
+function head(arr) {
+  return arr[0];
+}
+
+// src/array/tail.ts
+function tail(arr) {
+  const len = arr.length;
+  if (len <= 1) {
+    return [];
+  }
+  const result = new Array(len - 1);
+  for (let i = 1; i < len; i++) {
+    result[i - 1] = arr[i];
+  }
+  return result;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   chunk,
@@ -506,8 +563,10 @@ function without(array, ...values) {
   dropRightWhile,
   dropWhile,
   fill,
+  flatten,
   forEachRight,
   groupBy,
+  head,
   intersection,
   intersectionBy,
   intersectionWith,
@@ -519,6 +578,7 @@ function without(array, ...values) {
   sample,
   sampleSize,
   shuffle,
+  tail,
   take,
   takeRight,
   takeRightWhile,
@@ -529,6 +589,7 @@ function without(array, ...values) {
   uniq,
   uniqBy,
   uniqWith,
+  unzip,
   unzipWith,
   without,
   xor,