feat: Test, TestFunction

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

.eslintrc.cjs

@@ -10,7 +10,15 @@
  */
 const config = {
   extends: ['./.eslintrc.base.cjs'],
-  overrides: [...require('./.eslintrc.base.cjs').overrides],
+  overrides: [
+    ...require('./.eslintrc.base.cjs').overrides,
+    {
+      files: ['src/test-function.ts'],
+      rules: {
+        '@typescript-eslint/no-invalid-void-type': 0
+      }
+    }
+  ],
   root: true
 }
 

README.md

@@ -27,6 +27,9 @@
   - [`IsParent<Tree, Child>`](#isparenttree-child)
   - [`Parents<Tree[, Child]>`](#parentstree-child)
   - [`PositionalInfo<[T]>`](#positionalinfot)
+  - [`Test`](#test)
+  - [`TestFunction<[T][, P][, U]>`](#testfunctiont-p-u)
+    - [`fn(node[, index][, parent])`](#fnnode-index-parent)
   - [`Type<[T]>`](#typet)
   - [`Uint`](#uint)
 - [Contribute](#contribute)
@@ -60,8 +63,11 @@ import type {
   Ancestor,
   Children,
   InclusiveDescendant,
+  Index,
   Parents,
   PositionalInfo,
+  Test,
+  TestFunction,
   Type
 } from '@flex-development/unist-util-types'
 ```
@@ -164,6 +170,39 @@ Object containing the [*positional information*][positional-information] of [*tr
 
 > **source**: [`src/positional-info.ts`](src/positional-info.ts)
 
+### `Test`
+
+Union of test types for a [`Node`][node].
+
+See [`unist-util-is`][unist-util-is] for more details.
+
+> **source**: [`src/test.ts`](src/test.ts)
+
+### `TestFunction<[T][, P][, U]>`
+
+Check if a node passes a test.
+
+- `T` ([**`Node`**][node]): node to check
+  - **default**: [`Node`][node]
+- `P` ([**`Parent`**][parent]): [*parent(s)*][parent] of node `T`
+  - **default**: [`Parent`][parent]
+- `U` (**`any`**): `this` context
+  - **default**: `unknown`
+
+#### `fn(node[, index][, parent])`
+
+**Parameters**:
+
+- `node` (**`T`**): node to check
+- `index` (**[`Index`](#index) | `undefined`**): index of `node` in `parent.children`
+- `parent` (**[`Parent`][parent] | `undefined`**): [*parent*][parent] of `node`
+
+**Returns**:
+
+`boolean | undefined | void` test result for `node`
+
+> **source**: [`src/test-function.ts`](src/test-function.ts)
+
 ### `Type<[T]>`
 
 Extract [*type*][type] from [*tree*][tree] `T`.
@@ -199,6 +238,7 @@ community you agree to abide by its terms.
 [tree]: https://github.com/syntax-tree/unist#tree
 [type]: https://github.com/syntax-tree/unist#type
 [typescript]: https://www.typescriptlang.org
+[unist-util-is]: https://github.com/syntax-tree/unist-util-is
 [unist-utilities]: https://github.com/syntax-tree/unist#list-of-utilities
 [unist]: https://github.com/syntax-tree/unist
 [yarn]: https://yarnpkg.com

src/__tests__/test-function.spec-d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Type Tests - TestFunction
+ * @module unist-util-types/tests/unit-d/TestFunction
+ */
+
+import type * as docast from '@flex-development/docast'
+import type Index from '../index-number'
+import type Parents from '../parents'
+import type TestSubject from '../test-function'
+
+describe('unit-d:TestFunction', () => {
+  type T = docast.InlineTag
+  type P = Parents<docast.Root, T>
+  type U = { trash: WeakSet<docast.DocastNode> }
+  type Subject = TestSubject<T, P, U>
+
+  it('should be callable with [T, Index?, P?]', () => {
+    expectTypeOf<Subject>().parameters.toEqualTypeOf<[T, Index?, P?]>()
+  })
+
+  it('should match [this: U]', () => {
+    expectTypeOf<Subject>().thisParameter.toEqualTypeOf<U>()
+  })
+
+  it('should return boolean | undefined | void', () => {
+    expectTypeOf<Subject>().returns.toEqualTypeOf<boolean | undefined | void>()
+  })
+})

src/__tests__/test.spec-d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Type Tests - Test
+ * @module unist-util-types/tests/unit-d/Test
+ */
+
+import type { Node } from 'unist'
+import type TestSubject from '../test'
+import type TestFunction from '../test-function'
+import type Type from '../type'
+
+describe('unit-d:Test', () => {
+  it('should extract (Node | TestFunction | Type)[]', () => {
+    expectTypeOf<TestSubject>()
+      .extract<(Node | TestFunction | Type)[]>()
+      .not.toBeNever()
+  })
+
+  it('should extract Node', () => {
+    expectTypeOf<TestSubject>().extract<Node>().not.toBeNever()
+  })
+
+  it('should extract TestFunction', () => {
+    expectTypeOf<TestSubject>().extract<TestFunction>().not.toBeNever()
+  })
+
+  it('should extract Type', () => {
+    expectTypeOf<TestSubject>().extract<Type>().not.toBeNever()
+  })
+
+  it('should extract null', () => {
+    expectTypeOf<TestSubject>().extract<null>().not.toBeNever()
+  })
+
+  it('should extract undefined', () => {
+    expectTypeOf<TestSubject>().extract<undefined>().not.toBeNever()
+  })
+})

src/index.ts

@@ -13,5 +13,7 @@ export type { default as IsAncestor } from './is-ancestor'
 export type { default as IsParent } from './is-parent'
 export type { default as Parents } from './parents'
 export type { default as PositionalInfo } from './positional-info'
+export type { default as Test } from './test'
+export type { default as TestFunction } from './test-function'
 export type { default as Type } from './type'
 export type { default as Uint } from './uint'

src/test-function.ts

@@ -0,0 +1,38 @@
+/**
+ * @file TestFunction
+ * @module unist-util-types/TestFunction
+ */
+
+import type { Node, Parent } from 'unist'
+import type Index from './index-number'
+
+/**
+ * Check if `node` passes a test.
+ *
+ * @see {@linkcode Index}
+ * @see {@linkcode Node}
+ * @see {@linkcode Parent}
+ *
+ * @template {Node} [T=Node] - Node to check
+ * @template {Parent} [P=Parent] - Parent of node
+ * @template {any} [U=unknown] - `this` context
+ *
+ * @this {U}
+ *
+ * @param {T} node - Node to check
+ * @param {Index?} [index] - Index of `node` in `parent.children`
+ * @param {P?} [parent] - Parent of `node`
+ * @return {boolean | undefined | void} Test result
+ */
+type TestFunction<
+  T extends Node = Node,
+  P extends Parent = Parent,
+  U = unknown
+> = (
+  this: U,
+  node: T,
+  index?: Index,
+  parent?: P
+) => boolean | undefined | void
+
+export type { TestFunction as default }

src/test.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Test
+ * @module unist-util-types/Test
+ */
+
+import type { Node } from 'unist'
+import type TestFunction from './test-function'
+import type Type from './type'
+
+/**
+ * Union of test types for a {@linkcode Node}.
+ *
+ * @see {@linkcode TestFunction}
+ * @see {@linkcode Type}
+ * @see https://github.com/syntax-tree/unist-util-is
+ */
+type Test =
+  | (Node | TestFunction | Type)[]
+  | Node
+  | TestFunction
+  | Type
+  | null
+  | undefined
+
+export type { Test as default }