@naturalcycles/js-lib 14.215.0 → 14.217.0

package/src/decorators/memo.util.ts

@@ -1,5 +1,4 @@
-import { _isPrimitive } from '..'
-import type { Promisable } from '../typeFest'
+import { _isPrimitive, MISS, pDelay } from '..'
 
 export type MemoSerializer = (args: any[]) => any
 
@@ -11,11 +10,17 @@ export const jsonMemoSerializer: MemoSerializer = args => {
 
 export interface MemoCache<KEY = any, VALUE = any> {
   has: (k: KEY) => boolean
-  get: (k: KEY) => VALUE | Error | undefined
-  set: (k: KEY, v: VALUE | Error) => void
+  /**
+   * `get` return signature doesn't contain `undefined`,
+   * because `undefined` is a valid VALUE to store in the Cache.
+   * `undefined` does NOT mean cache miss.
+   * Cache misses are checked by calling `has` method instead.
+   */
+  get: (k: KEY) => VALUE
+  set: (k: KEY, v: VALUE) => void
 
   /**
-   * Clear is only called when `.dropCache()` is called.
+   * Clear is only called when `_getMemoCache().clear()` is called.
    * Otherwise the Cache is "persistent" (never cleared).
    */
   clear: () => void
@@ -25,18 +30,18 @@ export interface AsyncMemoCache<KEY = any, VALUE = any> {
   // `has` method is removed, because it is assumed that it has a cost and it's best to avoid doing both `has` and then `get`
   // has(k: any): Promise<boolean>
   /**
-   * `undefined` value returned indicates the ABSENCE of value in the Cache.
-   * This also means that you CANNOT store `undefined` value in the Cache, as it'll be treated as a MISS.
-   * You CAN store `null` value instead, it will be treated as a HIT.
+   * MISS symbol indicates the ABSENCE of value in the Cache.
+   * You can safely store `undefined` or `null` values in the Cache,
+   * they will not be interpreted as a cache miss, because there is a special MISS symbol for that.
    */
-  get: (k: KEY) => Promisable<VALUE | Error | undefined>
-  set: (k: KEY, v: VALUE | Error) => Promisable<void>
+  get: (k: KEY) => Promise<VALUE | typeof MISS>
+  set: (k: KEY, v: VALUE) => Promise<void>
 
   /**
-   * Clear is only called when `.dropCache()` is called.
+   * Clear is only called when `_getAsyncMemo().clear()` is called.
    * Otherwise the Cache is "persistent" (never cleared).
    */
-  clear: () => Promisable<void>
+  clear: () => Promise<void>
 }
 
 // SingleValueMemoCache and ObjectMemoCache are example-only, not used in production code
@@ -85,20 +90,18 @@ export class ObjectMemoCache implements MemoCache {
 }
  */
 
-export class MapMemoCache<KEY = any, VALUE = any>
-  implements MemoCache<KEY, VALUE>, AsyncMemoCache<KEY, VALUE>
-{
-  private m = new Map<KEY, VALUE | Error>()
+export class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALUE> {
+  private m = new Map<KEY, VALUE>()
 
   has(k: KEY): boolean {
     return this.m.has(k)
   }
 
-  get(k: KEY): VALUE | Error | undefined {
-    return this.m.get(k)
+  get(k: KEY): VALUE {
+    return this.m.get(k)!
   }
 
-  set(k: KEY, v: VALUE | Error): void {
+  set(k: KEY, v: VALUE): void {
     this.m.set(k, v)
   }
 
@@ -106,3 +109,30 @@ export class MapMemoCache<KEY = any, VALUE = any>
     this.m.clear()
   }
 }
+
+/**
+ * Implementation of AsyncMemoCache backed by a synchronous Map.
+ * Doesn't have a practical use except testing,
+ * because the point of AsyncMemoCache is to have an **async** backed cache.
+ */
+export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
+  constructor(private delay = 0) {}
+
+  private m = new Map<KEY, VALUE>()
+
+  async get(k: KEY): Promise<VALUE | typeof MISS> {
+    await pDelay(this.delay)
+    if (!this.m.has(k)) return MISS
+    return this.m.get(k)!
+  }
+
+  async set(k: KEY, v: VALUE): Promise<void> {
+    await pDelay(this.delay)
+    this.m.set(k, v)
+  }
+
+  async clear(): Promise<void> {
+    await pDelay(this.delay)
+    this.m.clear()
+  }
+}

package/src/decorators/memoFn.ts

@@ -10,6 +10,8 @@ export interface MemoizedFunction {
  * Only supports Sync functions.
  * To support Async functions - use _memoFnAsync.
  * Technically, you can use it with Async functions, but it'll return the Promise without awaiting it.
+ *
+ * @experimental
  */
 export function _memoFn<T extends (...args: any[]) => any>(
   fn: T,
@@ -17,7 +19,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
 ): T & MemoizedFunction {
   const {
     logger = console,
-    cacheErrors = true,
     cacheFactory = () => new MapMemoCache(),
     cacheKeyFn = jsonMemoSerializer,
   } = opt
@@ -27,39 +28,20 @@ export function _memoFn<T extends (...args: any[]) => any>(
   const memoizedFn = function (this: any, ...args: any[]): T {
     const ctx = this
     const cacheKey = cacheKeyFn(args)
-    let value: any
 
     if (cache.has(cacheKey)) {
-      value = cache.get(cacheKey)
-
-      if (value instanceof Error) {
-        throw value
-      }
-
-      return value
+      return cache.get(cacheKey)
     }
 
-    try {
-      value = fn.apply(ctx, args)
-
-      try {
-        cache.set(cacheKey, value)
-      } catch (err) {
-        logger.error(err)
-      }
+    const value = fn.apply(ctx, args)
 
-      return value
+    try {
+      cache.set(cacheKey, value)
     } catch (err) {
-      if (cacheErrors) {
-        try {
-          cache.set(cacheKey, err)
-        } catch (err) {
-          logger.error(err)
-        }
-      }
-
-      throw err
+      logger.error(err)
     }
+
+    return value
   }
 
   Object.assign(memoizedFn, { cache })

package/src/decorators/memoFnAsync.ts

@@ -1,3 +1,4 @@
+import { MISS } from '../types'
 import type { AsyncMemoOptions } from './asyncMemo.decorator'
 import type { AsyncMemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
@@ -7,16 +8,14 @@ export interface MemoizedAsyncFunction {
 }
 
 /**
- * Only supports Sync functions.
- * To support Async functions - use _memoFnAsync
+ * @experimental
  */
 export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
   fn: T,
-  opt: AsyncMemoOptions = {},
+  opt: AsyncMemoOptions,
 ): T & MemoizedAsyncFunction {
   const {
     logger = console,
-    cacheRejections = true,
     cacheFactory = () => new MapMemoCache(),
     cacheKeyFn = jsonMemoSerializer,
   } = opt
@@ -34,39 +33,21 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
       logger.error(err)
     }
 
-    if (value !== undefined) {
-      if (value instanceof Error) {
-        throw value
-      }
-
+    if (value !== MISS) {
       return value
     }
 
-    try {
-      value = await fn.apply(ctx, args)
-
-      void (async () => {
-        try {
-          await cache.set(cacheKey, value)
-        } catch (err) {
-          logger.error(err)
-        }
-      })()
+    value = await fn.apply(ctx, args)
 
-      return value
-    } catch (err) {
-      if (cacheRejections) {
-        void (async () => {
-          try {
-            await cache.set(cacheKey, err)
-          } catch (err) {
-            logger.error(err)
-          }
-        })()
+    void (async () => {
+      try {
+        await cache.set(cacheKey, value)
+      } catch (err) {
+        logger.error(err)
       }
+    })()
 
-      throw err
-    }
+    return value
   }
 
   Object.assign(memoizedFn, { cache })

package/src/form.util.ts

@@ -8,7 +8,9 @@ import type { AnyObject } from './types'
  */
 export function objectToFormData(obj: AnyObject = {}): FormData {
   const fd = new FormData()
-  Object.entries(obj).forEach(([k, v]) => fd.append(k, v))
+  for (const [k, v] of Object.entries(obj)) {
+    fd.append(k, v)
+  }
   return fd
 }
 

package/src/http/fetcher.ts

@@ -82,7 +82,7 @@ export class Fetcher {
     this.cfg = this.normalizeCfg(cfg)
 
     // Dynamically create all helper methods
-    HTTP_METHODS.forEach(method => {
+    for (const method of HTTP_METHODS) {
       const m = method.toLowerCase()
 
       // responseType=void
@@ -114,7 +114,7 @@ export class Fetcher {
           ...opt,
         })
       }
-    })
+    }
   }
 
   /**

package/src/math/math.util.ts

@@ -62,7 +62,7 @@ export function _percentiles(values: number[], pcs: number[]): Record<number, nu
 
   const sorted = _sortNumbers(values)
 
-  pcs.forEach(pc => {
+  for (const pc of pcs) {
     // Floating pos in the range of [0; length - 1]
     const pos = ((values.length - 1) * pc) / 100
     const dec = pos % 1
@@ -70,7 +70,7 @@ export function _percentiles(values: number[], pcs: number[]): Record<number, nu
     const ceilPos = Math.ceil(pos)
 
     r[pc] = _averageWeighted([sorted[floorPos]!, sorted[ceilPos]!], [1 - dec, dec])
-  })
+  }
 
   return r
 }

package/src/object/object.util.ts

@@ -440,7 +440,11 @@ export function _deepFreeze(o: any): void {
  */
 export function _objectAssignExact<T extends AnyObject>(target: T, source: T): void {
   Object.assign(target, source)
-  Object.keys(target)
-    .filter(k => !(k in source))
-    .forEach(k => delete target[k])
+
+  for (const k of Object.keys(target)) {
+    if (!(k in source)) {
+      // consider setting it to undefined maybe?
+      delete target[k]
+    }
+  }
 }

package/src/types.ts

@@ -101,6 +101,12 @@ export const END = Symbol('END')
  */
 export const SKIP = Symbol('SKIP')
 
+/**
+ * Symbol to indicate cache miss.
+ * To distinguish from cache returning `undefined` or `null`.
+ */
+export const MISS = Symbol('MISS')
+
 /**
  * Function which is called for every item in `input`. Expected to return a `Promise` or value.
  */