@naturalcycles/js-lib 14.69.0 → 14.69.4

package/dist/index.d.ts

@@ -54,8 +54,8 @@ import { Class, ConditionalExcept, ConditionalPick, Merge, Promisable, PromiseVa
 import { AsyncMapper, AsyncPredicate, BaseDBEntity, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, Saved, Unsaved, BatchResult, InstanceId, IsoDate, IsoDateTime, KeyValueTuple, Mapper, ObjectMapper, ObjectPredicate, Predicate, PromiseMap, AnyObject, AnyFunction, Reviver, SavedDBEntity, StringMap, UnixTimestamp, ValueOf, ValuesOf, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues } from './types';
 import { _gb, _hb, _kb, _mb } from './unit/size.util';
 import { is } from './vendor/is';
-import { CommonLogLevel, CommonLogFunction, CommonLogger, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix } from './log/commonLogger';
+import { CommonLogLevel, CommonLogFunction, CommonLogger, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, CommonLogWithLevelFunction, commonLoggerCreate } from './log/commonLogger';
 import { _safeJsonStringify } from './string/safeJsonStringify';
 import { PQueue, PQueueCfg } from './promise/pQueue';
-export type { PQueueCfg, MemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateTime, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, PromiseValue, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestamp, BaseDBEntity, SavedDBEntity, Saved, Unsaved, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogFunction, CommonLogger, };
-export { is, _Memo, _memoFn, _LogMethod, _getArgsSignature, _createPromiseDecorator, AppError, HttpError, AssertionError, _isErrorObject, _isHttpErrorObject, _isHttpErrorResponse, _assert, _assertEquals, _assertDeepEquals, _assertIsError, _assertIsString, _assertIsNumber, _assertTypeOf, _randomInt, _randomArrayItem, _createDeterministicRandom, _inRange, _stringMapValues, _stringMapEntries, _objectKeys, _capitalize, _upperFirst, _lowerFirst, _split, _removeWhitespace, _substringBefore, _substringBeforeLast, _substringAfter, _substringAfterLast, _substringBetweenLast, _replaceAll, _nl2br, _truncate, _truncateMiddle, _pick, _omit, _filterFalsyValues, _filterUndefinedValues, _filterNullishValues, _filterEmptyArrays, _filterEmptyValues, _filterObject, _undefinedIfEmpty, _isObject, _isPrimitive, _mapKeys, _mapValues, _mapObject, _objectNullValuesToUndefined, _deepEquals, _deepCopy, _isEmptyObject, _isEmpty, _merge, _deepTrim, _sortObjectDeep, _sortObject, _get, _set, _has, _unset, _mask, _invert, _invertMap, _by, _groupBy, _sortBy, _sortNumbers, _toFixed, _toPrecision, _round, _findLast, _takeWhile, _takeRightWhile, _dropWhile, _dropRightWhile, _countBy, _intersection, _difference, _shuffle, _mapToObject, _findKeyByValue, _anyToError, _anyToErrorObject, _errorToErrorObject, _errorObjectToAppError, _range, _uniq, _uniqBy, _flatten, _flattenDeep, _chunk, SimpleMovingAverage, _average, _averageWeighted, _percentile, _median, _debounce, _throttle, _Debounce, _Throttle, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, pBatch, ErrorMode, pFilter, pProps, pDelay, pDefer, pHang, pState, AggregatedError, pRetry, pTimeout, pTuple, _Retry, _Timeout, _tryCatch, _TryCatch, _try, pTry, _jsonParseIfPossible, _stringifyAny, _ms, _since, _hb, _gb, _mb, _kb, _snakeCase, _camelCase, _kebabCase, _sum, _sumBy, _clamp, _last, mergeJsonSchemaObjects, jsonSchema, JsonSchemaAnyBuilder, JSON_SCHEMA_ORDER, generateJsonSchemaFromData, _parseQueryString, _defineLazyProperty, _defineLazyProps, _lazyValue, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, _safeJsonStringify, PQueue, };
+export type { PQueueCfg, MemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateTime, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, PromiseValue, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestamp, BaseDBEntity, SavedDBEntity, Saved, Unsaved, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
+export { is, _Memo, _memoFn, _LogMethod, _getArgsSignature, _createPromiseDecorator, AppError, HttpError, AssertionError, _isErrorObject, _isHttpErrorObject, _isHttpErrorResponse, _assert, _assertEquals, _assertDeepEquals, _assertIsError, _assertIsString, _assertIsNumber, _assertTypeOf, _randomInt, _randomArrayItem, _createDeterministicRandom, _inRange, _stringMapValues, _stringMapEntries, _objectKeys, _capitalize, _upperFirst, _lowerFirst, _split, _removeWhitespace, _substringBefore, _substringBeforeLast, _substringAfter, _substringAfterLast, _substringBetweenLast, _replaceAll, _nl2br, _truncate, _truncateMiddle, _pick, _omit, _filterFalsyValues, _filterUndefinedValues, _filterNullishValues, _filterEmptyArrays, _filterEmptyValues, _filterObject, _undefinedIfEmpty, _isObject, _isPrimitive, _mapKeys, _mapValues, _mapObject, _objectNullValuesToUndefined, _deepEquals, _deepCopy, _isEmptyObject, _isEmpty, _merge, _deepTrim, _sortObjectDeep, _sortObject, _get, _set, _has, _unset, _mask, _invert, _invertMap, _by, _groupBy, _sortBy, _sortNumbers, _toFixed, _toPrecision, _round, _findLast, _takeWhile, _takeRightWhile, _dropWhile, _dropRightWhile, _countBy, _intersection, _difference, _shuffle, _mapToObject, _findKeyByValue, _anyToError, _anyToErrorObject, _errorToErrorObject, _errorObjectToAppError, _range, _uniq, _uniqBy, _flatten, _flattenDeep, _chunk, SimpleMovingAverage, _average, _averageWeighted, _percentile, _median, _debounce, _throttle, _Debounce, _Throttle, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, pBatch, ErrorMode, pFilter, pProps, pDelay, pDefer, pHang, pState, AggregatedError, pRetry, pTimeout, pTuple, _Retry, _Timeout, _tryCatch, _TryCatch, _try, pTry, _jsonParseIfPossible, _stringifyAny, _ms, _since, _hb, _gb, _mb, _kb, _snakeCase, _camelCase, _kebabCase, _sum, _sumBy, _clamp, _last, mergeJsonSchemaObjects, jsonSchema, JsonSchemaAnyBuilder, JSON_SCHEMA_ORDER, generateJsonSchemaFromData, _parseQueryString, _defineLazyProperty, _defineLazyProps, _lazyValue, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, _safeJsonStringify, PQueue, };

package/dist/index.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports._isObject = exports._undefinedIfEmpty = exports._filterObject = exports._filterEmptyValues = exports._filterEmptyArrays = exports._filterNullishValues = exports._filterUndefinedValues = exports._filterFalsyValues = exports._omit = exports._pick = exports._truncateMiddle = exports._truncate = exports._nl2br = exports._replaceAll = exports._substringBetweenLast = exports._substringAfterLast = exports._substringAfter = exports._substringBeforeLast = exports._substringBefore = exports._removeWhitespace = exports._split = exports._lowerFirst = exports._upperFirst = exports._capitalize = exports._objectKeys = exports._stringMapEntries = exports._stringMapValues = exports._inRange = exports._createDeterministicRandom = exports._randomArrayItem = exports._randomInt = exports._assertTypeOf = exports._assertIsNumber = exports._assertIsString = exports._assertIsError = exports._assertDeepEquals = exports._assertEquals = exports._assert = exports._isHttpErrorResponse = exports._isHttpErrorObject = exports._isErrorObject = exports.AssertionError = exports.HttpError = exports.AppError = exports._createPromiseDecorator = exports._getArgsSignature = exports._LogMethod = exports._memoFn = exports._Memo = exports.is = void 0;
 exports._average = exports.SimpleMovingAverage = exports._chunk = exports._flattenDeep = exports._flatten = exports._uniqBy = exports._uniq = exports._range = exports._errorObjectToAppError = exports._errorToErrorObject = exports._anyToErrorObject = exports._anyToError = exports._findKeyByValue = exports._mapToObject = exports._shuffle = exports._difference = exports._intersection = exports._countBy = exports._dropRightWhile = exports._dropWhile = exports._takeRightWhile = exports._takeWhile = exports._findLast = exports._round = exports._toPrecision = exports._toFixed = exports._sortNumbers = exports._sortBy = exports._groupBy = exports._by = exports._invertMap = exports._invert = exports._mask = exports._unset = exports._has = exports._set = exports._get = exports._sortObject = exports._sortObjectDeep = exports._deepTrim = exports._merge = exports._isEmpty = exports._isEmptyObject = exports._deepCopy = exports._deepEquals = exports._objectNullValuesToUndefined = exports._mapObject = exports._mapValues = exports._mapKeys = exports._isPrimitive = void 0;
 exports.JSON_SCHEMA_ORDER = exports.JsonSchemaAnyBuilder = exports.jsonSchema = exports.mergeJsonSchemaObjects = exports._last = exports._clamp = exports._sumBy = exports._sum = exports._kebabCase = exports._camelCase = exports._snakeCase = exports._kb = exports._mb = exports._gb = exports._hb = exports._since = exports._ms = exports._stringifyAny = exports._jsonParseIfPossible = exports.pTry = exports._try = exports._TryCatch = exports._tryCatch = exports._Timeout = exports._Retry = exports.pTuple = exports.pTimeout = exports.pRetry = exports.AggregatedError = exports.pState = exports.pHang = exports.pDefer = exports.pDelay = exports.pProps = exports.pFilter = exports.ErrorMode = exports.pBatch = exports._noop = exports._passNothingPredicate = exports._passthroughPredicate = exports._passUndefinedMapper = exports._passthroughMapper = exports.pMap = exports._Throttle = exports._Debounce = exports._throttle = exports._debounce = exports._median = exports._percentile = exports._averageWeighted = void 0;
-exports.PQueue = exports._safeJsonStringify = exports.commonLoggerPrefix = exports.commonLoggerPipe = exports.commonLogLevelNumber = exports.commonLoggerNoop = exports.commonLoggerMinLevel = exports._lazyValue = exports._defineLazyProps = exports._defineLazyProperty = exports._parseQueryString = exports.generateJsonSchemaFromData = void 0;
+exports.PQueue = exports._safeJsonStringify = exports.commonLoggerCreate = exports.commonLoggerPrefix = exports.commonLoggerPipe = exports.commonLogLevelNumber = exports.commonLoggerNoop = exports.commonLoggerMinLevel = exports._lazyValue = exports._defineLazyProps = exports._defineLazyProperty = exports._parseQueryString = exports.generateJsonSchemaFromData = void 0;
 const array_util_1 = require("./array/array.util");
 Object.defineProperty(exports, "_by", { enumerable: true, get: function () { return array_util_1._by; } });
 Object.defineProperty(exports, "_chunk", { enumerable: true, get: function () { return array_util_1._chunk; } });
@@ -217,6 +217,7 @@ Object.defineProperty(exports, "commonLoggerNoop", { enumerable: true, get: func
 Object.defineProperty(exports, "commonLogLevelNumber", { enumerable: true, get: function () { return commonLogger_1.commonLogLevelNumber; } });
 Object.defineProperty(exports, "commonLoggerPipe", { enumerable: true, get: function () { return commonLogger_1.commonLoggerPipe; } });
 Object.defineProperty(exports, "commonLoggerPrefix", { enumerable: true, get: function () { return commonLogger_1.commonLoggerPrefix; } });
+Object.defineProperty(exports, "commonLoggerCreate", { enumerable: true, get: function () { return commonLogger_1.commonLoggerCreate; } });
 const safeJsonStringify_1 = require("./string/safeJsonStringify");
 Object.defineProperty(exports, "_safeJsonStringify", { enumerable: true, get: function () { return safeJsonStringify_1._safeJsonStringify; } });
 const pQueue_1 = require("./promise/pQueue");

package/dist/log/commonLogger.d.ts

@@ -17,6 +17,7 @@ export declare const commonLogLevelNumber: Record<CommonLogLevel, number>;
  * @experimental
  */
 export declare type CommonLogFunction = (...args: any[]) => void;
+export declare type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) => void;
 /**
  * Interface is inspired/compatible with `console.*`
  * So, `console` is a valid CommonLogger implementation as-is.
@@ -46,3 +47,7 @@ export declare function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger;
  * Creates a "child" CommonLogger with prefix (one or multiple).
  */
 export declare function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): CommonLogger;
+/**
+ * Creates a CommonLogger from a single function that takes `level` and `args`.
+ */
+export declare function commonLoggerCreate(fn: CommonLogWithLevelFunction): CommonLogger;

package/dist/log/commonLogger.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.commonLoggerPrefix = exports.commonLoggerPipe = exports.commonLoggerMinLevel = exports.commonLoggerNoop = exports.commonLogLevelNumber = void 0;
+exports.commonLoggerCreate = exports.commonLoggerPrefix = exports.commonLoggerPipe = exports.commonLoggerMinLevel = exports.commonLoggerNoop = exports.commonLogLevelNumber = void 0;
 const index_1 = require("../index");
 exports.commonLogLevelNumber = {
     log: 10,
@@ -71,3 +71,14 @@ function commonLoggerPrefix(logger, ...prefixes) {
     };
 }
 exports.commonLoggerPrefix = commonLoggerPrefix;
+/**
+ * Creates a CommonLogger from a single function that takes `level` and `args`.
+ */
+function commonLoggerCreate(fn) {
+    return {
+        log: (...args) => fn('log', args),
+        warn: (...args) => fn('warn', args),
+        error: (...args) => fn('error', args),
+    };
+}
+exports.commonLoggerCreate = commonLoggerCreate;

package/dist/promise/pQueue.d.ts

@@ -1,9 +1,15 @@
+import { ErrorMode } from '../error/errorMode';
 import { CommonLogger } from '../log/commonLogger';
 export interface PQueueCfg {
     concurrency: number;
     /**
      * Default: THROW_IMMEDIATELY
+     *
+     * THROW_AGGREGATED is not supported.
+     *
+     * SUPPRESS_ERRORS will still log errors via logger. It will resolve the `.push` promise with void.
      */
+    errorMode?: ErrorMode;
     /**
      * @default true
      */
@@ -15,8 +21,17 @@ export interface PQueueCfg {
      * If true - will LOG EVERYTHING:)
      */
     debug?: boolean;
+    /**
+     * By default .push method resolves when the Promise is done (finished).
+     *
+     * If you set resolveOn = 'start' - .push method will resolve the Promise (with void) upon
+     * the START of the processing.
+     *
+     * @default finish
+     */
+    resolveOn?: 'finish' | 'start';
 }
-export declare type PromiseReturningFunction = () => Promise<any>;
+export declare type PromiseReturningFunction<R> = () => Promise<R>;
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
  *
@@ -39,5 +54,9 @@ export declare class PQueue {
      * Idle means 0 queue and 0 inFlight.
      */
     onIdle(): Promise<void>;
-    push(fn: PromiseReturningFunction): void;
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    push<R>(fn_: PromiseReturningFunction<R>): Promise<R>;
 }

package/dist/promise/pQueue.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PQueue = void 0;
+const errorMode_1 = require("../error/errorMode");
 const pDefer_1 = require("./pDefer");
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
@@ -17,8 +18,10 @@ class PQueue {
         this.onIdleListeners = [];
         this.cfg = {
             // concurrency: Number.MAX_SAFE_INTEGER,
+            errorMode: errorMode_1.ErrorMode.THROW_IMMEDIATELY,
             logger: console,
             debug: false,
+            resolveOn: 'finish',
             ...cfg,
         };
         if (!cfg.debug) {
@@ -37,21 +40,43 @@ class PQueue {
      * Idle means 0 queue and 0 inFlight.
      */
     onIdle() {
-        if (this.queue.length === 0)
+        if (this.queue.length === 0 && this.inFlight === 0)
             return Promise.resolve();
         const listener = (0, pDefer_1.pDefer)();
         this.onIdleListeners.push(listener);
         return listener;
     }
-    push(fn) {
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    push(fn_) {
         const { concurrency } = this.cfg;
+        const resolveOnStart = this.cfg.resolveOn === 'start';
+        const fn = fn_;
+        fn.defer || (fn.defer = (0, pDefer_1.pDefer)());
         if (this.inFlight < concurrency) {
             // There is room for more jobs. Can start immediately
             this.inFlight++;
             this.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
+            if (resolveOnStart)
+                fn.defer.resolve();
             fn()
+                .then(result => {
+                if (!resolveOnStart)
+                    fn.defer.resolve(result);
+            })
                 .catch(err => {
                 this.cfg.logger.error(err);
+                if (resolveOnStart)
+                    return;
+                if (this.cfg.errorMode === errorMode_1.ErrorMode.SUPPRESS) {
+                    fn.defer.resolve(); // resolve with `void`
+                }
+                else {
+                    // Should be handled on the outside, otherwise it'll cause UnhandledRejection
+                    fn.defer.reject(err);
+                }
             })
                 .finally(() => {
                 this.inFlight--;
@@ -59,7 +84,7 @@ class PQueue {
                 // check if there's room to start next job
                 if (this.queue.length && this.inFlight <= concurrency) {
                     const nextFn = this.queue.shift();
-                    this.push(nextFn);
+                    void this.push(nextFn);
                 }
                 else {
                     if (this.inFlight === 0) {
@@ -74,6 +99,7 @@ class PQueue {
             this.queue.push(fn);
             this.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`);
         }
+        return fn.defer;
     }
 }
 exports.PQueue = PQueue;

package/dist-esm/index.js

@@ -50,7 +50,7 @@ import { _ms, _since } from './time/time.util';
 import { _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues, } from './types';
 import { _gb, _hb, _kb, _mb } from './unit/size.util';
 import { is } from './vendor/is';
-import { commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, } from './log/commonLogger';
+import { commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, } from './log/commonLogger';
 import { _safeJsonStringify } from './string/safeJsonStringify';
 import { PQueue } from './promise/pQueue';
-export { is, _Memo, _memoFn, _LogMethod, _getArgsSignature, _createPromiseDecorator, AppError, HttpError, AssertionError, _isErrorObject, _isHttpErrorObject, _isHttpErrorResponse, _assert, _assertEquals, _assertDeepEquals, _assertIsError, _assertIsString, _assertIsNumber, _assertTypeOf, _randomInt, _randomArrayItem, _createDeterministicRandom, _inRange, _stringMapValues, _stringMapEntries, _objectKeys, _capitalize, _upperFirst, _lowerFirst, _split, _removeWhitespace, _substringBefore, _substringBeforeLast, _substringAfter, _substringAfterLast, _substringBetweenLast, _replaceAll, _nl2br, _truncate, _truncateMiddle, _pick, _omit, _filterFalsyValues, _filterUndefinedValues, _filterNullishValues, _filterEmptyArrays, _filterEmptyValues, _filterObject, _undefinedIfEmpty, _isObject, _isPrimitive, _mapKeys, _mapValues, _mapObject, _objectNullValuesToUndefined, _deepEquals, _deepCopy, _isEmptyObject, _isEmpty, _merge, _deepTrim, _sortObjectDeep, _sortObject, _get, _set, _has, _unset, _mask, _invert, _invertMap, _by, _groupBy, _sortBy, _sortNumbers, _toFixed, _toPrecision, _round, _findLast, _takeWhile, _takeRightWhile, _dropWhile, _dropRightWhile, _countBy, _intersection, _difference, _shuffle, _mapToObject, _findKeyByValue, _anyToError, _anyToErrorObject, _errorToErrorObject, _errorObjectToAppError, _range, _uniq, _uniqBy, _flatten, _flattenDeep, _chunk, SimpleMovingAverage, _average, _averageWeighted, _percentile, _median, _debounce, _throttle, _Debounce, _Throttle, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, pBatch, ErrorMode, pFilter, pProps, pDelay, pDefer, pHang, pState, AggregatedError, pRetry, pTimeout, pTuple, _Retry, _Timeout, _tryCatch, _TryCatch, _try, pTry, _jsonParseIfPossible, _stringifyAny, _ms, _since, _hb, _gb, _mb, _kb, _snakeCase, _camelCase, _kebabCase, _sum, _sumBy, _clamp, _last, mergeJsonSchemaObjects, jsonSchema, JsonSchemaAnyBuilder, JSON_SCHEMA_ORDER, generateJsonSchemaFromData, _parseQueryString, _defineLazyProperty, _defineLazyProps, _lazyValue, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, _safeJsonStringify, PQueue, };
+export { is, _Memo, _memoFn, _LogMethod, _getArgsSignature, _createPromiseDecorator, AppError, HttpError, AssertionError, _isErrorObject, _isHttpErrorObject, _isHttpErrorResponse, _assert, _assertEquals, _assertDeepEquals, _assertIsError, _assertIsString, _assertIsNumber, _assertTypeOf, _randomInt, _randomArrayItem, _createDeterministicRandom, _inRange, _stringMapValues, _stringMapEntries, _objectKeys, _capitalize, _upperFirst, _lowerFirst, _split, _removeWhitespace, _substringBefore, _substringBeforeLast, _substringAfter, _substringAfterLast, _substringBetweenLast, _replaceAll, _nl2br, _truncate, _truncateMiddle, _pick, _omit, _filterFalsyValues, _filterUndefinedValues, _filterNullishValues, _filterEmptyArrays, _filterEmptyValues, _filterObject, _undefinedIfEmpty, _isObject, _isPrimitive, _mapKeys, _mapValues, _mapObject, _objectNullValuesToUndefined, _deepEquals, _deepCopy, _isEmptyObject, _isEmpty, _merge, _deepTrim, _sortObjectDeep, _sortObject, _get, _set, _has, _unset, _mask, _invert, _invertMap, _by, _groupBy, _sortBy, _sortNumbers, _toFixed, _toPrecision, _round, _findLast, _takeWhile, _takeRightWhile, _dropWhile, _dropRightWhile, _countBy, _intersection, _difference, _shuffle, _mapToObject, _findKeyByValue, _anyToError, _anyToErrorObject, _errorToErrorObject, _errorObjectToAppError, _range, _uniq, _uniqBy, _flatten, _flattenDeep, _chunk, SimpleMovingAverage, _average, _averageWeighted, _percentile, _median, _debounce, _throttle, _Debounce, _Throttle, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, pBatch, ErrorMode, pFilter, pProps, pDelay, pDefer, pHang, pState, AggregatedError, pRetry, pTimeout, pTuple, _Retry, _Timeout, _tryCatch, _TryCatch, _try, pTry, _jsonParseIfPossible, _stringifyAny, _ms, _since, _hb, _gb, _mb, _kb, _snakeCase, _camelCase, _kebabCase, _sum, _sumBy, _clamp, _last, mergeJsonSchemaObjects, jsonSchema, JsonSchemaAnyBuilder, JSON_SCHEMA_ORDER, generateJsonSchemaFromData, _parseQueryString, _defineLazyProperty, _defineLazyProps, _lazyValue, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, _safeJsonStringify, PQueue, };

package/dist-esm/log/commonLogger.js

@@ -65,3 +65,13 @@ export function commonLoggerPrefix(logger, ...prefixes) {
         error: (...args) => logger.error(...prefixes, ...args),
     };
 }
+/**
+ * Creates a CommonLogger from a single function that takes `level` and `args`.
+ */
+export function commonLoggerCreate(fn) {
+    return {
+        log: (...args) => fn('log', args),
+        warn: (...args) => fn('warn', args),
+        error: (...args) => fn('error', args),
+    };
+}

package/dist-esm/promise/pQueue.js

@@ -1,3 +1,4 @@
+import { ErrorMode } from '../error/errorMode';
 import { pDefer } from './pDefer';
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
@@ -14,7 +15,7 @@ export class PQueue {
         this.onIdleListeners = [];
         this.cfg = Object.assign({ 
             // concurrency: Number.MAX_SAFE_INTEGER,
-            logger: console, debug: false }, cfg);
+            errorMode: ErrorMode.THROW_IMMEDIATELY, logger: console, debug: false, resolveOn: 'finish' }, cfg);
         if (!cfg.debug) {
             this.debug = () => { };
         }
@@ -31,21 +32,43 @@ export class PQueue {
      * Idle means 0 queue and 0 inFlight.
      */
     onIdle() {
-        if (this.queue.length === 0)
+        if (this.queue.length === 0 && this.inFlight === 0)
             return Promise.resolve();
         const listener = pDefer();
         this.onIdleListeners.push(listener);
         return listener;
     }
-    push(fn) {
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    push(fn_) {
         const { concurrency } = this.cfg;
+        const resolveOnStart = this.cfg.resolveOn === 'start';
+        const fn = fn_;
+        fn.defer || (fn.defer = pDefer());
         if (this.inFlight < concurrency) {
             // There is room for more jobs. Can start immediately
             this.inFlight++;
             this.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
+            if (resolveOnStart)
+                fn.defer.resolve();
             fn()
+                .then(result => {
+                if (!resolveOnStart)
+                    fn.defer.resolve(result);
+            })
                 .catch(err => {
                 this.cfg.logger.error(err);
+                if (resolveOnStart)
+                    return;
+                if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+                    fn.defer.resolve(); // resolve with `void`
+                }
+                else {
+                    // Should be handled on the outside, otherwise it'll cause UnhandledRejection
+                    fn.defer.reject(err);
+                }
             })
                 .finally(() => {
                 this.inFlight--;
@@ -53,7 +76,7 @@ export class PQueue {
                 // check if there's room to start next job
                 if (this.queue.length && this.inFlight <= concurrency) {
                     const nextFn = this.queue.shift();
-                    this.push(nextFn);
+                    void this.push(nextFn);
                 }
                 else {
                     if (this.inFlight === 0) {
@@ -68,5 +91,6 @@ export class PQueue {
             this.queue.push(fn);
             this.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`);
         }
+        return fn.defer;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.69.0",
+  "version": "14.69.4",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/index.ts

@@ -233,6 +233,8 @@ import {
   commonLogLevelNumber,
   commonLoggerPipe,
   commonLoggerPrefix,
+  CommonLogWithLevelFunction,
+  commonLoggerCreate,
 } from './log/commonLogger'
 import { _safeJsonStringify } from './string/safeJsonStringify'
 import { PQueue, PQueueCfg } from './promise/pQueue'
@@ -309,6 +311,7 @@ export type {
   JsonSchemaTuple,
   JsonSchemaBuilder,
   CommonLogLevel,
+  CommonLogWithLevelFunction,
   CommonLogFunction,
   CommonLogger,
 }
@@ -474,6 +477,7 @@ export {
   commonLogLevelNumber,
   commonLoggerPipe,
   commonLoggerPrefix,
+  commonLoggerCreate,
   _safeJsonStringify,
   PQueue,
 }

package/src/log/commonLogger.ts

@@ -25,6 +25,7 @@ export const commonLogLevelNumber: Record<CommonLogLevel, number> = {
  * @experimental
  */
 export type CommonLogFunction = (...args: any[]) => void
+export type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) => void
 
 /**
  * Interface is inspired/compatible with `console.*`
@@ -109,3 +110,14 @@ export function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): Co
     error: (...args) => logger.error(...prefixes, ...args),
   }
 }
+
+/**
+ * Creates a CommonLogger from a single function that takes `level` and `args`.
+ */
+export function commonLoggerCreate(fn: CommonLogWithLevelFunction): CommonLogger {
+  return {
+    log: (...args) => fn('log', args),
+    warn: (...args) => fn('warn', args),
+    error: (...args) => fn('error', args),
+  }
+}

package/src/promise/pQueue.ts

@@ -1,3 +1,4 @@
+import { ErrorMode } from '../error/errorMode'
 import { CommonLogger } from '../log/commonLogger'
 import { DeferredPromise, pDefer } from './pDefer'
 
@@ -6,8 +7,12 @@ export interface PQueueCfg {
 
   /**
    * Default: THROW_IMMEDIATELY
+   *
+   * THROW_AGGREGATED is not supported.
+   *
+   * SUPPRESS_ERRORS will still log errors via logger. It will resolve the `.push` promise with void.
    */
-  // errorMode?: ErrorMode
+  errorMode?: ErrorMode
 
   /**
    * @default true
@@ -28,9 +33,23 @@ export interface PQueueCfg {
   // logSizeChange?: boolean
 
   // timeout
+
+  /**
+   * By default .push method resolves when the Promise is done (finished).
+   *
+   * If you set resolveOn = 'start' - .push method will resolve the Promise (with void) upon
+   * the START of the processing.
+   *
+   * @default finish
+   */
+  resolveOn?: 'finish' | 'start'
 }
 
-export type PromiseReturningFunction = () => Promise<any>
+export type PromiseReturningFunction<R> = () => Promise<R>
+
+interface PromiseReturningFunctionWithDefer<R> extends PromiseReturningFunction<R> {
+  defer: DeferredPromise<R>
+}
 
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
@@ -44,8 +63,10 @@ export class PQueue {
   constructor(cfg: PQueueCfg) {
     this.cfg = {
       // concurrency: Number.MAX_SAFE_INTEGER,
+      errorMode: ErrorMode.THROW_IMMEDIATELY,
       logger: console,
       debug: false,
+      resolveOn: 'finish',
       ...cfg,
     }
 
@@ -61,7 +82,7 @@ export class PQueue {
   }
 
   inFlight = 0
-  private queue: PromiseReturningFunction[] = []
+  private queue: PromiseReturningFunction<any>[] = []
   private onIdleListeners: DeferredPromise[] = []
 
   get queueSize(): number {
@@ -74,24 +95,44 @@ export class PQueue {
    * Idle means 0 queue and 0 inFlight.
    */
   onIdle(): Promise<void> {
-    if (this.queue.length === 0) return Promise.resolve()
+    if (this.queue.length === 0 && this.inFlight === 0) return Promise.resolve()
 
     const listener = pDefer()
     this.onIdleListeners.push(listener)
     return listener
   }
 
-  push(fn: PromiseReturningFunction): void {
+  /**
+   * Push PromiseReturningFunction to the Queue.
+   * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+   */
+  push<R>(fn_: PromiseReturningFunction<R>): Promise<R> {
     const { concurrency } = this.cfg
+    const resolveOnStart = this.cfg.resolveOn === 'start'
+
+    const fn = fn_ as PromiseReturningFunctionWithDefer<R>
+    fn.defer ||= pDefer<R>()
 
     if (this.inFlight < concurrency) {
       // There is room for more jobs. Can start immediately
       this.inFlight++
       this.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
+      if (resolveOnStart) fn.defer.resolve()
 
       fn()
+        .then(result => {
+          if (!resolveOnStart) fn.defer.resolve(result)
+        })
         .catch(err => {
           this.cfg.logger.error(err)
+          if (resolveOnStart) return
+
+          if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+            fn.defer.resolve() // resolve with `void`
+          } else {
+            // Should be handled on the outside, otherwise it'll cause UnhandledRejection
+            fn.defer.reject(err)
+          }
         })
         .finally(() => {
           this.inFlight--
@@ -100,7 +141,7 @@ export class PQueue {
           // check if there's room to start next job
           if (this.queue.length && this.inFlight <= concurrency) {
             const nextFn = this.queue.shift()!
-            this.push(nextFn)
+            void this.push(nextFn)
           } else {
             if (this.inFlight === 0) {
               this.debug('onIdle')
@@ -113,5 +154,7 @@ export class PQueue {
       this.queue.push(fn)
       this.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`)
     }
+
+    return fn.defer
   }
 }