@thi.ng/resolve-map 6.0.1 → 6.1.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-05-07T11:33:35Z
+- **Last updated**: 2022-06-09T16:14:01Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ 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.
 
+## [6.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@6.1.0) (2022-05-23)
+
+#### 🚀 Features
+
+- add support for protected values ([6280510](https://github.com/thi-ng/umbrella/commit/6280510))
+  - add `Resolved` wrapper & factory fn for protecting values from
+    future/duplicate resolution attempts
+  - add tests
+  - update docs/readme
+
 # [6.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@6.0.0) (2022-05-02)
 
 #### 🛑 Breaking changes

package/README.md

@@ -19,6 +19,7 @@ This project is part of the
   - [Theme configuration](#theme-configuration)
 - [API](#api)
   - [`resolve(obj)`](#resolveobj)
+    - [Protecting values](#protecting-values)
 - [Authors](#authors)
 - [License](#license)
 
@@ -75,7 +76,7 @@ node --experimental-repl-await
 > const resolveMap = await import("@thi.ng/resolve-map");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 929 bytes
+Package sizes (gzipped, pre-treeshake): ESM: 1.03 KB
 
 ## Dependencies
 
@@ -297,6 +298,15 @@ res.e(2);
 // 20
 ```
 
+#### Protecting values
+
+Values can be protected from further resolution attempts by wrapping them via
+[`resolved()`](https://docs.thi.ng/umbrella/resolve-map/modules.html#resolved).
+The wrapped value can be later obtained via the standard [`IDeref`
+interface/mechanism](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html).
+In lookup/resolution functions, the unwrapped value will be supplied, no
+`.deref()` necessary there.
+
 ## Authors
 
 Karsten Schmidt

package/index.d.ts

@@ -1,6 +1,6 @@
-import type { Fn, NumOrString } from "@thi.ng/api";
+import type { Fn, IDeref, NumOrString } from "@thi.ng/api";
 export declare type Unresolved<T> = {
-    [K in keyof T]: Unresolved<T[K]> | Fn<T, T[K]> | Fn<ResolveFn, T[K]> | Function | string;
+    [K in keyof T]: Unresolved<T[K]> | Resolved<T[K]> | Fn<T, T[K]> | Fn<ResolveFn, T[K]> | Function | string;
 };
 export declare type ResolveFn = (path: string) => any;
 export declare type LookupPath = NumOrString[];
@@ -19,6 +19,11 @@ export declare type LookupPath = NumOrString[];
  * access any parent levels. Absolute refs are always resolved from the root
  * level (the original object passed to this function).
  *
+ * Values can be protected from further resolution attempts by wrapping them via
+ * {@link resolved}. The wrapped value can be later obtained via the standard
+ * {@link @thi.ng/api#IDeref} interface/mechanism. In lookup functions, the
+ * unwrapped value will be supplied, no `.deref()` necessary there.
+ *
  * @example
  * ```ts
  * // `c` references sibling `d`
@@ -96,4 +101,22 @@ export declare function resolve<T>(root: Unresolved<T[]>, prefix?: string): T[];
  * @param idx -
  */
 export declare const absPath: (curr: LookupPath, path: string, idx?: number) => NumOrString[];
+/**
+ * Value wrapper to protect from future recursive resolution attempts. See
+ * {@link resolved} for further details.
+ */
+export declare class Resolved<T> implements IDeref<T> {
+    protected _value: T;
+    constructor(_value: T);
+    deref(): T;
+}
+/**
+ * Factory function for {@link Resolved} to wrap & protect values from further
+ * resolution attempts. The wrapped value can be later obtained via the standard
+ * {@link @thi.ng/api#IDeref} interface/mechanism. In lookup functions, the
+ * unwrapped value will be supplied, no `.deref()` necessary there.
+ *
+ * @param val
+ */
+export declare const resolved: <T>(val: T) => Resolved<T>;
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -4,7 +4,6 @@ import { isFunction } from "@thi.ng/checks/is-function";
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { isString } from "@thi.ng/checks/is-string";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
-import { getInUnsafe } from "@thi.ng/paths/get-in";
 import { mutInUnsafe } from "@thi.ng/paths/mut-in";
 import { exists } from "@thi.ng/paths/path";
 const RE_ARGS = /^(function\s+\w+)?\s*\(\{([\w\s,:]+)\}/;
@@ -48,8 +47,12 @@ const _resolve = (root, path, resolved, stack, prefix) => {
         illegalArgs(`cyclic references not allowed: ${pathID}`);
     }
     // console.log(pp, resolved[pp], stack);
-    let v = getInUnsafe(root, path);
+    let [v, isResolved] = getInUnsafe(root, path);
     if (!resolved[pathID]) {
+        if (isResolved) {
+            resolved[pathID] = true;
+            return v;
+        }
         let res = SEMAPHORE;
         stack.push(pathID);
         if (isPlainObject(v)) {
@@ -190,3 +193,47 @@ export const absPath = (curr, path, idx = 1) => {
     !curr.length && illegalArgs(`invalid lookup path: ${path}`);
     return curr;
 };
+/**
+ * Value wrapper to protect from future recursive resolution attempts. See
+ * {@link resolved} for further details.
+ */
+export class Resolved {
+    constructor(_value) {
+        this._value = _value;
+    }
+    deref() {
+        return this._value;
+    }
+}
+/**
+ * Factory function for {@link Resolved} to wrap & protect values from further
+ * resolution attempts. The wrapped value can be later obtained via the standard
+ * {@link @thi.ng/api#IDeref} interface/mechanism. In lookup functions, the
+ * unwrapped value will be supplied, no `.deref()` necessary there.
+ *
+ * @param val
+ */
+export const resolved = (val) => new Resolved(val);
+/**
+ * Special version of {@link @thi.ng/paths#getInUnsafe} with extra support for
+ * intermediate wrapped {@link Resolved} values and returning tuple of:
+ * `[val,isResolved]`.
+ *
+ * @param obj
+ * @param path
+ *
+ * @internal
+ */
+const getInUnsafe = (obj, path) => {
+    const n = path.length - 1;
+    let res = obj;
+    let isResolved = obj instanceof Resolved;
+    for (let i = 0; res != null && i <= n; i++) {
+        res = res[path[i]];
+        if (res instanceof Resolved) {
+            isResolved = true;
+            res = res.deref();
+        }
+    }
+    return [res, isResolved];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/resolve-map",
-  "version": "6.0.1",
+  "version": "6.1.2",
   "description": "DAG resolution of vanilla objects & arrays with internally linked values",
   "type": "module",
   "module": "./index.js",
@@ -34,18 +34,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.3.6",
-    "@thi.ng/checks": "^3.1.6",
-    "@thi.ng/errors": "^2.1.6",
-    "@thi.ng/paths": "^5.1.6"
+    "@thi.ng/api": "^8.3.7",
+    "@thi.ng/checks": "^3.2.1",
+    "@thi.ng/errors": "^2.1.7",
+    "@thi.ng/paths": "^5.1.8"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.23.1",
-    "@thi.ng/testament": "^0.2.6",
+    "@microsoft/api-extractor": "^7.25.0",
+    "@thi.ng/testament": "^0.2.8",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.15",
-    "typescript": "^4.6.4"
+    "typedoc": "^0.22.17",
+    "typescript": "^4.7.3"
   },
   "keywords": [
     "configuration",
@@ -76,5 +76,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "cf084be5fd5932226054d2dd32bad35481379f5d\n"
+  "gitHead": "ab0188234419f2d9f471de80871df930e5555bd6\n"
 }