@thi.ng/resolve-map 5.1.5 → 6.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-04-07T14:17:30Z
+- **Last updated**: 2022-05-23T11:18:39Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,25 @@ 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
+
+- add `Unresolved` type & type checking ([a997fd2](https://github.com/thi-ng/umbrella/commit/a997fd2))
+- BREAKING CHANGE: add type checking to `resolve()`.
+  This MIGHT require additional type generics (of the result object type)
+  to be added to any call sites. See tests for examples.
+
 ### [5.1.5](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@5.1.5) (2022-04-07)
 
 #### ♻️ Refactoring

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: 922 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,4 +1,7 @@
-import type { 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]> | 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[];
 /**
@@ -7,6 +10,7 @@ export declare type LookupPath = NumOrString[];
  * references are not allowed and will throw an error. However, refs pointing to
  * other refs are recursively resolved (again, provided there are no cycles).
  *
+ * @remarks
  * Reference values are special strings representing lookup paths of other
  * values in the object and are prefixed with given `prefix` string (default:
  * `@`) for relative refs or `@/` for absolute refs and both using `/` as path
@@ -15,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`
@@ -81,7 +90,8 @@ export declare type LookupPath = NumOrString[];
  * @param root -
  * @param prefix -
  */
-export declare const resolve: (root: any, prefix?: string) => any;
+export declare function resolve<T>(root: Unresolved<T>, prefix?: string): T;
+export declare function resolve<T>(root: Unresolved<T[]>, prefix?: string): T[];
 /**
  * Takes the path for the current key and a lookup path string. Converts
  * the possibly relative lookup path into its absolute form.
@@ -91,4 +101,22 @@ export declare const resolve: (root: any, prefix?: string) => any;
  * @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,91 +4,10 @@ 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,:]+)\}/;
-/**
- * Visits all key-value pairs or array items in depth-first order, expands any
- * reference values, mutates the original object and returns it. Cyclic
- * references are not allowed and will throw an error. However, refs pointing to
- * other refs are recursively resolved (again, provided there are no cycles).
- *
- * Reference values are special strings representing lookup paths of other
- * values in the object and are prefixed with given `prefix` string (default:
- * `@`) for relative refs or `@/` for absolute refs and both using `/` as path
- * separator (Note: trailing slashes are NOT allowed!). Relative refs are
- * resolved from the currently visited object and support "../" prefixes to
- * access any parent levels. Absolute refs are always resolved from the root
- * level (the original object passed to this function).
- *
- * @example
- * ```ts
- * // `c` references sibling `d`
- * // `d` references parent `a`
- * resolve({ a: 1, b: { c: "@d", d: "@/a" } })
- * // { a: 1, b: { c: 1, d: 1 } }
- * ```
- *
- * Any function values are called using two possible conventions:
- *
- * 1) If the user function uses ES6 object destructuring for its first
- *    argument, the given object keys are resolved prior to calling the
- *    function and the resolved values provided as first argument
- *    (object) and a general `resolve` function as second argument.
- * 2) If no de-structure form is found in the function's arguments, the
- *    function is only called with `resolve` as argument.
- *
- * **Important:** Since ES6 var names can't contain special characters,
- * destructured keys can ALWAYS only be looked up as siblings of the
- * currently processed key.
- *
- * The `resolve` function provided as arg to the user function accepts a
- * path (**without `@` prefix**) to look up any other values in the root
- * object.
- *
- * ```
- * // `c` uses ES6 destructuring form to look up `a` & `b` values
- * // `d` uses provided resolve fn arg `$` to look up `c`
- * resolve({ a: 1, b: 2, c: ({ a, b }) => a + b, d: ($) => $("c") })
- * // { a: 1, b: 2, c: 3, d: 3 }
- *
- * // last item references item @ index = 2
- * resolve([1, 2, ($) => $("0") + $("1"), "@2"])
- * // [1, 2, 3, 3]
- * ```
- *
- * The return value of the user provided function is used as final value
- * for that key in the object. This mechanism can be used to compute
- * derived values of other values stored anywhere in the root object.
- * **Function values will always be called only once.** Therefore, in
- * order to associate a function as final value to a key, it MUST be
- * wrapped with an additional function, as shown for the `e` key in the
- * example below. Similarly, if an actual string value should happen to
- * start with `@`, it needs to be wrapped in a function (see `f` key
- * below).
- *
- * ```
- * // `a` is derived from 1st array element in `b.d`
- * // `b.c` is looked up from `b.d[0]`
- * // `b.d[1]` is derived from calling `e(2)`
- * // `e` is a wrapped function
- * res = resolve({
- *   a: ($) => $("b/c") * 100,
- *   b: { c: "@d/0", d: [2, ($) => $("../../e")(2) ] },
- *   e: () => (x) => x * 10,
- *   f: () => "@foo",
- * })
- * // { a: 200, b: { c: 2, d: [ 2, 20 ] }, e: [Function], f: "@foo" }
- *
- * res.e(2);
- * // 20
- * ```
- *
- * @param root -
- * @param prefix -
- */
-export const resolve = (root, prefix = "@") => {
+export function resolve(root, prefix = "@") {
     if (isPlainObject(root)) {
         return resolveMap(root, prefix);
     }
@@ -96,7 +15,7 @@ export const resolve = (root, prefix = "@") => {
         return resolveArray(root, prefix);
     }
     return root;
-};
+}
 const resolveMap = (obj, prefix, root, path = [], resolved = {}, stack = []) => {
     root = root || obj;
     for (let k in obj) {
@@ -128,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)) {
@@ -270,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": "5.1.5",
+  "version": "6.1.0",
   "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.5",
-    "@thi.ng/checks": "^3.1.5",
-    "@thi.ng/errors": "^2.1.5",
-    "@thi.ng/paths": "^5.1.5"
+    "@thi.ng/api": "^8.3.6",
+    "@thi.ng/checks": "^3.1.6",
+    "@thi.ng/errors": "^2.1.6",
+    "@thi.ng/paths": "^5.1.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.19.4",
-    "@thi.ng/testament": "^0.2.5",
+    "@microsoft/api-extractor": "^7.23.1",
+    "@thi.ng/testament": "^0.2.7",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.13",
-    "typescript": "^4.6.2"
+    "typedoc": "^0.22.15",
+    "typescript": "^4.6.4"
   },
   "keywords": [
     "configuration",
@@ -76,5 +76,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "5ee1feb590dd935593b1dd4e7f38a3ed3ba64765\n"
+  "gitHead": "0b6722006c2abbd917f115be290402c380fec87b\n"
 }