@thi.ng/memoize 3.3.13 → 4.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-10-05T12:12:32Z
+- **Last updated**: 2024-11-03T16:41:34Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [4.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/memoize@4.0.0) (2024-10-31)
+
+#### 🛑 Breaking changes
+
+- add async versions of all memoize functions ([#493](https://github.com/thi-ng/umbrella/issues/493)) ([e31543c](https://github.com/thi-ng/umbrella/commit/e31543c))
+- BREAKING CHANGE: remove obsolete arity overrides (i.e. 2/3/4 suffixed versions)
+  - add memoizeAsync()
+  - add memoizeAsync1()
+  - add memoizeAsyncJ()
+  - add memoizeAsyncO()
+  - refactor memoize fns to be variadic
+  - remove obsolete fixed arity versions (e.g. `memoize2O`, 3O, 4O etc.)
+  - update tests
+
 ### [3.3.5](https://github.com/thi-ng/umbrella/tree/@thi.ng/memoize@3.3.5) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -30,7 +30,7 @@
 
 ## About
 
-Function memoization with configurable caching.
+Function memoization with configurable caching and support for async functions.
 
 This package provides different function memoization implementations for
 functions with arbitrary arguments and custom result caching using ES6
@@ -48,10 +48,10 @@ based on different strategies. See doc strings for further details.
 - [defOnce()](https://docs.thi.ng/umbrella/memoize/functions/defOnce.html)
 - [delay()](https://docs.thi.ng/umbrella/memoize/functions/delay.html)
 - [doOnce()](https://docs.thi.ng/umbrella/memoize/functions/doOnce.html)
-- [memoize()](https://docs.thi.ng/umbrella/memoize/functions/memoize.html)
-- [memoize1()](https://docs.thi.ng/umbrella/memoize/functions/memoize1.html)
-- [memoizeJ()](https://docs.thi.ng/umbrella/memoize/functions/memoizeJ.html)
-- [memoizeO()](https://docs.thi.ng/umbrella/memoize/functions/memoizeO.html)
+- [memoize()](https://docs.thi.ng/umbrella/memoize/functions/memoize.html) / [memoizeAsync()](https://docs.thi.ng/umbrella/memoize/functions/memoizeAsync.html)
+- [memoize1()](https://docs.thi.ng/umbrella/memoize/functions/memoize1.html) / [memoizeAsync1()](https://docs.thi.ng/umbrella/memoize/functions/memoizeAsync1.html)
+- [memoizeJ()](https://docs.thi.ng/umbrella/memoize/functions/memoizeJ.html) / [memoizeAsyncJ()](https://docs.thi.ng/umbrella/memoize/functions/memoizeAsyncJ.html)
+- [memoizeO()](https://docs.thi.ng/umbrella/memoize/functions/memoizeO.html) / [memoizeAsyncO()](https://docs.thi.ng/umbrella/memoize/functions/memoizeAsyncO.html)
 
 ## Status
 
@@ -89,7 +89,7 @@ For Node.js REPL:
 const mem = await import("@thi.ng/memoize");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 506 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 507 bytes
 
 ## Dependencies
 
@@ -126,7 +126,10 @@ import { LRUCache } from "@thi.ng/cache";
 ```ts
 import { memoize1 } from "@thi.ng/memoize";
 
-foo = memoize1((x) => (console.log("exec"), x * 10));
+foo = memoize1((x: number) => {
+    console.log("exec");
+    return x * 10;
+});
 
 foo(1);
 // exec
@@ -138,7 +141,7 @@ import { EquivMap } from "@thi.ng/associative";
 
 // with custom cache
 foo = memoize1(
-    (x) => (console.log("exec"), x[0] * 10),
+    (x: number[]) => (console.log("exec"), x[0] * 10),
     // custom ES6 Map impl which compares by value, not by reference
     new EquivMap()
 );
@@ -148,6 +151,7 @@ foo([1]);
 // 10
 
 // would be a cache miss w/ native ES6 Map
+// due to lack of value equality semantics
 foo([1]);
 // 10
 
@@ -155,7 +159,7 @@ import { LRUCache } from "@thi.ng/cache";
 
 // use LRU cache to limit cache size
 foo = memoize1(
-    (x) => (console.log("exec"), x[0] * 10),
+    (x: number[]) => (console.log("exec"), x[0] * 10),
     new LRUCache(null, { maxlen: 3 })
 );
 ```
@@ -167,7 +171,10 @@ import { memoize } from "@thi.ng/memoize";
 import { EquivMap } from "@thi.ng/associative";
 
 const dotProduct = memoize(
-    (x, y) => (console.log("exec"), x[0] * y[0] + x[1] * y[1]),
+    (x: number[], y: number[]) => {
+        console.log("exec");
+        return x[0] * y[0] + x[1] * y[1];
+    },
     new EquivMap()
 );
 
@@ -184,11 +191,16 @@ dotProduct([1,2], [3,4]);
 import { memoizeJ } from "@thi.ng/memoize";
 
 const dotProduct = memoizeJ(
-    (x, y) => (console.log("exec"), x[0] * y[0] + x[1] * y[1])
+    (x: number[], y: number[]) => {
+        console.log("exec");
+        return x[0] * y[0] + x[1] * y[1];
+    }
 );
+
 dotProduct([1, 2], [3, 4]);
 // exec
 // 11
+
 dotProduct([1, 2], [3, 4]);
 // 11
 ```

package/memoize.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, Fn2, Fn3, Fn4 } from "@thi.ng/api";
+import type { FnAny } from "@thi.ng/api";
 import type { MapLike } from "./api.js";
 /**
  * Function memoization for arbitrary argument counts. Returns augmented
@@ -17,8 +17,12 @@ import type { MapLike } from "./api.js";
  * @param fn -
  * @param cache -
  */
-export declare function memoize<A, B>(fn: Fn<A, B>, cache: MapLike<A, B>): Fn<A, B>;
-export declare function memoize<A, B, C>(fn: Fn2<A, B, C>, cache: MapLike<[A, B], C>): Fn2<A, B, C>;
-export declare function memoize<A, B, C, D>(fn: Fn3<A, B, C, D>, cache: MapLike<[A, B, C], D>): Fn3<A, B, C, D>;
-export declare function memoize<A, B, C, D, E>(fn: Fn4<A, B, C, D, E>, cache: MapLike<[A, B, C, D], E>): Fn4<A, B, C, D, E>;
+export declare function memoize<T extends FnAny<any>>(fn: T, cache: MapLike<any, any>): T;
+/**
+ * Async version of {@link memoize}.
+ *
+ * @param fn
+ * @param cache
+ */
+export declare function memoizeAsync<T extends FnAny<any>>(fn: T, cache: MapLike<any, any>): (...xs: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 //# sourceMappingURL=memoize.d.ts.map

package/memoize.js

@@ -4,6 +4,13 @@ function memoize(fn, cache) {
     return cache.has(args) ? cache.get(args) : (cache.set(args, res = fn.apply(null, args)), res);
   };
 }
+function memoizeAsync(fn, cache) {
+  return async (...args) => {
+    let res;
+    return cache.has(args) ? cache.get(args) : (cache.set(args, res = await fn.apply(null, args)), res);
+  };
+}
 export {
-  memoize
+  memoize,
+  memoizeAsync
 };

package/memoize1.d.ts

@@ -1,4 +1,4 @@
-import type { Fn } from "@thi.ng/api";
+import type { Fn, MaybePromise } from "@thi.ng/api";
 import type { MapLike } from "./api.js";
 /**
  * Optimized memoization for single arg functions.
@@ -16,4 +16,11 @@ import type { MapLike } from "./api.js";
  * @param cache -
  */
 export declare const memoize1: <A, B>(fn: Fn<A, B>, cache?: MapLike<A, B>) => (x: A) => B;
+/**
+ * Async version of {@link memoize1}.
+ *
+ * @param fn
+ * @param cache
+ */
+export declare const memoizeAsync1: <A, B>(fn: Fn<A, MaybePromise<B>>, cache?: MapLike<A, B>) => (x: A) => Promise<B>;
 //# sourceMappingURL=memoize1.d.ts.map

package/memoize1.js

@@ -2,6 +2,11 @@ const memoize1 = (fn, cache = /* @__PURE__ */ new Map()) => (x) => {
   let res;
   return cache.has(x) ? cache.get(x) : (cache.set(x, res = fn(x)), res);
 };
+const memoizeAsync1 = (fn, cache = /* @__PURE__ */ new Map()) => async (x) => {
+  let res;
+  return cache.has(x) ? cache.get(x) : (cache.set(x, res = await fn(x)), res);
+};
 export {
-  memoize1
+  memoize1,
+  memoizeAsync1
 };

package/memoizej.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, Fn2, Fn3, Fn4, IObjectOf } from "@thi.ng/api";
+import type { FnAny, IObjectOf } from "@thi.ng/api";
 /**
  * Function memoization for arbitrary argument counts. Returns augmented
  * function, which uses `JSON.stringify()` to obtain (and store)
@@ -14,8 +14,12 @@ import type { Fn, Fn2, Fn3, Fn4, IObjectOf } from "@thi.ng/api";
  * @param fn -
  * @param cache -
  */
-export declare function memoizeJ<A, B>(fn: Fn<A, B>, cache?: IObjectOf<B>): Fn<A, B>;
-export declare function memoizeJ<A, B, C>(fn: Fn2<A, B, C>, cache?: IObjectOf<C>): Fn2<A, B, C>;
-export declare function memoizeJ<A, B, C, D>(fn: Fn3<A, B, C, D>, cache?: IObjectOf<D>): Fn3<A, B, C, D>;
-export declare function memoizeJ<A, B, C, D, E>(fn: Fn4<A, B, C, D, E>, cache?: IObjectOf<E>): Fn4<A, B, C, D, E>;
+export declare function memoizeJ<T extends FnAny<any>>(fn: T, cache?: IObjectOf<any>): T;
+/**
+ * Async version of {@link memoizeJ}.
+ *
+ * @param fn
+ * @param cache
+ */
+export declare function memoizeAsyncJ<T extends FnAny<any>>(fn: T, cache?: IObjectOf<any>): (...xs: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 //# sourceMappingURL=memoizej.d.ts.map

package/memoizej.js

@@ -7,6 +7,16 @@ function memoizeJ(fn, cache = /* @__PURE__ */ Object.create(null)) {
     return fn.apply(null, args);
   };
 }
+function memoizeAsyncJ(fn, cache = /* @__PURE__ */ Object.create(null)) {
+  return async (...args) => {
+    const key = JSON.stringify(args);
+    if (key !== void 0) {
+      return key in cache ? cache[key] : cache[key] = await fn.apply(null, args);
+    }
+    return await fn.apply(null, args);
+  };
+}
 export {
+  memoizeAsyncJ,
   memoizeJ
 };

package/memoizeo.d.ts

@@ -1,11 +1,15 @@
-import type { Fn, Fn2, Fn3, Fn4, NumOrString } from "@thi.ng/api";
+import type { Fn, Fn2, Fn3, Fn4, IObjectOf, MaybePromise, NumOrString } from "@thi.ng/api";
 /**
- * The most minimalistic & fastest memoization function of this package. Similar
- * to {@link memoize1}, but only supports numbers or strings as keys and uses a
- * vanilla JS object as cache.
+ * The most minimalistic memoization function of this package, but only supports
+ * numbers or strings as arguments (max. 4) and uses a vanilla JS object as
+ * cache.
  *
  * @remarks
- * Also see {@link memoize1}, {@link memoizeJ}, {@link memoize}.
+ * If `fn` throws an error, no result value will be cached and no memoization
+ * happens for this invocation using the given arguments.
+ *
+ * Use {@link memoizeAsyncO} for async functions or other functions returning
+ * promises.
  *
  * @example
  * ```ts tangle:../export/memoizeo.ts
@@ -28,26 +32,22 @@ import type { Fn, Fn2, Fn3, Fn4, NumOrString } from "@thi.ng/api";
  * @param fn
  * @param cache
  */
-export declare const memoizeO: <A extends NumOrString, B>(fn: Fn<A, B>, cache?: Record<NumOrString, B>) => (x: A) => B;
-/**
- * Like {@link memoizeO}, but for functions with 2 arguments.
- *
- * @param fn
- * @param cache
- */
-export declare const memoize2O: <A extends NumOrString, B extends NumOrString, C>(fn: Fn2<A, B, C>, cache?: Record<string, C>) => (a: A, b: B) => C;
+export declare function memoizeO<A extends NumOrString, B>(fn: Fn<A, B>, cache?: IObjectOf<B>): Fn<A, B>;
+export declare function memoizeO<A extends NumOrString, B extends NumOrString, C>(fn: Fn2<A, B, C>, cache?: IObjectOf<C>): Fn2<A, B, C>;
+export declare function memoizeO<A extends NumOrString, B extends NumOrString, C extends NumOrString, D>(fn: Fn3<A, B, C, D>, cache?: IObjectOf<D>): Fn3<A, B, C, D>;
+export declare function memoizeO<A extends NumOrString, B extends NumOrString, C extends NumOrString, D extends NumOrString, E>(fn: Fn4<A, B, C, D, E>, cache?: IObjectOf<E>): Fn4<A, B, C, D, E>;
 /**
- * Like {@link memoizeO}, but for functions with 3 arguments.
+ * Async version of {@link memoizeO}.
  *
- * @param fn
- * @param cache
- */
-export declare const memoize3O: <A extends NumOrString, B extends NumOrString, C extends NumOrString, D>(fn: Fn3<A, B, C, D>, cache?: Record<string, D>) => (a: A, b: B, c: C) => D;
-/**
- * Like {@link memoizeO}, but for functions with 4 arguments.
+ * @remarks
+ * If `fn` throws an error, no result value will be cached and no memoization
+ * happens for this invocation using the given arguments.
  *
  * @param fn
  * @param cache
  */
-export declare const memoize4O: <A extends NumOrString, B extends NumOrString, C extends NumOrString, D extends NumOrString, E>(fn: Fn4<A, B, C, D, E>, cache?: Record<string, E>) => (a: A, b: B, c: C, d: D) => E;
+export declare function memoizeAsyncO<A extends NumOrString, B>(fn: Fn<A, MaybePromise<B>>, cache?: IObjectOf<B>): Fn<A, Promise<B>>;
+export declare function memoizeAsyncO<A extends NumOrString, B extends NumOrString, C>(fn: Fn2<A, B, MaybePromise<C>>, cache?: IObjectOf<C>): Fn2<A, B, Promise<C>>;
+export declare function memoizeAsyncO<A extends NumOrString, B extends NumOrString, C extends NumOrString, D>(fn: Fn3<A, B, C, MaybePromise<D>>, cache?: IObjectOf<D>): Fn3<A, B, C, Promise<D>>;
+export declare function memoizeAsyncO<A extends NumOrString, B extends NumOrString, C extends NumOrString, D extends NumOrString, E>(fn: Fn4<A, B, C, D, MaybePromise<E>>, cache?: IObjectOf<E>): Fn4<A, B, C, D, Promise<E>>;
 //# sourceMappingURL=memoizeo.d.ts.map

package/memoizeo.js

@@ -1,19 +1,16 @@
-const memoizeO = (fn, cache = /* @__PURE__ */ Object.create(null)) => (x) => x in cache ? cache[x] : cache[x] = fn(x);
-const memoize2O = (fn, cache = /* @__PURE__ */ Object.create(null)) => (a, b) => {
-  const key = a + "-" + b;
-  return key in cache ? cache[key] : cache[key] = fn(a, b);
-};
-const memoize3O = (fn, cache = /* @__PURE__ */ Object.create(null)) => (a, b, c) => {
-  const key = a + "-" + b + "-" + c;
-  return key in cache ? cache[key] : cache[key] = fn(a, b, c);
-};
-const memoize4O = (fn, cache = /* @__PURE__ */ Object.create(null)) => (a, b, c, d) => {
-  const key = a + "-" + b + "-" + c + "-" + d;
-  return key in cache ? cache[key] : cache[key] = fn(a, b, c, d);
-};
+function memoizeO(fn, cache = /* @__PURE__ */ Object.create(null)) {
+  return (...xs) => {
+    const key = xs.join("-");
+    return key in cache ? cache[key] : cache[key] = fn(...xs);
+  };
+}
+function memoizeAsyncO(fn, cache = /* @__PURE__ */ Object.create(null)) {
+  return async (...xs) => {
+    const key = xs.join("-");
+    return key in cache ? cache[key] : cache[key] = await fn(...xs);
+  };
+}
 export {
-  memoize2O,
-  memoize3O,
-  memoize4O,
+  memoizeAsyncO,
   memoizeO
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/memoize",
-  "version": "3.3.13",
-  "description": "Function memoization with configurable caching",
+  "version": "4.0.1",
+  "description": "Function memoization with configurable caching and support for async functions",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -45,6 +45,7 @@
     "typescript": "^5.6.2"
   },
   "keywords": [
+    "async",
     "cache",
     "functional",
     "memoization",
@@ -95,5 +96,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "11ae480076e61a2263f5730ffb37dfddbf01c7d1\n"
+  "gitHead": "1148f3130b867c65141957b4b7617021d7ac7fc9\n"
 }