@inox-tools/utils 0.1.4 → 0.3.0-beta.0

package/dist/lazy.js

@@ -1,5 +1,2 @@
-class a{constructor(i){this.factory=i;}initialized=!1;value;static of(i){return new this(i)}get(){return this.initialized||(this.value=this.factory(),this.initialized=!0),this.value}}
-
-export { a as Lazy };
-//# sourceMappingURL=lazy.js.map
+class a{constructor(i){this.factory=i;}initialized=!1;value;static of(i){return new this(i)}get(){return this.initialized||(this.value=this.factory(),this.initialized=!0),this.value}}export{a as Lazy};//# sourceMappingURL=lazy.js.map
 //# sourceMappingURL=lazy.js.map

package/dist/once.js

@@ -1,5 +1,2 @@
-class o{#i=!1;do(i){this.#i||(i(),this.#i=!0);}async doAsync(i){this.#i||(await i(),this.#i=!0);}}
-
-export { o as Once };
-//# sourceMappingURL=once.js.map
+class o{#i=!1;do(i){this.#i||(i(),this.#i=!0);}async doAsync(i){this.#i||(await i(),this.#i=!0);}}export{o as Once};//# sourceMappingURL=once.js.map
 //# sourceMappingURL=once.js.map

package/dist/types.js

@@ -1,3 +1,2 @@
-
 //# sourceMappingURL=types.js.map
 //# sourceMappingURL=types.js.map

package/dist/unist/visit.d.ts

@@ -0,0 +1,135 @@
+import * as unist_util_is from 'unist-util-is';
+import * as unist from 'unist';
+
+/**
+ * Continue traversing as normal.
+ */
+declare const CONTINUE = true;
+/**
+ * Stop traversing immediately.
+ */
+declare const EXIT = false;
+/**
+ * Do not traverse this node’s children.
+ */
+declare const SKIP = "skip";
+type Options<Tree extends unist.Node, Check extends Test> = {
+    tree: Tree;
+    test?: Check;
+    enter?: BuildVisitor<Tree, Check>;
+    leave?: BuildVisitor<Tree, Check>;
+    reverse?: boolean;
+};
+declare function visitParents<Tree extends unist.Node, Check extends Test>({ tree, test, enter: enterVisitor, leave: leaveVisitor, reverse, }: Options<Tree, Check>): void;
+type UnistNode = unist.Node;
+type UnistParent = unist.Parent;
+/**
+ * Test from `unist-util-is`.
+ *
+ * Note: we have remove and add `undefined`, because otherwise when generating
+ * automatic `.d.ts` files, TS tries to flatten paths from a local perspective,
+ * which doesn’t work when publishing on npm.
+ */
+type Test = Exclude<unist_util_is.Test, undefined> | undefined;
+/**
+ * Get the value of a type guard `Fn`.
+ */
+type Predicate<Fn, Fallback> = Fn extends (value: any) => value is infer Thing ? Thing : Fallback;
+/**
+ * Check whether a node matches a primitive check in the type system.
+ */
+type MatchesOne<Value, Check> = Check extends null | undefined ? Value : Value extends {
+    type: Check;
+} ? Value : Value extends Check ? Value : Check extends Function ? Predicate<Check, Value> extends Value ? Predicate<Check, Value> : never : never;
+/**
+ * Check whether a node matches a check in the type system.
+ */
+type Matches<Value, Check> = Check extends Array<any> ? MatchesOne<Value, Check[keyof Check]> : MatchesOne<Value, Check>;
+/**
+ * Number; capped reasonably.
+ */
+type Uint = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+/**
+ * Increment a number in the type system.
+ */
+type Increment<I extends Uint = 0> = I extends 0 ? 1 : I extends 1 ? 2 : I extends 2 ? 3 : I extends 3 ? 4 : I extends 4 ? 5 : I extends 5 ? 6 : I extends 6 ? 7 : I extends 7 ? 8 : I extends 8 ? 9 : 10;
+/**
+ * Collect nodes that can be parents of `Child`.
+ */
+type InternalParent<Node extends unist.Node, Child extends unist.Node> = Node extends unist.Parent ? Node extends {
+    children: (infer Children)[];
+} ? Child extends Children ? Node : never : never : never;
+/**
+ * Collect nodes in `Tree` that can be parents of `Child`.
+ */
+type Parent<Tree extends unist.Node, Child extends unist.Node> = InternalParent<InclusiveDescendant<Tree>, Child>;
+/**
+ * Collect nodes in `Tree` that can be ancestors of `Child`.
+ */
+type InternalAncestor<Node extends unist.Node, Child extends unist.Node, Max extends Uint = 10, Depth extends Uint = 0> = Depth extends Max ? never : InternalParent<Node, Child> | InternalAncestor<Node, InternalParent<Node, Child>, Max, Increment<Depth>>;
+/**
+ * Collect nodes in `Tree` that can be ancestors of `Child`.
+ */
+type Ancestor<Tree extends unist.Node, Child extends unist.Node> = InternalAncestor<InclusiveDescendant<Tree>, Child>;
+/**
+ * Collect all (inclusive) descendants of `Tree`.
+ *
+ * > 👉 **Note**: for performance reasons, this seems to be the fastest way to
+ * > recurse without actually running into an infinite loop, which the
+ * > previous version did.
+ * >
+ * > Practically, a max of `2` is typically enough assuming a `Root` is
+ * > passed, but it doesn’t improve performance.
+ * > It gets higher with `List > ListItem > Table > TableRow > TableCell`.
+ * > Using up to `10` doesn’t hurt or help either.
+ */
+type InclusiveDescendant<Tree extends unist.Node, Max extends Uint = 10, Depth extends Uint = 0> = Tree extends UnistParent ? Depth extends Max ? Tree : Tree | InclusiveDescendant<Tree['children'][number], Max, Increment<Depth>> : Tree;
+/**
+ * Union of the action types.
+ */
+type Action = 'skip' | boolean;
+/**
+ * Move to the sibling at `index` next (after node itself is completely
+ * traversed).
+ *
+ * Useful if mutating the tree, such as removing the node the visitor is
+ * currently on, or any of its previous siblings.
+ * Results less than 0 or greater than or equal to `children.length` stop
+ * traversing the parent.
+ */
+type Index = number;
+/**
+ * List with one or two values, the first an action, the second an index.
+ */
+type ActionTuple = [(Action | null | undefined | void)?, (Index | null | undefined)?];
+/**
+ * Any value that can be returned from a visitor.
+ */
+type VisitorResult = Action | [(void | Action | null | undefined)?, (number | null | undefined)?] | Index | null | undefined | void;
+/**
+ * Handle a node (matching `test`, if given).
+ *
+ * Visitors are free to transform `node`.
+ * They can also transform the parent of node (the last of `ancestors`).
+ *
+ * Replacing `node` itself, if `SKIP` is not returned, still causes its
+ * descendants to be walked (which is a bug).
+ *
+ * When adding or removing previous siblings of `node` (or next siblings, in
+ * case of reverse), the `Visitor` should return a new `Index` to specify the
+ * sibling to traverse after `node` is traversed.
+ * Adding or removing next siblings of `node` (or previous siblings, in case
+ * of reverse) is handled as expected without needing to return a new `Index`.
+ *
+ * Removing the children property of an ancestor still results in them being
+ * traversed.
+ */
+type Visitor<Visited extends unist.Node = unist.Node, VisitedParents extends unist.Parent = unist.Parent> = (node: Visited, ancestors: Array<VisitedParents>) => VisitorResult;
+/**
+ * Build a typed `Visitor` function from a tree and a test.
+ *
+ * It will infer which values are passed as `node` and which as `parents`.
+ */
+type BuildVisitor<Tree extends unist.Node = unist.Node, Check extends Test = Test> = Visitor<Matches<InclusiveDescendant<Tree>, Check>, Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>>;
+
+export { type Action, type ActionTuple, type Ancestor, type BuildVisitor, CONTINUE, EXIT, type InclusiveDescendant, type Increment, type Index, type InternalAncestor, type InternalParent, type Matches, type MatchesOne, type Options, type Parent, type Predicate, SKIP, type Test, type Uint, type UnistNode, type UnistParent, type Visitor, type VisitorResult, visitParents };

package/dist/unist/visit.js

@@ -0,0 +1,2 @@
+import {convert}from'unist-util-is';const a=[],A=!0,f=!1,P="skip";function M({tree:e,test:u,enter:l,leave:c,reverse:p}){if(!e)throw new TypeError("A tree is required");if(!l&&!c)throw new Error("At least one visitor (`enter` or `leave`) must be provided");const I=convert(u),x=p?-1:1;h(e,void 0,[])();function h(n,k,s){const d=n;if(typeof d.type=="string"){const t=typeof d.tagName=="string"?d.tagName:typeof d.name=="string"?d.name:void 0;Object.defineProperty(y,"name",{value:"node ("+n.type+(t?"<"+t+">":"")+")"});}return y;function y(){let t=a,o,i,T;const m=!u||I(n,k,s[s.length-1]);if(m&&(t=C(l?.(n,s)),t[0]===f))return t;if("children"in n&&n.children){const r=n;if(r.children&&t[0]!==P)for(i=(p?r.children.length:-1)+x,T=s.concat(r);i>-1&&i<r.children.length;){const N=r.children[i];if(o=h(N,i,T)(),o[0]===f)return o;i=typeof o[1]=="number"?o[1]:i+x;}}if(m&&c){const r=C(c(n,s));return r===a?t:r}return t}}}function C(e){return Array.isArray(e)?e:typeof e=="number"?[A,e]:e==null?a:[e]}export{A as CONTINUE,f as EXIT,P as SKIP,M as visitParents};//# sourceMappingURL=visit.js.map
+//# sourceMappingURL=visit.js.map

package/dist/unist/visit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/unist/visit.ts"],"names":["empty","CONTINUE","EXIT","SKIP","visitParents","tree","test","enterVisitor","leaveVisitor","reverse","is","convert","step","factory","node","index","parents","value","name","visit","result","subresult","offset","grandparents","isMatch","toResult","nodeAsParent","child","leaveResult"],"mappings":"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","file":"visit.js","sourcesContent":["import { convert } from 'unist-util-is';\n\nconst empty: ActionTuple = [];\n\n/**\n * Continue traversing as normal.\n */\nexport const CONTINUE = true;\n\n/**\n * Stop traversing immediately.\n */\nexport const EXIT = false;\n\n/**\n * Do not traverse this node’s children.\n */\nexport const SKIP = 'skip';\n\nexport type Options<Tree extends import('unist').Node, Check extends Test> = {\n\ttree: Tree;\n\ttest?: Check;\n\tenter?: BuildVisitor<Tree, Check>;\n\tleave?: BuildVisitor<Tree, Check>;\n\treverse?: boolean;\n};\n\nexport function visitParents<Tree extends import('unist').Node, Check extends Test>({\n\ttree,\n\ttest,\n\tenter: enterVisitor,\n\tleave: leaveVisitor,\n\treverse,\n}: Options<Tree, Check>) {\n\tif (!tree) {\n\t\tthrow new TypeError('A tree is required');\n\t}\n\n\tif (!enterVisitor && !leaveVisitor) {\n\t\tthrow new Error('At least one visitor (`enter` or `leave`) must be provided');\n\t}\n\n\tconst is = convert(test) as (\n\t\tnode: UnistNode,\n\t\tindex?: number,\n\t\tparent?: UnistParent\n\t) => node is Matches<InclusiveDescendant<Tree>, Check>;\n\tconst step = reverse ? -1 : 1;\n\n\tfactory(tree, undefined, [])();\n\n\tfunction factory(node: UnistNode, index: number | undefined, parents: UnistParent[]) {\n\t\tconst value = node as UnistNode & Record<string, unknown>;\n\n\t\tif (typeof value.type === 'string') {\n\t\t\tconst name =\n\t\t\t\t// `hast`\n\t\t\t\ttypeof value.tagName === 'string'\n\t\t\t\t\t? value.tagName\n\t\t\t\t\t: // `xast`\n\t\t\t\t\t\ttypeof value.name === 'string'\n\t\t\t\t\t\t? value.name\n\t\t\t\t\t\t: undefined;\n\n\t\t\tObject.defineProperty(visit, 'name', {\n\t\t\t\tvalue: 'node (' + node.type + (name ? '<' + name + '>' : '') + ')',\n\t\t\t});\n\t\t}\n\n\t\treturn visit;\n\n\t\tfunction visit() {\n\t\t\tlet result: Readonly<ActionTuple> = empty;\n\t\t\tlet subresult: Readonly<ActionTuple>;\n\t\t\tlet offset: number;\n\t\t\tlet grandparents: UnistParent[];\n\t\t\tconst isMatch = !test || is(node, index, parents[parents.length - 1]);\n\n\t\t\tif (isMatch) {\n\t\t\t\tresult = toResult(\n\t\t\t\t\tenterVisitor?.(\n\t\t\t\t\t\tnode as Matches<InclusiveDescendant<Tree>, Check>,\n\t\t\t\t\t\tparents as Array<Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>>\n\t\t\t\t\t)\n\t\t\t\t);\n\n\t\t\t\tif (result[0] === EXIT) {\n\t\t\t\t\treturn result;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif ('children' in node && node.children) {\n\t\t\t\tconst nodeAsParent = node as UnistParent;\n\n\t\t\t\tif (nodeAsParent.children && result[0] !== SKIP) {\n\t\t\t\t\toffset = (reverse ? nodeAsParent.children.length : -1) + step;\n\t\t\t\t\tgrandparents = parents.concat(nodeAsParent);\n\n\t\t\t\t\twhile (offset > -1 && offset < nodeAsParent.children.length) {\n\t\t\t\t\t\tconst child = nodeAsParent.children[offset];\n\n\t\t\t\t\t\tsubresult = factory(child, offset, grandparents)();\n\n\t\t\t\t\t\tif (subresult[0] === EXIT) {\n\t\t\t\t\t\t\treturn subresult;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\toffset = typeof subresult[1] === 'number' ? subresult[1] : offset + step;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (isMatch && leaveVisitor) {\n\t\t\t\tconst leaveResult = toResult(\n\t\t\t\t\tleaveVisitor(\n\t\t\t\t\t\tnode as Matches<InclusiveDescendant<Tree>, Check>,\n\t\t\t\t\t\tparents as Array<Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>>\n\t\t\t\t\t)\n\t\t\t\t);\n\n\t\t\t\treturn leaveResult === empty ? result : leaveResult;\n\t\t\t}\n\n\t\t\treturn result;\n\t\t}\n\t}\n}\n\n/**\n * Turn a return value into a clean result.\n */\nfunction toResult(value: VisitorResult): Readonly<ActionTuple> {\n\tif (Array.isArray(value)) {\n\t\treturn value;\n\t}\n\n\tif (typeof value === 'number') {\n\t\treturn [CONTINUE, value];\n\t}\n\n\treturn value === null || value === undefined ? empty : [value];\n}\n\nexport type UnistNode = import('unist').Node;\nexport type UnistParent = import('unist').Parent;\n/**\n * Test from `unist-util-is`.\n *\n * Note: we have remove and add `undefined`, because otherwise when generating\n * automatic `.d.ts` files, TS tries to flatten paths from a local perspective,\n * which doesn’t work when publishing on npm.\n */\nexport type Test = Exclude<import('unist-util-is').Test, undefined> | undefined;\n/**\n * Get the value of a type guard `Fn`.\n */\nexport type Predicate<Fn, Fallback> = Fn extends (value: any) => value is infer Thing\n\t? Thing\n\t: Fallback;\n/**\n * Check whether a node matches a primitive check in the type system.\n */\nexport type MatchesOne<Value, Check> = Check extends null | undefined\n\t? Value\n\t: Value extends {\n\t\t\t\ttype: Check;\n\t\t  }\n\t\t? Value\n\t\t: Value extends Check\n\t\t\t? Value\n\t\t\t: Check extends Function\n\t\t\t\t? Predicate<Check, Value> extends Value\n\t\t\t\t\t? Predicate<Check, Value>\n\t\t\t\t\t: never\n\t\t\t\t: never;\n/**\n * Check whether a node matches a check in the type system.\n */\nexport type Matches<Value, Check> =\n\tCheck extends Array<any> ? MatchesOne<Value, Check[keyof Check]> : MatchesOne<Value, Check>;\n/**\n * Number; capped reasonably.\n */\nexport type Uint = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;\n/**\n * Increment a number in the type system.\n */\nexport type Increment<I extends Uint = 0> = I extends 0\n\t? 1\n\t: I extends 1\n\t\t? 2\n\t\t: I extends 2\n\t\t\t? 3\n\t\t\t: I extends 3\n\t\t\t\t? 4\n\t\t\t\t: I extends 4\n\t\t\t\t\t? 5\n\t\t\t\t\t: I extends 5\n\t\t\t\t\t\t? 6\n\t\t\t\t\t\t: I extends 6\n\t\t\t\t\t\t\t? 7\n\t\t\t\t\t\t\t: I extends 7\n\t\t\t\t\t\t\t\t? 8\n\t\t\t\t\t\t\t\t: I extends 8\n\t\t\t\t\t\t\t\t\t? 9\n\t\t\t\t\t\t\t\t\t: 10;\n/**\n * Collect nodes that can be parents of `Child`.\n */\nexport type InternalParent<\n\tNode extends import('unist').Node,\n\tChild extends import('unist').Node,\n> = Node extends import('unist').Parent\n\t? Node extends {\n\t\t\tchildren: (infer Children)[];\n\t\t}\n\t\t? Child extends Children\n\t\t\t? Node\n\t\t\t: never\n\t\t: never\n\t: never;\n/**\n * Collect nodes in `Tree` that can be parents of `Child`.\n */\nexport type Parent<\n\tTree extends import('unist').Node,\n\tChild extends import('unist').Node,\n> = InternalParent<InclusiveDescendant<Tree>, Child>;\n/**\n * Collect nodes in `Tree` that can be ancestors of `Child`.\n */\nexport type InternalAncestor<\n\tNode extends import('unist').Node,\n\tChild extends import('unist').Node,\n\tMax extends Uint = 10,\n\tDepth extends Uint = 0,\n> = Depth extends Max\n\t? never\n\t:\n\t\t\t| InternalParent<Node, Child>\n\t\t\t| InternalAncestor<Node, InternalParent<Node, Child>, Max, Increment<Depth>>;\n/**\n * Collect nodes in `Tree` that can be ancestors of `Child`.\n */\nexport type Ancestor<\n\tTree extends import('unist').Node,\n\tChild extends import('unist').Node,\n> = InternalAncestor<InclusiveDescendant<Tree>, Child>;\n/**\n * Collect all (inclusive) descendants of `Tree`.\n *\n * > 👉 **Note**: for performance reasons, this seems to be the fastest way to\n * > recurse without actually running into an infinite loop, which the\n * > previous version did.\n * >\n * > Practically, a max of `2` is typically enough assuming a `Root` is\n * > passed, but it doesn’t improve performance.\n * > It gets higher with `List > ListItem > Table > TableRow > TableCell`.\n * > Using up to `10` doesn’t hurt or help either.\n */\nexport type InclusiveDescendant<\n\tTree extends import('unist').Node,\n\tMax extends Uint = 10,\n\tDepth extends Uint = 0,\n> = Tree extends UnistParent\n\t? Depth extends Max\n\t\t? Tree\n\t\t: Tree | InclusiveDescendant<Tree['children'][number], Max, Increment<Depth>>\n\t: Tree;\n/**\n * Union of the action types.\n */\nexport type Action = 'skip' | boolean;\n/**\n * Move to the sibling at `index` next (after node itself is completely\n * traversed).\n *\n * Useful if mutating the tree, such as removing the node the visitor is\n * currently on, or any of its previous siblings.\n * Results less than 0 or greater than or equal to `children.length` stop\n * traversing the parent.\n */\nexport type Index = number;\n/**\n * List with one or two values, the first an action, the second an index.\n */\nexport type ActionTuple = [(Action | null | undefined | void)?, (Index | null | undefined)?];\n/**\n * Any value that can be returned from a visitor.\n */\nexport type VisitorResult =\n\t| Action\n\t| [(void | Action | null | undefined)?, (number | null | undefined)?]\n\t| Index\n\t| null\n\t| undefined\n\t| void;\n/**\n * Handle a node (matching `test`, if given).\n *\n * Visitors are free to transform `node`.\n * They can also transform the parent of node (the last of `ancestors`).\n *\n * Replacing `node` itself, if `SKIP` is not returned, still causes its\n * descendants to be walked (which is a bug).\n *\n * When adding or removing previous siblings of `node` (or next siblings, in\n * case of reverse), the `Visitor` should return a new `Index` to specify the\n * sibling to traverse after `node` is traversed.\n * Adding or removing next siblings of `node` (or previous siblings, in case\n * of reverse) is handled as expected without needing to return a new `Index`.\n *\n * Removing the children property of an ancestor still results in them being\n * traversed.\n */\nexport type Visitor<\n\tVisited extends import('unist').Node = import('unist').Node,\n\tVisitedParents extends import('unist').Parent = import('unist').Parent,\n> = (node: Visited, ancestors: Array<VisitedParents>) => VisitorResult;\n\n/**\n * Build a typed `Visitor` function from a tree and a test.\n *\n * It will infer which values are passed as `node` and which as `parents`.\n */\nexport type BuildVisitor<\n\tTree extends import('unist').Node = import('unist').Node,\n\tCheck extends Test = Test,\n> = Visitor<\n\tMatches<InclusiveDescendant<Tree>, Check>,\n\tAncestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>\n>;\n"]}

package/dist/values.d.ts

@@ -35,5 +35,39 @@ type MaybeAsyncThunk<T> = MaybeThunk<MaybePromise<T>>;
  * @see MaybeThunk
  */
 declare function loadThunkValue<T>(value: MaybeThunk<T>): T;
+type NextDepth = [1, 2, 3, 4, 5, 6, 7];
+/**
+ * Extract key-value entry pairs for each node in an object tree.
+ */
+type NodeEntries<T, NoCircle = never, MaxDepth extends number = 0> = MaxDepth extends 7 ? never : T extends object ? {
+    [Key in keyof T & string]-?: T[Key] extends NoCircle ? never : NodeEntries<T[Key], NoCircle | T[Key], NextDepth[MaxDepth]> extends infer Nested ? Nested extends {
+        key: string;
+        value: unknown;
+    } ? Nested['key'] extends '' ? {
+        key: Key;
+        value: Nested['value'];
+    } : {
+        key: Key;
+        value: T[Key];
+    } | {
+        key: `${Key}.${Nested['key']}`;
+        value: Nested['value'];
+    } : never : never;
+}[keyof T & string] : {
+    key: '';
+    value: T;
+};
+/**
+ * Sets a value nested in an object tree, creating the path as needed.
+ */
+declare function setNested<T extends object, const P extends NodeEntries<T>['key']>(obj: T, prop: P, value: Extract<NodeEntries<T>, {
+    key: P;
+}>['value']): void;
+/**
+ * Sets a value nested in an object tree, creating the path as needed, if it is not already set to a non-nullish value.
+ */
+declare function setNestedIfNullish<T extends object, const P extends NodeEntries<T>['key']>(obj: T, prop: P, value: Extract<NodeEntries<T>, {
+    key: P;
+}>['value']): void;
 
-export { type MaybeAsyncThunk, type MaybePromise, type MaybeThunk, loadThunkValue };
+export { type MaybeAsyncThunk, type MaybePromise, type MaybeThunk, type NodeEntries, loadThunkValue, setNested, setNestedIfNullish };

package/dist/values.js

@@ -1,5 +1,2 @@
-function T(e){return typeof e=="function"?e():e}
-
-export { T as loadThunkValue };
-//# sourceMappingURL=values.js.map
+function p(n){return typeof n=="function"?n():n}function u(n,i,y){if(n==null)throw new Error("Root object is nullish.");const t=i.split(".");let e=n;for(const[l,s]of t.slice(0,-1).entries()){const o=e[s],r=t.slice(0,l).join(".");if(o==null){e=e[s]={};continue}if(typeof o!="object")throw new Error(`Cannot set property on ${typeof o} value at "${r}".`);e=o;}e[t[t.length-1]]=y;}function a(n,i,y){if(n==null)throw new Error("Root object is nullish.");const t=i.split(".");let e=n;for(const[s,o]of t.slice(0,-1).entries()){const r=e[o],c=t.slice(0,s).join(".");if(r==null){e=e[o]={};continue}if(typeof r!="object")throw new Error(`Cannot set property on ${typeof r} value at "${c}".`);e=r;}const l=t[t.length-1];e[l]==null&&(e[t[t.length-1]]=y);}export{p as loadThunkValue,u as setNested,a as setNestedIfNullish};//# sourceMappingURL=values.js.map
 //# sourceMappingURL=values.js.map

package/dist/values.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/values.ts"],"names":["loadThunkValue","value"],"mappings":"AAuCO,SAASA,CAAAA,CAAkBC,EAAyB,CAC1D,OAAO,OAAOA,CAAU,EAAA,UAAA,CAAaA,CAAM,EAAA,CAAIA,CAChD","file":"values.js","sourcesContent":["/**\n * A value that can be might be pending to be resolved.\n */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * A value or a thunk for a value.\n *\n * A \"thunk\" is a function that takes no arguments and return\n * a value that is potentially expensive to compute.\n * This can be used when the value might not be needed and as\n * such can be computed on demand potentially saving the\n * expensive computation.\n *\n * If the value is not expensive to compute it can be used directly\n * for simplicity.\n *\n * A value type that is itself a function cannot be a \"maybe\" thunk.\n *\n * @see https://en.wikipedia.org/wiki/Thunk\n */\nexport type MaybeThunk<T> = T extends Function ? never : T | (() => T);\n\n/**\n * A value or a thunk for a synchronous or asynchronous value.\n *\n * @see MaybePromise\n * @see MaybeThunk\n */\nexport type MaybeAsyncThunk<T> = MaybeThunk<MaybePromise<T>>;\n\n/**\n * Load a value from a possibly thunk argument.\n *\n * If the value is a thunk it is called and the result is returned.\n * Otherwise the value itself is returned.\n *\n * @see MaybeThunk\n */\nexport function loadThunkValue<T>(value: MaybeThunk<T>): T {\n\treturn typeof value === 'function' ? value() : value;\n}\n"]}
+{"version":3,"sources":["../src/values.ts"],"names":["loadThunkValue","value","setNested","obj","prop","parts","current","idx","propName","next","path","setNestedIfNullish","key"],"mappings":"AAuCO,SAASA,CAAAA,CAAkBC,EAAyB,CAC1D,OAAO,OAAOA,CAAU,EAAA,UAAA,CAAaA,GAAUA,CAAAA,CAChD,CAkCO,SAASC,CAAAA,CACfC,EACAC,CACAH,CAAAA,CAAAA,CACO,CACP,GAAIE,CAAAA,EAAO,IAAM,CAAA,MAAM,IAAI,KAAA,CAAM,yBAAyB,CAC1D,CAAA,MAAME,EAAQD,CAAK,CAAA,KAAA,CAAM,GAAG,CAE5B,CAAA,IAAIE,EAAeH,CACnB,CAAA,IAAA,KAAW,CAACI,CAAKC,CAAAA,CAAQ,IAAKH,CAAM,CAAA,KAAA,CAAM,EAAG,CAAE,CAAA,CAAA,CAAE,OAAQ,EAAA,CAAG,CAC3D,MAAMI,EAAOH,CAAQE,CAAAA,CAAQ,EACvBE,CAAOL,CAAAA,CAAAA,CAAM,MAAM,CAAGE,CAAAA,CAAG,EAAE,IAAK,CAAA,GAAG,EAEzC,GAAIE,CAAAA,EAAQ,KAAM,CACjBH,CAAAA,CAAUA,EAAQE,CAAQ,CAAA,CAAI,EAAC,CAC/B,QACD,CAEA,GAAI,OAAOC,CAAAA,EAAS,SACnB,MAAM,IAAI,MAAM,CAA0B,uBAAA,EAAA,OAAOA,CAAI,CAAcC,WAAAA,EAAAA,CAAI,IAAI,CAE5EJ,CAAAA,CAAAA,CAAUG,EACX,CAEAH,CAAAA,CAAQD,EAAMA,CAAM,CAAA,MAAA,CAAS,CAAC,CAAC,CAAIJ,CAAAA,EACpC,CAKO,SAASU,CAAAA,CACfR,EACAC,CACAH,CAAAA,CAAAA,CACO,CACP,GAAIE,CAAAA,EAAO,KAAM,MAAM,IAAI,MAAM,yBAAyB,CAAA,CAC1D,MAAME,CAAQD,CAAAA,CAAAA,CAAK,MAAM,GAAG,CAAA,CAE5B,IAAIE,CAAAA,CAAeH,CACnB,CAAA,IAAA,KAAW,CAACI,CAAKC,CAAAA,CAAQ,IAAKH,CAAM,CAAA,KAAA,CAAM,EAAG,CAAE,CAAA,CAAA,CAAE,SAAW,CAAA,CAC3D,MAAMI,CAAOH,CAAAA,CAAAA,CAAQE,CAAQ,CACvBE,CAAAA,CAAAA,CAAOL,EAAM,KAAM,CAAA,CAAA,CAAGE,CAAG,CAAA,CAAE,IAAK,CAAA,GAAG,EAEzC,GAAIE,CAAAA,EAAQ,KAAM,CACjBH,CAAAA,CAAUA,EAAQE,CAAQ,CAAA,CAAI,EAC9B,CAAA,QACD,CAEA,GAAI,OAAOC,GAAS,QACnB,CAAA,MAAM,IAAI,KAAM,CAAA,CAAA,uBAAA,EAA0B,OAAOA,CAAI,CAAcC,WAAAA,EAAAA,CAAI,IAAI,CAE5EJ,CAAAA,CAAAA,CAAUG,EACX,CAEA,MAAMG,EAAMP,CAAMA,CAAAA,CAAAA,CAAM,OAAS,CAAC,CAAA,CAC9BC,EAAQM,CAAG,CAAA,EAAK,OACnBN,CAAQD,CAAAA,CAAAA,CAAMA,EAAM,MAAS,CAAA,CAAC,CAAC,CAAA,CAAIJ,CAErC,EAAA","file":"values.js","sourcesContent":["/**\n * A value that can be might be pending to be resolved.\n */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * A value or a thunk for a value.\n *\n * A \"thunk\" is a function that takes no arguments and return\n * a value that is potentially expensive to compute.\n * This can be used when the value might not be needed and as\n * such can be computed on demand potentially saving the\n * expensive computation.\n *\n * If the value is not expensive to compute it can be used directly\n * for simplicity.\n *\n * A value type that is itself a function cannot be a \"maybe\" thunk.\n *\n * @see https://en.wikipedia.org/wiki/Thunk\n */\nexport type MaybeThunk<T> = T extends Function ? never : T | (() => T);\n\n/**\n * A value or a thunk for a synchronous or asynchronous value.\n *\n * @see MaybePromise\n * @see MaybeThunk\n */\nexport type MaybeAsyncThunk<T> = MaybeThunk<MaybePromise<T>>;\n\n/**\n * Load a value from a possibly thunk argument.\n *\n * If the value is a thunk it is called and the result is returned.\n * Otherwise the value itself is returned.\n *\n * @see MaybeThunk\n */\nexport function loadThunkValue<T>(value: MaybeThunk<T>): T {\n\treturn typeof value === 'function' ? value() : value;\n}\n\ntype NextDepth = [1, 2, 3, 4, 5, 6, 7];\n\n/**\n * Extract key-value entry pairs for each node in an object tree.\n */\nexport type NodeEntries<T, NoCircle = never, MaxDepth extends number = 0> = MaxDepth extends 7\n\t? never\n\t: T extends object\n\t\t? {\n\t\t\t\t[Key in keyof T & string]-?: T[Key] extends NoCircle\n\t\t\t\t\t? never\n\t\t\t\t\t: NodeEntries<T[Key], NoCircle | T[Key], NextDepth[MaxDepth]> extends infer Nested\n\t\t\t\t\t\t? Nested extends { key: string; value: unknown }\n\t\t\t\t\t\t\t? Nested['key'] extends ''\n\t\t\t\t\t\t\t\t? {\n\t\t\t\t\t\t\t\t\t\tkey: Key;\n\t\t\t\t\t\t\t\t\t\tvalue: Nested['value'];\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t:\n\t\t\t\t\t\t\t\t\t\t| { key: Key; value: T[Key] }\n\t\t\t\t\t\t\t\t\t\t| {\n\t\t\t\t\t\t\t\t\t\t\t\tkey: `${Key}.${Nested['key']}`;\n\t\t\t\t\t\t\t\t\t\t\t\tvalue: Nested['value'];\n\t\t\t\t\t\t\t\t\t\t  }\n\t\t\t\t\t\t\t: never\n\t\t\t\t\t\t: never;\n\t\t\t}[keyof T & string]\n\t\t: { key: ''; value: T };\n\n/**\n * Sets a value nested in an object tree, creating the path as needed.\n */\nexport function setNested<T extends object, const P extends NodeEntries<T>['key']>(\n\tobj: T,\n\tprop: P,\n\tvalue: Extract<NodeEntries<T>, { key: P }>['value']\n): void {\n\tif (obj == null) throw new Error('Root object is nullish.');\n\tconst parts = prop.split('.');\n\n\tlet current: any = obj;\n\tfor (const [idx, propName] of parts.slice(0, -1).entries()) {\n\t\tconst next = current[propName];\n\t\tconst path = parts.slice(0, idx).join('.');\n\n\t\tif (next == null) {\n\t\t\tcurrent = current[propName] = {};\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (typeof next !== 'object')\n\t\t\tthrow new Error(`Cannot set property on ${typeof next} value at \"${path}\".`);\n\n\t\tcurrent = next;\n\t}\n\n\tcurrent[parts[parts.length - 1]] = value;\n}\n\n/**\n * Sets a value nested in an object tree, creating the path as needed, if it is not already set to a non-nullish value.\n */\nexport function setNestedIfNullish<T extends object, const P extends NodeEntries<T>['key']>(\n\tobj: T,\n\tprop: P,\n\tvalue: Extract<NodeEntries<T>, { key: P }>['value']\n): void {\n\tif (obj == null) throw new Error('Root object is nullish.');\n\tconst parts = prop.split('.');\n\n\tlet current: any = obj;\n\tfor (const [idx, propName] of parts.slice(0, -1).entries()) {\n\t\tconst next = current[propName];\n\t\tconst path = parts.slice(0, idx).join('.');\n\n\t\tif (next == null) {\n\t\t\tcurrent = current[propName] = {};\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (typeof next !== 'object')\n\t\t\tthrow new Error(`Cannot set property on ${typeof next} value at \"${path}\".`);\n\n\t\tcurrent = next;\n\t}\n\n\tconst key = parts[parts.length - 1];\n\tif (current[key] == null) {\n\t\tcurrent[parts[parts.length - 1]] = value;\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inox-tools/utils",
-  "version": "0.1.4",
+  "version": "0.3.0-beta.0",
   "description": "A collection of utilities used throughout Inox Tools",
   "keywords": [
     "utilities"
@@ -20,15 +20,21 @@
     "src"
   ],
   "devDependencies": {
-    "@types/node": "^22.5.4",
-    "@vitest/coverage-v8": "^2.0.5",
-    "@vitest/ui": "^2.0.5",
-    "astro": "^4.15.3",
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.8.4",
+    "@types/unist": "^3.0.3",
+    "@types/xast": "^2.0.4",
+    "@vitest/coverage-v8": "^2.1.4",
+    "@vitest/ui": "^2.1.4",
+    "astro": "^5.0.0-beta",
     "jest-extended": "^4.0.2",
-    "tsup": "8.2.4",
-    "typescript": "^5.5.4",
-    "vite": "^5.4.3",
-    "vitest": "^2.0.5"
+    "mdast-util-from-markdown": "^2.0.2",
+    "tsup": "8.3.5",
+    "typescript": "^5.6.3",
+    "unist-util-is": "^6.0.0",
+    "vite": "^6.0.0-beta",
+    "vitest": "^2.1.4"
   },
   "scripts": {
     "build": "tsup",

package/src/unist/visit.ts

@@ -0,0 +1,332 @@
+import { convert } from 'unist-util-is';
+
+const empty: ActionTuple = [];
+
+/**
+ * Continue traversing as normal.
+ */
+export const CONTINUE = true;
+
+/**
+ * Stop traversing immediately.
+ */
+export const EXIT = false;
+
+/**
+ * Do not traverse this node’s children.
+ */
+export const SKIP = 'skip';
+
+export type Options<Tree extends import('unist').Node, Check extends Test> = {
+	tree: Tree;
+	test?: Check;
+	enter?: BuildVisitor<Tree, Check>;
+	leave?: BuildVisitor<Tree, Check>;
+	reverse?: boolean;
+};
+
+export function visitParents<Tree extends import('unist').Node, Check extends Test>({
+	tree,
+	test,
+	enter: enterVisitor,
+	leave: leaveVisitor,
+	reverse,
+}: Options<Tree, Check>) {
+	if (!tree) {
+		throw new TypeError('A tree is required');
+	}
+
+	if (!enterVisitor && !leaveVisitor) {
+		throw new Error('At least one visitor (`enter` or `leave`) must be provided');
+	}
+
+	const is = convert(test) as (
+		node: UnistNode,
+		index?: number,
+		parent?: UnistParent
+	) => node is Matches<InclusiveDescendant<Tree>, Check>;
+	const step = reverse ? -1 : 1;
+
+	factory(tree, undefined, [])();
+
+	function factory(node: UnistNode, index: number | undefined, parents: UnistParent[]) {
+		const value = node as UnistNode & Record<string, unknown>;
+
+		if (typeof value.type === 'string') {
+			const name =
+				// `hast`
+				typeof value.tagName === 'string'
+					? value.tagName
+					: // `xast`
+						typeof value.name === 'string'
+						? value.name
+						: undefined;
+
+			Object.defineProperty(visit, 'name', {
+				value: 'node (' + node.type + (name ? '<' + name + '>' : '') + ')',
+			});
+		}
+
+		return visit;
+
+		function visit() {
+			let result: Readonly<ActionTuple> = empty;
+			let subresult: Readonly<ActionTuple>;
+			let offset: number;
+			let grandparents: UnistParent[];
+			const isMatch = !test || is(node, index, parents[parents.length - 1]);
+
+			if (isMatch) {
+				result = toResult(
+					enterVisitor?.(
+						node as Matches<InclusiveDescendant<Tree>, Check>,
+						parents as Array<Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>>
+					)
+				);
+
+				if (result[0] === EXIT) {
+					return result;
+				}
+			}
+
+			if ('children' in node && node.children) {
+				const nodeAsParent = node as UnistParent;
+
+				if (nodeAsParent.children && result[0] !== SKIP) {
+					offset = (reverse ? nodeAsParent.children.length : -1) + step;
+					grandparents = parents.concat(nodeAsParent);
+
+					while (offset > -1 && offset < nodeAsParent.children.length) {
+						const child = nodeAsParent.children[offset];
+
+						subresult = factory(child, offset, grandparents)();
+
+						if (subresult[0] === EXIT) {
+							return subresult;
+						}
+
+						offset = typeof subresult[1] === 'number' ? subresult[1] : offset + step;
+					}
+				}
+			}
+
+			if (isMatch && leaveVisitor) {
+				const leaveResult = toResult(
+					leaveVisitor(
+						node as Matches<InclusiveDescendant<Tree>, Check>,
+						parents as Array<Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>>
+					)
+				);
+
+				return leaveResult === empty ? result : leaveResult;
+			}
+
+			return result;
+		}
+	}
+}
+
+/**
+ * Turn a return value into a clean result.
+ */
+function toResult(value: VisitorResult): Readonly<ActionTuple> {
+	if (Array.isArray(value)) {
+		return value;
+	}
+
+	if (typeof value === 'number') {
+		return [CONTINUE, value];
+	}
+
+	return value === null || value === undefined ? empty : [value];
+}
+
+export type UnistNode = import('unist').Node;
+export type UnistParent = import('unist').Parent;
+/**
+ * Test from `unist-util-is`.
+ *
+ * Note: we have remove and add `undefined`, because otherwise when generating
+ * automatic `.d.ts` files, TS tries to flatten paths from a local perspective,
+ * which doesn’t work when publishing on npm.
+ */
+export type Test = Exclude<import('unist-util-is').Test, undefined> | undefined;
+/**
+ * Get the value of a type guard `Fn`.
+ */
+export type Predicate<Fn, Fallback> = Fn extends (value: any) => value is infer Thing
+	? Thing
+	: Fallback;
+/**
+ * Check whether a node matches a primitive check in the type system.
+ */
+export type MatchesOne<Value, Check> = Check extends null | undefined
+	? Value
+	: Value extends {
+				type: Check;
+		  }
+		? Value
+		: Value extends Check
+			? Value
+			: Check extends Function
+				? Predicate<Check, Value> extends Value
+					? Predicate<Check, Value>
+					: never
+				: never;
+/**
+ * Check whether a node matches a check in the type system.
+ */
+export type Matches<Value, Check> =
+	Check extends Array<any> ? MatchesOne<Value, Check[keyof Check]> : MatchesOne<Value, Check>;
+/**
+ * Number; capped reasonably.
+ */
+export type Uint = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+/**
+ * Increment a number in the type system.
+ */
+export type Increment<I extends Uint = 0> = I extends 0
+	? 1
+	: I extends 1
+		? 2
+		: I extends 2
+			? 3
+			: I extends 3
+				? 4
+				: I extends 4
+					? 5
+					: I extends 5
+						? 6
+						: I extends 6
+							? 7
+							: I extends 7
+								? 8
+								: I extends 8
+									? 9
+									: 10;
+/**
+ * Collect nodes that can be parents of `Child`.
+ */
+export type InternalParent<
+	Node extends import('unist').Node,
+	Child extends import('unist').Node,
+> = Node extends import('unist').Parent
+	? Node extends {
+			children: (infer Children)[];
+		}
+		? Child extends Children
+			? Node
+			: never
+		: never
+	: never;
+/**
+ * Collect nodes in `Tree` that can be parents of `Child`.
+ */
+export type Parent<
+	Tree extends import('unist').Node,
+	Child extends import('unist').Node,
+> = InternalParent<InclusiveDescendant<Tree>, Child>;
+/**
+ * Collect nodes in `Tree` that can be ancestors of `Child`.
+ */
+export type InternalAncestor<
+	Node extends import('unist').Node,
+	Child extends import('unist').Node,
+	Max extends Uint = 10,
+	Depth extends Uint = 0,
+> = Depth extends Max
+	? never
+	:
+			| InternalParent<Node, Child>
+			| InternalAncestor<Node, InternalParent<Node, Child>, Max, Increment<Depth>>;
+/**
+ * Collect nodes in `Tree` that can be ancestors of `Child`.
+ */
+export type Ancestor<
+	Tree extends import('unist').Node,
+	Child extends import('unist').Node,
+> = InternalAncestor<InclusiveDescendant<Tree>, Child>;
+/**
+ * Collect all (inclusive) descendants of `Tree`.
+ *
+ * > 👉 **Note**: for performance reasons, this seems to be the fastest way to
+ * > recurse without actually running into an infinite loop, which the
+ * > previous version did.
+ * >
+ * > Practically, a max of `2` is typically enough assuming a `Root` is
+ * > passed, but it doesn’t improve performance.
+ * > It gets higher with `List > ListItem > Table > TableRow > TableCell`.
+ * > Using up to `10` doesn’t hurt or help either.
+ */
+export type InclusiveDescendant<
+	Tree extends import('unist').Node,
+	Max extends Uint = 10,
+	Depth extends Uint = 0,
+> = Tree extends UnistParent
+	? Depth extends Max
+		? Tree
+		: Tree | InclusiveDescendant<Tree['children'][number], Max, Increment<Depth>>
+	: Tree;
+/**
+ * Union of the action types.
+ */
+export type Action = 'skip' | boolean;
+/**
+ * Move to the sibling at `index` next (after node itself is completely
+ * traversed).
+ *
+ * Useful if mutating the tree, such as removing the node the visitor is
+ * currently on, or any of its previous siblings.
+ * Results less than 0 or greater than or equal to `children.length` stop
+ * traversing the parent.
+ */
+export type Index = number;
+/**
+ * List with one or two values, the first an action, the second an index.
+ */
+export type ActionTuple = [(Action | null | undefined | void)?, (Index | null | undefined)?];
+/**
+ * Any value that can be returned from a visitor.
+ */
+export type VisitorResult =
+	| Action
+	| [(void | Action | null | undefined)?, (number | null | undefined)?]
+	| Index
+	| null
+	| undefined
+	| void;
+/**
+ * Handle a node (matching `test`, if given).
+ *
+ * Visitors are free to transform `node`.
+ * They can also transform the parent of node (the last of `ancestors`).
+ *
+ * Replacing `node` itself, if `SKIP` is not returned, still causes its
+ * descendants to be walked (which is a bug).
+ *
+ * When adding or removing previous siblings of `node` (or next siblings, in
+ * case of reverse), the `Visitor` should return a new `Index` to specify the
+ * sibling to traverse after `node` is traversed.
+ * Adding or removing next siblings of `node` (or previous siblings, in case
+ * of reverse) is handled as expected without needing to return a new `Index`.
+ *
+ * Removing the children property of an ancestor still results in them being
+ * traversed.
+ */
+export type Visitor<
+	Visited extends import('unist').Node = import('unist').Node,
+	VisitedParents extends import('unist').Parent = import('unist').Parent,
+> = (node: Visited, ancestors: Array<VisitedParents>) => VisitorResult;
+
+/**
+ * Build a typed `Visitor` function from a tree and a test.
+ *
+ * It will infer which values are passed as `node` and which as `parents`.
+ */
+export type BuildVisitor<
+	Tree extends import('unist').Node = import('unist').Node,
+	Check extends Test = Test,
+> = Visitor<
+	Matches<InclusiveDescendant<Tree>, Check>,
+	Ancestor<Tree, Matches<InclusiveDescendant<Tree>, Check>>
+>;

package/src/values.ts

@@ -40,3 +40,95 @@ export type MaybeAsyncThunk<T> = MaybeThunk<MaybePromise<T>>;
 export function loadThunkValue<T>(value: MaybeThunk<T>): T {
 	return typeof value === 'function' ? value() : value;
 }
+
+type NextDepth = [1, 2, 3, 4, 5, 6, 7];
+
+/**
+ * Extract key-value entry pairs for each node in an object tree.
+ */
+export type NodeEntries<T, NoCircle = never, MaxDepth extends number = 0> = MaxDepth extends 7
+	? never
+	: T extends object
+		? {
+				[Key in keyof T & string]-?: T[Key] extends NoCircle
+					? never
+					: NodeEntries<T[Key], NoCircle | T[Key], NextDepth[MaxDepth]> extends infer Nested
+						? Nested extends { key: string; value: unknown }
+							? Nested['key'] extends ''
+								? {
+										key: Key;
+										value: Nested['value'];
+									}
+								:
+										| { key: Key; value: T[Key] }
+										| {
+												key: `${Key}.${Nested['key']}`;
+												value: Nested['value'];
+										  }
+							: never
+						: never;
+			}[keyof T & string]
+		: { key: ''; value: T };
+
+/**
+ * Sets a value nested in an object tree, creating the path as needed.
+ */
+export function setNested<T extends object, const P extends NodeEntries<T>['key']>(
+	obj: T,
+	prop: P,
+	value: Extract<NodeEntries<T>, { key: P }>['value']
+): void {
+	if (obj == null) throw new Error('Root object is nullish.');
+	const parts = prop.split('.');
+
+	let current: any = obj;
+	for (const [idx, propName] of parts.slice(0, -1).entries()) {
+		const next = current[propName];
+		const path = parts.slice(0, idx).join('.');
+
+		if (next == null) {
+			current = current[propName] = {};
+			continue;
+		}
+
+		if (typeof next !== 'object')
+			throw new Error(`Cannot set property on ${typeof next} value at "${path}".`);
+
+		current = next;
+	}
+
+	current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Sets a value nested in an object tree, creating the path as needed, if it is not already set to a non-nullish value.
+ */
+export function setNestedIfNullish<T extends object, const P extends NodeEntries<T>['key']>(
+	obj: T,
+	prop: P,
+	value: Extract<NodeEntries<T>, { key: P }>['value']
+): void {
+	if (obj == null) throw new Error('Root object is nullish.');
+	const parts = prop.split('.');
+
+	let current: any = obj;
+	for (const [idx, propName] of parts.slice(0, -1).entries()) {
+		const next = current[propName];
+		const path = parts.slice(0, idx).join('.');
+
+		if (next == null) {
+			current = current[propName] = {};
+			continue;
+		}
+
+		if (typeof next !== 'object')
+			throw new Error(`Cannot set property on ${typeof next} value at "${path}".`);
+
+		current = next;
+	}
+
+	const key = parts[parts.length - 1];
+	if (current[key] == null) {
+		current[parts[parts.length - 1]] = value;
+	}
+}