@naturalcycles/js-lib 14.115.2 → 14.117.0

package/dist/datetime/dateInterval.d.ts

@@ -1,7 +1,7 @@
 import type { Inclusiveness, LocalDateConfig, LocalDateUnit } from './localDate';
 import { LocalDate } from './localDate';
-export declare type DateIntervalConfig = DateInterval | DateIntervalString;
-export declare type DateIntervalString = string;
+export type DateIntervalConfig = DateInterval | DateIntervalString;
+export type DateIntervalString = string;
 /**
  * Class that supports ISO8601 "Time interval" standard that looks like `2022-02-24/2022-03-30`.
  *

package/dist/datetime/localDate.d.ts

@@ -1,10 +1,10 @@
 import type { IsoDateString, IsoDateTimeString, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import { LocalTime } from './localTime';
-export declare type LocalDateUnit = LocalDateUnitStrict | 'week';
-export declare type LocalDateUnitStrict = 'year' | 'month' | 'day';
-export declare type Inclusiveness = '()' | '[]' | '[)' | '(]';
-export declare type LocalDateConfig = LocalDate | IsoDateString;
-export declare type LocalDateFormatter = (ld: LocalDate) => string;
+export type LocalDateUnit = LocalDateUnitStrict | 'week';
+export type LocalDateUnitStrict = 'year' | 'month' | 'day';
+export type Inclusiveness = '()' | '[]' | '[)' | '(]';
+export type LocalDateConfig = LocalDate | IsoDateString;
+export type LocalDateFormatter = (ld: LocalDate) => string;
 /**
  * @experimental
  */

package/dist/datetime/localTime.d.ts

@@ -1,7 +1,7 @@
 import type { IsoDateString, IsoDateTimeString, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import type { Inclusiveness } from './localDate';
 import { LocalDate } from './localDate';
-export declare type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
+export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 export declare enum ISODayOfWeek {
     MONDAY = 1,
     TUESDAY = 2,
@@ -11,8 +11,8 @@ export declare enum ISODayOfWeek {
     SATURDAY = 6,
     SUNDAY = 7
 }
-export declare type LocalTimeConfig = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber;
-export declare type LocalTimeFormatter = (ld: LocalTime) => string;
+export type LocalTimeConfig = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber;
+export type LocalTimeFormatter = (ld: LocalTime) => string;
 export interface LocalTimeComponents {
     year: number;
     month: number;

package/dist/datetime/timeInterval.d.ts

@@ -2,8 +2,8 @@ import type { UnixTimestampNumber } from '../types';
 import type { Inclusiveness } from './localDate';
 import type { LocalTimeConfig } from './localTime';
 import { LocalTime } from './localTime';
-export declare type TimeIntervalConfig = TimeInterval | TimeIntervalString;
-export declare type TimeIntervalString = string;
+export type TimeIntervalConfig = TimeInterval | TimeIntervalString;
+export type TimeIntervalString = string;
 /**
  * Class that supports an "interval of time" between 2 timestamps - start and end.
  * Example: `1649267185/1649267187`.

package/dist/decorators/logMethod.decorator.d.ts

@@ -4,7 +4,7 @@ import type { CommonLogger } from '..';
  *
  * @returns array of tokens that will be `.filter(Boolean).join(' ')`
  */
-declare type LogResultFn = (r: any) => any[];
+type LogResultFn = (r: any) => any[];
 export interface LogMethodOptions {
     /**
      * Log "moving average" elapsed time for up to `avg` last method calls

package/dist/decorators/logMethod.decorator.js

@@ -80,7 +80,7 @@ function logFinished(logger, callSignature, started, sma, logResultFn, res, err)
     if (sma) {
         t.push(`(avg ${(0, time_util_1._ms)(sma.push(millis))})`);
     }
-    if (typeof err !== 'undefined') {
+    if (err !== undefined) {
         t.push('ERROR:', (0, __1._stringifyAny)(err, { includeErrorData: true }));
     }
     else if (logResultFn) {

package/dist/decorators/memo.util.d.ts

@@ -1,5 +1,5 @@
 import type { Promisable } from '../typeFest';
-export declare type MemoSerializer = (args: any[]) => any;
+export type MemoSerializer = (args: any[]) => any;
 export declare const jsonMemoSerializer: MemoSerializer;
 export interface MemoCache<KEY = any, VALUE = any> {
     has(k: KEY): boolean;

package/dist/decorators/timeout.decorator.js

@@ -12,8 +12,8 @@ function _Timeout(opt) {
         const keyStr = String(key);
         descriptor.value = async function (...args) {
             const ctx = this;
-            opt.name || (opt.name = (0, decorator_util_1._getMethodSignature)(ctx, keyStr));
-            return await (0, pTimeout_1.pTimeout)(originalFn.apply(this, args), opt);
+            opt.name ||= (0, decorator_util_1._getMethodSignature)(ctx, keyStr);
+            return await (0, pTimeout_1.pTimeout)(() => originalFn.apply(this, args), opt);
         };
         return descriptor;
     };

package/dist/error/try.d.ts

@@ -1,3 +1,4 @@
+import type { Class } from '../typeFest';
 import type { AnyFunction } from '../types';
 import { AppError } from './app.error';
 /**
@@ -41,10 +42,18 @@ export declare class UnexpectedPassError extends AppError {
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export declare function _expectedError<ERR = Error>(fn: AnyFunction): ERR;
+export declare function _expectedError<ERR = Error>(fn: AnyFunction, errorClass?: Class<ERR>): ERR;
 /**
  * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export declare function pExpectedError<ERR = Error>(promise: Promise<any>): Promise<ERR>;
+export declare function pExpectedError<ERR = Error>(promise: Promise<any>, errorClass?: Class<ERR>): Promise<ERR>;

package/dist/error/try.js

@@ -62,8 +62,12 @@ exports.UnexpectedPassError = UnexpectedPassError;
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-function _expectedError(fn) {
+function _expectedError(fn, errorClass) {
     try {
         fn();
         // Unexpected!
@@ -72,6 +76,10 @@ function _expectedError(fn) {
     catch (err) {
         if (err instanceof UnexpectedPassError)
             throw err; // re-throw
+        if (errorClass && !(err instanceof errorClass)) {
+            console.warn(`_expectedError expected ${errorClass.constructor.name} but got different error class`);
+            throw err;
+        }
         return err; // this is expected!
     }
 }
@@ -79,8 +87,12 @@ exports._expectedError = _expectedError;
 /**
  * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-async function pExpectedError(promise) {
+async function pExpectedError(promise, errorClass) {
     try {
         await promise;
         // Unexpected!
@@ -89,6 +101,10 @@ async function pExpectedError(promise) {
     catch (err) {
         if (err instanceof UnexpectedPassError)
             throw err; // re-throw
+        if (errorClass && !(err instanceof errorClass)) {
+            console.warn(`pExpectedError expected ${errorClass.constructor.name} but got different error class`);
+            throw err;
+        }
         return err; // this is expected!
     }
 }

package/dist/is.util.d.ts

@@ -1,8 +1,8 @@
 import type { Primitive } from './typeFest';
 import type { AnyObject, FalsyValue, NullishValue } from './types';
-declare type Nullish<T> = T extends NullishValue ? T : never;
-declare type Truthy<T> = T extends FalsyValue ? never : T;
-declare type Falsy<T> = T extends FalsyValue ? T : never;
+type Nullish<T> = T extends NullishValue ? T : never;
+type Truthy<T> = T extends FalsyValue ? never : T;
+type Falsy<T> = T extends FalsyValue ? T : never;
 export declare const _isNull: <T>(v: T) => v is T extends null ? T : never;
 export declare const _isUndefined: <T>(v: T) => v is T extends undefined ? T : never;
 export declare const _isNullish: <T>(v: T) => v is Nullish<T>;

package/dist/is.util.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports._isEmpty = exports._isEmptyObject = exports._isPrimitive = exports._isObject = exports._isFalsy = exports._isTruthy = exports._isNotNullish = exports._isNullish = exports._isUndefined = exports._isNull = void 0;
 const _isNull = (v) => v === null;
 exports._isNull = _isNull;
-const _isUndefined = (v) => typeof v === 'undefined';
+const _isUndefined = (v) => v === undefined;
 exports._isUndefined = _isUndefined;
-const _isNullish = (v) => typeof v === 'undefined' || v === null;
+const _isNullish = (v) => v === undefined || v === null;
 exports._isNullish = _isNullish;
 const _isNotNullish = (v) => v !== undefined && v !== null;
 exports._isNotNullish = _isNotNullish;

package/dist/json-schema/from-data/generateJsonSchemaFromData.js

@@ -15,7 +15,7 @@ function objectToJsonSchema(rows) {
     const typesByKey = {};
     rows.forEach(r => {
         Object.keys(r).forEach(key => {
-            typesByKey[key] || (typesByKey[key] = new Set());
+            typesByKey[key] ||= new Set();
             typesByKey[key].add(getTypeOfValue(r[key]));
         });
     });

package/dist/json-schema/jsonSchema.model.d.ts

@@ -1,5 +1,5 @@
 import type { AnyObject, StringMap } from '../types';
-export declare type JsonSchema<T = unknown> = JsonSchemaAny<T> | JsonSchemaOneOf<T> | JsonSchemaAllOf<T> | JsonSchemaAnyOf<T> | JsonSchemaNot<T> | JsonSchemaRef<T> | JsonSchemaConst<T> | JsonSchemaEnum<T> | JsonSchemaString | JsonSchemaNumber | JsonSchemaBoolean | JsonSchemaNull | JsonSchemaObject | JsonSchemaArray<T> | JsonSchemaTuple<T>;
+export type JsonSchema<T = unknown> = JsonSchemaAny<T> | JsonSchemaOneOf<T> | JsonSchemaAllOf<T> | JsonSchemaAnyOf<T> | JsonSchemaNot<T> | JsonSchemaRef<T> | JsonSchemaConst<T> | JsonSchemaEnum<T> | JsonSchemaString | JsonSchemaNumber | JsonSchemaBoolean | JsonSchemaNull | JsonSchemaObject | JsonSchemaArray<T> | JsonSchemaTuple<T>;
 export interface JsonSchemaAny<T = unknown> {
     $schema?: string;
     $id?: string;

package/dist/lodash.types.d.ts

@@ -1,4 +1,4 @@
-export declare type PropertyName = string | number | symbol;
-export declare type RecursiveArray<T> = (T | RecursiveArray<T>)[];
-export declare type Many<T> = T | readonly T[];
-export declare type PropertyPath = Many<PropertyName>;
+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/log/commonLogger.d.ts

@@ -8,7 +8,7 @@
  *
  * @experimental
  */
-export declare type CommonLogLevel = 'log' | 'warn' | 'error';
+export type CommonLogLevel = 'log' | 'warn' | 'error';
 export declare const commonLogLevelNumber: Record<CommonLogLevel, number>;
 /**
  * Function that takes any number of arguments and logs them all.
@@ -16,8 +16,8 @@ export declare const commonLogLevelNumber: Record<CommonLogLevel, number>;
  *
  * @experimental
  */
-export declare type CommonLogFunction = (...args: any[]) => void;
-export declare type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) => void;
+export type CommonLogFunction = (...args: any[]) => void;
+export type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) => void;
 /**
  * Interface is inspired/compatible with `console.*`
  * So, `console` is a valid CommonLogger implementation as-is.

package/dist/promise/pQueue.d.ts

@@ -31,7 +31,7 @@ export interface PQueueCfg {
      */
     resolveOn?: 'finish' | 'start';
 }
-export declare type PromiseReturningFunction<R> = () => Promise<R>;
+export type PromiseReturningFunction<R> = () => Promise<R>;
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
  *

package/dist/promise/pQueue.js

@@ -54,7 +54,7 @@ class PQueue {
         const { concurrency } = this.cfg;
         const resolveOnStart = this.cfg.resolveOn === 'start';
         const fn = fn_;
-        fn.defer || (fn.defer = (0, pDefer_1.pDefer)());
+        fn.defer ||= (0, pDefer_1.pDefer)();
         if (this.inFlight < concurrency) {
             // There is room for more jobs. Can start immediately
             this.inFlight++;

package/dist/promise/pTimeout.d.ts

@@ -1,6 +1,6 @@
 import { AppError } from '../error/app.error';
 import type { ErrorData } from '../error/error.model';
-import type { AnyFunction } from '../types';
+import type { AnyAsyncFunction } from '../types';
 export declare class TimeoutError extends AppError {
 }
 export interface PTimeoutOptions {
@@ -16,8 +16,11 @@ export interface PTimeoutOptions {
     /**
      * If provided - will be called INSTEAD of throwing an error.
      * Can be used to thrown a custom error OR resolve a promise without throwing.
+     *
+     * err (which is TimeoutError) is passed as an argument for convenience, so it can
+     * be logged or such. You don't have to consume it in any way though.
      */
-    onTimeout?: () => any;
+    onTimeout?: (err: TimeoutError) => any;
     /**
      * Defaults to true.
      * If true - preserves the stack trace in case of a Timeout (usually - very useful!).
@@ -33,13 +36,16 @@ export interface PTimeoutOptions {
 }
 /**
  * Decorates a Function with a timeout.
+ * Returns a decorated Function.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export declare function pTimeoutFn<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T;
+export declare function pTimeoutFn<T extends AnyAsyncFunction>(fn: T, opt: PTimeoutOptions): T;
 /**
  * Decorates a Function with a timeout and immediately calls it.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export declare function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Promise<T>;
+export declare function pTimeout<T>(fn: AnyAsyncFunction<T>, opt: PTimeoutOptions): Promise<T>;

package/dist/promise/pTimeout.js

@@ -7,32 +7,37 @@ class TimeoutError extends app_error_1.AppError {
 exports.TimeoutError = TimeoutError;
 /**
  * Decorates a Function with a timeout.
+ * Returns a decorated Function.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
 function pTimeoutFn(fn, opt) {
-    opt.name || (opt.name = fn.name);
+    opt.name ||= fn.name;
     return async function pTimeoutInternalFn(...args) {
-        return await pTimeout(fn.apply(this, args), opt);
+        return await pTimeout(() => fn.apply(this, args), opt);
     };
 }
 exports.pTimeoutFn = pTimeoutFn;
 /**
  * Decorates a Function with a timeout and immediately calls it.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-async function pTimeout(promise, opt) {
-    // todo: check how we can automatically infer function name (only applicable to named functions)
-    const { timeout, name, onTimeout, keepStackTrace = true } = opt;
+async function pTimeout(fn, opt) {
+    const { timeout, name = fn.name || 'pTimeout function', onTimeout, keepStackTrace = true } = opt;
     const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined;
     // eslint-disable-next-line no-async-promise-executor
     return await new Promise(async (resolve, reject) => {
         // Prepare the timeout timer
         const timer = setTimeout(() => {
+            const err = new TimeoutError(`"${name}" timed out after ${timeout} ms`, opt.errorData);
+            if (fakeError)
+                err.stack = fakeError.stack; // keep original stack
             if (onTimeout) {
                 try {
-                    resolve(onTimeout());
+                    resolve(onTimeout(err));
                 }
                 catch (err) {
                     if (fakeError)
@@ -45,14 +50,11 @@ async function pTimeout(promise, opt) {
                 }
                 return;
             }
-            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`, opt.errorData);
-            if (fakeError)
-                err.stack = fakeError.stack; // keep original stack
             reject(err);
         }, timeout);
         // Execute the Function
         try {
-            resolve(await promise);
+            resolve(await fn());
         }
         catch (err) {
             reject(err);

package/dist/string/stringifyAny.d.ts

@@ -1,5 +1,5 @@
 import type { Reviver } from '../types';
-export declare type JsonStringifyFunction = (obj: any, reviver?: Reviver, space?: number) => string;
+export type JsonStringifyFunction = (obj: any, reviver?: Reviver, space?: number) => string;
 export interface StringifyAnyOptions {
     /**
      * @default 10_000

package/dist/typeFest.d.ts

@@ -3,11 +3,11 @@
 
  @category Basic
  */
-export declare type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+export type Primitive = null | undefined | string | number | boolean | symbol | bigint;
 /**
  Flatten the type output to improve type hints shown in editors.
  */
-export declare type Simplify<T> = {
+export type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
 };
 /**
@@ -15,14 +15,14 @@ export declare type Simplify<T> = {
  @link https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650
  @link https://stackoverflow.com/questions/68961864/how-does-the-equals-work-in-typescript/68963796#68963796
  */
-export declare type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
+export type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
 /**
  * Filter out keys from an object.
  * Returns `never` if `Exclude` is strictly equal to `Key`.
  * Returns `never` if `Key` extends `Exclude`.
  * Returns `Key` otherwise.
  */
-declare type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : KeyType extends ExcludeType ? never : KeyType;
+type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : KeyType extends ExcludeType ? never : KeyType;
 /**
  Create a type from an object type without certain keys.
 
@@ -46,7 +46,7 @@ declare type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extend
 
  @category Utilities
  */
-export declare type Except<ObjectType, KeysType extends keyof ObjectType> = {
+export type Except<ObjectType, KeysType extends keyof ObjectType> = {
     [KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
 };
 /**
@@ -80,7 +80,7 @@ export declare type Except<ObjectType, KeysType extends keyof ObjectType> = {
 
  @category Utilities
  */
-export declare type ReadonlyDeep<T> = T extends Primitive | ((...args: any[]) => unknown) ? T : T extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMapDeep<KeyType, ValueType> : T extends ReadonlySet<infer ItemType> ? ReadonlySetDeep<ItemType> : T extends object ? ReadonlyObjectDeep<T> : unknown;
+export type ReadonlyDeep<T> = T extends Primitive | ((...args: any[]) => unknown) ? T : T extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMapDeep<KeyType, ValueType> : T extends ReadonlySet<infer ItemType> ? ReadonlySetDeep<ItemType> : T extends object ? ReadonlyObjectDeep<T> : unknown;
 /**
  Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.
  */
@@ -94,7 +94,7 @@ interface ReadonlySetDeep<ItemType> extends ReadonlySet<ReadonlyDeep<ItemType>>
 /**
  Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`.
  */
-declare type ReadonlyObjectDeep<ObjectType extends object> = {
+type ReadonlyObjectDeep<ObjectType extends object> = {
     readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>;
 };
 /**
@@ -102,7 +102,7 @@ declare type ReadonlyObjectDeep<ObjectType extends object> = {
  * This is the counterpart of `OmitIndexSignature`.
  * When you use a type that will iterate through an object that has indexed keys and explicitly defined keys you end up with a type where only the indexed keys are kept. This is because `keyof` of an indexed type always returns `string | number | symbol`, because every key is possible in that object. With this type, you can save the indexed keys and reinject them later, like in the second example below.
  */
-export declare type PickIndexSignature<ObjectType> = {
+export type PickIndexSignature<ObjectType> = {
     [KeyType in keyof ObjectType as {} extends Record<KeyType, unknown> ? KeyType : never]: ObjectType[KeyType];
 };
 /**
@@ -115,7 +115,7 @@ export declare type PickIndexSignature<ObjectType> = {
  * It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
  * (The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
  */
-export declare type OmitIndexSignature<ObjectType> = {
+export type OmitIndexSignature<ObjectType> = {
     [KeyType in keyof ObjectType as {} extends Record<KeyType, unknown> ? never : KeyType]: ObjectType[KeyType];
 };
 /**
@@ -139,7 +139,7 @@ export declare type OmitIndexSignature<ObjectType> = {
 
  @category Utilities
  */
-export declare type Merge<Destination, Source> = {
+export type Merge<Destination, Source> = {
     [Key in keyof OmitIndexSignature<Destination & Source>]: Key extends keyof Source ? Source[Key] : Key extends keyof Destination ? Destination[Key] : never;
 } & PickIndexSignature<Destination & Source>;
 /**
@@ -166,7 +166,7 @@ export declare type Merge<Destination, Source> = {
  @category Utilities
  ```
  */
-export declare type Promisable<T> = T | PromiseLike<T>;
+export type Promisable<T> = T | PromiseLike<T>;
 /**
  Extract the keys from a type where the value type of the key extends the given `Condition`.
  Internally this is used for the `ConditionalPick` and `ConditionalExcept` types.
@@ -190,7 +190,7 @@ export declare type Promisable<T> = T | PromiseLike<T>;
  ```
  @category Utilities
  */
-export declare type ConditionalKeys<Base, Condition> = NonNullable<{
+export type ConditionalKeys<Base, Condition> = NonNullable<{
     [Key in keyof Base]: Base[Key] extends Condition ? Key : never;
 }[keyof Base]>;
 /**
@@ -222,7 +222,7 @@ export declare type ConditionalKeys<Base, Condition> = NonNullable<{
  ```
  @category Utilities
  */
-export declare type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Base, Condition>>;
+export type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Base, Condition>>;
 /**
  Pick keys from the shape that matches the given `Condition`.
  This is useful when you want to create a new type from a specific subset of an existing type. For example, you might want to pick all the primitive properties from a class and form a new automatically derived type.
@@ -252,16 +252,16 @@ export declare type ConditionalExcept<Base, Condition> = Except<Base, Conditiona
  ```
  @category Utilities
  */
-export declare type ConditionalPick<Base, Condition> = Pick<Base, ConditionalKeys<Base, Condition>>;
+export type ConditionalPick<Base, Condition> = Pick<Base, ConditionalKeys<Base, Condition>>;
 /**
  Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
  @category Basic
  */
-export declare type Class<T = any> = new (...args: any[]) => T;
+export type Class<T = any> = new (...args: any[]) => T;
 /**
  Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
  */
-export declare type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
 declare global {
     interface SymbolConstructor {
         readonly observable: symbol;

package/dist/types.d.ts

@@ -11,10 +11,10 @@ export interface StringMap<T = string> {
  * Convenience shorthand for `Record<string, any>`.
  * Because `object` type is not safe/recommended to be used (e.g discouraged by eslint-typescript due to: https://github.com/microsoft/TypeScript/issues/21732)
  */
-export declare type AnyObject = Record<string, any>;
-export declare type AnyEnum = NumberEnum;
-export declare type NumberEnum = Record<string, number | string>;
-export declare type StringEnum = Record<string, string>;
+export type AnyObject = Record<string, any>;
+export type AnyEnum = NumberEnum;
+export type NumberEnum = Record<string, number | string>;
+export type StringEnum = Record<string, string>;
 export interface CreatedUpdated {
     created: number;
     updated: number;
@@ -47,17 +47,18 @@ export interface SavedDBEntity<ID extends string | number = string> {
  * 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<ID extends string | number = string> = Partial<SavedDBEntity<ID>>;
-export declare type Saved<T extends Partial<ObjectWithId>> = T extends AnyObject ? Omit<T, 'id' | 'created' | 'updated'> & SavedDBEntity<NonNullable<T['id']>> : T;
-export declare type Unsaved<T extends Partial<ObjectWithId>> = T extends AnyObject ? Omit<T, 'id' | 'created' | 'updated'> & BaseDBEntity<NonNullable<T['id']>> : T;
-export declare type UnsavedId<T extends Partial<ObjectWithId>> = Omit<T, 'id'> & {
+export type BaseDBEntity<ID extends string | number = string> = Partial<SavedDBEntity<ID>>;
+export type Saved<T extends Partial<ObjectWithId>> = T extends AnyObject ? Omit<T, 'id' | 'created' | 'updated'> & SavedDBEntity<NonNullable<T['id']>> : T;
+export type Unsaved<T extends Partial<ObjectWithId>> = T extends AnyObject ? Omit<T, 'id' | 'created' | 'updated'> & BaseDBEntity<NonNullable<T['id']>> : T;
+export type UnsavedId<T extends Partial<ObjectWithId>> = Omit<T, 'id'> & {
     id?: T['id'];
 };
 /**
  * Convenience type shorthand.
  * Because `Function` type is discouraged by eslint.
  */
-export declare type AnyFunction = (...args: any[]) => any;
+export type AnyFunction<T = any> = (...args: any[]) => T;
+export type AnyAsyncFunction<T = any> = (...args: any[]) => Promise<T>;
 /**
  * Symbol to indicate END of Sequence.
  */
@@ -69,20 +70,20 @@ export declare const SKIP: unique symbol;
 /**
  * Function which is called for every item in `input`. Expected to return a `Promise` or value.
  */
-export declare type AsyncMapper<IN = any, OUT = any> = (input: IN, index: number) => OUT | PromiseLike<OUT>;
-export declare type Mapper<IN = any, OUT = any> = (input: IN, index: number) => OUT;
+export type AsyncMapper<IN = any, OUT = any> = (input: IN, index: number) => OUT | PromiseLike<OUT>;
+export type Mapper<IN = any, OUT = any> = (input: IN, index: number) => OUT;
 export declare const _passthroughMapper: Mapper;
 export declare const _passUndefinedMapper: Mapper<any, void>;
 /**
  * Function that does nothings and returns `undefined`.
  */
 export declare const _noop: (..._args: any[]) => undefined;
-export declare type Predicate<T> = (item: T, index: number) => boolean;
-export declare type AsyncPredicate<T> = (item: T, index: number) => boolean | PromiseLike<boolean>;
-export declare type AbortablePredicate<T> = (item: T, i: number) => boolean | typeof END;
-export declare type AbortableAsyncPredicate<T> = (item: T, i: number) => Promisable<boolean | typeof END>;
-export declare type AbortableMapper<IN = any, OUT = any> = (input: IN, i: number) => OUT | typeof SKIP | typeof END;
-export declare type AbortableAsyncMapper<IN = any, OUT = any> = (input: IN, i: number) => Promisable<OUT | typeof SKIP | typeof END>;
+export type Predicate<T> = (item: T, index: number) => boolean;
+export type AsyncPredicate<T> = (item: T, index: number) => boolean | PromiseLike<boolean>;
+export type AbortablePredicate<T> = (item: T, i: number) => boolean | typeof END;
+export type AbortableAsyncPredicate<T> = (item: T, i: number) => Promisable<boolean | typeof END>;
+export type AbortableMapper<IN = any, OUT = any> = (input: IN, i: number) => OUT | typeof SKIP | typeof END;
+export type AbortableAsyncMapper<IN = any, OUT = any> = (input: IN, i: number) => Promisable<OUT | typeof SKIP | typeof END>;
 export declare const _passthroughPredicate: Predicate<any>;
 export declare const _passNothingPredicate: Predicate<any>;
 export interface BatchResult<RES = any, ERR = Error> {
@@ -105,7 +106,7 @@ export interface BatchResult<RES = any, ERR = Error> {
  * const arr = ['a', 'b'] as const
  * type Foo = ValuesOf<typeof arr> // 'a' | 'b'
  */
-export declare type ValuesOf<T extends readonly any[]> = T[number];
+export type ValuesOf<T extends readonly any[]> = T[number];
 /**
  * Based on: https://stackoverflow.com/a/49286056/4919972
  *
@@ -114,10 +115,10 @@ export declare type ValuesOf<T extends readonly any[]> = T[number];
  * type Foo = { a: string, b: number }
  * type ValueOfFoo = ValueOf<Foo> // string | number
  */
-export declare type ValueOf<T> = T[keyof T];
-export declare type KeyValueTuple<K, V> = [key: K, value: V];
-export declare type ObjectMapper<OBJ, OUT> = (key: string, value: Exclude<OBJ[keyof OBJ], undefined>, obj: OBJ) => OUT;
-export declare type ObjectPredicate<OBJ> = (key: keyof OBJ, value: Exclude<OBJ[keyof OBJ], undefined>, obj: OBJ) => boolean;
+export type ValueOf<T> = T[keyof T];
+export type KeyValueTuple<K, V> = [key: K, value: V];
+export type ObjectMapper<OBJ, OUT> = (key: string, value: Exclude<OBJ[keyof OBJ], undefined>, obj: OBJ) => OUT;
+export type ObjectPredicate<OBJ> = (key: keyof OBJ, value: Exclude<OBJ[keyof OBJ], undefined>, obj: OBJ) => boolean;
 /**
  * Allows to identify instance of Class by `instanceId`.
  */
@@ -132,44 +133,44 @@ export interface InstanceId {
  *
  * @example '2019-06-21'
  */
-export declare type IsoDateString = string;
+export type IsoDateString = string;
 /**
  * @deprecated use IsoDateString
  */
-export declare type IsoDate = string;
+export type IsoDate = string;
 /**
  * Interface explicitly states that the value is an ISO DateTime string (with time).
  *
  * @example '2019-06-21T05:21:73Z'
  */
-export declare type IsoDateTimeString = string;
+export type IsoDateTimeString = string;
 /**
  * Interface explicitly states that the value is a Unix timestamp (in seconds).
  *
  * @example 1628945450
  */
-export declare type UnixTimestampNumber = number;
+export type UnixTimestampNumber = number;
 /**
  * Interface explicitly states that the value is a "Unix timestamp in **milleseconds**" (not seconds)
  *
  * @example 1628945450000
  */
-export declare type UnixTimestampMillisNumber = number;
+export type UnixTimestampMillisNumber = number;
 /**
  * @deprecated use UnixTimestampNumber
  */
-export declare type UnixTimestamp = number;
+export type UnixTimestamp = number;
 /**
  * Same as `number`, but with semantic meaning that it's an Integer.
  */
-export declare type Integer = number;
-export declare type Base64String = string;
-export declare type Base64UrlString = string;
-export declare type JWTString = string;
+export type Integer = number;
+export type Base64String = string;
+export type Base64UrlString = string;
+export type JWTString = string;
 /**
  * Named type for JSON.parse / JSON.stringify second argument
  */
-export declare type Reviver = (this: any, key: string, value: any) => any;
+export type Reviver = (this: any, key: string, value: any) => any;
 /**
  * Needed due to https://github.com/microsoft/TypeScript/issues/13778
  * Only affects typings, no runtime effect.
@@ -185,8 +186,8 @@ export declare const _stringMapEntries: <T>(m: StringMap<T>) => [k: string, v: T
  * This is how TypeScript should work, actually.
  */
 export declare const _objectKeys: <T extends AnyObject>(obj: T) => (keyof T)[];
-export declare type NullishValue = null | undefined;
-export declare type FalsyValue = false | '' | 0 | null | undefined;
+export type NullishValue = null | undefined;
+export type FalsyValue = false | '' | 0 | null | undefined;
 /**
  * Utility function that helps to cast *existing variable* to needed type T.
  *

package/dist/vendor/is.d.ts

@@ -5,10 +5,10 @@
 /// <reference lib="dom" />
 import { Class, ObservableLike, Primitive, TypedArray } from '../typeFest';
 declare const objectTypeNames: readonly ["Function", "Generator", "AsyncGenerator", "GeneratorFunction", "AsyncGeneratorFunction", "AsyncFunction", "Observable", "Array", "Buffer", "Object", "RegExp", "Date", "Error", "Map", "Set", "WeakMap", "WeakSet", "ArrayBuffer", "SharedArrayBuffer", "DataView", "Promise", "URL", "FormData", "URLSearchParams", "HTMLElement", "Int8Array", "Uint8Array", "Uint8ClampedArray", "Int16Array", "Uint16Array", "Int32Array", "Uint32Array", "Float32Array", "Float64Array", "BigInt64Array", "BigUint64Array"];
-declare type ObjectTypeName = typeof objectTypeNames[number];
+type ObjectTypeName = typeof objectTypeNames[number];
 declare const primitiveTypeNames: readonly ["null", "undefined", "string", "number", "bigint", "boolean", "symbol"];
-declare type PrimitiveTypeName = typeof primitiveTypeNames[number];
-export declare type TypeName = ObjectTypeName | PrimitiveTypeName;
+type PrimitiveTypeName = typeof primitiveTypeNames[number];
+export type TypeName = ObjectTypeName | PrimitiveTypeName;
 export declare function is(value: unknown): TypeName;
 export declare namespace is {
     var undefined: (value: unknown) => value is undefined;
@@ -101,7 +101,7 @@ export interface NodeStream extends NodeJS.EventEmitter {
         end?: boolean;
     }): T;
 }
-export declare type Predicate = (value: unknown) => boolean;
+export type Predicate = (value: unknown) => boolean;
 export declare const enum AssertionTypeDescription {
     class_ = "Class",
     numericString = "string with a number",

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

@@ -76,7 +76,7 @@ function logFinished(logger, callSignature, started, sma, logResultFn, res, err)
     if (sma) {
         t.push(`(avg ${_ms(sma.push(millis))})`);
     }
-    if (typeof err !== 'undefined') {
+    if (err !== undefined) {
         t.push('ERROR:', _stringifyAny(err, { includeErrorData: true }));
     }
     else if (logResultFn) {

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

@@ -10,7 +10,7 @@ export function _Timeout(opt) {
         descriptor.value = async function (...args) {
             const ctx = this;
             opt.name || (opt.name = _getMethodSignature(ctx, keyStr));
-            return await pTimeout(originalFn.apply(this, args), opt);
+            return await pTimeout(() => originalFn.apply(this, args), opt);
         };
         return descriptor;
     };

package/dist-esm/error/try.js

@@ -56,8 +56,12 @@ export class UnexpectedPassError extends AppError {
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export function _expectedError(fn) {
+export function _expectedError(fn, errorClass) {
     try {
         fn();
         // Unexpected!
@@ -66,14 +70,22 @@ export function _expectedError(fn) {
     catch (err) {
         if (err instanceof UnexpectedPassError)
             throw err; // re-throw
+        if (errorClass && !(err instanceof errorClass)) {
+            console.warn(`_expectedError expected ${errorClass.constructor.name} but got different error class`);
+            throw err;
+        }
         return err; // this is expected!
     }
 }
 /**
  * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export async function pExpectedError(promise) {
+export async function pExpectedError(promise, errorClass) {
     try {
         await promise;
         // Unexpected!
@@ -82,6 +94,10 @@ export async function pExpectedError(promise) {
     catch (err) {
         if (err instanceof UnexpectedPassError)
             throw err; // re-throw
+        if (errorClass && !(err instanceof errorClass)) {
+            console.warn(`pExpectedError expected ${errorClass.constructor.name} but got different error class`);
+            throw err;
+        }
         return err; // this is expected!
     }
 }

package/dist-esm/is.util.js

@@ -1,6 +1,6 @@
 export const _isNull = (v) => v === null;
-export const _isUndefined = (v) => typeof v === 'undefined';
-export const _isNullish = (v) => typeof v === 'undefined' || v === null;
+export const _isUndefined = (v) => v === undefined;
+export const _isNullish = (v) => v === undefined || v === null;
 export const _isNotNullish = (v) => v !== undefined && v !== null;
 /**
  * Same as Boolean, but with correct type output.

package/dist-esm/promise/pMap.js

@@ -36,7 +36,7 @@ import { AggregatedError } from './AggregatedError';
  * })();
  */
 export async function pMap(iterable, mapper, opt = {}) {
-    var e_1, _a;
+    var _a, e_1, _b, _c;
     const ret = [];
     // const iterator = iterable[Symbol.iterator]()
     const items = [...iterable];
@@ -52,29 +52,36 @@ export async function pMap(iterable, mapper, opt = {}) {
     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;
+            for (var _d = true, items_1 = __asyncValues(items), items_1_1; items_1_1 = await items_1.next(), _a = items_1_1.done, !_a;) {
+                _c = items_1_1.value;
+                _d = false;
                 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);
+                    const item = _c;
+                    try {
+                        const r = await mapper(item, currentIndex++);
+                        if (r === END)
+                            break;
+                        if (r !== SKIP)
+                            ret.push(r);
                     }
-                    // otherwise, suppress completely
+                    catch (err) {
+                        if (errorMode === ErrorMode.THROW_IMMEDIATELY)
+                            throw err;
+                        if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                            errors.push(err);
+                        }
+                        // otherwise, suppress completely
+                    }
+                }
+                finally {
+                    _d = true;
                 }
             }
         }
         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);
+                if (!_d && !_a && (_b = items_1.return)) await _b.call(items_1);
             }
             finally { if (e_1) throw e_1.error; }
         }

package/dist-esm/promise/pTimeout.js

@@ -3,31 +3,36 @@ export class TimeoutError extends AppError {
 }
 /**
  * Decorates a Function with a timeout.
+ * Returns a decorated Function.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
 export function pTimeoutFn(fn, opt) {
     opt.name || (opt.name = fn.name);
     return async function pTimeoutInternalFn(...args) {
-        return await pTimeout(fn.apply(this, args), opt);
+        return await pTimeout(() => fn.apply(this, args), opt);
     };
 }
 /**
  * Decorates a Function with a timeout and immediately calls it.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export async function pTimeout(promise, opt) {
-    // todo: check how we can automatically infer function name (only applicable to named functions)
-    const { timeout, name, onTimeout, keepStackTrace = true } = opt;
+export async function pTimeout(fn, opt) {
+    const { timeout, name = fn.name || 'pTimeout function', onTimeout, keepStackTrace = true } = opt;
     const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined;
     // eslint-disable-next-line no-async-promise-executor
     return await new Promise(async (resolve, reject) => {
         // Prepare the timeout timer
         const timer = setTimeout(() => {
+            const err = new TimeoutError(`"${name}" timed out after ${timeout} ms`, opt.errorData);
+            if (fakeError)
+                err.stack = fakeError.stack; // keep original stack
             if (onTimeout) {
                 try {
-                    resolve(onTimeout());
+                    resolve(onTimeout(err));
                 }
                 catch (err) {
                     if (fakeError)
@@ -37,14 +42,11 @@ export async function pTimeout(promise, opt) {
                 }
                 return;
             }
-            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`, opt.errorData);
-            if (fakeError)
-                err.stack = fakeError.stack; // keep original stack
             reject(err);
         }, timeout);
         // Execute the Function
         try {
-            resolve(await promise);
+            resolve(await fn());
         }
         catch (err) {
             reject(err);

package/package.json

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

package/src/decorators/logMethod.decorator.ts

@@ -154,7 +154,7 @@ function logFinished(
     t.push(`(avg ${_ms(sma.push(millis))})`)
   }
 
-  if (typeof err !== 'undefined') {
+  if (err !== undefined) {
     t.push('ERROR:', _stringifyAny(err, { includeErrorData: true }))
   } else if (logResultFn) {
     t.push(...logResultFn(res))

package/src/decorators/timeout.decorator.ts

@@ -14,7 +14,7 @@ export function _Timeout(opt: PTimeoutOptions): MethodDecorator {
     descriptor.value = async function (this: typeof target, ...args: any[]) {
       const ctx = this
       opt.name ||= _getMethodSignature(ctx, keyStr)
-      return await pTimeout(originalFn.apply(this, args), opt)
+      return await pTimeout(() => originalFn.apply(this, args), opt)
     } as any
 
     return descriptor

package/src/error/try.ts

@@ -1,3 +1,4 @@
+import type { Class } from '../typeFest'
 import type { AnyFunction } from '../types'
 import { AppError } from './app.error'
 
@@ -63,14 +64,24 @@ export class UnexpectedPassError extends AppError {
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export function _expectedError<ERR = Error>(fn: AnyFunction): ERR {
+export function _expectedError<ERR = Error>(fn: AnyFunction, errorClass?: Class<ERR>): ERR {
   try {
     fn()
     // Unexpected!
     throw new UnexpectedPassError()
   } catch (err) {
     if (err instanceof UnexpectedPassError) throw err // re-throw
+    if (errorClass && !(err instanceof errorClass)) {
+      console.warn(
+        `_expectedError expected ${errorClass.constructor.name} but got different error class`,
+      )
+      throw err
+    }
     return err as ERR // this is expected!
   }
 }
@@ -78,14 +89,27 @@ export function _expectedError<ERR = Error>(fn: AnyFunction): ERR {
 /**
  * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.
+ *
+ * If `errorClass` is passed:
+ * 1. It automatically infers it's type
+ * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
  */
-export async function pExpectedError<ERR = Error>(promise: Promise<any>): Promise<ERR> {
+export async function pExpectedError<ERR = Error>(
+  promise: Promise<any>,
+  errorClass?: Class<ERR>,
+): Promise<ERR> {
   try {
     await promise
     // Unexpected!
     throw new UnexpectedPassError()
   } catch (err) {
     if (err instanceof UnexpectedPassError) throw err // re-throw
+    if (errorClass && !(err instanceof errorClass)) {
+      console.warn(
+        `pExpectedError expected ${errorClass.constructor.name} but got different error class`,
+      )
+      throw err
+    }
     return err as ERR // this is expected!
   }
 }

package/src/is.util.ts

@@ -6,9 +6,8 @@ type Truthy<T> = T extends FalsyValue ? never : T
 type Falsy<T> = T extends FalsyValue ? T : never
 
 export const _isNull = <T>(v: T): v is T extends null ? T : never => v === null
-export const _isUndefined = <T>(v: T): v is T extends undefined ? T : never =>
-  typeof v === 'undefined'
-export const _isNullish = <T>(v: T): v is Nullish<T> => typeof v === 'undefined' || v === null
+export const _isUndefined = <T>(v: T): v is T extends undefined ? T : never => v === undefined
+export const _isNullish = <T>(v: T): v is Nullish<T> => v === undefined || v === null
 export const _isNotNullish = <T>(v: T): v is NonNullable<T> => v !== undefined && v !== null
 
 /**

package/src/promise/pTimeout.ts

@@ -1,6 +1,6 @@
 import { AppError } from '../error/app.error'
 import type { ErrorData } from '../error/error.model'
-import type { AnyFunction } from '../types'
+import type { AnyAsyncFunction } from '../types'
 
 export class TimeoutError extends AppError {}
 
@@ -19,8 +19,11 @@ export interface PTimeoutOptions {
   /**
    * If provided - will be called INSTEAD of throwing an error.
    * Can be used to thrown a custom error OR resolve a promise without throwing.
+   *
+   * err (which is TimeoutError) is passed as an argument for convenience, so it can
+   * be logged or such. You don't have to consume it in any way though.
    */
-  onTimeout?: () => any
+  onTimeout?: (err: TimeoutError) => any
 
   /**
    * Defaults to true.
@@ -39,34 +42,39 @@ export interface PTimeoutOptions {
 
 /**
  * Decorates a Function with a timeout.
+ * Returns a decorated Function.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export function pTimeoutFn<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
+export function pTimeoutFn<T extends AnyAsyncFunction>(fn: T, opt: PTimeoutOptions): T {
   opt.name ||= fn.name
 
   return async function pTimeoutInternalFn(this: any, ...args: any[]) {
-    return await pTimeout(fn.apply(this, args), opt)
-  } as any
+    return await pTimeout(() => fn.apply(this, args), opt)
+  } as T
 }
 
 /**
  * Decorates a Function with a timeout and immediately calls it.
+ *
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export async function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Promise<T> {
-  // todo: check how we can automatically infer function name (only applicable to named functions)
-  const { timeout, name, onTimeout, keepStackTrace = true } = opt
+export async function pTimeout<T>(fn: AnyAsyncFunction<T>, opt: PTimeoutOptions): Promise<T> {
+  const { timeout, name = fn.name || 'pTimeout function', onTimeout, keepStackTrace = true } = opt
   const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined
 
   // eslint-disable-next-line no-async-promise-executor
   return await new Promise(async (resolve, reject) => {
     // Prepare the timeout timer
     const timer = setTimeout(() => {
+      const err = new TimeoutError(`"${name}" timed out after ${timeout} ms`, opt.errorData)
+      if (fakeError) err.stack = fakeError.stack // keep original stack
+
       if (onTimeout) {
         try {
-          resolve(onTimeout())
+          resolve(onTimeout(err))
         } catch (err: any) {
           if (fakeError) err.stack = fakeError.stack // keep original stack
           err.data = {
@@ -78,17 +86,12 @@ export async function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Pr
         return
       }
 
-      const err = new TimeoutError(
-        `"${name || 'pTimeout function'}" timed out after ${timeout} ms`,
-        opt.errorData,
-      )
-      if (fakeError) err.stack = fakeError.stack // keep original stack
       reject(err)
     }, timeout)
 
     // Execute the Function
     try {
-      resolve(await promise)
+      resolve(await fn())
     } catch (err) {
       reject(err)
     } finally {

package/src/types.ts

@@ -78,7 +78,8 @@ export type UnsavedId<T extends Partial<ObjectWithId>> = Omit<T, 'id'> & {
  * Convenience type shorthand.
  * Because `Function` type is discouraged by eslint.
  */
-export type AnyFunction = (...args: any[]) => any
+export type AnyFunction<T = any> = (...args: any[]) => T
+export type AnyAsyncFunction<T = any> = (...args: any[]) => Promise<T>
 
 /**
  * Symbol to indicate END of Sequence.