feat: InclusiveDescendant

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

src/__tests__/descendant-inclusive.spec-d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Type Tests - InclusiveDescendant
+ * @module unist-util-types/tests/unit-d/InclusiveDescendant
+ */
+
+import type * as docast from '@flex-development/docast'
+import type * as mdast from 'mdast'
+import type TestSubject from '../descendant-inclusive'
+
+describe('unit-d:InclusiveDescendant', () => {
+  it('should equal Tree if Tree does not extend Parent', () => {
+    // Arrange
+    type Tree = docast.InlineTag
+
+    // Expect
+    expectTypeOf<TestSubject<Tree>>().toEqualTypeOf<Tree>()
+  })
+
+  describe('Tree extends Parent', () => {
+    type Tree = docast.Comment
+
+    it('should equal Tree if Depth extends Max', () => {
+      // Arrange
+      type Depth = 10
+
+      // Expect
+      expectTypeOf<TestSubject<Tree, Depth, Depth>>().toEqualTypeOf<Tree>()
+    })
+
+    it('should unionize Tree and all descendents', () => {
+      // Arrange
+      type Expect =
+        | docast.BlockTag
+        | docast.BlockTagContent
+        | docast.Description
+        | docast.DescriptionContent
+        | mdast.Heading
+        | Tree
+
+      // Expect
+      expectTypeOf<TestSubject<Tree>>().toEqualTypeOf<Expect>()
+    })
+  })
+})

src/descendant-inclusive.ts

@@ -0,0 +1,35 @@
+/**
+ * @file InclusiveDescendant
+ * @module unist-util-types/InclusiveDescendant
+ */
+
+import type { Node, Parent } from 'unist'
+import type Increment from './increment'
+import type Uint from './uint'
+
+/**
+ * Collect all [*inclusive descendants*][1] of [`Tree`][2].
+ *
+ * [1]: https://github.com/syntax-tree/unist#descendant
+ * [2]: https://github.com/syntax-tree/unist#tree
+ *
+ * @see {@linkcode Node}
+ * @see {@linkcode Uint}
+ *
+ * @template {Node} Tree - Tree to collect descendants from
+ * @template {Uint} Max - Maximum tree depth
+ * @template {Uint} Depth - Current tree depth
+ */
+// dprint-ignore
+type InclusiveDescendant<
+  Tree extends Node,
+  Max extends Uint = 10,
+  Depth extends Uint = 0
+> = Tree extends Parent
+    ? Depth extends Max
+      ? Tree
+      : | InclusiveDescendant<Tree['children'][number], Max, Increment<Depth>>
+        | Tree
+    : Tree
+
+export type { InclusiveDescendant as default }

src/index.ts

@@ -4,5 +4,6 @@
  */
 
 export type { default as Decrement } from './decrement'
+export type { default as InclusiveDescendant } from './descendant-inclusive'
 export type { default as Increment } from './increment'
 export type { default as Uint } from './uint'