@thi.ng/memoize 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-27T09:53:45Z
+- **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,19 @@ 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

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: 334 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 518 bytes
 
 ## Dependencies
 

package/defonce.d.ts

@@ -17,5 +17,7 @@ import type { Fn0 } from "@thi.ng/api";
  * @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 = /* @__PURE__ */ Object.create(null);
-const defonce = (id, factory) => id in cache ? cache[id] : cache[id] = factory();
+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/index.d.ts

@@ -1,5 +1,6 @@
 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";

package/index.js

@@ -1,5 +1,6 @@
 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";

package/memoizeo.d.ts

@@ -8,7 +8,7 @@ import type { Fn, Fn2, Fn3, Fn4, NumOrString } from "@thi.ng/api";
  * Also see {@link memoize1}, {@link memoizeJ}, {@link memoize}.
  *
  * @example
- * ```ts tangle:../../export/memoizeo.ts
+ * ```ts tangle:../export/memoizeo.ts
  * import { memoizeO } from "@thi.ng/memoize";
  *
  * const test = memoizeO((x: number) => (console.log("exec", x), x * 10));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/memoize",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Function memoization with configurable caching",
   "type": "module",
   "module": "./index.js",
@@ -36,7 +36,7 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.31"
+    "@thi.ng/api": "^8.10.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.43.0",
@@ -71,6 +71,9 @@
     "./defonce": {
       "default": "./defonce.js"
     },
+    "./delay": {
+      "default": "./delay.js"
+    },
     "./do-once": {
       "default": "./do-once.js"
     },
@@ -93,5 +96,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "feb3b24654f2c931cd3c3308c1c0c807ee14d0e4\n"
+  "gitHead": "85ac4bd4d6d89f8e3689e2863d5bea0cecdb371c\n"
 }