@naturalcycles/js-lib 14.213.0 → 14.215.0

package/dist/object/object.util.d.ts

@@ -1,4 +1,3 @@
-import type { PropertyPath } from '../lodash.types';
 import { KeyValueTuple, Reviver, SKIP } from '../types';
 import type { AnyObject, ObjectMapper, ObjectPredicate, ValueOf } from '../types';
 /**
@@ -146,6 +145,8 @@ export declare function _invertMap<K, V>(m: ReadonlyMap<K, V>): Map<V, K>;
  * _get(obj, 'unknown.path') // undefined
  */
 export declare function _get<T extends AnyObject>(obj?: T, path?: string): unknown;
+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.
@@ -207,3 +208,4 @@ export declare function _deepFreeze(o: any): void;
  * To make mutation extra clear - function returns void (unlike Object.assign).
  */
 export declare function _objectAssignExact<T extends AnyObject>(target: T, source: T): void;
+export {};

package/dist/object/set2.d.ts

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

package/dist/object/set2.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Set2 = void 0;
+/**
+ * Like Set, but serializes to JSON as an array.
+ *
+ * Fixes the "issue" of stock Set being json-serialized as `{}`.
+ *
+ * @experimental
+ */
+class Set2 extends Set {
+    toArray() {
+        return [...this];
+    }
+    toJSON() {
+        return [...this];
+    }
+}
+exports.Set2 = Set2;

package/dist/string/stringify.js

@@ -111,6 +111,12 @@ function _stringify(obj, opt = {}) {
         //
         // Other
         //
+        if (obj instanceof Map) {
+            obj = Object.fromEntries(obj);
+        }
+        else if (obj instanceof Set) {
+            obj = [...obj];
+        }
         try {
             const { stringifyFn = globalStringifyFunction } = opt;
             s = stringifyFn(obj, undefined, 2);

package/dist-esm/array/array.util.js

@@ -160,6 +160,9 @@ export function _sortDescBy(items, mapper, mutate = false) {
 }
 /**
  * Like items.find(), but it tries to find from the END of the array.
+ *
+ * Node 18+ supports native array.findLast() - use that.
+ * iOS Safari only has it since 15.4
  */
 export function _findLast(items, predicate) {
     return [...items].reverse().find(predicate);

package/dist-esm/decorators/asyncMemo.decorator.js

@@ -1,9 +1,12 @@
-import { _since } from '../time/time.util';
-import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
+import { _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
 /**
  * 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).
  */
@@ -15,7 +18,7 @@ export const _AsyncMemo = (opt = {}) => (target, key, descriptor) => {
     const originalFn = descriptor.value;
     // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
     const cache = new Map();
-    const { logHit = false, logMiss = false, logArgs = true, logger = console, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, cacheRejections = true, } = opt;
+    const { logger = console, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, cacheRejections = true, } = opt;
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = async function (...args) {
@@ -36,16 +39,12 @@ export const _AsyncMemo = (opt = {}) => (target, key, descriptor) => {
         }
         if (value !== undefined) {
             // hit!
-            if (logHit) {
-                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, logArgs)}) @_AsyncMemo hit`);
-            }
             if (value instanceof Error) {
                 throw value;
             }
             return value;
         }
         // Here we know it's a MISS, let's execute the real method
-        const started = Date.now();
         try {
             value = await originalFn.apply(ctx, args);
             // Save the value in the Cache, without awaiting it
@@ -77,11 +76,6 @@ export const _AsyncMemo = (opt = {}) => (target, key, descriptor) => {
             }
             throw err;
         }
-        finally {
-            if (logMiss) {
-                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, logArgs)}) @_AsyncMemo miss (${_since(started)})`);
-            }
-        }
     };
     descriptor.value.dropCache = async () => {
         logger.log(`${methodSignature} @_AsyncMemo.dropCache()`);

package/dist-esm/decorators/memo.decorator.js

@@ -1,5 +1,4 @@
-import { _since } from '../time/time.util';
-import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
+import { _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
 /**
  * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
@@ -34,7 +33,7 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
     // UPD: tests show that normal Map also doesn't leak (to be tested further)
     // Normal Map is needed to allow .dropCache()
     const cache = new Map();
-    const { logHit = false, logMiss = false, logArgs = true, logger = console, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, cacheErrors = true, } = opt;
+    const { logger = console, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, cacheErrors = true, } = opt;
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = function (...args) {
@@ -45,16 +44,12 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
             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) {
                 throw value;
             }
             return value;
         }
-        const started = Date.now();
         try {
             value = originalFn.apply(ctx, args);
             try {
@@ -76,11 +71,6 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
             }
             throw err;
         }
-        finally {
-            if (logMiss) {
-                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, logArgs)}) @_Memo miss (${_since(started)})`);
-            }
-        }
     };
     descriptor.value.dropCache = () => {
         logger.log(`${methodSignature} @_Memo.dropCache()`);

package/dist-esm/decorators/memoFn.js

@@ -1,5 +1,3 @@
-import { _since } from '../time/time.util';
-import { _getArgsSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
 /**
  * Only supports Sync functions.
@@ -7,24 +5,19 @@ import { jsonMemoSerializer, MapMemoCache } from './memo.util';
  * Technically, you can use it with Async functions, but it'll return the Promise without awaiting it.
  */
 export function _memoFn(fn, opt = {}) {
-    const { logHit = false, logMiss = false, logArgs = true, logger = console, cacheErrors = true, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
+    const { logger = console, cacheErrors = true, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
     const cache = cacheFactory();
-    const fnName = fn.name;
     const memoizedFn = function (...args) {
         const ctx = this;
         const cacheKey = cacheKeyFn(args);
         let value;
         if (cache.has(cacheKey)) {
-            if (logHit) {
-                logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFn hit`);
-            }
             value = cache.get(cacheKey);
             if (value instanceof Error) {
                 throw value;
             }
             return value;
         }
-        const started = Date.now();
         try {
             value = fn.apply(ctx, args);
             try {
@@ -46,11 +39,6 @@ export function _memoFn(fn, opt = {}) {
             }
             throw err;
         }
-        finally {
-            if (logMiss) {
-                logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFn miss (${_since(started)})`);
-            }
-        }
     };
     Object.assign(memoizedFn, { cache });
     return memoizedFn;

package/dist-esm/decorators/memoFnAsync.js

@@ -1,14 +1,11 @@
-import { _since } from '../time/time.util';
-import { _getArgsSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
 /**
  * Only supports Sync functions.
  * To support Async functions - use _memoFnAsync
  */
 export function _memoFnAsync(fn, opt = {}) {
-    const { logHit = false, logMiss = false, logArgs = true, logger = console, cacheRejections = true, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
+    const { logger = console, cacheRejections = true, cacheFactory = () => new MapMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
     const cache = cacheFactory();
-    const fnName = fn.name;
     const memoizedFn = async function (...args) {
         const ctx = this;
         const cacheKey = cacheKeyFn(args);
@@ -20,15 +17,11 @@ export function _memoFnAsync(fn, opt = {}) {
             logger.error(err);
         }
         if (value !== undefined) {
-            if (logHit) {
-                logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync hit`);
-            }
             if (value instanceof Error) {
                 throw value;
             }
             return value;
         }
-        const started = Date.now();
         try {
             value = await fn.apply(ctx, args);
             void (async () => {
@@ -54,11 +47,6 @@ export function _memoFnAsync(fn, opt = {}) {
             }
             throw err;
         }
-        finally {
-            if (logMiss) {
-                logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync miss (${_since(started)})`);
-            }
-        }
     };
     Object.assign(memoizedFn, { cache });
     return memoizedFn;

package/dist-esm/decorators/memoSimple.decorator.js

@@ -3,7 +3,7 @@
 // http://decodize.com/blog/2012/08/27/javascript-memoization-caching-results-for-better-performance/
 // http://inlehmansterms.net/2015/03/01/javascript-memoization/
 // https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
-import { _getArgsSignature, _getTargetMethodSignature } from './decorator.util';
+import { _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
 // memoSimple decorator is NOT exported. Only used in benchmarks currently
 /**
@@ -34,23 +34,16 @@ export const memoSimple = (opt = {}) => (target, key, descriptor) => {
   }
    */
     const cache = new MapMemoCache();
-    const { logHit, logMiss, logArgs = true, logger = console } = opt;
+    const { logger = console } = opt;
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = function (...args) {
         const ctx = this;
         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 = originalFn.apply(ctx, args);
-        if (logMiss) {
-            logger.log(`${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo miss (${Date.now() - d} ms)`);
-        }
         cache.set(cacheKey, res);
         return res;
     };

package/dist-esm/index.js

@@ -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/dist-esm/object/deepEquals.js

@@ -1,70 +1,163 @@
-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).
+ 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 _deepJsonEquals(a, b) {
+export function _deepEquals(a, b) {
     if (a === b)
         return true;
-    const aj = JSON.stringify(a);
-    const bj = JSON.stringify(b);
-    if (aj === bj)
+    if (Number.isNaN(a)) {
+        return Number.isNaN(b);
+    }
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        if (a.constructor !== b.constructor)
+            return false;
+        if (Array.isArray(a)) {
+            const length = a.length;
+            if (length !== b.length)
+                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;
+        }
+        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;
+        }
+        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();
+        for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            if (!_deepEquals(a[key], b[key]))
+                return false;
+        }
         return true;
-    return _deepEquals(JSON.parse(aj), JSON.parse(bj));
+    }
+    return a === b;
 }
 /**
- * Based on: https://github.com/epoberezkin/fast-deep-equal/
+ 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 _deepEquals(a, b) {
+export function _deepJsonEquals(a, b) {
     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') {
-        const arrA = isArray(a);
-        const arrB = isArray(b);
-        let i;
-        let length;
-        let key;
-        if (arrA !== arrB)
-            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]))
+            for (let i = length; i-- !== 0;) {
+                if (!_deepJsonEquals(a[i], b[i]))
                     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();
-        const regexpA = a instanceof RegExp;
-        const regexpB = b instanceof RegExp;
-        if (regexpA !== regexpB)
-            return false;
-        if (regexpA && regexpB)
-            return a.toString() === b.toString();
-        const keys = keyList(a);
-        length = keys.length;
-        if (length !== keyList(b).length)
-            return false;
-        for (i = length; i-- !== 0;)
-            if (!hasProp.call(b, keys[i]))
-                return false;
-        for (i = length; i-- !== 0;) {
-            key = keys[i];
-            if (!_deepEquals(a[key], b[key]))
+        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, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
 }

package/dist-esm/object/map2.js

@@ -0,0 +1,21 @@
+/**
+ * Like Map, but serializes to JSON as an object.
+ *
+ * Fixes the "issue" of stock Map being json-serialized as `{}`.
+ *
+ * @experimental
+ */
+export class Map2 extends Map {
+    /**
+     * Convenience way to create Map2 from object.
+     */
+    static of(obj) {
+        return new Map2(Object.entries(obj));
+    }
+    toObject() {
+        return Object.fromEntries(this);
+    }
+    toJSON() {
+        return Object.fromEntries(this);
+    }
+}

package/dist-esm/object/set2.js

@@ -0,0 +1,15 @@
+/**
+ * Like Set, but serializes to JSON as an array.
+ *
+ * Fixes the "issue" of stock Set being json-serialized as `{}`.
+ *
+ * @experimental
+ */
+export class Set2 extends Set {
+    toArray() {
+        return [...this];
+    }
+    toJSON() {
+        return [...this];
+    }
+}

package/dist-esm/string/stringify.js

@@ -107,6 +107,12 @@ export function _stringify(obj, opt = {}) {
         //
         // Other
         //
+        if (obj instanceof Map) {
+            obj = Object.fromEntries(obj);
+        }
+        else if (obj instanceof Set) {
+            obj = [...obj];
+        }
         try {
             const { stringifyFn = globalStringifyFunction } = opt;
             s = stringifyFn(obj, undefined, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.213.0",
+  "version": "14.215.0",
   "scripts": {
     "prepare": "husky",
     "build-prod": "build-prod-esm-cjs",
@@ -25,9 +25,6 @@
     "vitepress": "^1.0.0",
     "vue": "^3.2.45"
   },
-  "resolutions": {
-    "expect-type": "0.15.0"
-  },
   "files": [
     "dist",
     "dist-esm",

package/src/array/array.util.ts

@@ -196,6 +196,9 @@ export function _sortDescBy<T>(items: T[], mapper: Mapper<T, any>, mutate = fals
 
 /**
  * Like items.find(), but it tries to find from the END of the array.
+ *
+ * Node 18+ supports native array.findLast() - use that.
+ * iOS Safari only has it since 15.4
  */
 export function _findLast<T>(items: T[], predicate: Predicate<T>): T | undefined {
   return [...items].reverse().find(predicate)