@thi.ng/resolve-map 5.1.5 → 6.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-04-07T14:17:30Z
+- **Last updated**: 2022-05-02T11:57:05Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.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/index.d.ts

@@ -1,4 +1,7 @@
-import type { NumOrString } from "@thi.ng/api";
+import type { Fn, 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;
+};
 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
@@ -81,7 +85,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.

package/index.js

@@ -8,87 +8,7 @@ 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 +16,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) {

package/package.json

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