@thi.ng/resolve-map 6.1.2 → 7.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-06-09T16:14:01Z
+- **Last updated**: 2022-07-12T19:50:54Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,34 @@ 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.
 
+## [7.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@7.1.0) (2022-07-12)
+
+#### 🚀 Features
+
+- add `onlyFnRefs` option ([a23fc98](https://github.com/thi-ng/umbrella/commit/a23fc98))
+
+# [7.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@7.0.0) (2022-07-07)
+
+#### 🛑 Breaking changes
+
+- add ResolveOpts, conditional unwrapping ([a23308b](https://github.com/thi-ng/umbrella/commit/a23308b))
+- BREAKING CHANGE: update resolve() signature, use new `ResolveOpts`
+  - this change has only downstream impact on use cases requiring custom
+  prefixes to indicate lookup paths
+  - add new option to control value unwrapping in final result
+  - update docs/readme
+  - add new tests
+
+## [6.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@6.2.0) (2022-07-07)
+
+#### 🚀 Features
+
+- unwrap all resolved() values in result ([888fa33](https://github.com/thi-ng/umbrella/commit/888fa33))
+  - add unwrapResolved() to unwrap any values wrapped via `resolved()`
+  - update resolveMap/Array()
+  - update doc strings
+  - update tests
+
 ## [6.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/resolve-map@6.1.0) (2022-05-23)
 
 #### 🚀 Features

package/README.md

@@ -76,7 +76,7 @@ node --experimental-repl-await
 > const resolveMap = await import("@thi.ng/resolve-map");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.03 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.13 KB
 
 ## Dependencies
 
@@ -237,7 +237,7 @@ resolve({ a: 1, b: { c: "@d", d: "@/a"} })
 // { a: 1, b: { c: 1, d: 1 } }
 
 // same with custom lookup prefix
-resolve({ a: 1, b: { c: ">>>d", d: ">>>/a"} }, ">>>")
+resolve({ a: 1, b: { c: ">>>d", d: ">>>/a"} }, { prefix: ">>>" })
 // { a: 1, b: { c: 1, d: 1 } }
 ```
 
@@ -256,8 +256,8 @@ the 2nd (legacy) form. Also, 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
+The `resolve` function provided as arg to the user function accepts a path
+(**without `@` (or custom) prefix**) to look up any other values in the root
 object.
 
 ```ts
@@ -302,10 +302,37 @@ res.e(2);
 
 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.
+By default, these wrapped values are only used during the resolution phase and
+the final result object/array will only contain the original, unwrapped values.
+Unwrapped values will also be supplied to any lookup functions, no
+[`.deref()`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) necessary
+there.
+
+```ts
+resolve({ a: 42, b: ({a}) => resolved(a) });
+// { a: 42, b: 42 }
+
+const res = resolve({ a: 42, b: ({a}) => resolved(a) }, { unwrap: false });
+// { a: 42, b: Resolved { _value: 42 } }
+
+// obtain b's value via .deref()
+res.b.deref()
+// 42
+```
+
+Since v7.1.0 a new `onlyFnRefs` option has been added which changes the
+resolution behavior to **not** consider string values for resolution at all
+anymore and instead requires the use of function values to trigger resolution.
+
+```ts
+// default behavior
+resolve({ a: "@c", b: ({a}) => a, c: 42 })
+// { a: 42, b: 42, c: 42 }
+
+// with option enabled
+resolve({ a: "@c", b: ({a}) => a, c: 42 }, { onlyFnRefs: true })
+// { a: '@c', b: '@c', c: 42 }
+```
 
 ## Authors
 

package/index.d.ts

@@ -4,6 +4,27 @@ export declare type Unresolved<T> = {
 };
 export declare type ResolveFn = (path: string) => any;
 export declare type LookupPath = NumOrString[];
+export interface ResolveOpts {
+    /**
+     * Prefix for auto-recognizing & interpreting embedded string values as
+     * lookup paths (only if {@link ResolveOpts.onlyFnRefs} is false, default)
+     *
+     * @defaultValue `@`
+     */
+    prefix: string;
+    /**
+     * If true (default), all known values wrapped using {@link resolved} will
+     * be unwrapped in the final result.
+     *
+     * @defaultValue true
+     */
+    unwrap: boolean;
+    /**
+     * If true, only function values (not strings!) will be considered for
+     * resolution.
+     */
+    onlyFnRefs: boolean;
+}
 /**
  * Visits all key-value pairs or array items in depth-first order, expands any
  * reference values, mutates the original object and returns it. Cyclic
@@ -19,10 +40,17 @@ 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.
+ * Values can be protected from (further) resolution attempts in two ways:
+ *
+ * 1) by wrapping them via {@link resolved}. By default (unless `unwrap` is set
+ *    to `false`), these wrapped values are only used during the resolution
+ *    phase and the final result object/array will only contain the original,
+ *    unwrapped values. In any way, unwrapped values will also be supplied to
+ *    any lookup functions, no `.deref()` necessary there.
+ * 2) Enabling the `onlyFnRefs` option, only function values will be considered
+ *    for resolution and strings (regardless of prefix) will be ignored.
+ *
+ * See {@link ResolveOpts} and package readme for further details.
  *
  * @example
  * ```ts
@@ -88,10 +116,10 @@ export declare type LookupPath = NumOrString[];
  * ```
  *
  * @param root -
- * @param prefix -
+ * @param opts -
  */
-export declare function resolve<T>(root: Unresolved<T>, prefix?: string): T;
-export declare function resolve<T>(root: Unresolved<T[]>, prefix?: string): T[];
+export declare function resolve<T>(root: Unresolved<T>, opts?: Partial<ResolveOpts>): T;
+export declare function resolve<T>(root: Unresolved<T[]>, opts?: Partial<ResolveOpts>): T[];
 /**
  * Takes the path for the current key and a lookup path string. Converts
  * the possibly relative lookup path into its absolute form.

package/index.js

@@ -7,28 +7,33 @@ import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { mutInUnsafe } from "@thi.ng/paths/mut-in";
 import { exists } from "@thi.ng/paths/path";
 const RE_ARGS = /^(function\s+\w+)?\s*\(\{([\w\s,:]+)\}/;
-export function resolve(root, prefix = "@") {
-    if (isPlainObject(root)) {
-        return resolveMap(root, prefix);
-    }
-    else if (isArray(root)) {
-        return resolveArray(root, prefix);
-    }
-    return root;
+export function resolve(root, opts) {
+    const $opts = { prefix: "@", unwrap: true, ...opts };
+    return isPlainObject(root)
+        ? resolveMap(root, $opts)
+        : isArray(root)
+            ? resolveArray(root, $opts)
+            : root;
 }
-const resolveMap = (obj, prefix, root, path = [], resolved = {}, stack = []) => {
+/** @internal */
+const resolveMap = (obj, opts, root, path = [], resolved = {}, stack = []) => {
     root = root || obj;
     for (let k in obj) {
-        _resolve(root, [...path, k], resolved, stack, prefix);
+        _resolve(root, [...path, k], resolved, stack, opts);
     }
-    return obj;
+    return !opts.unwrap || path.length
+        ? obj
+        : unwrapResolved(obj, resolved);
 };
-const resolveArray = (arr, prefix, root, path = [], resolved = {}, stack = []) => {
+/** @internal */
+const resolveArray = (arr, opts, root, path = [], resolved = {}, stack = []) => {
     root = root || arr;
     for (let k = 0, n = arr.length; k < n; k++) {
-        _resolve(root, [...path, k], resolved, stack, prefix);
+        _resolve(root, [...path, k], resolved, stack, opts);
     }
-    return arr;
+    return !opts.unwrap || path.length
+        ? arr
+        : unwrapResolved(arr, resolved);
 };
 /**
  * The actual recursive resolution mechanism. Takes root object, key
@@ -40,8 +45,10 @@ const resolveArray = (arr, prefix, root, path = [], resolved = {}, stack = []) =
  * @param path -
  * @param resolved -
  * @param stack -
+ *
+ * @internal
  */
-const _resolve = (root, path, resolved, stack, prefix) => {
+const _resolve = (root, path, resolved, stack, opts) => {
     const pathID = path.join("/");
     if (stack.indexOf(pathID) >= 0) {
         illegalArgs(`cyclic references not allowed: ${pathID}`);
@@ -56,19 +63,21 @@ const _resolve = (root, path, resolved, stack, prefix) => {
         let res = SEMAPHORE;
         stack.push(pathID);
         if (isPlainObject(v)) {
-            resolveMap(v, prefix, root, path, resolved, stack);
+            resolveMap(v, { ...opts, unwrap: false }, root, path, resolved, stack);
         }
         else if (isArray(v)) {
-            resolveArray(v, prefix, root, path, resolved, stack);
+            resolveArray(v, { ...opts, unwrap: false }, root, path, resolved, stack);
         }
-        else if (isString(v) && v.startsWith(prefix)) {
-            res = _resolve(root, absPath(path, v, prefix.length), resolved, stack, prefix);
+        else if (!opts.onlyFnRefs &&
+            isString(v) &&
+            v.startsWith(opts.prefix)) {
+            res = _resolve(root, absPath(path, v, opts.prefix.length), resolved, stack, opts);
         }
         else if (isFunction(v)) {
-            res = resolveFunction(v, (p) => _resolve(root, absPath(path, p, 0), resolved, stack, prefix), pathID, resolved);
+            res = resolveFunction(v, (p) => _resolve(root, absPath(path, p, 0), resolved, stack, opts), pathID, resolved);
         }
         else if (!exists(root, path)) {
-            v = resolvePath(root, path, resolved, stack, prefix);
+            v = resolvePath(root, path, resolved, stack, opts);
         }
         if (res !== SEMAPHORE) {
             mutInUnsafe(root, path, res);
@@ -95,13 +104,15 @@ const _resolve = (root, path, resolved, stack, prefix) => {
  * @param root -
  * @param path -
  * @param resolved -
+ *
+ * @internal
  */
-const resolvePath = (root, path, resolved, stack, prefix) => {
+const resolvePath = (root, path, resolved, stack, opts) => {
     // temporarily remove current path to avoid cycle detection
     let pathID = stack.pop();
     let v;
     for (let i = 1, n = path.length; i <= n; i++) {
-        v = _resolve(root, path.slice(0, i), resolved, stack, prefix);
+        v = _resolve(root, path.slice(0, i), resolved, stack, opts);
     }
     // restore
     stack.push(pathID);
@@ -123,6 +134,8 @@ const resolvePath = (root, path, resolved, stack, prefix) => {
  * @param resolve -
  * @param pathID - current base path for marking
  * @param resolved -
+ *
+ * @internal
  */
 const resolveFunction = (fn, resolve, pathID, resolved) => {
     const match = RE_ARGS.exec(fn.toString());
@@ -142,6 +155,7 @@ const resolveFunction = (fn, resolve, pathID, resolved) => {
     markResolved(res, pathID, resolved);
     return res;
 };
+/** @internal */
 const markResolved = (v, path, resolved) => {
     resolved[path] = true;
     if (isPlainObject(v)) {
@@ -151,6 +165,7 @@ const markResolved = (v, path, resolved) => {
         markArrayResolved(v, path, resolved);
     }
 };
+/** @internal */
 const markObjResolved = (obj, path, resolved) => {
     let v, p;
     for (let k in obj) {
@@ -159,6 +174,7 @@ const markObjResolved = (obj, path, resolved) => {
         markResolved(v, p, resolved);
     }
 };
+/** @internal */
 const markArrayResolved = (arr, path, resolved) => {
     let v, p;
     for (let i = 0, n = arr.length; i < n; i++) {
@@ -237,3 +253,19 @@ const getInUnsafe = (obj, path) => {
     }
     return [res, isResolved];
 };
+/**
+ * Unwraps all known values wrapped using {@link Resolved} in-place.
+ *
+ * @param root
+ * @param resolved
+ *
+ * @internal
+ */
+const unwrapResolved = (root, resolved) => {
+    for (let path in resolved) {
+        const $path = path.split("/");
+        const val = getInUnsafe(root, $path);
+        val[1] && mutInUnsafe(root, $path, val[0]);
+    }
+    return root;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/resolve-map",
-  "version": "6.1.2",
+  "version": "7.1.0",
   "description": "DAG resolution of vanilla objects & arrays with internally linked values",
   "type": "module",
   "module": "./index.js",
@@ -76,5 +76,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "ab0188234419f2d9f471de80871df930e5555bd6\n"
+  "gitHead": "21abd94ba9e13d4636f3e9a85d3a7d4e9ea269ba\n"
 }