feat(types): VisitedAncestor, VisitedParent

Signed-off-by: Lexus Drumgold <[email protected]>

src/types/__tests__/visited-ancestor.spec-d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Type Tests - VisitedAncestor
+ * @module unist-util-visit/types/tests/unit-d/VisitedAncestor
+ */
+
+import type * as docast from '@flex-development/docast'
+import type { Parent } from 'unist'
+import type TestSubject from '../visited-ancestor'
+
+describe('unit-d:types/VisitedAncestor', () => {
+  it('should equal Parent if Node extends Tree', () => {
+    expectTypeOf<TestSubject>().toEqualTypeOf<Parent>()
+  })
+
+  it('should unionize ancestors of nodes in Tree that pass Check', () => {
+    // Arrange
+    type Tree = docast.Root
+    type Check = (value: unknown) => value is docast.TypeExpression
+    type Expect = docast.BlockTag | docast.Comment | Tree
+
+    // Expect
+    expectTypeOf<TestSubject<Tree, Check>>().toEqualTypeOf<Expect>()
+  })
+})

src/types/__tests__/visited-parent.spec-d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Type Tests - VisitedParent
+ * @module unist-util-visit/types/tests/unit-d/VisitedParent
+ */
+
+import type * as docast from '@flex-development/docast'
+import type { Parent } from 'unist'
+import type TestSubject from '../visited-parent'
+
+describe('unit-d:types/VisitedParent', () => {
+  it('should equal Parent if Node extends Tree', () => {
+    expectTypeOf<TestSubject>().toEqualTypeOf<Parent>()
+  })
+
+  it('should unionize parents of nodes in Tree that pass Check', () => {
+    // Arrange
+    type Check = (value: unknown) => value is docast.TypeExpression
+    type Expect = docast.BlockTag
+
+    // Expect
+    expectTypeOf<TestSubject<docast.Root, Check>>().toEqualTypeOf<Expect>()
+  })
+})

src/types/index.ts

@@ -9,4 +9,6 @@ export type { default as ActionTuple } from './action-tuple'
 export type { default as Continue } from './continue'
 export type { default as Exit } from './exit'
 export type { default as Skip } from './skip'
+export type { default as VisitedAncestor } from './visited-ancestor'
+export type { default as VisitedParent } from './visited-parent'
 export type { default as VisitorResult } from './visitor-result'

src/types/visited-ancestor.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Type Definitions - VisitedAncestor
+ * @module unist-util-visit/types/VisitedAncestor
+ */
+
+import type {
+  Ancestor,
+  MatchInclusiveDescendant,
+  Test
+} from '@flex-development/unist-util-types'
+import type { Node, Parent } from 'unist'
+
+/**
+ * Collect [*ancestors*][1] of nodes in [`Tree`][2] that pass a test.
+ *
+ * [1]: https://github.com/syntax-tree/unist#ancestor
+ * [2]: https://github.com/syntax-tree/unist#tree
+ *
+ * @see {@linkcode Node}
+ * @see {@linkcode Test}
+ *
+ * @template {Node} Tree - Tree to extract ancestors from
+ * @template {Test} Check - Node test
+ */
+type VisitedAncestor<
+  Tree extends Node = Node,
+  Check extends Test = Test
+> = // dprint-ignore
+  Node extends Tree
+    ? Parent
+    : Ancestor<Tree, MatchInclusiveDescendant<Tree, Check>>
+
+export type { VisitedAncestor as default }

src/types/visited-parent.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Type Definitions - VisitedParent
+ * @module unist-util-visit/types/VisitedParent
+ */
+
+import type {
+  InclusiveDescendant,
+  MatchInclusiveDescendant,
+  Parents,
+  Test
+} from '@flex-development/unist-util-types'
+import type { Node, Parent } from 'unist'
+
+/**
+ * Collect [*parents*][1] of nodes in [`Tree`][2] that pass a test.
+ *
+ * [1]: https://github.com/syntax-tree/unist#parent
+ * [2]: https://github.com/syntax-tree/unist#tree
+ *
+ * @see {@linkcode Node}
+ * @see {@linkcode Test}
+ *
+ * @template {Node} Tree - Tree to extract parents from
+ * @template {Test} Check - Node test
+ */
+type VisitedParent<
+  Tree extends Node = Node,
+  Check extends Test = Test
+> = // dprint-ignore
+  Node extends Tree
+    ? Parent
+    : Parents<
+        Extract<InclusiveDescendant<Tree>, Parent>,
+        MatchInclusiveDescendant<Tree, Check>
+      >
+
+export type { VisitedParent as default }