@naturalcycles/js-lib 14.75.0 → 14.78.0

package/src/promise/pRetry.ts

@@ -1,6 +1,12 @@
-import { _since, _stringifyAny, CommonLogger } from '..'
+import { _since, _stringifyAny, AnyFunction, CommonLogger } from '..'
 
 export interface PRetryOptions {
+  /**
+   * If set - will be included in the error message.
+   * Can be used to identify the place in the code that failed.
+   */
+  name?: string
+
   /**
    * How many attempts to try.
    * First attempt is not a retry, but "initial try". It still counts.
@@ -75,13 +81,14 @@ export interface PRetryOptions {
  * 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 Function>(fn: T, opt: PRetryOptions = {}): T {
+export function pRetry<T extends AnyFunction>(fn: T, opt: PRetryOptions = {}): T {
   const {
     maxAttempts = 4,
     delay: initialDelay = 1000,
     delayMultiplier = 2,
     predicate,
     logger = console,
+    name = fn.name,
   } = opt
 
   let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt
@@ -93,7 +100,7 @@ export function pRetry<T extends Function>(fn: T, opt: PRetryOptions = {}): T {
     logSuccess = logFirstAttempt = logRetries = logFailures = false
   }
 
-  const fname = ['pRetry', fn.name].filter(Boolean).join('.')
+  const fname = ['pRetry', name].filter(Boolean).join('.')
 
   return async function (this: any, ...args: any[]) {
     let delay = initialDelay
@@ -118,9 +125,10 @@ export function pRetry<T extends Function>(fn: T, opt: PRetryOptions = {}): T {
         } catch (err) {
           if (logFailures) {
             logger.warn(
-              `${fname} attempt #${attempt} error in ${_since(started)}:\n${_stringifyAny(err, {
+              `${fname} attempt #${attempt} error in ${_since(started)}:`,
+              _stringifyAny(err, {
                 includeErrorData: true,
-              })}`,
+              }),
             )
           }
 

package/src/promise/pTimeout.ts

@@ -1,5 +1,8 @@
+import { AppError } from '../error/app.error'
 import { AnyFunction } from '../types'
 
+export class TimeoutError extends AppError {}
+
 export interface PTimeoutOptions {
   /**
    * Timeout in milliseconds.
@@ -24,37 +27,46 @@ export interface PTimeoutOptions {
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export function pTimeout<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
-  // const fname = fn.name || 'function'
+export function pTimeoutFn<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
+  opt.name ||= fn.name
+
+  return async function pTimeoutInternalFn(this: any, ...args: any[]) {
+    return await pTimeout(fn.apply(this, args), opt)
+  } as any
+}
+
+/**
+ * Decorates a Function with a timeout and immediately calls it.
+ * Throws an Error if the Function is not resolved in a certain time.
+ * If the Function rejects - passes this rejection further.
+ */
+export async function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Promise<T> {
+  // todo: check how we can automatically infer function name (only applicable to named functions)
   const { timeout, name, onTimeout } = opt
 
-  return async function (this: any, ...args: any[]) {
-    // eslint-disable-next-line no-async-promise-executor
-    return await new Promise(async (resolve, reject) => {
-      // Prepare the timeout timer
-      const timer = setTimeout(() => {
-        if (onTimeout) {
-          try {
-            resolve(onTimeout())
-          } catch (err) {
-            reject(err)
-          }
-          return
+  // eslint-disable-next-line no-async-promise-executor
+  return await new Promise(async (resolve, reject) => {
+    // Prepare the timeout timer
+    const timer = setTimeout(() => {
+      if (onTimeout) {
+        try {
+          resolve(onTimeout())
+        } catch (err) {
+          reject(err)
         }
-
-        reject(
-          new Error(`"${name || fn.name || 'pTimeout function'}" timed out after ${timeout} ms`),
-        )
-      }, timeout)
-
-      // Execute the Function
-      try {
-        resolve(await fn.apply(this, args))
-      } catch (err) {
-        reject(err)
-      } finally {
-        clearTimeout(timer)
+        return
       }
-    })
-  } as any
+
+      reject(new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`))
+    }, timeout)
+
+    // Execute the Function
+    try {
+      resolve(await promise)
+    } catch (err) {
+      reject(err)
+    } finally {
+      clearTimeout(timer)
+    }
+  })
 }

package/src/seq/seq.ts

@@ -140,6 +140,16 @@ export class Sequence<T> implements Iterable<T> {
       a.push(v)
     }
   }
+
+  forEach(fn: (v: T, i: number) => void): void {
+    let i = -1
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const v = this.next()
+      if (v === END) return
+      fn(v, ++i)
+    }
+  }
 }
 
 /**

package/src/string/stringifyAny.ts

@@ -76,16 +76,20 @@ export function _stringifyAny(obj: any, opt: StringifyAnyOptions = {}): string {
     // Error or ErrorObject
     //
 
+    // Omit "default" error name as non-informative
+    // UPD: no, it's still important to understand that we're dealing with Error and not just some string
+    // if (obj?.name === 'Error') {
+    //   s = obj.message
+    // }
+    s = [obj.name, obj.message].join(': ')
+
     if (opt.includeErrorStack && obj.stack) {
-      // Stack includes message
-      s = obj.stack
-    } else {
-      // Omit "default" error name as non-informative
-      // UPD: no, it's still important to understand that we're dealing with Error and not just some string
-      // if (obj?.name === 'Error') {
-      //   s = obj.message
-      // }
-      s = [obj.name, obj.message].join(': ')
+      // Here we're using the previously-generated "title line" (e.g "Error: some_message"),
+      // concatenating it with the Stack (but without the title line of the Stack)
+      // This is to fix the rare error (happened with Got) where `err.message` was changed,
+      // but err.stack had "old" err.message
+      // This should "fix" that
+      s = [s, ...obj.stack.split('\n').slice(1)].join('\n')
     }
 
     if (_isErrorObject(obj)) {

package/src/types.ts

@@ -122,9 +122,18 @@ export type ValueOf<T> = T[keyof T]
 
 export type KeyValueTuple<K, V> = [key: K, value: V]
 
-export type ObjectMapper<OBJ, OUT> = (key: string, value: OBJ[keyof OBJ], obj: OBJ) => OUT
-
-export type ObjectPredicate<OBJ> = (key: keyof OBJ, value: OBJ[keyof OBJ], obj: OBJ) => boolean
+// Exclude<something, undefined> is used here to support StringMap<OBJ> (because values of StringMap add `undefined`)
+export type ObjectMapper<OBJ, OUT> = (
+  key: string,
+  value: Exclude<OBJ[keyof OBJ], undefined>,
+  obj: OBJ,
+) => OUT
+
+export type ObjectPredicate<OBJ> = (
+  key: keyof OBJ,
+  value: Exclude<OBJ[keyof OBJ], undefined>,
+  obj: OBJ,
+) => boolean
 
 /**
  * Allows to identify instance of Class by `instanceId`.

package/src/unit/size.util.ts

@@ -1,9 +1,9 @@
 export function _gb(b: number): number {
-  return Math.round(b / (1024 * 1024 * 1024))
+  return Math.round(b / 1024 ** 3)
 }
 
 export function _mb(b: number): number {
-  return Math.round(b / (1024 * 1024))
+  return Math.round(b / 1024 ** 2)
 }
 
 export function _kb(b: number): number {
@@ -14,8 +14,24 @@ export function _kb(b: number): number {
  * Byte size to Human byte size string
  */
 export function _hb(b = 0): string {
-  if (b < 800) return `${Math.round(b)} byte(s)`
-  if (b < 800 * 1024) return `${Math.round(b / 1024)} Kb`
-  if (b < 800 * 1024 * 1024) return `${Math.round(b / 1024 / 1024)} Mb`
-  return `${Math.round(b / 1024 / 1024 / 1024)} Gb`
+  if (b < 1024) return `${Math.round(b)} byte`
+  if (b < 1024 ** 2) return `${(b / 1024).toPrecision(3)} Kb`
+  if (b < 1024 ** 3) return `${(b / 1024 ** 2).toPrecision(3)} Mb`
+  if (b < 1024 ** 4) return `${(b / 1024 ** 3).toPrecision(3)} Gb`
+  if (b < 1024 ** 5) return `${(b / 1024 ** 4).toPrecision(3)} Tb`
+  return `${Math.round(b / 1024 ** 4)} Tb`
+}
+
+/**
+ * hc stands for "human count", similar to "human bytes" `_hb` function.
+ * Helpful to print big numbers, as it adds `K` (kilo), `M` (mega), etc to make
+ * them more readable.
+ */
+export function _hc(c = 0): string {
+  if (c < 10 ** 4) return String(c)
+  if (c < 10 ** 6) return (c / 10 ** 3).toPrecision(3) + ' K'
+  if (c < 10 ** 9) return (c / 10 ** 6).toPrecision(3) + ' M' // million
+  if (c < 10 ** 12) return (c / 10 ** 9).toPrecision(3) + ' B' // billion
+  if (c < 10 ** 15) return (c / 10 ** 12).toPrecision(3) + ' T' // trillion
+  return Math.round(c / 10 ** 12) + ' T'
 }