@naturalcycles/js-lib 14.80.0 → 14.83.0

package/dist/promise/pRetry.js

@@ -1,58 +1,90 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pRetry = void 0;
+exports.pRetry = exports.pRetryFn = void 0;
 const __1 = require("..");
+const pTimeout_1 = require("./pTimeout");
 /**
  * Returns a Function (!), enhanced with retry capabilities.
  * Implements "Exponential back-off strategy" by multiplying the delay by `delayMultiplier` with each try.
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
-function pRetry(fn, opt = {}) {
-    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name = fn.name, } = opt;
+function pRetryFn(fn, opt = {}) {
+    return async function pRetryFunction(...args) {
+        return await pRetry(() => fn.call(this, ...args), opt);
+    };
+}
+exports.pRetryFn = pRetryFn;
+async function pRetry(fn, opt = {}) {
+    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name, keepStackTrace = true, timeout, } = opt;
+    const fakeError = keepStackTrace ? new Error('RetryError') : undefined;
     let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt;
     if (opt.logAll) {
-        logFirstAttempt = logRetries = logFailures = true;
+        logSuccess = logFirstAttempt = logRetries = logFailures = true;
     }
     if (opt.logNone) {
         logSuccess = logFirstAttempt = logRetries = logFailures = false;
     }
-    const fname = ['pRetry', name].filter(Boolean).join('.');
-    return async function (...args) {
-        let delay = initialDelay;
-        let attempt = 0;
-        return await new Promise((resolve, reject) => {
-            const next = async () => {
-                const started = Date.now();
-                try {
-                    attempt++;
-                    if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
-                        logger.log(`${fname} attempt #${attempt}...`);
-                    }
-                    const r = await fn.apply(this, args);
-                    if (logSuccess) {
-                        logger.log(`${fname} attempt #${attempt} succeeded in ${(0, __1._since)(started)}`);
-                    }
-                    resolve(r);
+    const fname = name || fn.name || 'pRetry function';
+    let delay = initialDelay;
+    let attempt = 0;
+    let timer;
+    let timedOut = false;
+    return await new Promise((resolve, reject) => {
+        const rejectWithTimeout = () => {
+            timedOut = true; // to prevent more tries
+            const err = new pTimeout_1.TimeoutError(`"${fname}" timed out after ${timeout} ms`);
+            if (fakeError) {
+                // keep original stack
+                err.stack = fakeError.stack.replace('Error: RetryError', 'TimeoutError');
+            }
+            reject(err);
+        };
+        const next = async () => {
+            if (timedOut)
+                return;
+            if (timeout) {
+                timer = setTimeout(rejectWithTimeout, timeout);
+            }
+            const started = Date.now();
+            try {
+                attempt++;
+                if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
+                    logger.log(`${fname} attempt #${attempt}...`);
                 }
-                catch (err) {
-                    if (logFailures) {
-                        logger.warn(`${fname} attempt #${attempt} error in ${(0, __1._since)(started)}:`, (0, __1._stringifyAny)(err, {
-                            includeErrorData: true,
-                        }));
-                    }
-                    if (attempt >= maxAttempts || (predicate && !predicate(err, attempt, maxAttempts))) {
-                        // Give up
-                        reject(err);
-                    }
-                    else {
-                        // Retry after delay
-                        delay *= delayMultiplier;
-                        setTimeout(next, delay);
+                const r = await fn(attempt);
+                clearTimeout(timer);
+                if (logSuccess) {
+                    logger.log(`${fname} attempt #${attempt} succeeded in ${(0, __1._since)(started)}`);
+                }
+                resolve(r);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                if (logFailures) {
+                    logger.warn(`${fname} attempt #${attempt} error in ${(0, __1._since)(started)}:`, (0, __1._stringifyAny)(err, {
+                        includeErrorData: true,
+                    }));
+                }
+                if (attempt >= maxAttempts ||
+                    (predicate && !predicate(err, attempt, maxAttempts))) {
+                    // Give up
+                    if (fakeError) {
+                        // Preserve the original call stack
+                        Object.defineProperty(err, 'stack', {
+                            value: err.stack +
+                                '\n    --' +
+                                fakeError.stack.replace('Error: RetryError', ''),
+                        });
                     }
+                    reject(err);
                 }
-            };
-            void next();
-        });
-    };
+                else {
+                    // Retry after delay
+                    delay *= delayMultiplier;
+                    setTimeout(next, delay);
+                }
+            }
+        };
+        void next();
+    });
 }
 exports.pRetry = pRetry;

package/dist/types.d.ts

@@ -127,8 +127,8 @@ export declare type UnixTimestamp = number;
 /**
  * Base interface for any Entity that was saved to DB.
  */
-export interface SavedDBEntity {
-    id: string;
+export interface SavedDBEntity<ID = string> {
+    id: ID;
     /**
      * unixTimestamp of when the entity was first created (in the DB).
      */
@@ -144,9 +144,9 @@ export interface SavedDBEntity {
  * hence `id`, `created` and `updated` fields CAN BE undefined (yet).
  * When it's known to be saved - `SavedDBEntity` interface can be used instead.
  */
-export declare type BaseDBEntity = Partial<SavedDBEntity>;
-export declare type Saved<E> = Merge<E, SavedDBEntity>;
-export declare type Unsaved<E> = Merge<E, BaseDBEntity>;
+export declare type BaseDBEntity<ID = string> = Partial<SavedDBEntity<ID>>;
+export declare type Saved<E, ID = string> = Merge<E, SavedDBEntity<ID>>;
+export declare type Unsaved<E, ID = string> = Merge<E, BaseDBEntity<ID>>;
 /**
  * Named type for JSON.parse / JSON.stringify second argument
  */

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

@@ -0,0 +1,104 @@
+import { __asyncValues } from "tslib";
+import { _since } from '../time/time.util';
+import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
+import { CACHE_DROP } from './memo.decorator';
+import { jsonMemoSerializer } from './memo.util';
+/**
+ * Like @_Memo, but allowing async MemoCache implementation.
+ *
+ * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
+ * Return `null` instead (it'll be cached).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const _AsyncMemo = (opt) => (target, key, descriptor) => {
+    if (typeof descriptor.value !== 'function') {
+        throw new TypeError('Memoization can be applied only to methods');
+    }
+    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, noLogArgs = false, logger = console, cacheFactory, cacheKeyFn = jsonMemoSerializer, noCacheRejected = false, noCacheResolved = false, } = opt;
+    const keyStr = String(key);
+    const methodSignature = _getTargetMethodSignature(target, keyStr);
+    descriptor.value = async function (...args) {
+        var e_1, _a;
+        const ctx = this;
+        const cacheKey = cacheKeyFn(args);
+        if (!cache.has(ctx)) {
+            cache.set(ctx, cacheFactory());
+            // here, no need to check the cache. It's definitely a miss, because the cacheLayers is just created
+            // UPD: no! AsyncMemo supports "persistent caches" (e.g Database-backed cache)
+        }
+        if (args.length === 1 && args[0] === CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_AsyncMemo.dropCache()`);
+            try {
+                await Promise.all(cache.get(ctx).map(c => c.clear()));
+            }
+            catch (err) {
+                logger.error(err);
+            }
+            return;
+        }
+        let value;
+        try {
+            try {
+                for (var _b = __asyncValues(cache.get(ctx)), _c; _c = await _b.next(), !_c.done;) {
+                    const cacheLayer = _c.value;
+                    value = await cacheLayer.get(cacheKey);
+                    if (value !== undefined) {
+                        // it's a hit!
+                        break;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) await _a.call(_b);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            // log error, but don't throw, treat it as a "miss"
+            logger.error(err);
+        }
+        if (value !== undefined) {
+            // hit!
+            if (logHit) {
+                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, noLogArgs)}) @_AsyncMemo hit`);
+            }
+            return value instanceof Error ? Promise.reject(value) : Promise.resolve(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);
+            if (!noCacheResolved) {
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, value))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            return value;
+        }
+        catch (err) {
+            if (!noCacheRejected) {
+                // We put it to cache as raw Error, not Promise.reject(err)
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, err))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            throw err;
+        }
+        finally {
+            if (logMiss) {
+                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, noLogArgs)}) @_AsyncMemo miss (${_since(started)})`);
+            }
+        }
+    };
+    return descriptor;
+};

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

@@ -6,6 +6,10 @@
 import { _since } from '../time/time.util';
 import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
+/**
+ * Symbol to indicate that the Cache should be dropped.
+ */
+export const CACHE_DROP = Symbol('CACHE_DROP');
 /**
  * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
  * of the cache is the same. Key, by defaul, is calculated as `JSON.stringify(...args)`.
@@ -35,7 +39,14 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = function (...args) {
+        var _a;
         const ctx = this;
+        if (args.length === 1 && args[0] === CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_Memo.CACHE_DROP`);
+            return (_a = cache.get(ctx)) === null || _a === void 0 ? void 0 : _a.clear();
+        }
         const cacheKey = cacheKeyFn(args);
         if (!cache.has(ctx)) {
             cache.set(ctx, cacheFactory());
@@ -88,10 +99,5 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
             return res;
         }
     };
-    descriptor.value.dropCache = () => {
-        logger.log(`${methodSignature} @_Memo.dropCache()`);
-        cache.forEach(memoCache => memoCache.clear());
-        cache.clear();
-    };
     return descriptor;
 };

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

@@ -1,6 +1,6 @@
 import { _isPrimitive } from '../object/object.util';
 export const jsonMemoSerializer = args => {
-    if (!args.length)
+    if (args.length === 0)
         return undefined;
     if (args.length === 1 && _isPrimitive(args[0]))
         return args[0];
@@ -68,3 +68,17 @@ export class MapMemoCache {
         this.m.clear();
     }
 }
+export class MapAsyncMemoCache {
+    constructor() {
+        this.m = new Map();
+    }
+    async get(k) {
+        return this.m.get(k);
+    }
+    async set(k, v) {
+        this.m.set(k, v);
+    }
+    async clear() {
+        this.m.clear();
+    }
+}

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

@@ -1,9 +1,9 @@
-import { pRetry } from '..';
+import { pRetryFn } from '..';
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Retry(opt = {}) {
     return (target, key, descriptor) => {
         const originalFn = descriptor.value;
-        descriptor.value = pRetry(originalFn, opt);
+        descriptor.value = pRetryFn(originalFn, opt);
         return descriptor;
     };
 }

package/dist-esm/index.js

@@ -8,6 +8,7 @@ export * from './decorators/debounce.decorator';
 export * from './decorators/decorator.util';
 export * from './decorators/logMethod.decorator';
 export * from './decorators/memo.decorator';
+export * from './decorators/asyncMemo.decorator';
 export * from './decorators/memoFn';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
@@ -31,14 +32,13 @@ export * from './object/object.util';
 export * from './object/sortObject';
 export * from './object/sortObjectDeep';
 import { AggregatedError } from './promise/AggregatedError';
-export * from './promise/pBatch';
 import { pDefer } from './promise/pDefer';
 export * from './promise/pDelay';
 export * from './promise/pFilter';
 export * from './promise/pHang';
 import { pMap } from './promise/pMap';
 export * from './promise/pProps';
-import { pRetry } from './promise/pRetry';
+import { pRetry, pRetryFn } from './promise/pRetry';
 export * from './promise/pState';
 import { pTimeout, pTimeoutFn } from './promise/pTimeout';
 export * from './promise/pTuple';
@@ -55,4 +55,4 @@ export * from './string/safeJsonStringify';
 import { PQueue } from './promise/pQueue';
 export * from './seq/seq';
 export * from './math/stack.util';
-export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };
+export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pRetryFn, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };

package/dist-esm/json-schema/jsonSchemaBuilder.js

@@ -301,16 +301,16 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         Object.assign(this.schema, { additionalProperties });
         return this;
     }
-    baseDBEntity() {
+    baseDBEntity(idType = 'string') {
         Object.assign(this.schema.properties, {
-            id: { type: 'string' },
+            id: { type: idType },
             created: { type: 'number', format: 'unixTimestamp' },
             updated: { type: 'number', format: 'unixTimestamp' },
         });
         return this;
     }
-    savedDBEntity() {
-        return this.baseDBEntity().addRequired(['id', 'created', 'updated']);
+    savedDBEntity(idType = 'string') {
+        return this.baseDBEntity(idType).addRequired(['id', 'created', 'updated']);
     }
     extend(s2) {
         const builder = new JsonSchemaObjectBuilder();

package/dist-esm/promise/AggregatedError.js

@@ -5,17 +5,12 @@
  */
 export class AggregatedError extends Error {
     constructor(errors, results = []) {
-        const mappedErrors = errors.map(e => {
-            if (typeof e === 'string')
-                return new Error(e);
-            return e;
-        });
         const message = [
             `${errors.length} errors:`,
-            ...mappedErrors.map((e, i) => `${i + 1}. ${e.message}`),
+            ...errors.map((e, i) => `${i + 1}. ${e.message}`),
         ].join('\n');
         super(message);
-        this.errors = mappedErrors;
+        this.errors = errors;
         this.results = results;
         Object.defineProperty(this, 'name', {
             value: this.constructor.name,

package/dist-esm/promise/pFilter.js

@@ -1,5 +1,5 @@
-import { pMap } from './pMap';
-export async function pFilter(iterable, filterFn, opt) {
-    const values = await pMap(iterable, async (item, index) => await Promise.all([filterFn(item, index), item]), opt);
-    return values.filter(value => Boolean(value[0])).map(value => value[1]);
+export async function pFilter(iterable, filterFn) {
+    const items = [...iterable];
+    const predicates = await Promise.all(items.map((item, i) => filterFn(item, i)));
+    return items.filter((item, i) => predicates[i]);
 }

package/dist-esm/promise/pMap.js

@@ -6,6 +6,7 @@ Improvements:
 - Included Typescript typings (no need for @types/p-map)
 - Compatible with pProps (that had typings issues)
  */
+import { __asyncValues } from "tslib";
 import { END, ErrorMode, SKIP } from '..';
 import { AggregatedError } from './AggregatedError';
 /**
@@ -35,28 +36,85 @@ import { AggregatedError } from './AggregatedError';
  * })();
  */
 export async function pMap(iterable, mapper, opt = {}) {
+    var e_1, _a;
+    const ret = [];
+    // const iterator = iterable[Symbol.iterator]()
+    const items = [...iterable];
+    const itemsLength = items.length;
+    if (itemsLength === 0)
+        return []; // short circuit
+    const { concurrency = itemsLength, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt;
+    const errors = [];
+    let isSettled = false;
+    let resolvingCount = 0;
+    let currentIndex = 0;
+    // Special cases that are able to preserve async stack traces
+    if (concurrency === 1) {
+        try {
+            // Special case for concurrency == 1
+            for (var items_1 = __asyncValues(items), items_1_1; items_1_1 = await items_1.next(), !items_1_1.done;) {
+                const item = items_1_1.value;
+                try {
+                    const r = await mapper(item, currentIndex++);
+                    if (r === END)
+                        break;
+                    if (r !== SKIP)
+                        ret.push(r);
+                }
+                catch (err) {
+                    if (errorMode === ErrorMode.THROW_IMMEDIATELY)
+                        throw err;
+                    if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                        errors.push(err);
+                    }
+                    // otherwise, suppress completely
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (items_1_1 && !items_1_1.done && (_a = items_1.return)) await _a.call(items_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        if (errors.length) {
+            throw new AggregatedError(errors, ret);
+        }
+        return ret;
+    }
+    else if (!opt.concurrency || items.length <= opt.concurrency) {
+        // Special case for concurrency == infinity or iterable.length < concurrency
+        if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
+            return (await Promise.all(items.map((item, i) => mapper(item, i)))).filter(r => r !== SKIP && r !== END);
+        }
+        ;
+        (await Promise.allSettled(items.map((item, i) => mapper(item, i)))).forEach(r => {
+            if (r.status === 'fulfilled') {
+                if (r.value !== SKIP && r.value !== END)
+                    ret.push(r.value);
+            }
+            else if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                errors.push(r.reason);
+            }
+        });
+        if (errors.length) {
+            throw new AggregatedError(errors, ret);
+        }
+        return ret;
+    }
     return new Promise((resolve, reject) => {
-        const { concurrency = Number.POSITIVE_INFINITY, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt;
-        const ret = [];
-        const iterator = iterable[Symbol.iterator]();
-        const errors = [];
-        let isSettled = false;
-        let isIterableDone = false;
-        let resolvingCount = 0;
-        let currentIndex = 0;
-        const next = (skipped = false) => {
+        const next = () => {
             if (isSettled) {
                 return;
             }
-            const nextItem = iterator.next();
-            const i = currentIndex;
-            if (!skipped)
-                currentIndex++;
-            if (nextItem.done) {
-                isIterableDone = true;
+            const nextItem = items[currentIndex];
+            const i = currentIndex++;
+            if (currentIndex > itemsLength) {
                 if (resolvingCount === 0) {
+                    isSettled = true;
                     const r = ret.filter(r => r !== SKIP);
-                    if (errors.length && errorMode === ErrorMode.THROW_AGGREGATED) {
+                    if (errors.length) {
                         reject(new AggregatedError(errors, r));
                     }
                     else {
@@ -66,7 +124,7 @@ export async function pMap(iterable, mapper, opt = {}) {
                 return;
             }
             resolvingCount++;
-            Promise.resolve(nextItem.value)
+            Promise.resolve(nextItem)
                 .then(async (element) => await mapper(element, i))
                 .then(value => {
                 if (value === END) {
@@ -82,7 +140,9 @@ export async function pMap(iterable, mapper, opt = {}) {
                     reject(err);
                 }
                 else {
-                    errors.push(err);
+                    if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                        errors.push(err);
+                    }
                     resolvingCount--;
                     next();
                 }
@@ -90,7 +150,7 @@ export async function pMap(iterable, mapper, opt = {}) {
         };
         for (let i = 0; i < concurrency; i++) {
             next();
-            if (isIterableDone) {
+            if (isSettled) {
                 break;
             }
         }