@thi.ng/resolve-map 6.2.0 → 7.1.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-07-07T12:39:33Z
+- **Last updated**: 2022-07-19T15:36:12Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,24 @@ 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

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.08 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,12 +302,38 @@ 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).
-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
+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
 
 Karsten Schmidt

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,11 +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}. 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()` 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
@@ -89,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,30 +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;
 }
 /** @internal */
-const resolveMap = (obj, prefix, root, path = [], resolved = {}, stack = []) => {
+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 path.length ? obj : unwrapResolved(obj, resolved);
+    return !opts.unwrap || path.length
+        ? obj
+        : unwrapResolved(obj, resolved);
 };
 /** @internal */
-const resolveArray = (arr, prefix, root, path = [], resolved = {}, stack = []) => {
+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 path.length ? arr : unwrapResolved(arr, resolved);
+    return !opts.unwrap || path.length
+        ? arr
+        : unwrapResolved(arr, resolved);
 };
 /**
  * The actual recursive resolution mechanism. Takes root object, key
@@ -45,7 +48,7 @@ const resolveArray = (arr, prefix, root, path = [], resolved = {}, 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}`);
@@ -60,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);
@@ -102,12 +107,12 @@ const _resolve = (root, path, resolved, stack, prefix) => {
  *
  * @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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/resolve-map",
-  "version": "6.2.0",
+  "version": "7.1.1",
   "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.7",
-    "@thi.ng/checks": "^3.2.1",
-    "@thi.ng/errors": "^2.1.7",
-    "@thi.ng/paths": "^5.1.8"
+    "@thi.ng/api": "^8.3.8",
+    "@thi.ng/checks": "^3.2.2",
+    "@thi.ng/errors": "^2.1.8",
+    "@thi.ng/paths": "^5.1.9"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.25.0",
-    "@thi.ng/testament": "^0.2.8",
+    "@thi.ng/testament": "^0.2.9",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
-    "typescript": "^4.7.3"
+    "typescript": "^4.7.4"
   },
   "keywords": [
     "configuration",
@@ -76,5 +76,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "04acabdda49dfcfe8cdcf044401f25ce23c872d0\n"
+  "gitHead": "108a6357b77d457912d30681d7cc5603ae995209\n"
 }