@naturalcycles/js-lib 14.213.0 → 14.215.0

package/src/decorators/asyncMemo.decorator.ts

@@ -1,7 +1,6 @@
 import type { CommonLogger } from '../log/commonLogger'
-import { _since } from '../time/time.util'
 import type { AnyObject } from '../types'
-import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util'
+import { _getTargetMethodSignature } from './decorator.util'
 import type { AsyncMemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
 
@@ -28,23 +27,6 @@ export interface AsyncMemoOptions {
    */
   cacheRejections?: boolean
 
-  /**
-   * Default to false
-   */
-  logHit?: boolean
-
-  /**
-   * Default to false
-   */
-  logMiss?: boolean
-
-  /**
-   * Set to `false` to skip logging method arguments.
-   *
-   * Defaults to true.
-   */
-  logArgs?: boolean
-
   /**
    * Default to `console`
    */
@@ -54,6 +36,10 @@ export interface AsyncMemoOptions {
 /**
  * Like @_Memo, but allowing async MemoCache implementation.
  *
+ * Important: it awaits the method to return the result before caching it.
+ *
+ * todo: test for "swarm requests", it should return "the same promise" and not cause a swarm origin hit
+ *
  * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
  * Return `null` instead (it'll be cached).
  */
@@ -71,9 +57,6 @@ export const _AsyncMemo =
     const cache = new Map<AnyObject, AsyncMemoCache>()
 
     const {
-      logHit = false,
-      logMiss = false,
-      logArgs = true,
       logger = console,
       cacheFactory = () => new MapMemoCache(),
       cacheKeyFn = jsonMemoSerializer,
@@ -105,15 +88,6 @@ export const _AsyncMemo =
 
       if (value !== undefined) {
         // hit!
-        if (logHit) {
-          logger.log(
-            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
-              args,
-              logArgs,
-            )}) @_AsyncMemo hit`,
-          )
-        }
-
         if (value instanceof Error) {
           throw value
         }
@@ -122,8 +96,6 @@ export const _AsyncMemo =
       }
 
       // Here we know it's a MISS, let's execute the real method
-      const started = Date.now()
-
       try {
         value = await originalFn.apply(ctx, args)
 
@@ -154,15 +126,6 @@ export const _AsyncMemo =
         }
 
         throw err
-      } finally {
-        if (logMiss) {
-          logger.log(
-            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
-              args,
-              logArgs,
-            )}) @_AsyncMemo miss (${_since(started)})`,
-          )
-        }
       }
     } as any
     ;(descriptor.value as any).dropCache = async () => {

package/src/decorators/memo.decorator.ts

@@ -1,7 +1,6 @@
 import type { CommonLogger } from '../log/commonLogger'
-import { _since } from '../time/time.util'
 import type { AnyObject } from '../types'
-import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util'
+import { _getTargetMethodSignature } from './decorator.util'
 import type { MemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
 
@@ -27,21 +26,6 @@ export interface MemoOptions {
    */
   cacheErrors?: boolean
 
-  /**
-   * Default to false
-   */
-  logHit?: boolean
-  /**
-   * Default to false
-   */
-  logMiss?: boolean
-
-  /**
-   * Defaults to true.
-   * Set to false to skip logging method arguments.
-   */
-  logArgs?: boolean
-
   /**
    * Default to `console`
    */
@@ -87,9 +71,6 @@ export const _Memo =
     const cache = new Map<AnyObject, MemoCache>()
 
     const {
-      logHit = false,
-      logMiss = false,
-      logArgs = true,
       logger = console,
       cacheFactory = () => new MapMemoCache(),
       cacheKeyFn = jsonMemoSerializer,
@@ -107,12 +88,6 @@ export const _Memo =
       if (!cache.has(ctx)) {
         cache.set(ctx, cacheFactory())
       } else if (cache.get(ctx)!.has(cacheKey)) {
-        if (logHit) {
-          logger.log(
-            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, logArgs)}) @_Memo hit`,
-          )
-        }
-
         value = cache.get(ctx)!.get(cacheKey)
 
         if (value instanceof Error) {
@@ -122,8 +97,6 @@ export const _Memo =
         return value
       }
 
-      const started = Date.now()
-
       try {
         value = originalFn.apply(ctx, args)
 
@@ -144,15 +117,6 @@ export const _Memo =
         }
 
         throw err
-      } finally {
-        if (logMiss) {
-          logger.log(
-            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
-              args,
-              logArgs,
-            )}) @_Memo miss (${_since(started)})`,
-          )
-        }
       }
     } as any
     ;(descriptor.value as any).dropCache = () => {

package/src/decorators/memoFn.ts

@@ -1,5 +1,3 @@
-import { _since } from '../time/time.util'
-import { _getArgsSignature } from './decorator.util'
 import type { MemoOptions } from './memo.decorator'
 import type { MemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
@@ -18,9 +16,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
   opt: MemoOptions = {},
 ): T & MemoizedFunction {
   const {
-    logHit = false,
-    logMiss = false,
-    logArgs = true,
     logger = console,
     cacheErrors = true,
     cacheFactory = () => new MapMemoCache(),
@@ -28,7 +23,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
   } = opt
 
   const cache = cacheFactory()
-  const fnName = fn.name
 
   const memoizedFn = function (this: any, ...args: any[]): T {
     const ctx = this
@@ -36,10 +30,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
     let value: any
 
     if (cache.has(cacheKey)) {
-      if (logHit) {
-        logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFn hit`)
-      }
-
       value = cache.get(cacheKey)
 
       if (value instanceof Error) {
@@ -49,8 +39,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
       return value
     }
 
-    const started = Date.now()
-
     try {
       value = fn.apply(ctx, args)
 
@@ -71,12 +59,6 @@ export function _memoFn<T extends (...args: any[]) => any>(
       }
 
       throw err
-    } finally {
-      if (logMiss) {
-        logger.log(
-          `${fnName}(${_getArgsSignature(args, logArgs)}) memoFn miss (${_since(started)})`,
-        )
-      }
     }
   }
 

package/src/decorators/memoFnAsync.ts

@@ -1,6 +1,4 @@
-import { _since } from '../time/time.util'
 import type { AsyncMemoOptions } from './asyncMemo.decorator'
-import { _getArgsSignature } from './decorator.util'
 import type { AsyncMemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
 
@@ -17,9 +15,6 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
   opt: AsyncMemoOptions = {},
 ): T & MemoizedAsyncFunction {
   const {
-    logHit = false,
-    logMiss = false,
-    logArgs = true,
     logger = console,
     cacheRejections = true,
     cacheFactory = () => new MapMemoCache(),
@@ -27,7 +22,6 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
   } = opt
 
   const cache = cacheFactory()
-  const fnName = fn.name
 
   const memoizedFn = async function (this: any, ...args: any[]): Promise<any> {
     const ctx = this
@@ -41,10 +35,6 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
     }
 
     if (value !== undefined) {
-      if (logHit) {
-        logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync hit`)
-      }
-
       if (value instanceof Error) {
         throw value
       }
@@ -52,8 +42,6 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
       return value
     }
 
-    const started = Date.now()
-
     try {
       value = await fn.apply(ctx, args)
 
@@ -78,12 +66,6 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
       }
 
       throw err
-    } finally {
-      if (logMiss) {
-        logger.log(
-          `${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync miss (${_since(started)})`,
-        )
-      }
     }
   }
 

package/src/decorators/memoSimple.decorator.ts

@@ -12,14 +12,11 @@ Benchmark shows similar perf for ObjectCache and MapCache.
  */
 
 import type { CommonLogger } from '../log/commonLogger'
-import { _getArgsSignature, _getTargetMethodSignature } from './decorator.util'
+import { _getTargetMethodSignature } from './decorator.util'
 import type { MemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
 
 export interface MemoOpts {
-  logHit?: boolean
-  logMiss?: boolean
-  logArgs?: boolean
   logger?: CommonLogger
 }
 
@@ -58,7 +55,7 @@ export const memoSimple =
    */
     const cache: MemoCache = new MapMemoCache()
 
-    const { logHit, logMiss, logArgs = true, logger = console } = opt
+    const { logger = console } = opt
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)
 
@@ -67,26 +64,11 @@ export const memoSimple =
       const cacheKey = jsonMemoSerializer(args)
 
       if (cache.has(cacheKey)) {
-        if (logHit) {
-          logger.log(`${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo hit`)
-        }
         return cache.get(cacheKey)
       }
 
-      const d = Date.now()
-
       const res: any = originalFn.apply(ctx, args)
-
-      if (logMiss) {
-        logger.log(
-          `${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo miss (${
-            Date.now() - d
-          } ms)`,
-        )
-      }
-
       cache.set(cacheKey, res)
-
       return res
     } as any
     ;(descriptor.value as any).dropCache = () => {

package/src/index.ts

@@ -35,6 +35,8 @@ export * from './object/deepEquals'
 export * from './object/object.util'
 export * from './object/sortObject'
 export * from './object/sortObjectDeep'
+export * from './object/map2'
+export * from './object/set2'
 export * from './promise/pDefer'
 export * from './promise/pDelay'
 export * from './promise/pFilter'

package/src/object/deepEquals.ts

@@ -1,68 +1,159 @@
-const isArray = Array.isArray
-const keyList = Object.keys
-const hasProp = Object.prototype.hasOwnProperty
+// Heavily inspired by https://github.com/epoberezkin/fast-deep-equal
 
 /**
- * deepEquals, but after JSON stringify/parse
- * E.g if object A has extra properties with value `undefined` -
- * it won't be _deepEquals true, but will be _deepJsonEquals true.
- * (because JSON.stringify removes undefined properties).
- */
-export function _deepJsonEquals(a: any, b: any): boolean {
-  if (a === b) return true
-  const aj = JSON.stringify(a)
-  const bj = JSON.stringify(b)
-  if (aj === bj) return true
-  return _deepEquals(JSON.parse(aj), JSON.parse(bj))
-}
-
-/**
- * Based on: https://github.com/epoberezkin/fast-deep-equal/
+ Returns true if a and b are deeply equal.
+ 
+ Equality is checked recursively, with the following rules/caveats:
+ - Primitive values are checked with ===
+ - NaN === NaN
+ - Array length should be the same, and every value should be equal
+ - Sets are checked similarly to arrays (but order doesn't matter in Sets)
+ - Objects and Maps are checked that all values match. Undefined values are treated the same as absent key (important!)
+ - Order of object/Map keys doesn't matter, unlike when comparing JSON.stringify(a) === JSON.stringify(b)
+ - Regex are compared by their source and flags
+ - Functions are compared by their `.toString`
+ - Any object that overrides `.toString()` is compared by that (e.g Function)
+ - Any object that overrides `.valueOf()` is compared by that (e.g Date)
+ 
+ What are the differences between various deep-equality functions?
+ There are:
+ - _deepEquals
+ - _deepJsonEquals
+ - _jsonEquals
+ 
+ _deepEquals uses "common sense" equality.
+ It tries to work "as you would expect it to".
+ With the important caveat that undefined values are treated the same as absent key.
+ So, _deepEquals should be the first choice.
+ It's also the most performant of 3.
+ 
+ _deepJsonEquals uses different logic, that's often not what you expect.
+ It should be used to compare objects of how they would look after "passing via JSON.stringify",
+ for example when you return it over the API to the Frontend,
+ or when you pass it to be saved to the Database.
+ If some object has custom .toJSON() implementation - it'll invoke that (similar to JSON.stringify).
+ For these cases - it can be better than _deepEquals.
+ And it's better than _jsonEquals, because it doesn't fail/depend on object key order.
+ 
+ _jsonEquals is simply JSON.stringify(a) === JSON.stringify(b).
+ It's the simplest implementation, but also the slowest of 3.
+ 
+ TLDR: _deepEquals should be useful in most of the cases, start there.
  */
 export function _deepEquals(a: any, b: any): boolean {
   if (a === b) return true
 
-  if (a && b && typeof a === 'object' && typeof b === 'object') {
-    const arrA = isArray(a)
-    const arrB = isArray(b)
-    let i: number
-    let length: number
-    let key: string
+  if (Number.isNaN(a)) {
+    return Number.isNaN(b)
+  }
 
-    if (arrA !== arrB) return false
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    if (a.constructor !== b.constructor) return false
 
-    if (arrA && arrB) {
-      length = a.length
+    if (Array.isArray(a)) {
+      const length = a.length
       if (length !== b.length) return false
-      for (i = length; i-- !== 0; ) if (!_deepEquals(a[i], b[i])) return false
+      for (let i = length; i-- !== 0; ) {
+        if (!_deepEquals(a[i], b[i])) return false
+      }
+      return true
+    }
+
+    if (a instanceof Map && b instanceof Map) {
+      for (const key of new Set([...a.keys(), ...b.keys()])) {
+        if (!_deepEquals(a.get(key), b.get(key))) return false
+      }
       return true
     }
 
-    const dateA = a instanceof Date
-    const dateB = b instanceof Date
-    if (dateA !== dateB) return false
-    if (dateA && dateB) return a.getTime() === b.getTime()
+    if (a instanceof Set && b instanceof Set) {
+      if (a.size !== b.size) return false
+      for (const key of a) {
+        if (!b.has(key)) return false
+      }
+      return true
+    }
 
-    const regexpA = a instanceof RegExp
-    const regexpB = b instanceof RegExp
-    if (regexpA !== regexpB) return false
-    if (regexpA && regexpB) return a.toString() === b.toString()
+    if (a.constructor === RegExp) return a.source === b.source && a.flags === b.flags
+    if (a.valueOf !== Object.prototype.valueOf) return a.valueOf() === b.valueOf()
+    if (a.toString !== Object.prototype.toString) return a.toString() === b.toString()
 
-    const keys = keyList(a)
-    length = keys.length
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (!_deepEquals(a[key], b[key])) return false
+    }
 
-    if (length !== keyList(b).length) return false
+    return true
+  }
 
-    for (i = length; i-- !== 0; ) if (!hasProp.call(b, keys[i]!)) return false
+  return a === b
+}
 
-    for (i = length; i-- !== 0; ) {
-      key = keys[i]!
-      if (!_deepEquals(a[key], b[key])) return false
+/**
+ Returns true if a and b are deeply equal.
+ 
+ Equality is checked in the same way as if both arguments are processed via
+ JSON.stringify and JSON.parse:
+ - undefined values are removed, undefined values in an array are turned into `null`, etc.
+ - Any Regex, Map, Set, Function stringifies to {}.
+ - Date stringifies to its IsoDateTimeString representation.
+ - Any object that implements toJSON is compared by the output of its toJSON().
+ - NaN stringifies to null
+ - Order of object keys does not matter, unlike when comparing JSON.stringify(a) === JSON.stringify(b)
+ 
+ See _deepEquals docs for more details and comparison.
+ */
+export function _deepJsonEquals(a: any, b: any): boolean {
+  if (a === b) return true
+
+  if (Number.isNaN(a)) {
+    a = null
+  } else if (typeof a === 'function') {
+    a = undefined
+  } else if (a && typeof a === 'object') {
+    if (a instanceof Date) {
+      a = a.valueOf()
+    } else if ('toJSON' in a) {
+      a = a.toJSON()
+    }
+  }
+  if (Number.isNaN(b)) {
+    b = null
+  } else if (typeof b === 'function') {
+    b = undefined
+  } else if (b && typeof b === 'object') {
+    if (b instanceof Date) {
+      b = b.valueOf()
+    } else if ('toJSON' in b) {
+      b = b.toJSON()
+    }
+  }
+
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    if (Array.isArray(a)) {
+      const length = a.length
+      if (length !== b.length) return false
+      for (let i = length; i-- !== 0; ) {
+        if (!_deepJsonEquals(a[i], b[i])) return false
+      }
+      return true
+    }
+
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (!_deepJsonEquals(a[key], b[key])) return false
     }
 
     return true
   }
 
-  // eslint-disable-next-line no-self-compare
-  return a !== a && b !== b
+  return a === b
+}
+
+/**
+ * Shortcut for JSON.stringify(a) === JSON.stringify(b)
+ *
+ * Simplest "deep equals" implementation, but also the slowest,
+ * and not robust, in the sense that it depends on the order of object keys.
+ */
+export function _jsonEquals(a: any, b: any): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
 }

package/src/object/map2.ts

@@ -0,0 +1,25 @@
+/**
+ * Like Map, but serializes to JSON as an object.
+ *
+ * Fixes the "issue" of stock Map being json-serialized as `{}`.
+ *
+ * @experimental
+ */
+export class Map2<K = any, V = any> extends Map<K, V> {
+  /**
+   * Convenience way to create Map2 from object.
+   */
+  static of<V>(obj: Record<any, V>): Map2<string, V> {
+    return new Map2(Object.entries(obj))
+  }
+
+  toObject(): Record<string, V> {
+    return Object.fromEntries(this)
+  }
+
+  toJSON(): Record<string, V> {
+    return Object.fromEntries(this)
+  }
+
+  // consider more helpful .toString() ?
+}

package/src/object/object.util.ts

@@ -1,5 +1,4 @@
 import { _isEmpty, _isObject } from '../is.util'
-import type { PropertyPath } from '../lodash.types'
 import { _objectEntries, KeyValueTuple, Reviver, SKIP } from '../types'
 import type { AnyObject, ObjectMapper, ObjectPredicate, ValueOf } from '../types'
 
@@ -328,6 +327,9 @@ export function _get<T extends AnyObject>(obj = {} as T, path = ''): unknown {
     .reduce((o, p) => o?.[p], obj)
 }
 
+type Many<T> = T | readonly T[]
+type PropertyPath = Many<PropertyKey>
+
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for
  * missing index properties while objects are created for all other missing properties.

package/src/object/set2.ts

@@ -0,0 +1,18 @@
+/**
+ * Like Set, but serializes to JSON as an array.
+ *
+ * Fixes the "issue" of stock Set being json-serialized as `{}`.
+ *
+ * @experimental
+ */
+export class Set2<T = any> extends Set<T> {
+  toArray(): T[] {
+    return [...this]
+  }
+
+  toJSON(): T[] {
+    return [...this]
+  }
+
+  // consider more helpful .toString() ?
+}

package/src/string/stringify.ts

@@ -158,6 +158,12 @@ export function _stringify(obj: any, opt: StringifyOptions = {}): string {
     //
     // Other
     //
+    if (obj instanceof Map) {
+      obj = Object.fromEntries(obj)
+    } else if (obj instanceof Set) {
+      obj = [...obj]
+    }
+
     try {
       const { stringifyFn = globalStringifyFunction } = opt
 

package/dist/lodash.types.d.ts

@@ -1,4 +0,0 @@
-export type PropertyName = string | number | symbol;
-export type RecursiveArray<T> = (T | RecursiveArray<T>)[];
-export type Many<T> = T | readonly T[];
-export type PropertyPath = Many<PropertyName>;

package/dist/lodash.types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist-esm/lodash.types.js

@@ -1 +0,0 @@
-export {};

package/src/lodash.types.ts

@@ -1,6 +0,0 @@
-export type PropertyName = string | number | symbol
-
-export type RecursiveArray<T> = (T | RecursiveArray<T>)[]
-
-export type Many<T> = T | readonly T[]
-export type PropertyPath = Many<PropertyName>