es-toolkit 1.12.0 → 1.13.0-dev.290

package/dist/compat/index.d.ts

@@ -1,6 +1,5 @@
 export { compact } from '../array/compact.js';
 export { countBy } from '../array/countBy.js';
-export { difference } from '../array/difference.js';
 export { differenceBy } from '../array/differenceBy.js';
 export { differenceWith } from '../array/differenceWith.js';
 export { drop } from '../array/drop.js';
@@ -43,7 +42,7 @@ export { zip } from '../array/zip.js';
 export { zipObject } from '../array/zipObject.js';
 export { zipWith } from '../array/zipWith.js';
 export { without } from '../array/without.js';
-export { head } from '../array/head.js';
+export { head as first, head } from '../array/head.js';
 export { tail } from '../array/tail.js';
 export { toFilled } from '../array/toFilled.js';
 export { last } from '../array/last.js';
@@ -71,11 +70,13 @@ export { pick } from '../object/pick.js';
 export { pickBy } from '../object/pickBy.js';
 export { invert } from '../object/invert.js';
 export { clone } from '../object/clone.js';
+export { flattenObject } from '../object/flattenObject.js';
 export { isEqual } from '../predicate/isEqual.js';
 export { isNil } from '../predicate/isNil.js';
 export { isNotNil } from '../predicate/isNotNil.js';
 export { isNull } from '../predicate/isNull.js';
 export { isUndefined } from '../predicate/isUndefined.js';
+export { isLength } from '../predicate/isLength.js';
 export { delay } from '../promise/delay.js';
 export { withTimeout } from '../promise/withTimeout.js';
 export { camelCase } from '../string/camelCase.js';
@@ -110,6 +111,37 @@ export { capitalize } from '../string/capitalize.js';
  */
 declare function chunk<T>(arr: readonly T[], size?: number): T[][];
 
+/**
+ * Concatenates multiple arrays and values into a single array.
+ *
+ * @template T The type of elements in the array.
+ * @param {...(T | readonly T[])} values - The values and/or arrays to concatenate.
+ * @returns {T[]} A new array containing all the input values.
+ *
+ * @example
+ * // Concatenate individual values
+ * concat(1, 2, 3);
+ * // returns [1, 2, 3]
+ *
+ * @example
+ * // Concatenate arrays of values
+ * concat([1, 2], [3, 4]);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate a mix of individual values and arrays
+ * concat(1, [2, 3], 4);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate nested arrays
+ * concat([1, [2, 3]], 4);
+ * // returns [1, [2, 3], 4]
+ */
+declare function concat<T>(...values: Array<T | readonly T[]>): T[];
+
+declare function difference<T>(arr: readonly T[], ...values: Array<readonly T[]>): T[];
+
 /**
  * Creates a deeply nested object given arrays of paths and values.
  *
@@ -427,6 +459,30 @@ declare function get(object: unknown, path: PropertyKey | readonly PropertyKey[]
  */
 declare function set<T>(obj: object, path: PropertyKey | readonly PropertyKey[], value: unknown): T;
 
+/**
+ * Checks if a given value is a plain object.
+ *
+ * A plain object is an object created by the `{}` literal, `new Object()`, or
+ * `Object.create(null)`.
+ *
+ * This function also handles objects with custom
+ * `Symbol.toStringTag` properties.
+ *
+ * `Symbol.toStringTag` is a built-in symbol that a constructor can use to customize the
+ * default string description of objects.
+ *
+ * @param {unknown} [object] - The value to check.
+ * @returns {boolean} - True if the value is a plain object, otherwise false.
+ *
+ * @example
+ * console.log(isPlainObject({})); // true
+ * console.log(isPlainObject([])); // false
+ * console.log(isPlainObject(null)); // false
+ * console.log(isPlainObject(Object.create(null))); // true
+ * console.log(isPlainObject(new Map())); // false
+ */
+declare function isPlainObject(object?: unknown): boolean;
+
 /**
  * Checks if a string contains another string at the beginning of the string.
  *
@@ -497,4 +553,4 @@ declare function max<T>(items?: readonly T[]): T;
  */
 declare function min<T>(items?: readonly T[]): T;
 
-export { chunk, endsWith, get, max, min, set, startsWith, zipObjectDeep };
+export { chunk, concat, difference, endsWith, get, isPlainObject, max, min, set, startsWith, zipObjectDeep };

package/dist/compat/index.js

@@ -62,10 +62,11 @@ __export(compat_exports, {
   clamp: () => clamp,
   clone: () => clone,
   compact: () => compact,
+  concat: () => concat,
   countBy: () => countBy,
   debounce: () => debounce,
   delay: () => delay,
-  difference: () => difference,
+  difference: () => difference2,
   differenceBy: () => differenceBy,
   differenceWith: () => differenceWith,
   drop: () => drop,
@@ -74,9 +75,11 @@ __export(compat_exports, {
   dropWhile: () => dropWhile,
   endsWith: () => endsWith,
   fill: () => fill,
+  first: () => head,
   flatMap: () => flatMap,
   flatten: () => flatten,
   flattenDeep: () => flattenDeep,
+  flattenObject: () => flattenObject,
   forEachRight: () => forEachRight,
   get: () => get,
   groupBy: () => groupBy,
@@ -88,9 +91,11 @@ __export(compat_exports, {
   intersectionWith: () => intersectionWith,
   invert: () => invert,
   isEqual: () => isEqual,
+  isLength: () => isLength,
   isNil: () => isNil,
   isNotNil: () => isNotNil,
   isNull: () => isNull,
+  isPlainObject: () => isPlainObject2,
   isUndefined: () => isUndefined,
   kebabCase: () => kebabCase,
   keyBy: () => keyBy,
@@ -924,6 +929,53 @@ function isPrimitive(value) {
   return value == null || typeof value !== "object" && typeof value !== "function";
 }
 
+// src/predicate/isPlainObject.ts
+function isPlainObject(object) {
+  if (typeof object !== "object") {
+    return false;
+  }
+  if (object == null) {
+    return false;
+  }
+  if (Object.getPrototypeOf(object) === null) {
+    return true;
+  }
+  if (object.toString() !== "[object Object]") {
+    return false;
+  }
+  let proto = object;
+  while (Object.getPrototypeOf(proto) !== null) {
+    proto = Object.getPrototypeOf(proto);
+  }
+  return Object.getPrototypeOf(object) === proto;
+}
+
+// src/object/flattenObject.ts
+function flattenObject(object) {
+  return flattenObjectImpl(object);
+}
+function flattenObjectImpl(object, prefix = "") {
+  const result = {};
+  const keys = Object.keys(object);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const value = object[key];
+    const prefixedKey = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value) && Object.keys(value).length > 0) {
+      Object.assign(result, flattenObjectImpl(value, prefixedKey));
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index++) {
+        result[`${prefixedKey}.${index}`] = value[index];
+      }
+      continue;
+    }
+    result[prefixedKey] = value;
+  }
+  return result;
+}
+
 // src/predicate/isEqual.ts
 function isEqual(a, b) {
   if (Object.is(a, b)) {
@@ -977,6 +1029,11 @@ function isUndefined(x) {
   return x === void 0;
 }
 
+// src/predicate/isLength.ts
+function isLength(value) {
+  return typeof value === "number" && value > -1 && value % 1 === 0 && value <= Number.MAX_SAFE_INTEGER;
+}
+
 // src/promise/delay.ts
 function delay(ms, { signal } = {}) {
   return new Promise((resolve, reject) => {
@@ -1076,6 +1133,18 @@ function chunk2(arr, size = 1) {
   return chunk(arr, size);
 }
 
+// src/compat/array/concat.ts
+function concat(...values) {
+  return flatten(values);
+}
+
+// src/compat/array/difference.ts
+function difference2(arr, ...values) {
+  const arr1 = arr;
+  const arr2 = flatten(values);
+  return difference(arr1, arr2);
+}
+
 // src/compat/_internal/isIndex.ts
 var IS_UNSIGNED_INTEGER = /^(?:0|[1-9]\d*)$/;
 function isIndex(value) {
@@ -1197,6 +1266,36 @@ function get(object, path, defaultValue) {
   return current != null ? current : defaultValue;
 }
 
+// src/compat/predicate/isPlainObject.ts
+function isPlainObject2(object) {
+  var _a;
+  if (typeof object !== "object") {
+    return false;
+  }
+  if (object == null) {
+    return false;
+  }
+  if (Object.getPrototypeOf(object) === null) {
+    return true;
+  }
+  if (object.toString() !== "[object Object]") {
+    const tag = object[Symbol.toStringTag];
+    if (tag == null) {
+      return false;
+    }
+    const isTagReadonly = !((_a = Object.getOwnPropertyDescriptor(object, Symbol.toStringTag)) == null ? void 0 : _a.writable);
+    if (isTagReadonly) {
+      return false;
+    }
+    return object.toString() === `[object ${tag}]`;
+  }
+  let proto = object;
+  while (Object.getPrototypeOf(proto) !== null) {
+    proto = Object.getPrototypeOf(proto);
+  }
+  return Object.getPrototypeOf(object) === proto;
+}
+
 // src/compat/string/startsWith.ts
 var startsWith = (str, target, position = 0) => {
   return str.startsWith(target, position);
@@ -1242,6 +1341,7 @@ function min(items = []) {
   clamp,
   clone,
   compact,
+  concat,
   countBy,
   debounce,
   delay,
@@ -1254,9 +1354,11 @@ function min(items = []) {
   dropWhile,
   endsWith,
   fill,
+  first,
   flatMap,
   flatten,
   flattenDeep,
+  flattenObject,
   forEachRight,
   get,
   groupBy,
@@ -1268,9 +1370,11 @@ function min(items = []) {
   intersectionWith,
   invert,
   isEqual,
+  isLength,
   isNil,
   isNotNil,
   isNull,
+  isPlainObject,
   isUndefined,
   kebabCase,
   keyBy,