moderndash 1.1.1 → 1.3.0

package/dist/index.d.ts

@@ -153,7 +153,7 @@ 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.
+ * @param arrays The arrays to inspect.
  * @returns Returns the new array of intersecting values.
  */
 declare function intersection<TArr>(...arrays: ArrayMinLength<TArr[], 2>): TArr[];
@@ -193,7 +193,7 @@ declare function range(start: number, end: number, step?: number): Generator<num
  *
  * sample([1, 2, 3, 4], 2)
  * // => [3, 1]
- * @param array - The array to sample.
+ * @param array The array to sample.
  * @returns Returns the random element.
  */
 declare function sample<TArr>(array: TArr[]): TArr | undefined;
@@ -206,7 +206,7 @@ declare function sample<TArr>(array: TArr[], multi: number): TArr[];
  * @example
  * shuffle([1, 2, 3, 4])
  * // => [4, 1, 3, 2]
- * @param array - The array or object to shuffle.
+ * @param array The array or object to shuffle.
  * @returns Returns the new shuffled array.
  */
 declare function shuffle<TArr>(array: TArr[]): TArr[];
@@ -226,8 +226,8 @@ declare function shuffle<TArr>(array: TArr[]): TArr[];
  *   { order: 'desc', by: item => item.b }
  * )
  * // => [{ a: 1, b: 2 }, { a: 1, b: 1 }, { a: 2, b: 1 }]
- * @param array - The array to sort.
- * @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 array The array to sort.
+ * @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.
  * @returns Returns the sorted array.
@@ -250,8 +250,8 @@ declare function sort<TInput>(array: TInput[], ...orders: {
  *
  * takeRightWhile(({ active }) => active, users)
  * // => objects for ['fred', 'pebbles']
- * @param predicate - The function invoked per iteration.
- * @param array - The array to query.
+ * @param predicate The function invoked per iteration.
+ * @param array The array to query.
  * @returns Returns the slice of `array`.
  */
 declare function takeRightWhile<TArr>(predicate: (elem: TArr) => boolean, array: TArr[]): TArr[];
@@ -286,16 +286,15 @@ declare function takeWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boole
  * // => [2, 1]
  *
  * const users = [
- *      { id: 1, name: 'a' },
- *      { id: 1, name: 'c' }
+ *   { id: 1, name: 'a' },
+ *   { id: 1, name: 'c' }
  * ]
  *
  * unique(users, (a, b) => a.id === b.id)
  * // => [{ id: 1, name: 'a' }]
  *
- *
- * @param array - The array to inspect.
- * @param iteratee - The iteratee invoked per element.
+ * @param array The array to inspect.
+ * @param iteratee The iteratee invoked per element.
  * @returns Returns the new duplicate free array.
  */
 declare function unique<TInput>(array: TInput[], compareFn?: (a: TInput, b: TInput) => boolean): TInput[];
@@ -321,7 +320,7 @@ declare function unique<TInput>(array: TInput[], compareFn?: (a: TInput, b: TInp
  * instance.testMethod("World");
  * // => Only the second invocation of `debouncedSayHello` is executed, after a delay of 1000ms.
  * ```
- * @param wait - Milliseconds to wait before invoking the decorated function after the last invocation.
+ * @param wait Milliseconds to wait before invoking the decorated function after the last invocation.
  */
 declare function decDebounce(wait: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
@@ -347,7 +346,7 @@ declare function decDebounce(wait: number): (target: unknown, key: string, descr
  * instance.testMethod(); // => 2
  * instance.testMethod(); // => 2
  * ```
- * @param n - The number of calls before the cached result is returned.
+ * @param n The number of calls before the cached result is returned.
  */
 declare function decMaxCalls(n: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
@@ -370,8 +369,8 @@ type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters
  * @example
  * ```typescript
  * function fibonacci(n: number) {
- *     if (n <= 1) return n;
- *     return fibonacci(n - 1) + fibonacci(n - 2);
+ *   if (n <= 1) return n;
+ *   return fibonacci(n - 1) + fibonacci(n - 2);
  * }
  *
  * const memoizedFib = memoize(fibonacci, { ttl: 1000 })
@@ -388,8 +387,8 @@ type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters
  * // This is the default way to create cache keys.
  * const defaultResolver = (...args: unknown[]) => JSON.stringify(args)
  * ```
- * @param func - The function to have its output memoized.
- * @param options - The options object with optional `resolver` and `ttl` parameters.
+ * @param func The function to have its output memoized.
+ * @param options The options object with optional `resolver` and `ttl` parameters.
  * @param options.resolver - A function that determines the cache key for storing the result based on the arguments provided.
  * @param options.ttl - The time to live for the cache in milliseconds.
  * @template TFunc The type of the function to memoize.
@@ -430,7 +429,7 @@ declare function memoize<TFunc extends GenericFunction<TFunc>, Cache extends Map
  * // After 1 second:
  * instance.testMethod(1, 2); // => 3 (cache miss)
  * ```
- * @param options - The options object.
+ * @param options The options object.
  * @param options.resolver - A function that determines the cache key for storing the result based on the arguments provided.
  * @param options.ttl - The time to live for the cache in milliseconds.
  */
@@ -479,7 +478,7 @@ declare function decMinCalls(n: number): (target: unknown, key: string, descript
  * instance.testMethod(); // => "Throttled!" is logged once per second.
  * instance.testMethod(); // nothing happens
  * ```
- * @param wait - The number of milliseconds to wait between invocations.
+ * @param wait The number of milliseconds to wait between invocations.
  */
 declare function decThrottle(wait: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
@@ -509,7 +508,7 @@ type Tail<T extends unknown[]> = T extends [infer _Head, ...infer Tail] ? Tail :
  * instance.testMethod();
  * // => Log "Hello World" and return 1
  * ```
- * @param func - The function to transform.
+ * @param func The function to transform.
  * @returns A decorator function that can be used to decorate a method.
  */
 declare function toDecorator<TFunc extends GenericFunction<TFunc>>(func: TFunc): (...args: Tail<Parameters<TFunc>>) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
@@ -530,8 +529,8 @@ declare function toDecorator<TFunc extends GenericFunction<TFunc>>(func: TFunc):
  * debouncedSayHello("John");
  * debouncedSayHello("Jane");
  * // => Only the second invocation of `debouncedSayHello` is executed, after a delay of 200ms.
- * @param func - The function to debounce.
- * @param wait - The number of milliseconds to wait before invoking `func`.
+ * @param func The function to debounce.
+ * @param wait The number of milliseconds to wait before invoking `func`.
  * @returns A debounced version of `func` with `cancel` and `flush` methods.
  */
 declare function debounce<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait: number): TFunc & {
@@ -556,8 +555,8 @@ declare function debounce<TFunc extends GenericFunction<TFunc>>(func: TFunc, wai
  * limitAddCount() // => 2
  * limitAddCount() // => 2
  * // => `limitAddCount` is invoked twice and the result is cached.
- * @param n - The number of calls before the cached result is returned.
- * @param func - The function to restrict.
+ * @param n The number of calls before the cached result is returned.
+ * @param func The function to restrict.
  * @returns Returns the new restricted function.
  */
 declare function maxCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): TFunc;
@@ -591,8 +590,8 @@ declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n:
  * throttled();
  * throttled();
  * // => "Throttled!" is logged once per second.
- * @param func - The function to throttle.
- * @param wait - The number of milliseconds to throttle invocations to.
+ * @param func The function to throttle.
+ * @param wait The number of milliseconds to throttle invocations to.
  * @returns Returns the new throttled function.
  */
 declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait: number): TFunc;
@@ -608,8 +607,8 @@ declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wai
  * // => [0.123, 0.456, 0.789]
  * times(() => 0, 4)
  * // => [0, 0, 0, 0]
- * @param n - The number of times to invoke `func`.
- * @param func - The function invoked per iteration.
+ * @param n The number of times to invoke `func`.
+ * @param func The function invoked per iteration.
  * @returns Returns an array of results.
  */
 declare function times<TInput>(func: (index: number) => TInput, n: number): TInput[];
@@ -621,7 +620,7 @@ declare function times<TInput>(func: (index: number) => TInput, n: number): TInp
  * @example
  * average([1, 2, 3, 4, 5]) // => 3
  *
- * @param numbers - The input array of numbers
+ * @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;
@@ -634,7 +633,7 @@ declare function average(numbers: number[]): number;
  * median([1, 2, 3, 4, 5]) // => 3
  * median([1, 2, 3, 4, 5, 6]) // => 3.5
  *
- * @param numbers - The input array of numbers
+ * @param numbers The input array of numbers
  * @returns The median of the input array
  */
 declare function median(numbers: number[]): number;
@@ -646,8 +645,8 @@ declare function median(numbers: number[]): number;
  * @example
  * randomFloat(1, 10) // => 1.123456789
  *
- * @param min - The smallest float that can be generated.
- * @param max - The largest float that can be generated.
+ * @param min The smallest float that can be generated.
+ * @param max The largest float that can be generated.
  *
  * @returns A random float between `min` and `max`, including `min` and `max`.
  */
@@ -660,13 +659,27 @@ declare function randomFloat(min: number, max: number): number;
  * @example
  * randomInt(1, 10) // => 5
  *
- * @param min - The smallest integer that can be generated.
- * @param max - The largest integer that can be generated.
+ * @param min The smallest integer that can be generated.
+ * @param max The largest integer that can be generated.
  *
  * @returns A random integer between `min` and `max`, including `min` and `max`.
  */
 declare function randomInt(min: number, max: number): number;
 
+/**
+ * Rounds a number to the given precision.
+ *
+ * @example
+ * round(1.23456, 2); // => 1.23
+ * round(1.235, 1); // => 1.2
+ * round(1234.56); // => 1234.56
+ *
+ * @param number The number to be rounded.
+ * @param precision The number of decimal places to round to. Defaults to 2.
+ * @returns The rounded number.
+ */
+declare function round(number: number, precision?: number): number;
+
 /**
  * Calculates the sum of an array of numbers.
  *
@@ -674,7 +687,7 @@ declare function randomInt(min: number, max: number): number;
  * @example
  * sum([1, 2, 3, 4, 5]) // => 15
  *
- * @param numbers - The input array of numbers
+ * @param numbers The input array of numbers
  * @returns The sum of the input array
  */
 declare function sum(numbers: number[]): number;
@@ -707,8 +720,8 @@ type PlainObject = Record<PropertyKey, unknown>;
  *
  * merge({ a: 1 }, { a: "Yes" })
  * // => { a: "Yes" }
- * @param target - The target object
- * @param sources - The source objects
+ * @param target The target object
+ * @param sources 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]>;
@@ -734,8 +747,8 @@ type MergeDeepObjects<A extends readonly [...unknown[]]> = A extends [infer L, .
  * omit(obj, ['a', 'b']);
  * // => {c: 3}
  *
- * @param object - The object to filter
- * @param keysToOmit - The keys to exclude from the returned object
+ * @param object The object to filter
+ * @param keysToOmit The keys to exclude from the returned object
  * @returns - An object without the specified keys
  *
  */
@@ -749,8 +762,8 @@ declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object:
  *
  * pick(object, ['a', 'c'])
  * // => { 'a': 1, 'c': 3 }
- * @param object - The source object.
- * @param keysToPick - The property paths to pick.
+ * @param object The source object.
+ * @param keysToPick The property paths to pick.
  * @returns Returns the new object.
  */
 declare function pick<TInput extends PlainObject, Key extends keyof TInput>(object: TInput, keysToPick: Key[]): Pick<TInput, Key>;
@@ -791,14 +804,14 @@ declare function set<TObj extends PlainObject>(obj: TObj, path: string, value: u
  * queue.add(() => fetch('https://example.com'));
  *
  * queue.add(async () => {
- *     const response = await fetch('https://example.com');
- *     return response.json();
+ *   const response = await fetch('https://example.com');
+ *   return response.json();
  * });
  *
  * // Add an array of tasks to the queue and wait for them to resolve
  * await queue.add([
- *      () => fetch('https://apple.com'),
- *      () => fetch('https://microsoft.com')
+ *   () => fetch('https://apple.com'),
+ *   () => fetch('https://microsoft.com')
  * ]);
  * // => [Response, Response]
  */
@@ -809,13 +822,13 @@ declare class Queue {
     private queue;
     /**
      * @constructor
-     * @param maxConcurrent - The maximum number of async functions to run concurrently.
+     * @param maxConcurrent The maximum number of async functions to run concurrently.
      */
     constructor(maxConcurrent: number);
     /**
      * Add aync functions or an array of async functions to the queue.
      *
-     * @param asyncFn - The aync function(s) to add to the queue.
+     * @param asyncFn The aync function(s) to add to the queue.
      * @returns A promise that resolves when the added function(s) finishes.
      */
     add<TProm, TAsyncFn extends () => Promise<TProm>>(asyncFn: TAsyncFn): Promise<TProm>;
@@ -864,9 +877,9 @@ declare function races<TRes>(waitFor: number, ...promises: Promise<TRes>[]): Pro
  *
  * // ---- Advanced example ----
  * const fetchSite = async () => {
- *    const response = await fetch('https://example.com');
- *    if(!response.ok)
- *        throw new Error('Failed to fetch');
+ *   const response = await fetch('https://example.com');
+ *   if(!response.ok)
+ *     throw new Error('Failed to fetch');
  * }
  *
  * const logger = (error: unknown, retry?: number) => console.log("Retrying", retry, error);
@@ -895,7 +908,7 @@ declare function retry<TRes>(func: () => Promise<TRes>, options?: {
  * @example
  * await sleep(1000);
  * // => Waits for 1 second.
- * @param ms -  Amount of time to sleep in milliseconds.
+ * @param ms  Amount of time to sleep in milliseconds.
  * @returns A promise that resolves after the given amount of time.
  */
 declare function sleep(ms: number): Promise<unknown>;
@@ -911,13 +924,33 @@ declare function sleep(ms: number): Promise<unknown>;
  *   // => 'Promise timed out after 1000ms'
  * }
  * @template TRes - The type of the resolved value.
- * @param promise - The promise to wrap.
- * @param timeout - The timeout in milliseconds.
+ * @param promise The promise to wrap.
+ * @param timeout The timeout in milliseconds.
  *
  * @returns A new promise that will reject with an error after the specified timeout.
  */
 declare function timeout<TRes>(promise: Promise<TRes>, timeout: number): Promise<TRes>;
 
+/**
+ * Attempts to execute a promise and returns an array with the result or error.
+ *
+ * This is useful for handling errors in async functions without try/catch blocks.
+ *
+ * @example
+ * ```typescript
+ * const [data, error] = await tryCatch(fetch('https://example.com/api'));
+ * if (error)
+ *   console.error(`Error: ${error.message}`);
+ * ```
+ * @param promise A Promise to be executed.
+ * @returns A Promise that resolves to an array containing the result or error.
+ * If the Promise executes successfully, the array contains the result and a null error.
+ * If the Promise throws an error, the array contains undefined for the result and the error object.
+ *
+ * @template TRes The type of the result.
+ */
+declare function tryCatch<TRes>(promise: Promise<TRes>): Promise<[TRes, undefined] | [undefined, Error]>;
+
 /**
  * Converts `string` to camelCase.
  *
@@ -928,7 +961,7 @@ declare function timeout<TRes>(promise: Promise<TRes>, timeout: number): Promise
  * // => 'fooBar'
  * camelCase('__FOO_BAR__')
  * // => 'fooBar'
- * @param str - The string to convert.
+ * @param str The string to convert.
  * @returns Returns the camel cased string.
  */
 declare function camelCase(str: string): string;
@@ -939,7 +972,7 @@ declare function camelCase(str: string): string;
  * @example
  * capitalize('FRED')
  * // => 'Fred'
- * @param str - The string to capitalize.
+ * @param str The string to capitalize.
  * @returns Returns the capitalized string.
  */
 declare function capitalize(str: string): string;
@@ -954,7 +987,7 @@ declare function capitalize(str: string): string;
  * @example
  * deburr('déjà vu')
  * // => 'deja vu'
- * @param str - The string to deburr.
+ * @param str The string to deburr.
  * @returns Returns the deburred string.
  */
 declare function deburr(str: string): string;
@@ -965,7 +998,7 @@ declare function deburr(str: string): string;
  * @example
  * escapeHtml('fred, barney, & pebbles')
  * // => 'fred, barney, &amp; pebbles'
- * @param str - The string to escape.
+ * @param str The string to escape.
  * @returns Returns the escaped string.
  */
 declare function escapeHtml(str: string): string;
@@ -977,7 +1010,7 @@ declare function escapeHtml(str: string): string;
  * @example
  * escapeRegExp('[moderndash](https://moderndash.io/)')
  * // => '\[moderndash\]\(https://moderndash\.io/\)'
- * @param str - The string to escape.
+ * @param str The string to escape.
  * @returns Returns the escaped string.
  */
 declare function escapeRegExp(str: string): string;
@@ -993,7 +1026,7 @@ declare function escapeRegExp(str: string): string;
  * kebabCase('__FOO_BAR__')
  * // => 'foo-bar'
  *
- * @param str - The string to convert.
+ * @param str The string to convert.
  * @returns Returns the kebab cased string.
  */
 declare function kebabCase(str: string): string;
@@ -1009,7 +1042,7 @@ declare function kebabCase(str: string): string;
  * pascalCase('__FOO_BAR__')
  * // => 'FooBar'
  *
- * @param str - The string to convert.
+ * @param str The string to convert.
  * @returns Returns the pascal cased string.
  */
 declare function pascalCase(str: string): string;
@@ -1027,7 +1060,7 @@ declare function pascalCase(str: string): string;
  * snakeCase('foo2bar')
  * // => 'foo_2_bar'
  *
- * @param str - The string to convert.
+ * @param str The string to convert.
  * @returns Returns the snake cased string.
  */
 declare function snakeCase(str: string): string;
@@ -1062,7 +1095,7 @@ declare function splitWords(str: string): string[];
  * // => 'Foo Bar'
  * titleCase('HélloWorld')
  * // => 'Hello World'
- * @param str - The string to convert.
+ * @param str The string to convert.
  * @returns Returns the title cased string.
  */
 declare function titleCase(str: string): string;
@@ -1074,7 +1107,7 @@ declare function titleCase(str: string): string;
  * @example
  * unescapeHtml('fred, barney, &amp; pebbles')
  * // => 'fred, barney, & pebbles'
- * @param str - The string to unescape.
+ * @param str The string to unescape.
  * @returns Returns the unescaped string.
  */
 declare function unescapeHtml(str: string): string;
@@ -1100,7 +1133,7 @@ declare function unescapeHtml(str: string): string;
  *
  * isEmpty({ 'a': 1 })
  * // => false
- * @param value - The value to check.
+ * @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;
@@ -1118,8 +1151,8 @@ declare function isEmpty(value: string | object | null | undefined): boolean;
  *
  * object === other;
  * // => false
- * @param a - The value to compare.
- * @param b - The other value to compare.
+ * @param a The value to compare.
+ * @param b The other value to compare.
  * @returns Returns `true` if the values are equivalent, else `false`.
  */
 declare function isEqual(a: unknown, b: unknown): boolean;
@@ -1135,7 +1168,7 @@ declare function isEqual(a: unknown, b: unknown): boolean;
  * isPlainObject([]) // => false
  * isPlainObject(new Function()) // => false
  * isPlainObject(new Date()) // => false
- * @param value - The value to check
+ * @param value The value to check
  * @returns Boolean indicating if the value is a plain object
  */
 declare function isPlainObject(value: unknown): value is PlainObject;
@@ -1148,9 +1181,9 @@ declare function isPlainObject(value: unknown): value is PlainObject;
  * // => true
  * isUrl('google.com')
  * // => false
- * @param str - The string to check.
+ * @param str The string to check.
  * @returns Returns `true` if given string is a valid URL, else `false`.
  */
 declare function isUrl(str: string): boolean;
 
-export { ArrayMinLength, GenericFunction, PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, omit, pascalCase, pick, races, randomFloat, randomInt, range, retry, sample, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, unescapeHtml, unique };
+export { ArrayMinLength, GenericFunction, PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, omit, pascalCase, pick, races, randomFloat, randomInt, range, retry, round, sample, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, tryCatch, unescapeHtml, unique };

package/dist/index.js

@@ -394,6 +394,12 @@ function randomInt(min, max) {
   return min + randomBuffer[0] % range2;
 }
 
+// src/number/round.ts
+function round(number, precision = 2) {
+  const factor = Math.pow(10, precision);
+  return Math.round((number + Number.EPSILON) * factor) / factor;
+}
+
 // src/object/merge.ts
 function merge(target, ...sources) {
   const targetCopy = { ...target };
@@ -448,7 +454,7 @@ var Queue = class {
   queue = [];
   /**
    * @constructor
-   * @param maxConcurrent - The maximum number of async functions to run concurrently.
+   * @param maxConcurrent The maximum number of async functions to run concurrently.
    */
   constructor(maxConcurrent) {
     this.maxConcurrent = maxConcurrent;
@@ -577,6 +583,18 @@ function timeout(promise, timeout2) {
   });
 }
 
+// src/promise/tryCatch.ts
+async function tryCatch(promise) {
+  try {
+    const data = await promise;
+    return [data, void 0];
+  } catch (error) {
+    if (error instanceof Error)
+      return [void 0, error];
+    throw error;
+  }
+}
+
 // src/string/splitWords.ts
 function splitWords(str) {
   const regex = new RegExp(
@@ -750,6 +768,7 @@ export {
   randomInt,
   range,
   retry,
+  round,
   sample,
   set,
   shuffle,
@@ -765,6 +784,7 @@ export {
   times,
   titleCase,
   toDecorator,
+  tryCatch,
   unescapeHtml,
   unique
 };