moderndash 0.0.16 → 0.0.18

package/dist/index.d.ts

@@ -18,13 +18,33 @@ type MinimumTwoArrays<TInput> = [TInput[], TInput[], ...TInput[][]];
 type IterateeFunction<T> = (value: T) => unknown;
 type PropertyShorthand<T> = keyof T;
 type RecordKey = string | number | symbol;
-type ArrayOrRecord<TInput> = TInput[] | Record<RecordKey, TInput>;
 type NoUnion<T, U = T> = T extends U ? [U] extends [T] ? T : never : never;
 /**
  * @description Generic function type, should fit any function
  * @typeParam TFunc - The input function type
  */
-type GenericFunction<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>> = (...args: Parameters<TFunc>) => ReturnType<TFunc>;
+type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters<TFunc>) => ReturnType<TFunc>;
+
+/**
+ * Creates an object composed of keys generated from the results of running
+ * each element of `collection` thru `iteratee`. The corresponding value of
+ * each key is the number of times the key was returned by `iteratee`.
+ *
+ * @example
+ * const users = [
+ *   { 'user': 'barney', 'active': true },
+ *   { 'user': 'betty', 'active': true },
+ *   { 'user': 'fred', 'active': false }
+ * ]
+ *
+ * count(users, value => value.active);
+ * // => { 'true': 2, 'false': 1 }
+ * @category Array
+ * @param iteratee - The iteratee to transform keys.
+ * @param collection - The array or record to iterate over.
+ * @returns Returns the composed aggregate object.
+ */
+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.
@@ -63,19 +83,17 @@ declare function differenceBy<T>(iteratee: IterateeFunction<T> | PropertyShortha
 
 /**
  * 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).
- *
- * **Note:** Unlike `pullAllWith`, this method returns a new array.
+ * 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).
  *
+ * @example
+ * differenceWith(isEqual, [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }], [{ 'x': 1, 'y': 2 }])
+ * // => [{ 'x': 2, 'y': 1 }]
  * @category Array
  * @param comparator - The comparator invoked per element.
  * @param arrays - First array to inspect. Others are excluded.
  * @returns Returns the new array of filtered values.
- * @example
- * differenceWith(isEqual, [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }], [{ 'x': 1, 'y': 2 }])
- * // => [{ 'x': 2, 'y': 1 }]
  */
 declare function differenceWith<T>(comparator: (a: T, b: T) => boolean, ...arrays: MinimumTwoArrays<T>): T[];
 
@@ -98,7 +116,7 @@ declare function differenceWith<T>(comparator: (a: T, b: T) => boolean, ...array
  * dropRightWhile(({ active }) => active, users)
  * // => objects for ['barney']
  */
-declare function dropRightWhile<T>(predicate: (value: T) => boolean, array: T[]): T[];
+declare function dropRightWhile<T>(array: T[], predicate: (value: T) => boolean): T[];
 
 /**
  * Creates a slice of `array` excluding elements dropped from the beginning.
@@ -119,7 +137,27 @@ declare function dropRightWhile<T>(predicate: (value: T) => boolean, array: T[])
  * dropWhile(({ active }) => active, users)
  * // => objects for ['pebbles']
  */
-declare function dropWhile<T>(predicate: (value: T) => boolean, array: T[]): T[];
+declare function dropWhile<T>(array: T[], predicate: (value: T) => boolean): T[];
+
+/**
+ * Creates an object composed of keys generated from the results of running
+ * each element of `collection` thru `iteratee`. The order of grouped values
+ * is determined by the order they occur in `collection`. The corresponding
+ * value of each key is an array of elements responsible for generating the
+ * key.
+ *
+ * @example
+ * 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] }
+ * @category Array
+ * @param collection - The array or object to iterate over.
+ * @param iteratee - The iteratee to transform keys.
+ * @returns Returns the composed aggregate object.
+ */
+declare function group<T, U extends RecordKey>(array: T[], iteratee: (value: T) => U): Record<U, T[]>;
 
 /**
  * Creates an array of unique values that are included in all given arrays.
@@ -173,14 +211,14 @@ declare function intersectionWith<T>(comparator: (a: T, b: T) => boolean, ...arr
 /**
  * Gets a random element from `array`.
  *
- * @category Array
- * @param array - The array to sample.
- * @returns Returns the random element.
  * @example
  * sample([1, 2, 3, 4])
  * // => 2
+ * @category Array
+ * @param array - The array to sample.
+ * @returns Returns the random element.
  */
-declare function sample<T>(array: T[]): T | undefined;
+declare function sample<TInput>(array: TInput[]): TInput | undefined;
 
 /**
  * Gets `n` random elements at unique keys from `array` up to the
@@ -197,22 +235,39 @@ declare function sample<T>(array: T[]): T | undefined;
  * sampleSize([1, 2, 3], 4)
  * // => [2, 3, 1]
  */
-declare function sampleSize<TInput>(size: number, array: TInput[]): TInput[];
+declare function sampleSize<TInput>(array: TInput[], size: number): TInput[];
 
 /**
  * Creates an array of shuffled values, using a version of the
  * [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle).
  *
- * @since 0.1.0
- * @category Array
- * @param array - The array or object to shuffle.
- * @returns Returns the new shuffled array.
  * @example
  * shuffle([1, 2, 3, 4])
  * // => [4, 1, 3, 2]
+ * @category Array
+ * @param array - The array or object to shuffle.
+ * @returns Returns the new shuffled array.
  */
 declare function shuffle<TInput>(array: TInput[]): TInput[];
 
+/**
+ * Sorts the array in ascending or descending order.
+ * An iteratee function is optional to sort the array based on a specific property.
+ *
+ * @example
+ * sort([1, 2, 3, 4], 'desc')
+ * // => [4, 3, 2, 1]
+ *
+ * sort([{ a: 1 }, { a: 2 }, { a: 3 }], 'asc', item => item.a)
+ * // => [{ a: 1 }, { a: 2 }, { a: 3 }]
+ * @category Array
+ * @param array - The array to sort.
+ * @param order - The order in which to sort the array.
+ * @param iteratee - The iteratee function to sort the array based on a specific property.
+ * @returns Returns the sorted array.
+ */
+declare function sort<TInput>(array: TInput[], order?: 'asc' | 'desc', iteratee?: (item: TInput) => number | bigint | Date | string): TInput[];
+
 /**
  * Creates a slice of `array` with elements taken from the end. Elements are
  * taken until `predicate` returns falsey. The predicate is invoked with
@@ -253,7 +308,7 @@ declare function takeRightWhile<T>(predicate: (elem: T) => boolean, array: T[]):
  * takeWhile(({ active }) => active, users)
  * // => objects for ['barney', 'fred']
  */
-declare function takeWhile<T>(predicate: (elem: T) => boolean, array: T[]): T[];
+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.
@@ -282,7 +337,7 @@ declare function uniq<TInput>(array: TInput[]): TInput[];
  * uniqBy(Math.floor, [2.1, 1.2, 2.3])
  * // => [2.1, 1.2]
  */
-declare function uniqBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>, array: T[]): T[];
+declare function uniqBy<T>(array: T[], iteratee: IterateeFunction<T> | PropertyShorthand<T>): T[];
 
 /**
  * This method is like `uniq` except that it accepts `comparator` which is invoked to compare elements of `array`.
@@ -298,41 +353,39 @@ declare function uniqBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>,
  * uniqWith(isEqual, objects)
  * // => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
  */
-declare function uniqWith<TInput>(comparator: (a: TInput, b: TInput) => boolean, array: TInput[]): TInput[];
+declare function uniqWith<TInput>(array: TInput[], comparator: (a: TInput, b: TInput) => boolean): 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.
  *
- * @category Array
- * @param array - The array of grouped elements to process.
- * @returns Returns the new array of regrouped elements.
  * @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. The iteratee is invoked with the
- * elements of each group: (...group).
+ * This method is like `unzip` except that it accepts `iteratee` to specify how regrouped values should be combined.
  *
- * @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.
  * @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>(iteratee: (...t: TInput) => TOutput, array: TInput[]): TOutput[];
+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,
@@ -365,62 +418,21 @@ type UnZip<A extends readonly unknown[]> = {
  */
 declare function zipWith<Args extends unknown[], TOutput>(combineFunc: (...args: Args) => TOutput, ...arrays: UnZip<Args>): TOutput[];
 
-/**
- * Creates an object composed of keys generated from the results of running
- * each element of `collection` thru `iteratee`. The corresponding value of
- * each key is the number of times the key was returned by `iteratee`.
- *
- * @example
- * const users = [
- *   { 'user': 'barney', 'active': true },
- *   { 'user': 'betty', 'active': true },
- *   { 'user': 'fred', 'active': false }
- * ]
- *
- * countBy(users, value => value.active);
- * // => { 'true': 2, 'false': 1 }
- * @category Collection
- * @param iteratee - The iteratee to transform keys.
- * @param collection - The array or record to iterate over.
- * @returns Returns the composed aggregate object.
- */
-declare function countBy<TInput, TKey extends RecordKey>(collection: ArrayOrRecord<TInput>, iteratee: (value: TInput) => TKey): Record<TKey, number>;
-
-/**
- * Creates an object composed of keys generated from the results of running
- * each element of `collection` thru `iteratee`. The order of grouped values
- * is determined by the order they occur in `collection`. The corresponding
- * value of each key is an array of elements responsible for generating the
- * key.
- *
- * @example
- * groupBy([6.1, 4.2, 6.3], Math.floor)
- * // => { '4': [4.2], '6': [6.1, 6.3] }
- * @category Collection
- * @param collection - The array or object to iterate over.
- * @param iteratee - The iteratee to transform keys.
- * @returns Returns the composed aggregate object.
- */
-declare function groupBy<T, U extends RecordKey>(collection: ArrayOrRecord<T>, iteratee: (value: T) => U): Record<U, T[]>;
-
-declare function sortBy<T, U>(iteratee: (item: T) => NoUnion<number | bigint | Date | string, U>, array: T[]): T[];
-
 /**
  * The opposite of `before`. This method creates a function that invokes `func` once it's called `n` or more times.
  *
- * @category Function
- * @param n The number of calls before `func` is invoked.
- * @param func The function to restrict.
- * @returns Returns the new restricted function.
  * @example
  * const caution = () => console.log("Caution!");
- *
  * const afterFN = after(2, caution);
  *
  * afterFN()
  * afterFN()
  * afterFN()
  * // => `caution` is invoked after called twice
+ * @category Function
+ * @param n The number of calls before `func` is invoked.
+ * @param func The function to restrict.
+ * @returns Returns the new restricted function.
  */
 declare function after<TFunc extends GenericFunction<TFunc>>(n: number, func: TFunc): (...args: Parameters<TFunc>) => ReturnType<TFunc> | undefined;
 
@@ -443,7 +455,7 @@ declare function after<TFunc extends GenericFunction<TFunc>>(n: number, func: TF
  * reducedCaution()
  * // => `caution` is invoked twice
  */
-declare function before<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>>(n: number, func: TFunc): TFunc;
+declare function before<TFunc extends GenericFunction<TFunc>>(n: number, func: TFunc): TFunc;
 
 declare function debounce<TFunc extends GenericFunction<TFunc>>(fn: TFunc, wait?: number, options?: {
     leading?: boolean;
@@ -457,18 +469,12 @@ declare function debounce<TFunc extends GenericFunction<TFunc>>(fn: TFunc, wait?
  * arguments provided to the memoized function. By default, all arguments
  * provided to the memoized function are used as the map cache key.
  *
- * **Note:** The cache is exposed as the `cache` property on the memoized
+ * The cache is exposed as the `cache` property on the memoized
  * function. Its creation may be customized by replacing the `memoize.Cache`
  * constructor with one whose instances implement the
  * [`Map`](http://ecma-international.org/ecma-262/7.0/#sec-properties-of-the-map-prototype-object)
  * method interface of `clear`, `delete`, `get`, `has`, and `set`.
  *
- * @category Function
- * @param func - The function to have its output memoized.
- * @param resolver - The function to resolve the cache key.
- * @typeParam TFunc - The input function type
- * @typeParam Cache - The cache map type
- * @returns  Returns the new memoized function.
  * @example
  * const object = \{ 'a': 1, 'b': 2 \}
  *
@@ -490,24 +496,28 @@ declare function debounce<TFunc extends GenericFunction<TFunc>>(fn: TFunc, wait?
  *
  * // Replace `memoize.Cache`.
  * memoize.Cache = WeakMap
+ * @category Function
+ * @param func - The function to have its output memoized.
+ * @param resolver - The function to resolve the cache key.
+ * @returns  Returns the new memoized function.
  */
 declare function memoize<TFunc extends GenericFunction<TFunc>, Cache extends Map<string | symbol, ReturnType<TFunc>>>(func: TFunc, resolver?: ((...args: Parameters<TFunc>) => string | symbol)): TFunc & {
     cache: Cache;
 };
 
 /**
- * Creates a function that is restricted to invoking `func` once. Repeat calls
- * to the function return the value of the first invocation. The `func` is
- * invoked with the `this` binding and arguments of the created function.
+ * Creates a function that is restricted to invoking `func` once.
+ * Repeat calls to the function return the value of the first invocation.
  *
- * @category Function
- * @param func - The function to restrict.
- * @returns Returns the new restricted function.
  * @example
  * const initialize = once(() => console.log('initialize'))
  * initialize()
  * initialize()
  * // => `createApplication` is invoked once
+ *
+ * @category Function
+ * @param func - The function to restrict.
+ * @returns Returns the new restricted function.
  */
 declare function once<TFunc extends GenericFunction<TFunc>>(func: TFunc): TFunc;
 
@@ -517,8 +527,10 @@ declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wai
 }): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc>;
 
 /**
- * Invokes the iteratee `n` times, returning an array of the results of
- * each invocation. The function is invoked with one argument: (index).
+ * Invokes a function `n` times, returning an array of the results of
+ * each invocation.
+ *
+ * The function is invoked with one argument: `index`
  *
  * @example
  * times(3, index => console.log("Run", index)))
@@ -529,10 +541,10 @@ declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wai
  * // => [0, 0, 0, 0]
  * @category Function
  * @param n - The number of times to invoke `func`.
- * @param iteratee - The function invoked per iteration.
- * @returns Returns the array of results.
+ * @param func - The function invoked per iteration.
+ * @returns Returns an array of results.
  */
-declare function times<T>(n: number, func: (index: number) => T): T[];
+declare function times<TInput>(n: number, func: (index: number) => TInput): TInput[];
 
 /**
  * Checks if `value` is an empty object, collection, map, or set.
@@ -543,9 +555,6 @@ declare function times<T>(n: number, func: (index: number) => T): T[];
  * Array-like values such as `arguments` objects, arrays, buffers, strings, or
  * Similarly, maps and sets are considered empty if they have a `size` of `0`.
  *
- * @category Lang
- * @param value - The value to check.
- * @returns Returns `true` if `value` is empty, else `false`.
  * @example
  * isEmpty(null)
  * // => true
@@ -564,6 +573,9 @@ declare function times<T>(n: number, func: (index: number) => T): T[];
  *
  * isEmpty({ 'a': 1 })
  * // => false
+ * @category Lang
+ * @param value - The value to check.
+ * @returns Returns `true` if given vlaue is empty, else `false`.
  */
 declare function isEmpty(value: string | object | null | undefined): boolean;
 
@@ -585,7 +597,7 @@ declare function isEmpty(value: string | object | null | undefined): boolean;
  * var object = { 'a': 1 };
  * var other = { 'a': 1 };
  *
- * _.isEqual(object, other);
+ * isEqual(object, other);
  * // => true
  *
  * object === other;
@@ -600,10 +612,6 @@ declare function isEqual(value1: unknown, value2: unknown): boolean;
  * six arguments: (objValue, othValue [, index|key, object, other, stack]).
  *
  * @category Lang
- * @param value1 - The value to compare.
- * @param value2 - The other value to compare.
- * @param customizer - The function to customize comparisons.
- * @returns Returns `true` if the values are equivalent, else `false`.
  * @example
  * function isGreeting(value) {
  *   return /^h(?:i|ello)$/.test(value);
@@ -620,6 +628,10 @@ declare function isEqual(value1: unknown, value2: unknown): boolean;
  *
  * isEqualWith(array, other, customizer);
  * // => true
+ * @param a - The value to compare.
+ * @param b - The other value to compare.
+ * @param customizer - The function to customize comparisons.
+ * @returns Returns `true` if the values are equivalent, else `false`.
 */
 declare function isEqualWith<T>(a: T, b: T, customizer: (value: T) => unknown): boolean;
 
@@ -638,7 +650,7 @@ declare function isPlainObject(value: unknown): value is object;
  * @param keys - The property paths to pick.
  * @returns Returns the new object.
  */
-declare function pick<T, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
+declare function pick<TInput, Key extends keyof TInput>(object: TInput, keys: Key[]): Pick<TInput, Key>;
 
 /**
  * Converts `string` to camelCase.
@@ -729,11 +741,11 @@ declare function kebabCase(str: string): string;
  * Converts a string to PascalCase.
  *
  * @example
- * kebabCase('Foo Bar')
+ * pascalCase('Foo Bar')
  * // => 'FooBar'
- * kebabCase('fooBar')
+ * pascalCase('fooBar')
  * // => 'FooBar'
- * kebabCase('__FOO_BAR__')
+ * pascalCase('__FOO_BAR__')
  * // => 'FooBar'
  * @category String
  * @param str - The string to convert.
@@ -785,7 +797,7 @@ declare function startCase(str: string): string;
  * @param str - The string to remove special characters from.
  * @returns Returns the string with special characters removed.
 */
-declare function stripSpecialChars(str: string): string;
+declare function stripSpecial(str: string): string;
 
 /**
  * Converts the HTML entities `&amp;`, `&lt;`, `&gt;`, `&quot;` and `&#39;`
@@ -800,4 +812,4 @@ declare function stripSpecialChars(str: string): string;
  */
 declare function unescape(str: string): string;
 
-export { ArrayOrRecord, GenericFunction, IterateeFunction, MinimumTwoArrays, NoUnion, PropertyShorthand, RecordKey, after, before, camelCase, capitalize, chunk, countBy, debounce, deburr, difference, differenceBy, differenceWith, dropRightWhile, dropWhile, escape, escapeRegExp, groupBy, intersection, intersectionBy, intersectionWith, isEmpty, isEqual, isEqualWith, isPlainObject, kebabCase, memoize, once, pascalCase, pick, sample, sampleSize, shuffle, snakeCase, sortBy, startCase, stripSpecialChars, takeRightWhile, takeWhile, throttle, times, unescape, uniq, uniqBy, uniqWith, unzip, unzipWith, zip, zipWith };
+export { GenericFunction, IterateeFunction, MinimumTwoArrays, NoUnion, PropertyShorthand, RecordKey, after, before, camelCase, capitalize, chunk, count, debounce, deburr, difference, differenceBy, differenceWith, dropRightWhile, dropWhile, escape, escapeRegExp, group, intersection, intersectionBy, intersectionWith, isEmpty, isEqual, isEqualWith, isPlainObject, kebabCase, memoize, once, pascalCase, pick, sample, sampleSize, shuffle, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, times, unescape, uniq, uniqBy, uniqWith, unzip, unzipWith, zip, zipWith };