@naturalcycles/js-lib 14.75.1 → 14.78.1

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.
@@ -17,6 +20,15 @@ export interface PTimeoutOptions {
    * Can be used to thrown a custom error OR resolve a promise without throwing.
    */
   onTimeout?: () => 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
+   */
+  keepStackTrace?: boolean
 }
 
 /**
@@ -24,37 +36,50 @@ 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'
-  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
-        }
+export function pTimeoutFn<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
+  opt.name ||= fn.name
 
-        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 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, keepStackTrace = true } = opt
+  const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined
+
+  // 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: any) {
+          if (fakeError) err.stack = fakeError.stack // keep original stack
+          reject(err)
+        }
+        return
+      }
+
+      const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`)
+      if (fakeError) err.stack = fakeError.stack // keep original stack
+      reject(err)
+    }, 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/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'
 }