moderndash 2.1.2 → 2.1.4

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  * @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[], size: 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.
@@ -98,7 +98,7 @@ declare function difference<TElem>(arrayOrCompFn: (a: TElem, b: TElem) => boolea
  * @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.
@@ -118,7 +118,7 @@ declare function dropRightWhile<TElem>(array: TElem[], predicate: (value: TElem)
  * @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 criteria The criteria to group by.
+ * @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[], criteria: (value: TElem) => TKey | boolean): 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[], criteria
  * 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.
@@ -237,9 +240,10 @@ declare function sort<TInput>(array: TInput[], ...orders: {
  * // => 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.
@@ -256,9 +260,10 @@ declare function takeRightWhile<TArr>(array: TArr[], predicate: (elem: TArr) =>
  * // => 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;
@@ -742,7 +748,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 +761,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 +787,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.
@@ -813,6 +819,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 +848,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 +863,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.
@@ -870,6 +879,7 @@ declare function pick<TInput extends PlainObject, Key extends keyof TInput>(obje
  * @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;

package/dist/index.js

@@ -23,17 +23,31 @@ function count(array, criteria) {
   return result;
 }
 
+// src/helpers/fastArrayFlat.ts
+function fastArrayFlat(arrays) {
+  let result = arrays.shift() ?? [];
+  for (const array of arrays) {
+    result = [...result, ...array];
+  }
+  return result;
+}
+
 // src/array/difference.ts
 function difference(arrayOrCompFn, ...arrays) {
   const withCompareFn = typeof arrayOrCompFn === "function";
-  const compareFN = withCompareFn ? arrayOrCompFn : (a, b) => a === b;
-  const [firstArray, ...restArrays] = withCompareFn ? arrays : [arrayOrCompFn, ...arrays];
+  const firstArray = withCompareFn ? arrays.shift() : arrayOrCompFn;
+  const combinedRestArray = fastArrayFlat(arrays);
+  if (!withCompareFn) {
+    const restSet = new Set(combinedRestArray);
+    return firstArray.filter((element) => !restSet.has(element));
+  }
+  const compareFN = arrayOrCompFn;
   const difference2 = [];
-  firstArray.forEach((element) => {
-    if (!restArrays.some((array) => array.some((item) => compareFN(item, element)))) {
+  for (const element of firstArray) {
+    if (combinedRestArray.every((item) => !compareFN(item, element))) {
       difference2.push(element);
     }
-  });
+  }
   return difference2;
 }
 
@@ -53,14 +67,11 @@ function dropWhile(array, predicate) {
 }
 
 // src/array/group.ts
-function group(array, criteria) {
+function group(array, getGroupKey) {
   const result = {};
-  for (const value of array) {
-    let key = criteria(value);
-    if (typeof key === "boolean")
-      key = key.toString();
-    result[key] = result[key] ?? [];
-    result[key].push(value);
+  for (const elem of array) {
+    const key = getGroupKey(elem);
+    (result[key] ??= []).push(elem);
   }
   return result;
 }
@@ -88,28 +99,27 @@ function unique(array, compareFn) {
 function intersection(arrayOrCompFn, ...arrays) {
   const withCompareFn = typeof arrayOrCompFn === "function";
   const firstArray = unique(withCompareFn ? arrays.shift() : arrayOrCompFn);
+  const combinedRestArray = fastArrayFlat(arrays);
   if (!withCompareFn) {
-    const restSets = arrays.map((array) => new Set(array));
-    return firstArray.filter((element) => restSets.every((set2) => set2.has(element)));
+    const restSet = new Set(combinedRestArray);
+    return firstArray.filter((element) => restSet.has(element));
   }
   const compareFN = arrayOrCompFn;
   const intersection2 = [];
-  firstArray.forEach((element) => {
-    if (arrays.every((array) => array.some((item) => compareFN(item, element)))) {
+  for (const element of firstArray) {
+    if (combinedRestArray.some((item) => compareFN(item, element))) {
       intersection2.push(element);
     }
-  });
+  }
   return intersection2;
 }
 
 // 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;
   }