moderndash 2.1.3 → 2.2.0

package/dist/index.d.ts

@@ -7,12 +7,12 @@
  *
  * chunk(['a', 'b', 'c', 'd'], 3)
  * // => [['a', 'b', 'c'], ['d']]
- * @param size The length of each chunk
+ * @param chunkSize The length of each chunk
  * @param array The array to chunk.
  * @template TElem The type of the array elements.
  * @returns Returns the new array of chunks.
  */
-declare function chunk<TElem>(array: TElem[], size: number): TElem[][];
+declare function chunk<TElem>(array: readonly TElem[], chunkSize: number): TElem[][];
 
 /**
  * Creates an object with counts of occurrences of items in the array.
@@ -24,18 +24,18 @@ declare function chunk<TElem>(array: TElem[], size: number): TElem[][];
  *   { 'user': 'fred', 'active': true, age: 40 }
  * ]
  *
- * count(users, value => value.active);
- * // => { 'true': 2, 'false': 1 }
+ * count(users, value => value.active ? 'active' : 'inactive');
+ * // => { 'active': 2, 'inactive': 1 }
  *
  * count(users, value => value.age);
- * // => { '36': 2, '40': 1 }
+ * // => { 36: 2, 40: 1 }
  *
  * @param criteria The criteria to count by.
  * @param array The array or record to iterate over.
  * @template TElem The type of the array elements.
  * @returns Returns the composed aggregate object.
  */
-declare function count<TElem, TKey extends PropertyKey>(array: TElem[], criteria: (value: TElem) => TKey): Record<TKey, number>;
+declare function count<TElem, TKey extends PropertyKey>(array: readonly TElem[], criteria: (value: TElem) => TKey): Record<TKey, number>;
 
 /**
  * This type builds an array with a minimum length.
@@ -77,8 +77,8 @@ type BuildArrayMinLength<TElem, TMinLength extends number, Current extends TElem
  * @template TElem The type of the array elements.
  * @returns Returns the new array of filtered values.
  */
-declare function difference<TElem>(...arrays: ArrayMinLength<TElem[], 2>): TElem[];
-declare function difference<TElem>(arrayOrCompFn: (a: TElem, b: TElem) => boolean, ...arrays: ArrayMinLength<TElem[], 2>): TElem[];
+declare function difference<TElem>(...arrays: ArrayMinLength<readonly TElem[], 2>): TElem[];
+declare function difference<TElem>(arrayOrCompFn: (a: TElem, b: TElem) => boolean, ...arrays: ArrayMinLength<readonly TElem[], 2>): TElem[];
 
 /**
  * Creates a slice of `array` excluding elements dropped from the end.
@@ -91,14 +91,14 @@ declare function difference<TElem>(arrayOrCompFn: (a: TElem, b: TElem) => boolea
  *   { 'user': 'pebbles', 'active': true }
  * ]
  *
- * dropRightWhile(users, ({ active }) => active)
+ * dropRightWhile(users, user => user.active)
  * // => objects for ['barney']
  * @param predicate The function invoked per iteration.
  * @param array The array to query.
  * @template TElem The type of the array elements.
  * @returns Returns the slice of `array`.
  */
-declare function dropRightWhile<TElem>(array: TElem[], predicate: (value: TElem) => boolean): TElem[];
+declare function dropRightWhile<TElem>(array: readonly TElem[], predicate: (value: TElem) => boolean): TElem[];
 
 /**
  * Creates a slice of `array` excluding elements dropped from the beginning.
@@ -111,14 +111,14 @@ declare function dropRightWhile<TElem>(array: TElem[], predicate: (value: TElem)
  *   { 'user': 'pebbles', 'active': false }
  * ]
  *
- * dropWhile(users, ({ active }) => active)
+ * dropWhile(users, user => user.active)
  * // => objects for ['pebbles']
  * @param predicate The function invoked per iteration.
  * @param array The array to query.
  * @template TElem The type of the array elements.
  * @returns Returns the slice of `array`.
  */
-declare function dropWhile<TElem>(array: TElem[], predicate: (value: TElem) => boolean): TElem[];
+declare function dropWhile<TElem>(array: readonly TElem[], predicate: (value: TElem) => boolean): TElem[];
 
 /**
  * Creates an object with grouped items in the array.
@@ -127,15 +127,15 @@ declare function dropWhile<TElem>(array: TElem[], predicate: (value: TElem) => b
  * group([6.1, 4.2, 6.3], Math.floor)
  * // => { 4: [4.2], 6: [6.1, 6.3] }
  *
- * group([6.1, 4.2, 6.3], value => value > 5)
- * // => { 'false': [4.2], 'true': [6.1, 6.3] }
+ * group([6.1, 4.2, 6.3], value => value > 5 ? '>5' : '<=5')
+ * // => { '<=5': [4.2], '>5': [6.1, 6.3] }
  *
  * @param collection The array or object to iterate over.
  * @param getGroupKey A function that returns the group id for each item.
  * @template TElem The type of the array elements.
  * @returns An object with grouped items.
  */
-declare function group<TElem, TKey extends PropertyKey>(array: TElem[], getGroupKey: (value: TElem) => TKey): Record<TKey, TElem[]>;
+declare function group<TElem, TKey extends PropertyKey>(array: readonly TElem[], getGroupKey: (elem: TElem) => TKey): Record<TKey, TElem[]>;
 
 /**
  * Create an array with unique values from all input arrays, with order based on the first array.
@@ -158,10 +158,11 @@ declare function group<TElem, TKey extends PropertyKey>(array: TElem[], getGroup
  * intersection((a, b) => a.id === b.id, arr1, arr2)
  * // => [{ id: 3, name: 'John' }]
  * @param arrays The arrays to inspect.
+ * @template TElem The type of the array elements.
  * @returns Returns the new array of intersecting values.
  */
-declare function intersection<TArr>(...arrays: ArrayMinLength<TArr[], 2>): TArr[];
-declare function intersection<TArr>(arrayOrCompFn: (a: TArr, b: TArr) => boolean, ...arrays: ArrayMinLength<TArr[], 2>): TArr[];
+declare function intersection<TElem>(...arrays: ArrayMinLength<readonly TElem[], 2>): TElem[];
+declare function intersection<TElem>(arrayOrCompFn: (a: TElem, b: TElem) => boolean, ...arrays: ArrayMinLength<readonly TElem[], 2>): TElem[];
 
 /**
  * Generates an iterable sequence of numbers starting from `start`, up to and including `end`,
@@ -192,9 +193,10 @@ declare function range(start: number, end: number, step?: number): Generator<num
  * shuffle([1, 2, 3, 4])
  * // => [4, 1, 3, 2]
  * @param array The array or object to shuffle.
+ * @template TElem The type of the array elements.
  * @returns Returns a new shuffled array.
  */
-declare function shuffle<TElem>(array: TElem[]): TElem[];
+declare function shuffle<TElem>(array: readonly TElem[]): TElem[];
 
 /**
  * Creates a new sorted array in ascending or descending order based on one or multiple sorting criteria.
@@ -215,12 +217,13 @@ declare function shuffle<TElem>(array: TElem[]): TElem[];
  * @param orders The sorting criteria, one or multiple objects with properties order (either 'asc' or 'desc') and by (iteratee function to sort based on a specific property).
  * @param orders.order - The order to sort in, either 'asc' or 'desc'.
  * @param orders.by - The iteratee function to sort based on a specific property.
+ * @template TElem The type of the array elements.
  * @returns Returns a new sorted array.
 */
-declare function sort<TInput>(array: TInput[], ...orders: {
+declare function sort<TElem>(array: readonly TElem[], ...orders: {
     order?: 'asc' | 'desc';
-    by?: (item: TInput) => number | bigint | Date | string;
-}[]): TInput[];
+    by?: (item: TElem) => number | bigint | Date | string;
+}[]): TElem[];
 
 /**
  * Creates a slice of `array` with elements taken from the end.
@@ -233,13 +236,14 @@ declare function sort<TInput>(array: TInput[], ...orders: {
  *   { 'user': 'pebbles', 'active': true }
  * ]
  *
- * takeRightWhile(users, ({ active }) => active)
+ * takeRightWhile(users, user => user.active)
  * // => objects for ['fred', 'pebbles']
  * @param predicate The function invoked per iteration.
  * @param array The array to query.
+ * @template TElem The type of the array elements.
  * @returns Returns the slice of `array`.
  */
-declare function takeRightWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boolean): TArr[];
+declare function takeRightWhile<TElem>(array: readonly TElem[], predicate: (elem: TElem) => boolean): TElem[];
 
 /**
  * Creates a slice of `array` with elements taken from the beginning.
@@ -252,13 +256,14 @@ declare function takeRightWhile<TArr>(array: TArr[], predicate: (elem: TArr) =>
  *   { 'user': 'pebbles', 'active': false }
  * ]
  *
- * takeWhile(users, ({ active }) => active)
+ * takeWhile(users, user => user.active)
  * // => objects for ['barney', 'fred']
  * @param predicate The function invoked per iteration.
  * @param array The array to query.
+ * @template TElem The type of the array elements.
  * @returns Returns the slice of `array`.
  */
-declare function takeWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boolean): TArr[];
+declare function takeWhile<TElem>(array: readonly TElem[], predicate: (elem: TElem) => boolean): TElem[];
 
 /**
  * Creates a duplicate-free version of an array, in which only the first occurrence of each element is kept.
@@ -273,7 +278,7 @@ declare function takeWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boole
  * // compare by object values
  * const users = [
  *   { id: 1, name: 'john' },
- *   { id: 2, name: 'john' }
+ *   { id: 2, name: 'john' },
  *   { id: 2, name: 'john' },
  * ]
  *
@@ -286,9 +291,10 @@ declare function takeWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boole
  *
  * @param array The array to inspect.
  * @param iteratee The iteratee invoked per element.
+ * @template TElem The type of the array elements.
  * @returns Returns the new duplicate free array.
  */
-declare function unique<TInput>(array: TInput[], compareFn?: (a: TInput, b: TInput) => boolean): TInput[];
+declare function unique<TElem>(array: readonly TElem[], compareFn?: (a: TElem, b: TElem) => boolean): TElem[];
 
 type JsonifiableObject = {
     [Key in string]?: Jsonifiable;
@@ -472,16 +478,18 @@ declare function decMaxCalls(n: number): (target: unknown, key: string, descript
 type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters<TFunc>) => ReturnType<TFunc>;
 
 /**
- * Creates a function that caches the result of `func`.
- *
- * The cache key is either determined by the provided `resolver` or by the arguments used in the cached function.
+ * Creates a function that memoizes the result of a given function.
  *
- * The `cache` property is exposed on the cached function. It is an instance of `Map` and can be used to clear or inspect the cache.
- * The cache property can be replaced by a custom cache as long as it implements the `Map` interface.
+ * The cache key is determined by the `resolver` or by the arguments from the function call.
  *
  * **Options:**
- * - `resolver` A function that determines the cache key for storing the result based on the arguments provided.
- * - `ttl` sets the time to live for the cache in milliseconds. After `ttl` milliseconds, the next call to the memoized function will result in a cache miss.
+ * - `resolver` A function that determines the cache key based on the arguments provided.
+ * - `ttl` the time to live for the cache entries in milliseconds.
+ *
+ * **Properties:**
+ * - `cache` The cache is an instance of `Map` and can be used to clear or inspect the cache.
+ * It can be replaced by a custom cache that matches the `Map` interface.
+ *
  *
  * This function can be used as a decorator with {@link decMemoize}.
  *
@@ -742,7 +750,7 @@ declare function times<TInput>(func: (index: number) => TInput, n: number): TInp
  * @param numbers The input array of numbers
  * @returns The average of the input array, or NaN if the input array is empty
  */
-declare function average(numbers: number[]): number;
+declare function average(numbers: readonly number[]): number;
 
 /**
  * Calculates the median of an array of numbers
@@ -755,7 +763,7 @@ declare function average(numbers: number[]): number;
  * @param numbers The input array of numbers
  * @returns The median of the input array
  */
-declare function median(numbers: number[]): number;
+declare function median(numbers: readonly number[]): number;
 
 /**
  * Rounds a number to the given precision.
@@ -781,7 +789,7 @@ declare function round(number: number, precision?: number): number;
  * @param numbers The input array of numbers
  * @returns The sum of the input array
  */
-declare function sum(numbers: number[]): number;
+declare function sum(numbers: readonly number[]): number;
 
 /**
  * The type of a plain object.
@@ -797,6 +805,20 @@ declare function sum(numbers: number[]): number;
  */
 type PlainObject = Record<PropertyKey, unknown>;
 
+/**
+ * Flattens an object into a single level object.
+ *
+ * @example
+ * const obj = { a: { b: 2, c: [{ d: 3 }, {d: 4 }] } };
+ * flatKeys(obj);
+ * // => { 'a.b': 2, 'a.c[0].d': 3, 'a.c[1].d': 4 }
+ *
+ * @param obj The object to flatten.
+ * @template TObj The type of the object to flatten.
+ * @returns A new object with flattened keys.
+ */
+declare function flatKeys<TObj extends PlainObject>(obj: TObj): Record<string, unknown>;
+
 /**
  * This function combines two or more objects into a single new object. Arrays and other types are overwritten.
  *
@@ -813,6 +835,8 @@ type PlainObject = Record<PropertyKey, unknown>;
  * // => { a: "Yes" }
  * @param target The target object
  * @param sources The source objects
+ * @template TTarget The type of the target object
+ * @template TSources The type of the source objects
  * @returns A new merged object
  */
 declare function merge<TTarget extends PlainObject, TSources extends ArrayMinLength<PlainObject, 1>>(target: TTarget, ...sources: TSources): MergeDeepObjects<[TTarget, ...TSources]>;
@@ -840,8 +864,8 @@ type MergeDeepObjects<A extends readonly [...unknown[]]> = A extends [infer L, .
  *
  * @param object The object to filter
  * @param keysToOmit The keys to exclude from the returned object
+ * @template TObj The type of the object
  * @returns - An object without the specified keys
- *
  */
 declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToOmit: Key[]): Omit<TObj, Key>;
 
@@ -855,9 +879,10 @@ declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object:
  * // => { 'a': 1, 'c': 3 }
  * @param object The source object.
  * @param keysToPick The property paths to pick.
+ * @template TObj The type of the object.
  * @returns Returns the new object.
  */
-declare function pick<TInput extends PlainObject, Key extends keyof TInput>(object: TInput, keysToPick: Key[]): Pick<TInput, Key>;
+declare function pick<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToPick: Key[]): Pick<TObj, Key>;
 
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist, it’s created.
@@ -867,12 +892,25 @@ declare function pick<TInput extends PlainObject, Key extends keyof TInput>(obje
  * set(obj, 'a.c', 1);
  * // => { a: { b: 2, c: 1 } }
  *
+ * // `[number]` can be used to access array elements
+ * set(obj, 'a.c[0]', 'hello');
+ * // => { a: { b: 2, c: ['hello'] } }
+ *
+ * // numbers with dots are treated as keys
+ * set(obj, 'a.c.0.d', 'world');
+ * // => { a: { b: 2, c: { 0: { d: 'world' } } }
+ *
+ * // supports numbers in keys
+ * set(obj, 'a.e0.a', 1);
+ * // => { a: { e0: { a: 1 } } }
+ *
  * @param obj The object to modify.
  * @param path The path of the property to set.
  * @param value The value to set.
+ * @template TObj The type of the object.
  * @returns The modified object.
  */
-declare function set<TObj extends PlainObject>(obj: TObj, path: string, value: unknown): TObj;
+declare function set(obj: PlainObject, path: string, value: unknown): PlainObject;
 
 /**
  * A class for managing a queue of async functions that runs a set number concurrently.
@@ -1277,4 +1315,4 @@ declare function isPlainObject(value: unknown): value is PlainObject;
  */
 declare function isUrl(str: string): boolean;
 
-export { ArrayMinLength, GenericFunction, Jsonifiable, PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, tryCatch, unescapeHtml, unique };
+export { ArrayMinLength, GenericFunction, Jsonifiable, PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, flatKeys, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, tryCatch, unescapeHtml, unique };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/array/chunk.ts
-function chunk(array, size) {
-  const intSize = Math.trunc(size);
+function chunk(array, chunkSize) {
+  const intSize = Math.trunc(chunkSize);
   if (array.length === 0 || intSize < 1) {
     return [];
   }
@@ -116,12 +116,10 @@ function intersection(arrayOrCompFn, ...arrays) {
 
 // src/array/range.ts
 function* range(start, end, step = 1) {
-  if (start > end) {
+  if (start > end)
     throw new Error("The start of the range must be less than or equal to the end.");
-  }
-  if (step <= 0) {
+  if (step <= 0)
     throw new Error("The step must be greater than 0.");
-  }
   for (let i = start; i <= end; i += step) {
     yield i;
   }
@@ -404,6 +402,29 @@ function isPlainObject(value) {
   return value?.constructor === Object;
 }
 
+// src/object/flatKeys.ts
+function flatKeys(obj) {
+  const result = {};
+  function addToResult(prefix, value) {
+    if (isPlainObject(value)) {
+      const flatObj = flatKeys(value);
+      for (const [flatKey, flatValue] of Object.entries(flatObj)) {
+        result[`${prefix}.${flatKey}`] = flatValue;
+      }
+    } else if (Array.isArray(value)) {
+      for (const [index, element] of value.entries()) {
+        addToResult(`${prefix}[${index}]`, element);
+      }
+    } else {
+      result[prefix] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    addToResult(key, value);
+  }
+  return result;
+}
+
 // src/object/merge.ts
 function merge(target, ...sources) {
   const targetCopy = { ...target };
@@ -432,18 +453,28 @@ function omit(object, keysToOmit) {
 }
 
 // src/object/set.ts
+var validPathRegex = /^(?:[^.[\]]+(?:\[\d+])*(?:\.|\[\d+]))+(?:[^.[\]]+(?:\[\d+])*)+$/;
+var pathSplitRegex = /\.|(?=\[)/g;
+var matchBracketsRegex = /[[\]]/g;
 function set(obj, path, value) {
-  const pathParts = path.split(/[.[\]]/g).filter((x) => Boolean(x.trim()));
+  if (!validPathRegex.test(path))
+    throw new Error("Invalid path, look at the examples for the correct format.");
+  const pathParts = path.split(pathSplitRegex);
   let currentObj = obj;
   for (let index = 0; index < pathParts.length; index++) {
-    const key = pathParts[index];
+    const key = pathParts[index].replace(matchBracketsRegex, "");
     if (index === pathParts.length - 1) {
       currentObj[key] = value;
       break;
     }
-    const nextIsNumber = !Number.isNaN(Number.parseInt(pathParts[index + 1]));
-    if (currentObj[key] === void 0)
-      currentObj[key] = nextIsNumber ? [] : {};
+    const nextElemIn = pathParts[index + 1].startsWith("[") ? "array" : "object";
+    if (currentObj[key] === void 0) {
+      currentObj[key] = nextElemIn === "array" ? [] : {};
+    } else if (nextElemIn === "array" && !Array.isArray(currentObj[key])) {
+      currentObj[key] = [];
+    } else if (nextElemIn === "object" && !isPlainObject(currentObj[key])) {
+      currentObj[key] = {};
+    }
     currentObj = currentObj[key];
   }
   return obj;
@@ -600,17 +631,18 @@ async function tryCatch(promise) {
 }
 
 // src/string/splitWords.ts
+var splitWordsRegex = new RegExp(
+  "[^\\dA-Za-z]|(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])"
+  // lookahead for an uppercase letter followed by a lowercase letter
+);
 function splitWords(str) {
-  const regex = new RegExp(
-    "[^\\dA-Za-z]|(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])"
-    // lookahead for an uppercase letter followed by a lowercase letter
-  );
-  return str.split(regex).filter(Boolean);
+  return str.split(splitWordsRegex).filter(Boolean);
 }
 
 // src/string/deburr.ts
+var accentControlRegex = /[\u0300-\u036F]/g;
 function deburr(str) {
-  return str.normalize("NFD").replace(/[\u0300-\u036F]/g, "");
+  return str.normalize("NFD").replace(accentControlRegex, "");
 }
 
 // src/string/camelCase.ts
@@ -632,20 +664,22 @@ function capitalize(str) {
 }
 
 // src/string/escapeHtml.ts
+var charRegex = /["&'<>]/g;
+var escapeChars = /* @__PURE__ */ new Map([
+  ["&", "&amp;"],
+  ["<", "&lt;"],
+  [">", "&gt;"],
+  ["'", "&#39;"],
+  ['"', "&quot;"]
+]);
 function escapeHtml(str) {
-  const escapeChars = {
-    "&": "&amp;",
-    "<": "&lt;",
-    ">": "&gt;",
-    "'": "&#39;",
-    '"': "&quot;"
-  };
-  return str.replace(/["&'<>]/g, (char) => escapeChars[char]);
+  return str.replace(charRegex, (char) => escapeChars.get(char));
 }
 
 // src/string/escapeRegExp.ts
+var escapleCharsRegex = /[$()*+.?[\\\]^{|}]/g;
 function escapeRegExp(str) {
-  return str.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+  return str.replace(escapleCharsRegex, "\\$&");
 }
 
 // src/string/kebabCase.ts
@@ -696,15 +730,16 @@ function titleCase(str) {
 }
 
 // src/string/unescapeHtml.ts
+var htmlEntitiesRegex = /&(?:amp|lt|gt|quot|#39);/g;
+var entityMap = /* @__PURE__ */ new Map([
+  ["&amp;", "&"],
+  ["&lt;", "<"],
+  ["&gt;", ">"],
+  ["&quot;", '"'],
+  ["&#39;", "'"]
+]);
 function unescapeHtml(str) {
-  const entityMap = {
-    "&amp;": "&",
-    "&lt;": "<",
-    "&gt;": ">",
-    "&quot;": '"',
-    "&#39;": "'"
-  };
-  return str.replace(/&(?:amp|lt|gt|quot|#(0+)?39);/g, (entity) => entityMap[entity]);
+  return str.replace(htmlEntitiesRegex, (entity) => entityMap.get(entity));
 }
 
 // src/validate/isEmpty.ts
@@ -793,6 +828,7 @@ export {
   dropWhile,
   escapeHtml,
   escapeRegExp,
+  flatKeys,
   group,
   hash,
   intersection,