moderndash 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -431,6 +431,125 @@ declare function omit<TObj extends object, Key extends keyof TObj>(object: TObj,
  */
 declare function pick<TInput, Key extends keyof TInput>(object: TInput, keysToPick: Key[]): Pick<TInput, Key>;
 
+/**
+ * A class for managing a queue of async functions that runs a set number concurrently.
+ * If for example you have 10 async functions and you want to run 3 at a time, you can use this class.
+ *
+ * If the queue is paused, the queue will not run any more async functions until it is resumed.
+ *
+ * ---
+ *
+ * **Methods:**
+ * - {@link Queue.add} - adds a async function or array of functions to the queue.
+ *     Returns a promise that resolves when the added function(s) finish.
+ * - {@link Queue.clear} - clears the queue.
+ * - {@link Queue.pause} - pauses the queue.
+ * - {@link Queue.resume} - resumes the queue.
+ * - {@link Queue.getQueue} - returns the queue.
+ * - {@link Queue.isPaused} - returns whether the queue is paused.
+ *
+ * @example
+ * // Create a queue that can run 3 tasks concurrently
+ * const queue = new Queue(3);
+ *
+ * queue.add(() => fetch('https://example.com'));
+ *
+ * queue.add(async () => {
+ *     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')
+ * ]);
+ * // => [Response, Response]
+ */
+declare class Queue {
+    private running;
+    private maxConcurrent;
+    private paused;
+    private queue;
+    /**
+     * @constructor
+     * @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.
+     * @returns A promise that resolves when the added function(s) finishes.
+     */
+    add<TProm, TAsyncFn extends () => Promise<TProm>>(asyncFn: TAsyncFn): Promise<TProm>;
+    add<TProm, TAsyncFn extends () => Promise<TProm>>(asyncFn: TAsyncFn[]): Promise<TProm[]>;
+    private buildWaitingPromise;
+    private run;
+    /** Removes all the tasks from the queue */
+    clear(): void;
+    /** Pauses the execution of the functions in the queue */
+    pause(): void;
+    /** Resumes the execution of the tasks in the queue */
+    resume(): void;
+    /** Returns the queue */
+    getQueue(): (() => Promise<any>)[];
+    /** Returns whether the queue is paused */
+    isPaused(): boolean;
+}
+
+/**
+ * Similar to [Promise.race](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race?retiredLocale=de)
+ * but allows to specify how many promises to wait for.
+ *
+ * @example
+ * const promise1 = Promise.resolve(1);
+ * const promise2 = Promise.resolve(2);
+ * const promise2 = Promise.resolve(3);
+ *
+ * const firstThree = await races(3, promise1, promise2, promise3);
+ * // => [1, 2, 3]
+ * @template TRes - The type of the result of the promises.
+ * @param waitFor - The number of promises to wait for.
+ * @param promises - The promises to wait for.
+ * @returns A promise that resolves an array of the results of the first n promises.
+ */
+declare function races<TRes>(waitFor: number, ...promises: Promise<TRes>[]): Promise<TRes[]>;
+
+/**
+ * Retry a function until it succeeds or the maximum number of retries is reached.
+ *
+ * Default maxRetries: `5`.
+ * Default backoff: `2^retries * 100ms` (100, 200, 400, 800, 1600, 3200, ...)
+ *
+ * @example
+ * await retry(() => fetch('https://example.com'));
+ *
+ * // ---- Advanced example ----
+ * const fetchSite = async (url: string) => {
+ *    const response = await fetch(url);
+ *    response.ok || throw new Error('Failed to fetch');
+ * }
+ *
+ * const logger = (error: unknown, retry?: number) => console.log("Retrying", retry, error);
+ *
+ * await retry(() => fetchSite('https://example.com'), { maxRetries: 3, backoff: retries => retries * 1000, onRetry: logger }));
+ * // => Will retry 3 times with a 1 second delay between each retry. Will log the error and retry number.
+ *
+ * @param func The function to retry.
+ * @param options The options for the retry.
+ * @param options.maxRetries The maximum number of retries. Defaults to `5`.
+ * @param options.backoff The backoff function to use. Defaults to `2^retries * 100`.
+ * @param options.onRetry The function to call when a retry is attempted.
+ * @template TRes The type of the result of the function.
+ * @returns A promise that resolves when the function succeeds.
+ */
+declare function retry<TRes>(func: () => Promise<TRes>, options?: {
+    maxRetries?: number;
+    backoff?: ((retries: number) => number);
+    onRetry: (error?: unknown, retry?: number) => void;
+}): Promise<TRes>;
+
 /**
  * Sleeps for the given amount of time.
  *
@@ -442,6 +561,24 @@ declare function pick<TInput, Key extends keyof TInput>(object: TInput, keysToPi
  */
 declare function sleep(ms: number): Promise<unknown>;
 
+/**
+ * Returns a new promise that will reject with an error after a specified timeout.
+ *
+ * @example
+ * try {
+ *   await timeout(fetch('https://example.com'), 1000);
+ * } catch (error) {
+ *   console.log(error.message);
+ *   // => '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.
+ *
+ * @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>;
+
 /**
  * Converts `string` to camelCase.
  *
@@ -470,6 +607,22 @@ declare function camelCase(str: string): string;
  */
 declare function capitalize(str: string): string;
 
+/**
+ * Converts a string to dash-case.
+ *
+ * @example
+ * dashCase('Foo Bar')
+ * // => 'foo-bar'
+ * dashCase('fooBar')
+ * // => 'foo-bar'
+ * dashCase('__FOO_BAR__')
+ * // => 'foo-bar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the dash cased string.
+ */
+declare function dashCase(str: string): string;
+
 /**
  * Deburrs a string by converting
  * [Latin-1 Supplement](https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)#Character_table)
@@ -581,7 +734,7 @@ declare function startCase(str: string): string;
  * Removes all special characters from a string.
  *
  * @example
- * stripSpecialChars('Héllo! World #$%&*!')
+ * stripSpecial('Héllo! World #$%&*!')
  * // => 'Hello World'
  * @category String
  * @param str - The string to remove special characters from.
@@ -602,81 +755,6 @@ declare function stripSpecial(str: string): string;
  */
 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. Other usage is limited.
- *
- * *Note: Check this [writeup](https://github.com/sindresorhus/type-fest/issues/334#issuecomment-987787840) for more details.*
- * @example
- * function setYear<T extends number>(x: Integer<T>){};
- *
- * setYear(1); // OK
- * setYear(1.1); // Error
- * @category type
-*/
-type Int<T extends number> = `${T}` extends `${bigint}` ? T : never;
-
-/**
- * A `number` that is not an integer.
- * You can't pass a `bigint` as they are already guaranteed to be integers.
- *
- * Use-case: Validating and documenting parameters. Other usage is limited.
- *
- * *Note: Check this [writeup](https://github.com/sindresorhus/type-fest/issues/334#issuecomment-987787840) for more details.*
- * @example
- * function setPercentage<T extends number>(x: Float<T>) {};
- *
- * setPercentage(1.1); // OK
- * setPercentage(1); // Error
- * @category type
-*/
-type Float<T extends number> = T extends Int<T> ? never : T;
-
-/**
- * A negative `number`/`bigint` (`-∞ < x < 0`)
- *
- * Use-case: Validating and documenting parameters. Other usage is limited.
- *
- * *Note: Check this [writeup](https://github.com/sindresorhus/type-fest/issues/334#issuecomment-987787840) for more details.*
- * @example
- * function setNegative<T extends number>(x: Negative<T>) {};
- *
- * setNegative(-1.2); // OK
- * setNegative(1); // Error
- *
- * function setNegInt<T extends number>(x: Negative<Int<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. Other usage is limited.
- *
- * *Note: Check this [writeup](https://github.com/sindresorhus/type-fest/issues/334#issuecomment-987787840) for more details.*
- * @example
- * function setPositive<T extends number>(x: Positive<T>) {};
- *
- * setPositive(1.2); // OK
- * setPositive(-1); // Error
- *
- * function setPosInt<T extends number>(x: Positive<Int<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;
-
 /**
  * Checks if `value` is an empty object, collection, map, or set.
  *
@@ -730,11 +808,11 @@ declare function isEmpty(value: string | object | null | undefined): boolean;
  * object === other;
  * // => false
  * @category Validate
- * @param value1 - The value to compare.
- * @param value2 - 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(value1: unknown, value2: unknown): boolean;
+declare function isEqual(a: unknown, b: unknown): boolean;
 
 declare function isPlainObject(value: unknown): value is object;
 
@@ -751,4 +829,4 @@ declare function isPlainObject(value: unknown): value is object;
  */
 declare function isUrl(str: string): boolean;
 
-export { Float, Int, 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, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, times, unescapeHtml, unique };
+export { Queue, after, before, camelCase, capitalize, chunk, count, dashCase, debounce, deburr, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, memoize, omit, once, pascalCase, pick, races, retry, sample, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, timeout, times, unescapeHtml, unique };

package/dist/index.js

@@ -28,17 +28,20 @@ function count(array, iteratee) {
 }
 
 // src/validate/isEqual.ts
-function isEqual(value1, value2) {
-  if (value1 === value2)
+function isEqual(a, b) {
+  if (Object.is(a, b))
     return true;
-  if (Array.isArray(value1) && Array.isArray(value2)) {
-    return isSameArray(value1, value2);
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
   }
-  if (value1 instanceof RegExp && value2 instanceof RegExp) {
-    return value1.toString() === value2.toString();
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return isSameArray(a, b);
   }
-  if (isObject(value1) && isObject(value2)) {
-    return isSameObject(value1, value2);
+  if (a instanceof RegExp && b instanceof RegExp) {
+    return a.toString() === b.toString();
+  }
+  if (isObject(a) && isObject(b)) {
+    return isSameObject(a, b);
   }
   return false;
 }
@@ -373,11 +376,134 @@ function omit(object, keysToOmit) {
   return pick(object, filteredKeys);
 }
 
+// src/promise/queue.ts
+var Queue = class {
+  running = 0;
+  maxConcurrent;
+  paused = false;
+  queue = [];
+  constructor(maxConcurrent) {
+    this.maxConcurrent = maxConcurrent;
+  }
+  add(asyncFn) {
+    if (Array.isArray(asyncFn)) {
+      const promises = asyncFn.map((fn) => this.buildWaitingPromise(fn));
+      return Promise.all(promises);
+    } else {
+      return this.buildWaitingPromise(asyncFn);
+    }
+  }
+  buildWaitingPromise(asyncFn) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ asyncFn, resolve, reject });
+      this.run();
+    });
+  }
+  run() {
+    while (this.queue.length > 0 && this.running < this.maxConcurrent && !this.paused) {
+      this.running++;
+      const queueElement = this.queue.shift();
+      void queueElement.asyncFn().then((result) => {
+        queueElement.resolve(result);
+      }).catch((error) => {
+        queueElement.reject(error);
+      }).finally(() => {
+        this.running--;
+        this.run();
+      });
+    }
+  }
+  clear() {
+    for (const queueElement of this.queue) {
+      queueElement.reject(new Error("Queue cleared"));
+    }
+    this.queue = [];
+  }
+  pause() {
+    this.paused = true;
+  }
+  resume() {
+    this.paused = false;
+    this.run();
+  }
+  getQueue() {
+    return this.queue.map((queueElement) => queueElement.asyncFn);
+  }
+  isPaused() {
+    return this.paused;
+  }
+};
+
+// src/promise/races.ts
+function races(waitFor, ...promises) {
+  return new Promise((resolve, reject) => {
+    if (promises.length < waitFor)
+      waitFor = promises.length;
+    const results = [];
+    let resolved = 0;
+    for (const promise of promises) {
+      promise.then((value) => {
+        results.push(value);
+        resolved++;
+        if (resolved >= waitFor) {
+          resolve(results);
+        }
+      }).catch((error) => {
+        reject(error);
+      });
+    }
+  });
+}
+
 // src/promise/sleep.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/promise/retry.ts
+async function retry(func, options) {
+  const backOffFn = options?.backoff ?? ((retries2) => 2 ** retries2 * 100);
+  const maxRetries = options?.maxRetries ?? 5;
+  const onRetry = options?.onRetry ?? (() => {
+  });
+  let retries = 0;
+  let lastError;
+  while (retries <= maxRetries) {
+    try {
+      if (retries > 0)
+        onRetry(lastError, retries);
+      return await func();
+    } catch (error) {
+      lastError = error;
+      retries++;
+      if (retries > maxRetries) {
+        throw error;
+      }
+      await sleep(backOffFn(retries));
+    }
+  }
+  throw new Error("Retry terminated without success, this should never happen");
+}
+
+// src/promise/timeout.ts
+function timeout(promise, timeout2) {
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new Error(`Promise timed out after ${timeout2}ms`));
+    }, timeout2);
+    promise.then(
+      (result) => {
+        clearTimeout(timeoutId);
+        resolve(result);
+      },
+      (error) => {
+        clearTimeout(timeoutId);
+        reject(error);
+      }
+    );
+  });
+}
+
 // src/string/deburr.ts
 function deburr(str) {
   return str.replace(/[^\u0000-\u007E]/g, (chr) => chr.normalize("NFD").replace(/[\u0300-\u036F]/g, ""));
@@ -409,6 +535,16 @@ function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
+// src/string/dashCase.ts
+function dashCase(str) {
+  const words = splitWords(str);
+  let dashCase2 = "";
+  for (const word of words) {
+    dashCase2 += word.toLowerCase() + "-";
+  }
+  return dashCase2.slice(0, -1);
+}
+
 // src/string/escapeHtml.ts
 function escapeHtml(str) {
   const escapeChars = {
@@ -519,12 +655,14 @@ function isUrl(str) {
   }
 }
 export {
+  Queue,
   after,
   before,
   camelCase,
   capitalize,
   chunk,
   count,
+  dashCase,
   debounce,
   deburr,
   difference,
@@ -544,6 +682,8 @@ export {
   once,
   pascalCase,
   pick,
+  races,
+  retry,
   sample,
   shuffle,
   sleep,
@@ -554,6 +694,7 @@ export {
   takeRightWhile,
   takeWhile,
   throttle,
+  timeout,
   times,
   unescapeHtml,
   unique