@naturalcycles/js-lib 14.80.0 → 14.83.0

package/src/promise/pMap.ts

@@ -55,36 +55,85 @@ export interface PMapOptions {
  * })();
  */
 export async function pMap<IN, OUT>(
-  iterable: Iterable<IN | PromiseLike<IN>>,
+  iterable: Iterable<IN>,
   mapper: AbortableAsyncMapper<IN, OUT>,
   opt: PMapOptions = {},
 ): Promise<OUT[]> {
-  return new Promise<OUT[]>((resolve, reject) => {
-    const { concurrency = Number.POSITIVE_INFINITY, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt
+  const ret: (OUT | typeof SKIP)[] = []
+  // const iterator = iterable[Symbol.iterator]()
+  const items = [...iterable]
+  const itemsLength = items.length
+  if (itemsLength === 0) return [] // short circuit
+
+  const { concurrency = itemsLength, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt
+
+  const errors: Error[] = []
+  let isSettled = false
+  let resolvingCount = 0
+  let currentIndex = 0
+
+  // Special cases that are able to preserve async stack traces
+
+  if (concurrency === 1) {
+    // Special case for concurrency == 1
+
+    for await (const item of items) {
+      try {
+        const r = await mapper(item, currentIndex++)
+        if (r === END) break
+        if (r !== SKIP) ret.push(r)
+      } catch (err) {
+        if (errorMode === ErrorMode.THROW_IMMEDIATELY) throw err
+        if (errorMode === ErrorMode.THROW_AGGREGATED) {
+          errors.push(err as Error)
+        }
+        // otherwise, suppress completely
+      }
+    }
+
+    if (errors.length) {
+      throw new AggregatedError(errors, ret)
+    }
+
+    return ret as OUT[]
+  } else if (!opt.concurrency || items.length <= opt.concurrency) {
+    // Special case for concurrency == infinity or iterable.length < concurrency
+
+    if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
+      return (await Promise.all(items.map((item, i) => mapper(item, i)))).filter(
+        r => r !== SKIP && r !== END,
+      ) as OUT[]
+    }
+
+    ;(await Promise.allSettled(items.map((item, i) => mapper(item, i)))).forEach(r => {
+      if (r.status === 'fulfilled') {
+        if (r.value !== SKIP && r.value !== END) ret.push(r.value)
+      } else if (errorMode === ErrorMode.THROW_AGGREGATED) {
+        errors.push(r.reason)
+      }
+    })
+
+    if (errors.length) {
+      throw new AggregatedError(errors, ret)
+    }
 
-    const ret: (OUT | typeof SKIP)[] = []
-    const iterator = iterable[Symbol.iterator]()
-    const errors: Error[] = []
-    let isSettled = false
-    let isIterableDone = false
-    let resolvingCount = 0
-    let currentIndex = 0
+    return ret as OUT[]
+  }
 
-    const next = (skipped = false) => {
+  return new Promise<OUT[]>((resolve, reject) => {
+    const next = () => {
       if (isSettled) {
         return
       }
 
-      const nextItem = iterator.next()
-      const i = currentIndex
-      if (!skipped) currentIndex++
-
-      if (nextItem.done) {
-        isIterableDone = true
+      const nextItem = items[currentIndex]!
+      const i = currentIndex++
 
+      if (currentIndex > itemsLength) {
         if (resolvingCount === 0) {
+          isSettled = true
           const r = ret.filter(r => r !== SKIP) as OUT[]
-          if (errors.length && errorMode === ErrorMode.THROW_AGGREGATED) {
+          if (errors.length) {
             reject(new AggregatedError(errors, r))
           } else {
             resolve(r)
@@ -96,7 +145,7 @@ export async function pMap<IN, OUT>(
 
       resolvingCount++
 
-      Promise.resolve(nextItem.value)
+      Promise.resolve(nextItem)
         .then(async element => await mapper(element, i))
         .then(
           value => {
@@ -114,7 +163,9 @@ export async function pMap<IN, OUT>(
               isSettled = true
               reject(err)
             } else {
-              errors.push(err)
+              if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                errors.push(err)
+              }
               resolvingCount--
               next()
             }
@@ -125,7 +176,7 @@ export async function pMap<IN, OUT>(
     for (let i = 0; i < concurrency; i++) {
       next()
 
-      if (isIterableDone) {
+      if (isSettled) {
         break
       }
     }

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

@@ -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,
-    }
-  }
-}