@naturalcycles/js-lib 14.79.0 → 14.82.0

package/src/promise/pRetry.ts

@@ -1,4 +1,5 @@
 import { _since, _stringifyAny, AnyFunction, CommonLogger } from '..'
+import { TimeoutError } from './pTimeout'
 
 export interface PRetryOptions {
   /**
@@ -7,6 +8,13 @@ export interface PRetryOptions {
    */
   name?: string
 
+  /**
+   * Timeout for each Try, in milliseconds.
+   *
+   * Defaults to no timeout.
+   */
+  timeout?: number
+
   /**
    * How many attempts to try.
    * First attempt is not a retry, but "initial try". It still counts.
@@ -34,7 +42,7 @@ export interface PRetryOptions {
    *
    * @default () => true
    */
-  predicate?: (err: unknown, attempt: number, maxAttempts: number) => boolean
+  predicate?: (err: Error, attempt: number, maxAttempts: number) => boolean
 
   /**
    * Log the first attempt (which is not a "retry" yet).
@@ -74,76 +82,132 @@ export interface PRetryOptions {
    * Default to `console`
    */
   logger?: CommonLogger
+
+  /**
+   * Defaults to true.
+   * If true - preserves the stack trace in case of a Timeout (usually - very useful!).
+   * It has a certain perf cost.
+   *
+   * @experimental
+   */
+  keepStackTrace?: boolean
 }
 
 /**
  * Returns a Function (!), enhanced with retry capabilities.
  * Implements "Exponential back-off strategy" by multiplying the delay by `delayMultiplier` with each try.
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
-export function pRetry<T extends AnyFunction>(fn: T, opt: PRetryOptions = {}): T {
+export function pRetryFn<T extends AnyFunction>(fn: T, opt: PRetryOptions = {}): T {
+  return async function pRetryFunction(this: any, ...args: any[]) {
+    return await pRetry(() => fn.call(this, ...args), opt)
+  } as any
+}
+
+export async function pRetry<T>(
+  fn: (attempt: number) => Promise<T>,
+  opt: PRetryOptions = {},
+): Promise<T> {
   const {
     maxAttempts = 4,
     delay: initialDelay = 1000,
     delayMultiplier = 2,
     predicate,
     logger = console,
-    name = fn.name,
+    name,
+    keepStackTrace = true,
+    timeout,
   } = opt
 
+  const fakeError = keepStackTrace ? new Error('RetryError') : undefined
+
   let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt
 
   if (opt.logAll) {
-    logFirstAttempt = logRetries = logFailures = true
+    logSuccess = logFirstAttempt = logRetries = logFailures = true
   }
   if (opt.logNone) {
     logSuccess = logFirstAttempt = logRetries = logFailures = false
   }
 
-  const fname = ['pRetry', name].filter(Boolean).join('.')
+  const fname = name || fn.name || 'pRetry function'
 
-  return async function (this: any, ...args: any[]) {
-    let delay = initialDelay
-    let attempt = 0
+  let delay = initialDelay
+  let attempt = 0
+  let timer: NodeJS.Timeout | undefined
+  let timedOut = false
 
-    return await new Promise((resolve, reject) => {
-      const next = async () => {
-        const started = Date.now()
+  return await new Promise((resolve, reject) => {
+    const rejectWithTimeout = () => {
+      timedOut = true // to prevent more tries
+      const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`)
+      if (fakeError) {
+        // keep original stack
+        err.stack = fakeError.stack!.replace('Error: RetryError', 'TimeoutError')
+      }
+      reject(err)
+    }
 
-        try {
-          attempt++
-          if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
-            logger.log(`${fname} attempt #${attempt}...`)
-          }
+    const next = async () => {
+      if (timedOut) return
 
-          const r = await fn.apply(this, args)
+      if (timeout) {
+        timer = setTimeout(rejectWithTimeout, timeout)
+      }
 
-          if (logSuccess) {
-            logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`)
-          }
-          resolve(r)
-        } catch (err) {
-          if (logFailures) {
-            logger.warn(
-              `${fname} attempt #${attempt} error in ${_since(started)}:`,
-              _stringifyAny(err, {
-                includeErrorData: true,
-              }),
-            )
-          }
+      const started = Date.now()
+
+      try {
+        attempt++
+        if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
+          logger.log(`${fname} attempt #${attempt}...`)
+        }
+
+        const r = await fn(attempt)
+
+        clearTimeout(timer!)
 
-          if (attempt >= maxAttempts || (predicate && !predicate(err, attempt, maxAttempts))) {
-            // Give up
-            reject(err)
-          } else {
-            // Retry after delay
-            delay *= delayMultiplier
-            setTimeout(next, delay)
+        if (logSuccess) {
+          logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`)
+        }
+
+        resolve(r)
+      } catch (err) {
+        clearTimeout(timer!)
+
+        if (logFailures) {
+          logger.warn(
+            `${fname} attempt #${attempt} error in ${_since(started)}:`,
+            _stringifyAny(err, {
+              includeErrorData: true,
+            }),
+          )
+        }
+
+        if (
+          attempt >= maxAttempts ||
+          (predicate && !predicate(err as Error, attempt, maxAttempts))
+        ) {
+          // Give up
+
+          if (fakeError) {
+            // Preserve the original call stack
+            Object.defineProperty(err, 'stack', {
+              value:
+                (err as Error).stack +
+                '\n    --' +
+                fakeError.stack!.replace('Error: RetryError', ''),
+            })
           }
+
+          reject(err)
+        } else {
+          // Retry after delay
+          delay *= delayMultiplier
+          setTimeout(next, delay)
         }
       }
+    }
 
-      void next()
-    })
-  } as any
+    void next()
+  })
 }

package/src/types.ts

@@ -29,15 +29,15 @@ export interface CreatedUpdated {
   updated: number
 }
 
-export interface CreatedUpdatedId extends CreatedUpdated {
-  id: string
+export interface CreatedUpdatedId<ID = string> extends CreatedUpdated {
+  id: ID
 }
 
-export interface ObjectWithId {
-  id: string
+export interface ObjectWithId<ID = string> {
+  id: ID
 }
 
-export interface AnyObjectWithId extends AnyObject, ObjectWithId {}
+export interface AnyObjectWithId<ID = string> extends AnyObject, ObjectWithId<ID> {}
 
 /**
  * Convenience type shorthand.
@@ -169,8 +169,8 @@ export type UnixTimestamp = number
 /**
  * Base interface for any Entity that was saved to DB.
  */
-export interface SavedDBEntity {
-  id: string
+export interface SavedDBEntity<ID = string> {
+  id: ID
 
   /**
    * unixTimestamp of when the entity was first created (in the DB).
@@ -189,10 +189,10 @@ export interface SavedDBEntity {
  * hence `id`, `created` and `updated` fields CAN BE undefined (yet).
  * When it's known to be saved - `SavedDBEntity` interface can be used instead.
  */
-export type BaseDBEntity = Partial<SavedDBEntity>
+export type BaseDBEntity<ID = string> = Partial<SavedDBEntity<ID>>
 
-export type Saved<E> = Merge<E, SavedDBEntity>
-export type Unsaved<E> = Merge<E, BaseDBEntity>
+export type Saved<E, ID = string> = Merge<E, SavedDBEntity<ID>>
+export type Unsaved<E, ID = string> = Merge<E, BaseDBEntity<ID>>
 
 /**
  * Named type for JSON.parse / JSON.stringify second argument

package/dist/promise/pBatch.d.ts

@@ -1,7 +0,0 @@
-import { AbortableAsyncMapper, BatchResult } from '..';
-/**
- * Like pMap, but doesn't fail on errors, instead returns both successful results and errors.
- */
-export declare function pBatch<IN, OUT>(iterable: Iterable<IN | PromiseLike<IN>>, mapper: AbortableAsyncMapper<IN, OUT>, opt?: {
-    concurrency?: number;
-}): Promise<BatchResult<OUT>>;

package/dist/promise/pBatch.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pBatch = void 0;
-const __1 = require("..");
-const pMap_1 = require("./pMap");
-/**
- * Like pMap, but doesn't fail on errors, instead returns both successful results and errors.
- */
-async function pBatch(iterable, mapper, opt) {
-    try {
-        const results = await (0, pMap_1.pMap)(iterable, mapper, {
-            ...opt,
-            errorMode: __1.ErrorMode.THROW_AGGREGATED,
-        });
-        return {
-            results,
-            errors: [],
-        };
-    }
-    catch (err) {
-        const { errors, results } = err;
-        if (!errors || !results)
-            throw err; // not an AggregatedError
-        return {
-            results,
-            errors,
-        };
-    }
-}
-exports.pBatch = pBatch;

package/dist-esm/promise/pBatch.js

@@ -1,23 +0,0 @@
-import { ErrorMode } from '..';
-import { pMap } from './pMap';
-/**
- * Like pMap, but doesn't fail on errors, instead returns both successful results and errors.
- */
-export async function pBatch(iterable, mapper, opt) {
-    try {
-        const results = await pMap(iterable, mapper, Object.assign(Object.assign({}, opt), { errorMode: ErrorMode.THROW_AGGREGATED }));
-        return {
-            results,
-            errors: [],
-        };
-    }
-    catch (err) {
-        const { errors, results } = err;
-        if (!errors || !results)
-            throw err; // not an AggregatedError
-        return {
-            results,
-            errors,
-        };
-    }
-}

package/src/promise/pBatch.ts

@@ -1,31 +0,0 @@
-import { AbortableAsyncMapper, BatchResult, ErrorMode } from '..'
-import { AggregatedError } from './AggregatedError'
-import { pMap } from './pMap'
-
-/**
- * Like pMap, but doesn't fail on errors, instead returns both successful results and errors.
- */
-export async function pBatch<IN, OUT>(
-  iterable: Iterable<IN | PromiseLike<IN>>,
-  mapper: AbortableAsyncMapper<IN, OUT>,
-  opt?: { concurrency?: number },
-): Promise<BatchResult<OUT>> {
-  try {
-    const results = await pMap(iterable, mapper, {
-      ...opt,
-      errorMode: ErrorMode.THROW_AGGREGATED,
-    })
-    return {
-      results,
-      errors: [],
-    }
-  } catch (err) {
-    const { errors, results } = err as AggregatedError<OUT>
-    if (!errors || !results) throw err // not an AggregatedError
-
-    return {
-      results,
-      errors,
-    }
-  }
-}