moderndash 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -6,17 +6,15 @@
  * @param chunkSize - The array to process.
  * @param array - The length of each chunk
  * @example
- * chunk(2, ['a', 'b', 'c', 'd'])
+ * chunk(['a', 'b', 'c', 'd'], 2)
  * // => [['a', 'b'], ['c', 'd']]
  *
- * chunk(3, ['a', 'b', 'c', 'd'])
+ * chunk(['a', 'b', 'c', 'd'], 3)
  * // => [['a', 'b', 'c'], ['d']]
  */
-declare function chunk<TInput>(chunkSize: number, array: TInput[]): TInput[][];
+declare function chunk<TInput>(array: TInput[], chunkSize: number): TInput[][];
 
 type MinimumTwoArrays<TInput> = [TInput[], TInput[], ...TInput[][]];
-type IterateeFunction<T> = (value: T) => unknown;
-type PropertyShorthand<T> = keyof T;
 type RecordKey = string | number | symbol;
 /**
  * @description Generic function type, should fit any function
@@ -46,55 +44,31 @@ type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters
 declare function count<TInput, TKey extends RecordKey>(array: TInput[], iteratee: (value: TInput) => TKey): Record<TKey, number>;
 
 /**
- * Creates an array of `array` values not included in the other given arrays. The order and references of result values are determined by the first array.
- *
- * **Note:** Unlike `pullAll`, this method returns a new array.
+ * Creates an array values not included in the other given arrays.
+ * The order and references of result values are determined by the first array.
  *
- * @category Array
- * @param arrays - First array is inspected, others are excluded.
- * @returns Returns the new array of filtered values.
+ * An compare function is optinal to specify how the elements of the arrays are compared.
+ * Default compare function is {@link isEqual}.
  * @example
  * difference([2, 1], [2, 3])
  * // => [1]
- */
-declare function difference<TInput>(...arrays: MinimumTwoArrays<TInput>): TInput[];
-
-/**
- * This method is like `difference` except that it accepts `iteratee` which
- * is invoked for each element of `array` and `values` to generate the criterion
- * by which they're compared. The order and references of result values are
- * determined by the first array.
  *
- * **Note:** Unlike `pullAllBy`, this method returns a new array.
+ * // ---- Custom compare function ----
+ * intersection((a, b) => Math.floor(a) === Math.floor(b), [1.2, 3.1], [1.3, 2.4])
+ * // => [3.1]
  *
- * @category Array
- * @param iteratee - The iteratee invoked per element. Or property shorthand.
- * @param arrays - First array to inspect. Others are excluded.
-
- * @returns Returns the new array of filtered values.
- * @example
- * differenceBy(Math.floor, [2.1, 1.2], [2.3, 3.4])
- * // => [1.2]
- * differenceBy('x', [{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }])
- * // => [{ 'x': 2 }]
- */
-declare function differenceBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>, ...arrays: MinimumTwoArrays<T>): T[];
-
-/**
- * This method is like `difference` except that it accepts `comparator`
- * which is invoked to compare elements of `array` to `values`.
- * The order and references of result values are determined by the first array.
- * The comparator is invoked with two arguments: (arrVal, othVal).
+ * // ---- Only compare by id ----
+ * const arr1 = [{ id: 1, name: 'Yeet' }, { id: 3, name: 'John' }];
+ * const arr2 = [{ id: 3, 'Carl' }, { id: 4, name: 'Max' }];
  *
- * @example
- * differenceWith(isEqual, [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }], [{ 'x': 1, 'y': 2 }])
- * // => [{ 'x': 2, 'y': 1 }]
+ * difference((a, b) => a.id === b.id, arr1, arr2)
+ * // => [{ id: 1, name: 'Yeet' }]
  * @category Array
- * @param comparator - The comparator invoked per element.
- * @param arrays - First array to inspect. Others are excluded.
+ * @param arrays - First array is inspected, others are excluded.
  * @returns Returns the new array of filtered values.
  */
-declare function differenceWith<T>(comparator: (a: T, b: T) => boolean, ...arrays: MinimumTwoArrays<T>): T[];
+declare function difference<TArr>(...arrays: MinimumTwoArrays<TArr>): TArr[];
+declare function difference<TArr>(arrayOrCompFn: (a: TArr, b: TArr) => boolean, ...arrays: MinimumTwoArrays<TArr>): TArr[];
 
 /**
  * Creates a slice of `array` excluding elements dropped from the end.
@@ -162,50 +136,29 @@ declare function group<T, U extends RecordKey>(array: T[], iteratee: (value: T)
  * Creates an array of unique values that are included in all given arrays.
  * The order and references of result values are determined by the first array.
  *
- * @category Array
- * @param arrays - The arrays to inspect.
- * @returns Returns the new array of intersecting values.
+ * An compare function is optinal to specify how the elements of the arrays are compared.
+ * Default compare function is {@link isEqual}.
+ *
  * @example
  * intersection([2, 1], [2, 3])
  * // => [2]
- */
-declare function intersection<TInput>(...arrays: MinimumTwoArrays<TInput>): TInput[];
-
-/**
- * This method is like `intersection` except that it accepts `iteratee`
- * which is invoked for each element of each `arrays` to generate the criterion
- * by which they're compared. The order and references of result values are
- * determined by the first array. The iteratee is invoked with one argument:
- * (value).
  *
- * @example
- * intersectionBy(Math.floor, [2.1, 1.2], [2.3, 3.4])
- * // => [2.1]
- * @category Array
- * @param iteratee - The iteratee invoked per element. Or property shorthand.
- * @param arrays - The arrays to inspect.
- * @returns Returns the new array of intersecting values.
- */
-declare function intersectionBy<TInput>(iteratee: IterateeFunction<TInput> | PropertyShorthand<TInput>, ...arrays: MinimumTwoArrays<TInput>): TInput[];
-
-/**
- * This method is like `intersection` except that it accepts `comparator`
- * which is invoked to compare elements of `arrays`. The order and references
- * of result values are determined by the first array. The comparator is
- * invoked with two arguments: (arrVal, othVal).
+ * // ---- Custom compare function ----
+ * intersection((a, b) => Math.floor(a) === Math.floor(b), [1.2, 1.1], [1.3, 2.4])
+ * // => [1.2]
  *
- * @example
- * const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
- * const others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }]
+ * // ---- Only compare by id ----
+ * const arr1 = [{ id: 1, name: 'Yeet' }, { id: 3, name: 'John' }];
+ * const arr2 = [{ id: 3, 'Carl' }, { id: 4, name: 'Max' }];
  *
- * intersectionWith(isEqual, objects, others)
- * // => [{ 'x': 1, 'y': 2 }]
+ * intersection((a, b) => a.id === b.id, arr1, arr2)
+ * // => [{ id: 3, name: 'John' }]
  * @category Array
- * @param comparator - The comparator invoked per element.
  * @param arrays - The arrays to inspect.
  * @returns Returns the new array of intersecting values.
  */
-declare function intersectionWith<T>(comparator: (a: T, b: T) => boolean, ...arrays: MinimumTwoArrays<T>): T[];
+declare function intersection<TArr>(...arrays: MinimumTwoArrays<TArr>): TArr[];
+declare function intersection<TArr>(arrayOrCompFn: (a: TArr, b: TArr) => boolean, ...arrays: MinimumTwoArrays<TArr>): TArr[];
 
 /**
  * Gets a random element from `array`.
@@ -313,7 +266,7 @@ declare function takeWhile<T>(array: T[], predicate: (elem: T) => boolean): T[];
  * Creates a duplicate-free version of an array, in which only the first occurrence of each element is kept.
  * The order of result values is determined by the order they occur in the array.
  *
- * An iteratee function is optional, to specify the value to be compared.
+ * An compare function is optinal to specify how the array is compared.
  *
  * @example
  * unique([2, 1, 2])
@@ -324,7 +277,7 @@ declare function takeWhile<T>(array: T[], predicate: (elem: T) => boolean): T[];
  *      { id: 1, name: 'c' }
  * ]
  *
- * unique(users, value => value.id)
+ * unique(users, (a, b) => a.id === b.id)
  * // => [{ id: 1, name: 'a' }]
  *
  *
@@ -333,70 +286,7 @@ declare function takeWhile<T>(array: T[], predicate: (elem: T) => boolean): T[];
  * @param iteratee - The iteratee invoked per element.
  * @returns Returns the new duplicate free array.
  */
-declare function unique<TInput>(array: TInput[], iteratee?: IterateeFunction<TInput>): TInput[];
-
-/**
- * This method is like `zip` except that it accepts an array of grouped
- * elements and creates an array regrouping the elements to their pre-zip configuration.
- *
- * @example
- * const zipped = zip(['a', 'b'], [1, 2], [true, false])
- * // => [['a', 1, true], ['b', 2, false]]
- *
- * unzip(zipped)
- * // => [['a', 'b'], [1, 2], [true, false]]
- * @category Array
- * @param array - The array of grouped elements to process.
- * @returns Returns the new array of regrouped elements.
- */
-declare function unzip<TInput extends unknown[]>(array: TInput[]): TInput[];
-
-/**
- * This method is like `unzip` except that it accepts `iteratee` to specify how regrouped values should be combined.
- *
- * @example
- * const zipped = zip([1, 2], [10, 20], [100, 200])
- * // => [[1, 10, 100], [2, 20, 200]]
- *
- * unzipWith(add, zipped)
- * // => [3, 30, 300]
- * @category Array
- * @param iteratee - The function to combine regrouped values.
- * @param array - The array of grouped elements to process.
- * @returns Returns the new array of regrouped elements.
- */
-declare function unzipWith<TInput extends unknown[], TOutput>(array: TInput[], iteratee: (...t: TInput) => TOutput): TOutput[];
-
-/**
- * Creates an array of grouped elements, the first of which contains the first elements of the given arrays,
- * the second of which contains the second elements of the given arrays, and so on.
- *
- * @category Array
- * @param arrays - The arrays to process.
- * @returns Returns the new array of grouped elements.
- * @example
- * zip(['a', 'b'], [1, 2], [true, false])
- * // => [['a', 1, true], ['b', 2, false]]
- */
-declare function zip<TInput>(...arrays: TInput[][]): TInput[][];
-
-type UnZip<A extends readonly unknown[]> = {
-    [K in keyof A]: readonly A[K][];
-};
-/**
- * This method is like `zip` except that it accepts `iteratee` to specify
- * how grouped values should be combined. The iteratee is invoked with the
- * elements of each group: (...group).
- *
- * @category Array
- * @param combineFunc - The function to combine grouped values.
- * @param arrays - The arrays to process.
- * @returns Returns the new array of grouped elements.
- * @example
- * zipWith([1, 2], [10, 20], [100, 200], (a, b, c) => a + b + c)
- * // => [111, 222]
- */
-declare function zipWith<Args extends unknown[], TOutput>(combineFunc: (...args: Args) => TOutput, ...arrays: UnZip<Args>): TOutput[];
+declare function unique<TInput>(array: TInput[], compareFn?: (a: TInput, b: TInput) => boolean): TInput[];
 
 /**
  * The opposite of `before`. This method creates a function that invokes `func` once it's called `n` or more times.
@@ -730,11 +620,13 @@ declare function unescapeHtml(str: string): string;
 /**
  * A `number` that is an integer.
  * You can't pass a `bigint` as they are already guaranteed to be integers.
+ *
  * Use-case: Validating and documenting parameters.
  * @example
- * function setYear<T extends number>(length: Integer<T>) {
- *  // ...
- * };
+ * function setYear<T extends number>(x: Integer<T>){};
+ *
+ * setYear(1); // OK
+ * setYear(1.1); // Error
  * @category type
 */
 type Integer<T extends number> = `${T}` extends `${bigint}` ? T : never;
@@ -744,9 +636,10 @@ type Integer<T extends number> = `${T}` extends `${bigint}` ? T : never;
  * You can't pass a `bigint` as they are already guaranteed to be integers.
  * Use-case: Validating and documenting parameters.
  * @example
- * function setPercentage<T extends number>(length: Float<T>) {
- *   // ...
- * };
+ * function setPercentage<T extends number>(x: Float<T>) {};
+ *
+ * setPercentage(1.1); // OK
+ * setPercentage(1); // Error
  *
  * @category type
 */
@@ -754,32 +647,40 @@ type Float<T extends number> = T extends Integer<T> ? never : T;
 
 /**
  * A negative `number`/`bigint` (`-∞ < x < 0`)
+ *
  * Use-case: Validating and documenting parameters.
  * @example
- * function setLength<T extends number>(length: Negative<T>) {
- *    // ...
- *  };
+ * function setNegative<T extends number>(x: Negative<T>) {};
+ *
+ * setNegative(-1.2); // OK
+ * setNegative(1); // Error
+ *
+ * function setNegInt<T extends number>(x: Negative<Integer<T>>) {};
  *
- * function setLength<T extends number>(length: Negative<Integer<T>>) {
- *   // ...
- *  };
+ * setNegInt(-1); // OK
+ * setNegInt(1); // Error
+ * setNegInt(-1.1); // Error
  * @category type
 */
 type Negative<T extends number | bigint> = T extends 0 | 0n ? never : `${T}` extends `-${string}` ? T : never;
 
 /**
-A positive `number`/`bigint` (`0 < x < ∞`).
-Use-case: Validating and documenting parameters.
-@example
-function setLength<T extends number>(length: Positive<T>) {
-    // ...
-};
-
-function setLength<T extends number>(length: Positive<Integer<T>>) {
-    // ...
-};
-
-@category type
+ * A positive `number`/`bigint` (`0 < x < ∞`).
+ *
+ * Use-case: Validating and documenting parameters.
+ * @example
+ * function setPositive<T extends number>(x: Positive<T>) {};
+ *
+ * setPositive(1.2); // OK
+ * setPositive(-1); // Error
+ *
+ * function setPosInt<T extends number>(x: Positive<Integer<T>>) {};
+ *
+ * setPosInt(1); // OK
+ * setPosInt(-1); // Error
+ * setPosInt(1.1); // Error
+ *
+ * @category type
 */
 type Positive<T extends number | bigint> = T extends 0 | 0n ? never : Negative<T> extends never ? T : never;
 
@@ -857,4 +758,4 @@ declare function isPlainObject(value: unknown): value is object;
  */
 declare function isUrl(str: string): boolean;
 
-export { Float, Integer, Negative, Positive, after, before, camelCase, capitalize, chunk, count, debounce, deburr, difference, differenceBy, differenceWith, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, intersectionBy, intersectionWith, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, memoize, omit, once, pascalCase, pick, sample, sampleSize, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, times, unescapeHtml, unique, unzip, unzipWith, zip, zipWith };
+export { Float, Integer, Negative, Positive, after, before, camelCase, capitalize, chunk, count, debounce, deburr, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, memoize, omit, once, pascalCase, pick, sample, sampleSize, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, times, unescapeHtml, unique };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/array/chunk.ts
-function chunk(chunkSize, array) {
+function chunk(array, chunkSize) {
   const sizeInteger = Math.trunc(chunkSize);
   if (array.length === 0 || sizeInteger < 1) {
     return [];
@@ -27,18 +27,6 @@ function count(array, iteratee) {
   return result;
 }
 
-// src/array/differenceWith.ts
-function differenceWith(comparator, ...arrays) {
-  const difference2 = [];
-  const [firstArray, ...restArrays] = arrays;
-  firstArray.forEach((element) => {
-    if (!restArrays.some((array) => array.some((item) => comparator(item, element)))) {
-      difference2.push(element);
-    }
-  });
-  return difference2;
-}
-
 // src/validate/isEqual.ts
 function isEqual(value1, value2) {
   if (value1 === value2)
@@ -79,33 +67,17 @@ function isSameArray(value1, value2) {
 }
 
 // src/array/difference.ts
-function difference(...arrays) {
-  return differenceWith(isEqual, ...arrays);
-}
-
-// src/helpers/typeofChecks.ts
-function isObjectKey(key) {
-  return typeof key === "string" || typeof key === "number" || typeof key === "symbol";
-}
-
-// src/helpers/shortHands.ts
-function getPropertyShorthand(key) {
-  return (object) => object[key];
-}
-function getIterateFunction(iteratee) {
-  if (typeof iteratee === "function") {
-    return iteratee;
-  } else if (isObjectKey(iteratee)) {
-    return getPropertyShorthand(iteratee);
-  } else {
-    throw new TypeError("Expected iteratee to be a function or a property name");
-  }
-}
-
-// src/array/differenceBy.ts
-function differenceBy(iteratee, ...arrays) {
-  const iterateeFn = getIterateFunction(iteratee);
-  return differenceWith((a, b) => isEqual(iterateeFn(a), iterateeFn(b)), ...arrays);
+function difference(arrayOrCompFn, ...arrays) {
+  const withCompareFn = typeof arrayOrCompFn === "function";
+  const compareFN = withCompareFn ? arrayOrCompFn : isEqual;
+  const [firstArray, ...restArrays] = withCompareFn ? arrays : [arrayOrCompFn, ...arrays];
+  const difference2 = [];
+  firstArray.forEach((element) => {
+    if (!restArrays.some((array) => array.some((item) => compareFN(item, element)))) {
+      difference2.push(element);
+    }
+  });
+  return difference2;
 }
 
 // src/array/dropRightWhile.ts
@@ -134,29 +106,20 @@ function group(array, iteratee) {
   return result;
 }
 
-// src/array/intersectionWith.ts
-function intersectionWith(comparator, ...arrays) {
+// src/array/intersection.ts
+function intersection(arrayOrCompFn, ...arrays) {
+  const withCompareFn = typeof arrayOrCompFn === "function";
+  const compareFN = withCompareFn ? arrayOrCompFn : isEqual;
+  const [firstArray, ...restArrays] = withCompareFn ? arrays : [arrayOrCompFn, ...arrays];
   const intersection2 = [];
-  const [firstArray, ...restArrays] = arrays;
   firstArray.forEach((element) => {
-    if (restArrays.every((array) => array.some((item) => comparator(item, element)))) {
+    if (restArrays.every((array) => array.some((item) => compareFN(item, element)))) {
       intersection2.push(element);
     }
   });
   return intersection2;
 }
 
-// src/array/intersection.ts
-function intersection(...arrays) {
-  return intersectionWith(isEqual, ...arrays);
-}
-
-// src/array/intersectionBy.ts
-function intersectionBy(iteratee, ...arrays) {
-  const iterateeFn = getIterateFunction(iteratee);
-  return intersectionWith((a, b) => isEqual(iterateeFn(a), iterateeFn(b)), ...arrays);
-}
-
 // src/array/sample.ts
 function sample(array) {
   if (array.length === 0) {
@@ -236,42 +199,12 @@ function takeWhile(array, predicate) {
 }
 
 // src/array/unique.ts
-function unique(array, iteratee) {
-  const compareFn = (a, b) => isEqual(iteratee ? iteratee(a) : a, iteratee ? iteratee(b) : b);
+function unique(array, compareFn = (a, b) => isEqual(a, b)) {
   return array.filter((value, index, self) => {
     return self.findIndex((otherValue) => compareFn(value, otherValue)) === index;
   });
 }
 
-// src/array/unzipWith.ts
-function unzipWith(array, iteratee) {
-  const result = [];
-  for (const elements of array) {
-    result.push(iteratee(...elements));
-  }
-  return result;
-}
-
-// src/array/unzip.ts
-function unzip(array) {
-  return unzipWith(array, (...t) => t);
-}
-
-// src/array/zipWith.ts
-function zipWith(combineFunc, ...arrays) {
-  const len = Math.min(...arrays.map((a) => a.length));
-  const zipped = [];
-  for (let i = 0; i < len; i++) {
-    zipped[i] = combineFunc(...arrays.map((a) => a[i]));
-  }
-  return zipped;
-}
-
-// src/array/zip.ts
-function zip(...arrays) {
-  return zipWith((...t) => t, ...arrays);
-}
-
 // src/function/after.ts
 function after(n, func) {
   let count2 = 1;
@@ -596,16 +529,12 @@ export {
   debounce,
   deburr,
   difference,
-  differenceBy,
-  differenceWith,
   dropRightWhile,
   dropWhile,
   escapeHtml,
   escapeRegExp,
   group,
   intersection,
-  intersectionBy,
-  intersectionWith,
   isEmpty,
   isEqual,
   isPlainObject,
@@ -629,10 +558,6 @@ export {
   throttle,
   times,
   unescapeHtml,
-  unique,
-  unzip,
-  unzipWith,
-  zip,
-  zipWith
+  unique
 };
 //# sourceMappingURL=index.js.map