@thi.ng/memoize 3.1.65 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-13T14:04:31Z
+- **Last updated**: 2024-04-08T14:59:29Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,33 @@ 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.
 
+## [3.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/memoize@3.3.0) (2024-04-08)
+
+#### 🚀 Features
+
+- add delay() wrapper ([d8f4733](https://github.com/thi-ng/umbrella/commit/d8f4733))
+  - migrated from [@thi.ng/compose](https://github.com/thi-ng/umbrella/tree/main/packages/compose) since conceptually better at home here
+  - add docs
+
+#### ♻️ Refactoring
+
+- rename `defonce()` => `defOnce()` ([08e876f](https://github.com/thi-ng/umbrella/commit/08e876f))
+  - deprecate old spelling
+
+## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/memoize@3.2.0) (2024-03-27)
+
+#### 🚀 Features
+
+- add memoizeO() ([af2ead9](https://github.com/thi-ng/umbrella/commit/af2ead9))
+- add memoize2/3/4O() ([8309236](https://github.com/thi-ng/umbrella/commit/8309236))
+
+#### ♻️ Refactoring
+
+- minor updates, use plain objects where possible ([f44be23](https://github.com/thi-ng/umbrella/commit/f44be23))
+  - update defOnce() & memoizeJ() to use Object.create(null) as default store
+  - update default args in others
+  - update docs
+
 ### [3.1.41](https://github.com/thi-ng/umbrella/tree/@thi.ng/memoize@3.1.41) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 190 standalone projects, maintained as part
+> This is one of 191 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,6 +15,7 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [Available memoization functions](#available-memoization-functions)
 - [Status](#status)
 - [Related packages](#related-packages)
 - [Installation](#installation)
@@ -32,7 +33,7 @@
 Function memoization with configurable caching.
 
 This package provides different function memoization implementations for
-functions with 1 or more arguments and custom result caching using ES6
+functions with arbitrary arguments and custom result caching using ES6
 Map API like implementations. Unlike native ES6 Maps, **the
 implementations MUST support value, not just referential, equality
 semantics** (e.g. those provided by
@@ -42,6 +43,16 @@ or
 The latter also support automatically pruning of memoization caches,
 based on different strategies. See doc strings for further details.
 
+### Available memoization functions
+
+- [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)
+
 ## Status
 
 **STABLE** - used in production
@@ -58,7 +69,13 @@ based on different strategies. See doc strings for further details.
 yarn add @thi.ng/memoize
 ```
 
-ES module import:
+ESM import:
+
+```ts
+import * as mem from "@thi.ng/memoize";
+```
+
+Browser ESM import:
 
 ```html
 <script type="module" src="https://cdn.skypack.dev/@thi.ng/memoize"></script>
@@ -69,10 +86,10 @@ ES module import:
 For Node.js REPL:
 
 ```js
-const memoize = await import("@thi.ng/memoize");
+const mem = await import("@thi.ng/memoize");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 247 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 518 bytes
 
 ## Dependencies
 

package/defonce.d.ts

@@ -1,17 +1,23 @@
 import type { Fn0 } from "@thi.ng/api";
 /**
- * Lightweight named singleton factory, intended for hot-module
- * replacement situations. Takes a (preferably globally unique) `id` and
- * `factory` function. If there's no value defined for `id` yet, calls
- * `factory` to produce the singleton value and caches it. Returns
- * singleton value.
+ * Lightweight named singleton factory, intended for hot-module replacement
+ * situations. Takes a (preferably globally unique) `id` and `factory` function.
+ * If there's no value defined for `id` yet, calls `factory` to produce the
+ * singleton value and caches it. Returns singleton value.
  *
- * Note: All created values will remain in the private cache until the
- * JS process terminates or this module itself has been reloaded (though
- * the latter shouldn't happen in an HMR workflow).
+ * @remarks
+ * Note: All created values will remain in the private cache until the JS
+ * process terminates or this module itself has been reloaded (though the latter
+ * shouldn't happen in an HMR workflow).
+ *
+ * For more control over memory usage, consider using other memoize functions in
+ * this package with one of the available cache implementations from
+ * [thi.ng/cache](https://thi.ng/cache).
  *
  * @param id -
  * @param factory -
  */
+export declare const defOnce: <T>(id: string, factory: Fn0<T>) => T;
+/** @deprecated renamed to {@link defOnce} */
 export declare const defonce: <T>(id: string, factory: Fn0<T>) => T;
 //# sourceMappingURL=defonce.d.ts.map

package/defonce.js

@@ -1,5 +1,7 @@
-const cache = {};
-const defonce = (id, factory) => cache.hasOwnProperty(id) ? cache[id] : cache[id] = factory();
+const cache = /* @__PURE__ */ Object.create(null);
+const defOnce = (id, factory) => id in cache ? cache[id] : cache[id] = factory();
+const defonce = defOnce;
 export {
+  defOnce,
   defonce
 };

package/delay.d.ts

@@ -0,0 +1,43 @@
+import type { Fn0, IDeref } from "@thi.ng/api";
+/**
+ * Syntax sugar for {@link Delay} ctor. Wraps given no-arg function in a
+ * {@link Delay} value/memoization wrapper and returns it. The function result
+ * can later be obtained via `.deref()`. The function will only be called the
+ * first time `.deref()` is used and the result will be cached. Future deref's
+ * will then only return the cached value.
+ *
+ * @remarks
+ * Use {@link Delay#isRealized} to check if the function result is already
+ * available (i.e. if the function has already been called).
+ *
+ * @example
+ * ```ts tangle:../export/delay.ts
+ * import { delay } from "@thi.ng/memoize";
+ *
+ * const a = delay(() => {
+ *   console.log("calculating answer...");
+ *   return 42;
+ * });
+ *
+ * // the function will only be called now (and once)
+ * console.log("first:", a.deref());
+ * // calculating answer...
+ * // first: 42
+ *
+ * // now only returns cached result
+ * console.log("second:", a.deref());
+ * // second: 42
+ * ```
+ *
+ * @param body
+ */
+export declare const delay: <T>(body: Fn0<T>) => Delay<T>;
+export declare class Delay<T> implements IDeref<T> {
+    protected value: T;
+    protected body: Fn0<T>;
+    protected realized: boolean;
+    constructor(body: Fn0<T>);
+    deref(): T;
+    isRealized(): boolean;
+}
+//# sourceMappingURL=delay.d.ts.map

package/delay.js

@@ -0,0 +1,24 @@
+const delay = (body) => new Delay(body);
+class Delay {
+  value;
+  body;
+  realized;
+  constructor(body) {
+    this.body = body;
+    this.realized = false;
+  }
+  deref() {
+    if (!this.realized) {
+      this.value = this.body();
+      this.realized = true;
+    }
+    return this.value;
+  }
+  isRealized() {
+    return this.realized;
+  }
+}
+export {
+  Delay,
+  delay
+};

package/do-once.js

@@ -1,11 +1,8 @@
-const doOnce = (fn, cache) => {
-  !cache && (cache = /* @__PURE__ */ new Map());
-  return (x) => {
-    if (!cache.has(x)) {
-      cache.set(x, true);
-      fn(x);
-    }
-  };
+const doOnce = (fn, cache = /* @__PURE__ */ new Map()) => (x) => {
+  if (!cache.has(x)) {
+    cache.set(x, true);
+    fn(x);
+  }
 };
 export {
   doOnce

package/index.d.ts

@@ -1,7 +1,9 @@
 export * from "./api.js";
 export * from "./defonce.js";
+export * from "./delay.js";
 export * from "./do-once.js";
 export * from "./memoize.js";
 export * from "./memoize1.js";
 export * from "./memoizej.js";
+export * from "./memoizeo.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,8 @@
 export * from "./api.js";
 export * from "./defonce.js";
+export * from "./delay.js";
 export * from "./do-once.js";
 export * from "./memoize.js";
 export * from "./memoize1.js";
 export * from "./memoizej.js";
+export * from "./memoizeo.js";

package/memoize.d.ts

@@ -6,10 +6,13 @@ import type { MapLike } from "./api.js";
  * memoized result of given args. Supports generics for up to 4 args (otherwise
  * untyped).
  *
+ * @remarks
  * **Important:** It only makes sense to use `Map` types which support value
  * (rather than object) equality, e.g. those provided by
  * [`thi.ng/associative`](https://thi.ng/associative). Using a native `Map` type
- * here will lead to memory leaks! Alternatively, use {@link memoizeJ}.
+ * here will lead to memory leaks!
+ *
+ * Also see {@link memoizeJ}, {@link memoize1}, {@link memoizeO}.
  *
  * @param fn -
  * @param cache -

package/memoize1.d.ts

@@ -1,11 +1,16 @@
 import type { Fn } from "@thi.ng/api";
 import type { MapLike } from "./api.js";
 /**
- * Optimized memoization for single arg functions. If the function expects args
- * other than strings or numbers, you MUST provide a `Map` implementation which
- * supports value (rather than object) equality, e.g. one of those provided by
+ * Optimized memoization for single arg functions.
+ *
+ * @remarks
+ * If the function expects args other than strings or numbers, you MUST provide
+ * a `Map` implementation which supports value (rather than object) equality,
+ * e.g. one of those provided by
  * [`thi.ng/associative`](https://thi.ng/associative). Using a native `Map` type
- * here will lead to memory leaks! Alternatively, use {@link memoizeJ}.
+ * here will lead to memory leaks!
+ *
+ * Also see {@link memoizeO}, {@link memoizeJ}, {@link memoize}.
  *
  * @param fn -
  * @param cache -

package/memoize1.js

@@ -1,9 +1,6 @@
-const memoize1 = (fn, cache) => {
-  !cache && (cache = /* @__PURE__ */ new Map());
-  return (x) => {
-    let res;
-    return cache.has(x) ? cache.get(x) : (cache.set(x, res = fn(x)), res);
-  };
+const memoize1 = (fn, cache = /* @__PURE__ */ new Map()) => (x) => {
+  let res;
+  return cache.has(x) ? cache.get(x) : (cache.set(x, res = fn(x)), res);
 };
 export {
   memoize1

package/memoizej.d.ts

@@ -5,9 +5,12 @@ import type { Fn, Fn2, Fn3, Fn4, IObjectOf } from "@thi.ng/api";
  * memoized result for given args. Supports generics for up to 4 args
  * (otherwise untyped).
  *
+ * @remarks
  * **Important:** If the given args cannot be stringified, the user
  * function will ALWAYS be called (without caching result).
  *
+ * Also see {@link memoize}, {@link memoize1}, {@link memoizeO}.
+ *
  * @param fn -
  * @param cache -
  */

package/memoizej.js

@@ -1,5 +1,4 @@
-function memoizeJ(fn, cache) {
-  !cache && (cache = {});
+function memoizeJ(fn, cache = /* @__PURE__ */ Object.create(null)) {
   return (...args) => {
     const key = JSON.stringify(args);
     if (key !== void 0) {

package/memoizeo.d.ts

@@ -0,0 +1,53 @@
+import type { Fn, Fn2, Fn3, Fn4, 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.
+ *
+ * @remarks
+ * Also see {@link memoize1}, {@link memoizeJ}, {@link memoize}.
+ *
+ * @example
+ * ```ts tangle:../export/memoizeo.ts
+ * import { memoizeO } from "@thi.ng/memoize";
+ *
+ * const test = memoizeO((x: number) => (console.log("exec", x), x * 10));
+ *
+ * console.log(test(1));
+ * // exec 1
+ * // 10
+ *
+ * console.log(test(1))
+ * // 10
+ *
+ * console.log(test(2));
+ * // exec 2
+ * // 20
+ * ```
+ *
+ * @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;
+/**
+ * Like {@link memoizeO}, but for functions with 3 arguments.
+ *
+ * @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.
+ *
+ * @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;
+//# sourceMappingURL=memoizeo.d.ts.map

package/memoizeo.js

@@ -0,0 +1,19 @@
+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);
+};
+export {
+  memoize2O,
+  memoize3O,
+  memoize4O,
+  memoizeO
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/memoize",
-  "version": "3.1.65",
+  "version": "3.3.0",
   "description": "Function memoization with configurable caching",
   "type": "module",
   "module": "./index.js",
@@ -36,14 +36,14 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.30"
+    "@thi.ng/api": "^8.10.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.42.3",
-    "esbuild": "^0.20.1",
+    "@microsoft/api-extractor": "^7.43.0",
+    "esbuild": "^0.20.2",
     "rimraf": "^5.0.5",
     "typedoc": "^0.25.12",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.3"
   },
   "keywords": [
     "cache",
@@ -71,6 +71,9 @@
     "./defonce": {
       "default": "./defonce.js"
     },
+    "./delay": {
+      "default": "./delay.js"
+    },
     "./do-once": {
       "default": "./do-once.js"
     },
@@ -82,6 +85,9 @@
     },
     "./memoizej": {
       "default": "./memoizej.js"
+    },
+    "./memoizeo": {
+      "default": "./memoizeo.js"
     }
   },
   "thi.ng": {
@@ -90,5 +96,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "7f3fcbd6c0462b0ce45afa141fe163d1f297fd51\n"
+  "gitHead": "85ac4bd4d6d89f8e3689e2863d5bea0cecdb371c\n"
 }