@naturalcycles/js-lib 14.267.2 → 14.269.0

package/dist/array/array.util.d.ts

@@ -173,8 +173,8 @@ export declare function _difference<T>(a1: T[], a2: T[] | Set<T>): T[];
 /**
  * Returns the sum of items, or 0 for empty array.
  */
-export declare function _sum(items: Iterable<number>): number;
-export declare function _sumBy<T>(items: Iterable<T>, mapper: Mapper<T, number | undefined>): number;
+export declare function _sum<N extends number>(items: Iterable<N>): N;
+export declare function _sumBy<T, N extends number>(items: Iterable<T>, mapper: Mapper<T, N | undefined>): N;
 /**
  * Map an array of T to a StringMap<V>,
  * by returning a tuple of [key, value] from a mapper function.

package/dist/array/array.util.js

@@ -336,7 +336,7 @@ function _difference(a1, a2) {
 function _sum(items) {
     let sum = 0;
     for (const n of items) {
-        sum += n;
+        sum = (sum + n);
     }
     return sum;
 }
@@ -347,7 +347,7 @@ function _sumBy(items, mapper) {
         const v = mapper(n, i++);
         if (typeof v === 'number') {
             // count only numbers, nothing else
-            sum += v;
+            sum = (sum + v);
         }
     }
     return sum;

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

@@ -1,7 +1,7 @@
 import type { CommonLogger } from '../log/commonLogger';
-import { AnyAsyncFunction, AnyFunction, AnyObject } from '../types';
-import { AsyncMemoCache } from './memo.util';
-export interface AsyncMemoOptions {
+import { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types';
+import { AsyncMemoCache, MethodDecorator } from './memo.util';
+export interface AsyncMemoOptions<T> {
     /**
      * Provide a custom implementation of AsyncMemoCache.
      * Function that creates an instance of `AsyncMemoCache`.
@@ -10,7 +10,7 @@ export interface AsyncMemoOptions {
     /**
      * Provide a custom implementation of CacheKey function.
      */
-    cacheKeyFn?: (args: any[]) => any;
+    cacheKeyFn?: (args: MaybeParameters<T>) => any;
     /**
      * Default to `console`
      */
@@ -32,7 +32,7 @@ export interface AsyncMemoInstance {
  *
  * @experimental consider normal @_Memo for most of the cases, it's stable and predictable
  */
-export declare const _AsyncMemo: (opt: AsyncMemoOptions) => MethodDecorator;
+export declare const _AsyncMemo: <T>(opt: AsyncMemoOptions<T>) => MethodDecorator<T>;
 /**
  Call it on a method that is decorated with `@_AsyncMemo` to get access to additional functions,
  e.g `clear` to clear the cache, or get its underlying data.

package/dist/decorators/asyncMemo.decorator.js

@@ -16,9 +16,7 @@ const memo_util_1 = require("./memo.util");
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const _AsyncMemo = (opt) => (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-        throw new TypeError('Memoization can be applied only to methods');
-    }
+    (0, assert_1._assertTypeOf)(descriptor.value, 'function', '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 instanceCache = new Map();

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

@@ -1,7 +1,8 @@
 import type { CommonLogger } from '../log/commonLogger';
-import { AnyFunction, AnyObject } from '../types';
+import { AnyFunction, AnyObject, MaybeParameters } from '../types';
 import type { MemoCache } from './memo.util';
-export interface MemoOptions {
+import { MethodDecorator } from './memo.util';
+export interface MemoOptions<T> {
     /**
      * Provide a custom implementation of MemoCache.
      * Function that creates an instance of `MemoCache`.
@@ -11,7 +12,7 @@ export interface MemoOptions {
     /**
      * Provide a custom implementation of CacheKey function.
      */
-    cacheKeyFn?: (args: any[]) => any;
+    cacheKeyFn?: (args: MaybeParameters<T>) => any;
     /**
      * Default to `console`
      */
@@ -45,7 +46,7 @@ export interface MemoInstance {
  * http://inlehmansterms.net/2015/03/01/javascript-memoization/
  * https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
  */
-export declare const _Memo: (opt?: MemoOptions) => MethodDecorator;
+export declare const _Memo: <T>(opt?: MemoOptions<T>) => MethodDecorator<T>;
 /**
  Call it on a method that is decorated with `@_Memo` to get access to additional functions,
  e.g `clear` to clear the cache, or get its underlying data.

package/dist/decorators/memo.decorator.js

@@ -28,9 +28,7 @@ const memo_util_1 = require("./memo.util");
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const _Memo = (opt = {}) => (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-        throw new TypeError('Memoization can be applied only to methods');
-    }
+    (0, assert_1._assertTypeOf)(descriptor.value, 'function', 'Memoization can be applied only to methods');
     const originalFn = descriptor.value;
     // Map<ctx => MemoCache<cacheKey, result>>
     //

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

@@ -1,4 +1,4 @@
-import type { UnixTimestamp } from '../types';
+import type { AnyObject, UnixTimestamp } from '../types';
 import { MISS } from '../types';
 export type MemoSerializer = (args: any[]) => any;
 export declare const jsonMemoSerializer: MemoSerializer;
@@ -59,3 +59,9 @@ export declare class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncM
     set(k: KEY, v: VALUE): Promise<void>;
     clear(): Promise<void>;
 }
+/**
+ * Generic override of Typescript's built in legacy MethodDecorator, that
+ * allows us to infer the parameters of the decorated method from the parameters
+ * of a decorator.
+ */
+export type MethodDecorator<T> = (target: AnyObject, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | undefined;

package/dist/decorators/memoFn.d.ts

@@ -1,3 +1,4 @@
+import { AnyFunction } from '../types';
 import type { MemoOptions } from './memo.decorator';
 import type { MemoCache } from './memo.util';
 export interface MemoizedFunction {
@@ -10,4 +11,4 @@ export interface MemoizedFunction {
  *
  * @experimental
  */
-export declare function _memoFn<T extends (...args: any[]) => any>(fn: T, opt?: MemoOptions): T & MemoizedFunction;
+export declare function _memoFn<T extends AnyFunction>(fn: T, opt?: MemoOptions<T>): T & MemoizedFunction;

package/dist/decorators/memoFnAsync.d.ts

@@ -1,3 +1,4 @@
+import { AnyAsyncFunction } from '../types';
 import type { AsyncMemoOptions } from './asyncMemo.decorator';
 import type { AsyncMemoCache } from './memo.util';
 export interface MemoizedAsyncFunction {
@@ -6,4 +7,4 @@ export interface MemoizedAsyncFunction {
 /**
  * @experimental
  */
-export declare function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(fn: T, opt: AsyncMemoOptions): T & MemoizedAsyncFunction;
+export declare function _memoFnAsync<T extends AnyAsyncFunction>(fn: T, opt: AsyncMemoOptions<T>): T & MemoizedAsyncFunction;

package/dist/types.d.ts

@@ -97,6 +97,10 @@ export type LazyPromise<T> = () => Promise<T>;
  * A function that lazily calculates something async, that can return null.
  */
 export type LazyNullablePromise<T> = () => Promise<T | null>;
+/**
+ * Evaluates to the parameters if T is a function, otherwise never
+ */
+export type MaybeParameters<T> = T extends AnyFunction ? Parameters<T> : never;
 /**
  * Symbol to indicate END of Sequence.
  */

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

@@ -295,7 +295,7 @@ export function _difference(a1, a2) {
 export function _sum(items) {
     let sum = 0;
     for (const n of items) {
-        sum += n;
+        sum = (sum + n);
     }
     return sum;
 }
@@ -306,7 +306,7 @@ export function _sumBy(items, mapper) {
         const v = mapper(n, i++);
         if (typeof v === 'number') {
             // count only numbers, nothing else
-            sum += v;
+            sum = (sum + v);
         }
     }
     return sum;

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

@@ -1,5 +1,5 @@
-import { _assert } from '../error/assert';
-import { _objectAssign, MISS } from '../types';
+import { _assert, _assertTypeOf } from '../error/assert';
+import { _objectAssign, MISS, } from '../types';
 import { _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer } from './memo.util';
 /**
@@ -12,9 +12,7 @@ import { jsonMemoSerializer } from './memo.util';
  */
 // 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');
-    }
+    _assertTypeOf(descriptor.value, 'function', '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 instanceCache = new Map();

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

@@ -1,4 +1,4 @@
-import { _assert } from '../error/assert';
+import { _assert, _assertTypeOf } from '../error/assert';
 import { _objectAssign } from '../types';
 import { _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
@@ -24,9 +24,7 @@ import { jsonMemoSerializer, MapMemoCache } from './memo.util';
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _Memo = (opt = {}) => (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-        throw new TypeError('Memoization can be applied only to methods');
-    }
+    _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
     const originalFn = descriptor.value;
     // Map<ctx => MemoCache<cacheKey, result>>
     //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.267.2",
+  "version": "14.269.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/array/array.util.ts

@@ -347,23 +347,26 @@ export function _difference<T>(a1: T[], a2: T[] | Set<T>): T[] {
 /**
  * Returns the sum of items, or 0 for empty array.
  */
-export function _sum(items: Iterable<number>): number {
-  let sum = 0
+export function _sum<N extends number>(items: Iterable<N>): N {
+  let sum = 0 as N
   for (const n of items) {
-    sum += n
+    sum = (sum + n) as N
   }
   return sum
 }
 
-export function _sumBy<T>(items: Iterable<T>, mapper: Mapper<T, number | undefined>): number {
-  let sum = 0
+export function _sumBy<T, N extends number>(
+  items: Iterable<T>,
+  mapper: Mapper<T, N | undefined>,
+): N {
+  let sum = 0 as N
   let i = 0
 
   for (const n of items) {
     const v = mapper(n, i++)
     if (typeof v === 'number') {
       // count only numbers, nothing else
-      sum += v
+      sum = (sum + v) as N
     }
   }
 

package/src/decorators/asyncMemo.decorator.ts

@@ -1,10 +1,17 @@
-import { _assert } from '../error/assert'
+import { _assert, _assertTypeOf } from '../error/assert'
 import type { CommonLogger } from '../log/commonLogger'
-import { _objectAssign, AnyAsyncFunction, AnyFunction, AnyObject, MISS } from '../types'
+import {
+  _objectAssign,
+  AnyAsyncFunction,
+  AnyFunction,
+  AnyObject,
+  MaybeParameters,
+  MISS,
+} from '../types'
 import { _getTargetMethodSignature } from './decorator.util'
-import { AsyncMemoCache, jsonMemoSerializer } from './memo.util'
+import { AsyncMemoCache, jsonMemoSerializer, MethodDecorator } from './memo.util'
 
-export interface AsyncMemoOptions {
+export interface AsyncMemoOptions<T> {
   /**
    * Provide a custom implementation of AsyncMemoCache.
    * Function that creates an instance of `AsyncMemoCache`.
@@ -14,7 +21,7 @@ export interface AsyncMemoOptions {
   /**
    * Provide a custom implementation of CacheKey function.
    */
-  cacheKeyFn?: (args: any[]) => any
+  cacheKeyFn?: (args: MaybeParameters<T>) => any
 
   /**
    * Default to `console`
@@ -43,11 +50,13 @@ export interface AsyncMemoInstance {
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo =
-  (opt: AsyncMemoOptions): MethodDecorator =>
+  <T>(opt: AsyncMemoOptions<T>): MethodDecorator<T> =>
   (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-      throw new TypeError('Memoization can be applied only to methods')
-    }
+    _assertTypeOf<AnyFunction>(
+      descriptor.value,
+      'function',
+      'Memoization can be applied only to methods',
+    )
 
     const originalFn = descriptor.value
 
@@ -66,7 +75,7 @@ export const _AsyncMemo =
     const methodSignature = _getTargetMethodSignature(target, keyStr)
 
     // eslint-disable-next-line @typescript-eslint/promise-function-async
-    descriptor.value = function (this: typeof target, ...args: any[]): Promise<any> {
+    descriptor.value = function (this: typeof target, ...args: MaybeParameters<T>): Promise<any> {
       const ctx = this
       const cacheKey = cacheKeyFn(args)
 

package/src/decorators/memo.decorator.ts

@@ -1,11 +1,11 @@
-import { _assert } from '../error/assert'
+import { _assert, _assertTypeOf } from '../error/assert'
 import type { CommonLogger } from '../log/commonLogger'
-import { _objectAssign, AnyFunction, AnyObject } from '../types'
+import { _objectAssign, AnyFunction, AnyObject, MaybeParameters } from '../types'
 import { _getTargetMethodSignature } from './decorator.util'
 import type { MemoCache } from './memo.util'
-import { jsonMemoSerializer, MapMemoCache } from './memo.util'
+import { jsonMemoSerializer, MapMemoCache, MethodDecorator } from './memo.util'
 
-export interface MemoOptions {
+export interface MemoOptions<T> {
   /**
    * Provide a custom implementation of MemoCache.
    * Function that creates an instance of `MemoCache`.
@@ -16,7 +16,7 @@ export interface MemoOptions {
   /**
    * Provide a custom implementation of CacheKey function.
    */
-  cacheKeyFn?: (args: any[]) => any
+  cacheKeyFn?: (args: MaybeParameters<T>) => any
 
   /**
    * Default to `console`
@@ -57,11 +57,13 @@ export interface MemoInstance {
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _Memo =
-  (opt: MemoOptions = {}): MethodDecorator =>
+  <T>(opt: MemoOptions<T> = {}): MethodDecorator<T> =>
   (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-      throw new TypeError('Memoization can be applied only to methods')
-    }
+    _assertTypeOf<AnyFunction>(
+      descriptor.value,
+      'function',
+      'Memoization can be applied only to methods',
+    )
 
     const originalFn = descriptor.value
 
@@ -83,7 +85,7 @@ export const _Memo =
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)
 
-    descriptor.value = function (this: typeof target, ...args: any[]): any {
+    descriptor.value = function (this: typeof target, ...args: MaybeParameters<T>): any {
       const ctx = this
       const cacheKey = cacheKeyFn(args)
 

package/src/decorators/memo.util.ts

@@ -1,6 +1,6 @@
 import { _isPrimitive } from '../is.util'
 import { pDelay } from '../promise/pDelay'
-import type { UnixTimestamp } from '../types'
+import type { AnyObject, UnixTimestamp } from '../types'
 import { MISS } from '../types'
 
 export type MemoSerializer = (args: any[]) => any
@@ -147,3 +147,14 @@ export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache
     this.m.clear()
   }
 }
+
+/**
+ * Generic override of Typescript's built in legacy MethodDecorator, that
+ * allows us to infer the parameters of the decorated method from the parameters
+ * of a decorator.
+ */
+export type MethodDecorator<T> = (
+  target: AnyObject,
+  propertyKey: string | symbol,
+  descriptor: TypedPropertyDescriptor<T>,
+) => TypedPropertyDescriptor<T> | undefined

package/src/decorators/memoFn.ts

@@ -1,3 +1,4 @@
+import { AnyFunction, MaybeParameters } from '../types'
 import type { MemoOptions } from './memo.decorator'
 import type { MemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
@@ -13,9 +14,9 @@ export interface MemoizedFunction {
  *
  * @experimental
  */
-export function _memoFn<T extends (...args: any[]) => any>(
+export function _memoFn<T extends AnyFunction>(
   fn: T,
-  opt: MemoOptions = {},
+  opt: MemoOptions<T> = {},
 ): T & MemoizedFunction {
   const {
     logger = console,
@@ -25,7 +26,7 @@ export function _memoFn<T extends (...args: any[]) => any>(
 
   const cache = cacheFactory()
 
-  const memoizedFn = function (this: any, ...args: any[]): T {
+  const memoizedFn = function (this: any, ...args: MaybeParameters<T>): T {
     const ctx = this
     const cacheKey = cacheKeyFn(args)
 

package/src/decorators/memoFnAsync.ts

@@ -1,4 +1,4 @@
-import { MISS } from '../types'
+import { AnyAsyncFunction, MaybeParameters, MISS } from '../types'
 import type { AsyncMemoOptions } from './asyncMemo.decorator'
 import type { AsyncMemoCache } from './memo.util'
 import { jsonMemoSerializer, MapMemoCache } from './memo.util'
@@ -10,9 +10,9 @@ export interface MemoizedAsyncFunction {
 /**
  * @experimental
  */
-export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
+export function _memoFnAsync<T extends AnyAsyncFunction>(
   fn: T,
-  opt: AsyncMemoOptions,
+  opt: AsyncMemoOptions<T>,
 ): T & MemoizedAsyncFunction {
   const {
     logger = console,
@@ -22,7 +22,7 @@ export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
 
   const cache = cacheFactory()
 
-  const memoizedFn = async function (this: any, ...args: any[]): Promise<any> {
+  const memoizedFn = async function (this: any, ...args: MaybeParameters<T>): Promise<any> {
     const ctx = this
     const cacheKey = cacheKeyFn(args)
     let value: any

package/src/types.ts

@@ -119,6 +119,10 @@ export type LazyPromise<T> = () => Promise<T>
  * A function that lazily calculates something async, that can return null.
  */
 export type LazyNullablePromise<T> = () => Promise<T | null>
+/**
+ * Evaluates to the parameters if T is a function, otherwise never
+ */
+export type MaybeParameters<T> = T extends AnyFunction ? Parameters<T> : never
 
 /**
  * Symbol to indicate END of Sequence.