@naturalcycles/js-lib 14.134.0 → 14.136.0

package/src/promise/pDefer.ts

@@ -3,7 +3,22 @@
  */
 export interface DeferredPromise<T = void> extends Promise<T> {
   resolve: (a?: T) => void
-  reject: (e?: Error) => void
+  reject: (err?: Error) => void
+
+  /**
+   * Can be overridden.
+   * Otherwise will reject with "Aborted" or "Aborted: $reason" on abort().
+   *
+   * @experimental
+   */
+  abort: (reason?: string) => void
+
+  /**
+   * Rejects the promise with `new Error('Aborted: $reason')`.
+   *
+   * @experimental
+   */
+  rejectAborted: (reason?: string) => void
 }
 
 /* eslint-disable @typescript-eslint/promise-function-async */
@@ -22,6 +37,9 @@ export function pDefer<T = void>(): DeferredPromise<T> {
 
   promise.resolve = resolve
   promise.reject = reject
+  promise.rejectAborted = reason =>
+    reject(new Error(['Aborted', reason].filter(Boolean).join(': ')))
+  promise.abort = reason => promise.rejectAborted(reason)
 
   return promise
 }

package/src/promise/pDelay.ts

@@ -1,3 +1,45 @@
-export async function pDelay<T>(ms: number = 0, value?: T): Promise<T> {
-  return await new Promise<T>(resolve => setTimeout(() => resolve(value as T), ms))
+import type { PromisableFunction } from '../types'
+import { DeferredPromise, pDefer } from './pDefer'
+
+/**
+ * Promisified version of setTimeout.
+ *
+ * Can return a value.
+ * If value is instanceof Error - rejects the Promise instead of resolving.
+ */
+export async function pDelay<T>(ms = 0, value?: T): Promise<T> {
+  return await new Promise<T>((resolve, reject) =>
+    setTimeout(value instanceof Error ? reject : resolve, ms, value),
+  )
+}
+
+/* eslint-disable @typescript-eslint/promise-function-async */
+
+/**
+ * Promisified version of setTimeout.
+ *
+ * Wraps the passed function with try/catch,
+ * catch will propagate to pDelayFn rejection,
+ * otherwise pDelayFn will resolve with returned value.
+ *
+ * On abort() - clears the Timeout and immediately resolves the Promise with void.
+ */
+export function pDelayFn<T>(ms = 0, fn: PromisableFunction<T>): DeferredPromise<T> {
+  const p = pDefer<T>()
+
+  const timer = setTimeout(async () => {
+    try {
+      p.resolve(await fn())
+    } catch (err) {
+      p.reject(err as Error)
+    }
+  }, ms)
+
+  p.abort = () => {
+    clearTimeout(timer)
+    // p.rejectAborted(reason) // nope
+    p.resolve()
+  }
+
+  return p
 }

package/src/promise/pRetry.ts

@@ -1,6 +1,5 @@
-import type { AnyFunction, AppError, CommonLogger, ErrorData } from '..'
-import { _since, _stringifyAny } from '..'
-import { TimeoutError } from './pTimeout'
+import type { AnyFunction, CommonLogger, ErrorData } from '..'
+import { _errorDataAppend, _since, pDelay, pTimeout } from '..'
 
 export interface PRetryOptions {
   /**
@@ -84,15 +83,6 @@ export interface PRetryOptions {
    */
   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
-
   /**
    * Will be merged with `err.data` object.
    */
@@ -120,12 +110,10 @@ export async function pRetry<T>(
     predicate,
     logger = console,
     name,
-    keepStackTrace = true,
     timeout,
   } = opt
 
-  const fakeError = keepStackTrace ? new Error('RetryError') : undefined
-
+  const fakeError = timeout ? new Error('TimeoutError') : undefined
   let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt
 
   if (opt.logAll) {
@@ -139,86 +127,50 @@ export async function pRetry<T>(
 
   let delay = initialDelay
   let attempt = 0
-  let timer: NodeJS.Timeout | undefined
-  let timedOut = false
-
-  return await new Promise((resolve, reject) => {
-    const rejectWithTimeout = () => {
-      timedOut = true // to prevent more tries
-      const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`, opt.errorData)
-      if (fakeError) {
-        // keep original stack
-        err.stack = fakeError.stack!.replace('Error: RetryError', 'TimeoutError')
+
+  /* eslint-disable no-await-in-loop, no-constant-condition */
+  while (true) {
+    const started = Date.now()
+
+    try {
+      attempt++
+      if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
+        logger.log(`${fname} attempt #${attempt}...`)
       }
-      reject(err)
-    }
 
-    const next = async () => {
-      if (timedOut) return
+      let result: any
 
       if (timeout) {
-        timer = setTimeout(rejectWithTimeout, timeout)
+        await pTimeout(async () => await fn(attempt), {
+          timeout,
+          name: fname,
+          errorData: opt.errorData,
+          fakeError,
+        })
+      } else {
+        result = await fn(attempt)
       }
 
-      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 (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', ''),
-            })
-          }
-
-          ;(err as AppError).data = {
-            ...(err as AppError).data,
-            ...opt.errorData,
-          }
-
-          reject(err)
-        } else {
-          // Retry after delay
-          delay *= delayMultiplier
-          setTimeout(next, delay)
-        }
+      if (logSuccess) {
+        logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`)
+      }
+
+      return result
+    } catch (err) {
+      if (logFailures) {
+        logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, err)
       }
-    }
 
-    void next()
-  })
+      if (attempt >= maxAttempts || (predicate && !predicate(err as Error, attempt, maxAttempts))) {
+        // Give up
+        _errorDataAppend(err, opt.errorData)
+        throw err
+      }
+
+      // Retry after delay
+      delay *= delayMultiplier
+      await pDelay(delay)
+      // back to while(true) loop
+    }
+  }
 }

package/src/promise/pState.ts

@@ -13,6 +13,6 @@ export async function pState(p: Promise<any>): Promise<'resolved' | 'rejected' |
     v => {
       return v === UNIQUE_VALUE ? 'pending' : 'resolved'
     },
-    () => 'rejected' as const,
+    () => 'rejected',
   )
 }

package/src/promise/pTimeout.ts

@@ -1,5 +1,6 @@
 import { AppError } from '../error/app.error'
 import type { ErrorData } from '../error/error.model'
+import { _errorDataAppend } from '../error/error.util'
 import type { AnyAsyncFunction } from '../types'
 
 export class TimeoutError extends AppError {
@@ -30,13 +31,11 @@ export interface PTimeoutOptions {
   onTimeout?: (err: TimeoutError) => any
 
   /**
-   * Defaults to true.
-   * If true - preserves the stack trace in case of a Timeout (usually - very useful!).
-   * It has a certain perf cost.
-   *
-   * @experimental
+   * If passed - fakeError.stack will be used as a stacktrace.
+   * This is to "keep stacktrace" when pTimeout is called from another
+   * function (like pRetry).
    */
-  keepStackTrace?: boolean
+  fakeError?: Error
 
   /**
    * Will be merged with `err.data` object.
@@ -66,25 +65,24 @@ export function pTimeoutFn<T extends AnyAsyncFunction>(fn: T, opt: PTimeoutOptio
  * If the Function rejects - passes this rejection further.
  */
 export async function pTimeout<T>(fn: AnyAsyncFunction<T>, opt: PTimeoutOptions): Promise<T> {
-  const { timeout, name = fn.name || 'pTimeout function', onTimeout, keepStackTrace = true } = opt
-  const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined
+  const { timeout, name = fn.name || 'pTimeout function', onTimeout } = opt
+  const fakeError = opt.fakeError || new Error('TimeoutError')
 
   // eslint-disable-next-line no-async-promise-executor
   return await new Promise(async (resolve, reject) => {
     // Prepare the timeout timer
     const timer = setTimeout(() => {
       const err = new TimeoutError(`"${name}" timed out after ${timeout} ms`, opt.errorData)
-      if (fakeError) err.stack = fakeError.stack // keep original stack
+      // keep original stack
+      err.stack = fakeError.stack!.replace('Error: TimeoutError', 'TimeoutError: ' + err.message)
 
       if (onTimeout) {
         try {
           resolve(onTimeout(err))
         } catch (err: any) {
-          if (fakeError) err.stack = fakeError.stack // keep original stack
-          err.data = {
-            ...err.data,
-            ...opt.errorData,
-          }
+          // keep original stack
+          err.stack = fakeError.stack!.replace('Error: TimeoutError', err.name + ': ' + err.message)
+          _errorDataAppend(err, opt.errorData)
           reject(err)
         }
         return

package/src/string/stringifyAny.ts

@@ -33,13 +33,6 @@ export interface StringifyAnyOptions {
    */
   maxLen?: number
 
-  /**
-   * Pass true to include "stringified" `error.data` in the output.
-   *
-   * @default false
-   */
-  includeErrorData?: boolean
-
   /**
    * Set to true to print Error.stack instead of just Error.message.
    *
@@ -130,12 +123,6 @@ export function _stringifyAny(obj: any, opt: StringifyAnyOptions = {}): string {
         // `replace` here works ONCE, exactly as we need it
         s = s.replace('HttpError', `HttpError(${obj.data.httpStatusCode})`)
       }
-
-      // Here we ensure it has `data`
-      const { data } = obj
-      if (opt.includeErrorData && Object.keys(data).length > 0) {
-        s = [s, _stringifyAny(data, opt)].join('\n')
-      }
     } else if (typeof (obj as any).code === 'string') {
       // Error that has no `data`, but has `code` property
       s = [s, `code: ${(obj as any).code}`].join('\n')

package/src/types.ts

@@ -80,6 +80,9 @@ export type UnsavedId<T extends Partial<ObjectWithId>> = Omit<T, 'id'> & {
  */
 export type AnyFunction<T = any> = (...args: any[]) => T
 export type AnyAsyncFunction<T = any> = (...args: any[]) => Promise<T>
+export type AsyncFunction<T = any> = () => Promise<T>
+export type AnyPromisableFunction<T = any> = (...args: any[]) => Promisable<T>
+export type PromisableFunction<T = any> = () => Promisable<T>
 
 /**
  * Symbol to indicate END of Sequence.

package/src/vendor/is.ts

@@ -25,7 +25,7 @@ const typedArrayTypeNames = [
   'BigUint64Array',
 ] as const
 
-type TypedArrayTypeName = typeof typedArrayTypeNames[number]
+type TypedArrayTypeName = (typeof typedArrayTypeNames)[number]
 
 function isTypedArrayName(name: unknown): name is TypedArrayTypeName {
   return typedArrayTypeNames.includes(name as TypedArrayTypeName)
@@ -60,7 +60,7 @@ const objectTypeNames = [
   ...typedArrayTypeNames,
 ] as const
 
-type ObjectTypeName = typeof objectTypeNames[number]
+type ObjectTypeName = (typeof objectTypeNames)[number]
 
 function isObjectTypeName(name: unknown): name is ObjectTypeName {
   return objectTypeNames.includes(name as ObjectTypeName)
@@ -76,7 +76,7 @@ const primitiveTypeNames = [
   'symbol',
 ] as const
 
-type PrimitiveTypeName = typeof primitiveTypeNames[number]
+type PrimitiveTypeName = (typeof primitiveTypeNames)[number]
 
 function isPrimitiveTypeName(name: unknown): name is PrimitiveTypeName {
   return primitiveTypeNames.includes(name as PrimitiveTypeName)