@inox-tools/utils 0.1.4 → 0.2.0

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,7 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inox-tools/utils",
-  "version": "0.1.4",
+  "version": "0.2.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.7.4",
+    "@types/unist": "^3.0.3",
+    "@types/xast": "^2.0.4",
+    "@vitest/coverage-v8": "^2.1.1",
+    "@vitest/ui": "^2.1.1",
+    "astro": "^4.15.9",
     "jest-extended": "^4.0.2",
+    "mdast-util-from-markdown": "^2.0.1",
     "tsup": "8.2.4",
     "typescript": "^5.5.4",
-    "vite": "^5.4.3",
-    "vitest": "^2.0.5"
+    "unist-util-is": "^6.0.0",
+    "vite": "^5.4.8",
+    "vitest": "^2.1.1"
   },
   "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>>
+>;