Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

index.test-d.ts

@@ -64,8 +64,11 @@ expectType<boolean>(is(heading))
 expectType<boolean>(is(heading, null))
 expectType<boolean>(is(heading, undefined))
 /* But not with a type predicate */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
 expectError(is<Node>(heading)) // But not with a type predicate
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
 expectError(is<Node>(heading, null))
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
 expectError(is<Node>(heading, undefined))
 
 /* Should support string tests. */

lib/index.js

@@ -1,102 +1,111 @@
 /**
  * @typedef {import('unist').Node} Node
  * @typedef {import('unist').Parent} Parent
- * @typedef {string} Type
+ */
+
+/**
  * @typedef {Record<string, unknown>} Props
- * @typedef {null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>} Test
+ * @typedef {null | undefined | string | Props | TestFunctionAnything | Array<string | Props | TestFunctionAnything>} Test
+ *   Check for an arbitrary node, unaware of TypeScript inferral.
  *
  * @callback TestFunctionAnything
- *   Arbitrary function to define whether a node passes.
+ *   Check if a node passes a test, unaware of TypeScript inferral.
  * @param {unknown} this
- *   The to `is` given `context`
+ *   The given context.
  * @param {Node} node
- *   Node to check.
- * @param {number|null|undefined} [index]
- *   Index of `node` in `parent`.
- * @param {Parent|null|undefined} [parent]
- *   Parent of `node`.
- * @returns {boolean|void}
- *   Whether `node` matches.
- *
- * @callback AssertAnything
- *   Check if a node is an element and passes a certain node test.
- * @param {unknown} [node]
- *   Thing to check and check that it’s a node.
- * @param {number|null|undefined} [index]
- *   Index of `node` in `parent`.
- * @param {Parent|null|undefined} [parent]
- *   Parent of `node`.
- * @returns {boolean}
- *   Whether `node` matches.
+ *   A node.
+ * @param {number | null | undefined} [index]
+ *   The node’s position in its parent.
+ * @param {Parent | null | undefined} [parent]
+ *   The node’s parent.
+ * @returns {boolean | void}
+ *   Whether this node passes the test.
  */
 
 /**
  * @template {Node} Kind
+ *   Node type.
+ * @typedef {Kind['type'] | Partial<Kind> | TestFunctionPredicate<Kind> | Array<Kind['type'] | Partial<Kind> | TestFunctionPredicate<Kind>>} PredicateTest
+ *   Check for a node that can be inferred by TypeScript.
+ */
+
+/**
+ * Check if a node passes a certain test.
+ *
+ * @template {Node} Kind
+ *   Node type.
  * @callback TestFunctionPredicate
- *   Arbitrary function to define whether a node passes, using a TypeScript type
- *   predicate.
+ *   Complex test function for a node that can be inferred by TypeScript.
  * @param {Node} node
- *   Node to check.
- * @param {number|null|undefined} [index]
- *   Index of `node` in `parent`.
- * @param {Parent|null|undefined} [parent]
- *   Parent of `node`.
+ *   A node.
+ * @param {number | null | undefined} [index]
+ *   The node’s position in its parent.
+ * @param {Parent | null | undefined} [parent]
+ *   The node’s parent.
  * @returns {node is Kind}
- *   Whether `node` matches.
+ *   Whether this node passes the test.
+ */
+
+/**
+ * @callback AssertAnything
+ *   Check that an arbitrary value is a node, unaware of TypeScript inferral.
+ * @param {unknown} [node]
+ *   Anything (typically a node).
+ * @param {number | null | undefined} [index]
+ *   The node’s position in its parent.
+ * @param {Parent | null | undefined} [parent]
+ *   The node’s parent.
+ * @returns {boolean}
+ *   Whether this is a node and passes a test.
  */
 
 /**
+ * Check if a node is a node and passes a certain node test.
+ *
  * @template {Node} Kind
+ *   Node type.
  * @callback AssertPredicate
- *   Check if a node is an element and passes a certain node test, using a
- *   TypeScript type predicate.
+ *   Check that an arbitrary value is a specific node, aware of TypeScript.
  * @param {unknown} [node]
- *   Thing to check and check that it’s a node.
- * @param {number|null|undefined} [index]
- *   Index of `node` in `parent`.
- * @param {Parent|null|undefined} [parent]
- *   Parent of `node`.
+ *   Anything (typically a node).
+ * @param {number | null | undefined} [index]
+ *   The node’s position in its parent.
+ * @param {Parent | null | undefined} [parent]
+ *   The node’s parent.
  * @returns {node is Kind}
- *   Whether `node` matches.
+ *   Whether this is a node and passes a test.
  */
 
 /**
- * Check if `node` passes a test.
- * When a `parent` node is given the `index` of node should also be given.
+ * Check if `node` is a `Node` and whether it passes the given test.
  *
  * @param node
- *   Node to check, can be anything.
+ *   Thing to check, typically `Node`.
  * @param test
- *   *   when nullish, checks if `node` is a `Node`.
- *   *   when `string`, works like passing `(node) => node.type === test`.
- *   *   when `array`, checks any one of the subtests pass.
- *   *   when `object`, checks that all keys in test are in node, and that they have (strictly) equal values.
- *   *   when `function` checks if function passed the node is true.
+ *   A check for a specific node.
  * @param index
- *   Position of `node` in `parent`, must be a number if `parent` is also given.
+ *   The node’s position in its parent.
  * @param parent
- *   Parent of `node`, must be given if `index` is also given.
- * @param context
- *   Context object to call `test` with
+ *   The node’s parent.
  * @returns
- *   Whether test passed and `node` is a `Node` (object with `type` set to
- *   non-empty `string`).
+ *   Whether `node` is a node and passes a test.
  */
 export const is =
   /**
    * @type {(
-   *   (<Kind extends Node>(node: unknown, test: Kind['type']|Partial<Kind>|TestFunctionPredicate<Kind>|Array<Kind['type']|Partial<Kind>|TestFunctionPredicate<Kind>>, index: number, parent: Parent, context?: unknown) => node is Kind) &
-   *   (<Kind extends Node>(node: unknown, test: Kind['type']|Partial<Kind>|TestFunctionPredicate<Kind>|Array<Kind['type']|Partial<Kind>|TestFunctionPredicate<Kind>>, index?: null|undefined, parent?: null|undefined, context?: unknown) => node is Kind) &
+   *   (() => false) &
+   *   (<Kind extends Node = Node>(node: unknown, test: PredicateTest<Kind>, index: number, parent: Parent, context?: unknown) => node is Kind) &
+   *   (<Kind extends Node = Node>(node: unknown, test: PredicateTest<Kind>, index?: null | undefined, parent?: null | undefined, context?: unknown) => node is Kind) &
    *   ((node: unknown, test: Test, index: number, parent: Parent, context?: unknown) => boolean) &
-   *   ((node?: unknown, test?: Test, index?: null|undefined, parent?: null|undefined, context?: unknown) => boolean)
+   *   ((node: unknown, test?: Test, index?: null | undefined, parent?: null | undefined, context?: unknown) => boolean)
    * )}
    */
   (
     /**
      * @param {unknown} [node]
      * @param {Test} [test]
-     * @param {number|null|undefined} [index]
-     * @param {Parent|null|undefined} [parent]
+     * @param {number | null | undefined} [index]
+     * @param {Parent | null | undefined} [parent]
      * @param {unknown} [context]
      * @returns {boolean}
      */
@@ -137,28 +146,27 @@ export const is =
   )
 
 /**
- * Create a test function from `test` that can later be called with a `node`,
- * `index`, and `parent`.
+ * Generate an assertion from a test.
+ *
  * Useful if you’re going to test many nodes, for example when creating a
- * utility where something else passes an is-compatible test.
+ * utility where something else passes a compatible test.
  *
- * The created function is slightly faster that using `is` because it expects
- * valid input only.
- * Therefore, passing invalid input yields unexpected results.
+ * The created function is a bit faster because it expects valid input only:
+ * a `node`, `index`, and `parent`.
  *
  * @param test
  *   *   when nullish, checks if `node` is a `Node`.
  *   *   when `string`, works like passing `(node) => node.type === test`.
- *   *   when `array`, checks any one of the subtests pass.
- *   *   when `object`, checks that all keys in test are in node, and that they have (strictly) equal values.
  *   *   when `function` checks if function passed the node is true.
+ *   *   when `object`, checks that all keys in test are in node, and that they have (strictly) equal values.
+ *   *   when `array`, checks if any one of the subtests pass.
  * @returns
- *   Check function that can be called as `check(node, index, parent)`.
+ *   An assertion.
  */
 export const convert =
   /**
    * @type {(
-   *   (<Kind extends Node>(test: Kind['type']|Partial<Kind>|TestFunctionPredicate<Kind>) => AssertPredicate<Kind>) &
+   *   (<Kind extends Node>(test: PredicateTest<Kind>) => AssertPredicate<Kind>) &
    *   ((test?: Test) => AssertAnything)
    * )}
    */
@@ -189,7 +197,7 @@ export const convert =
   )
 
 /**
- * @param {Array<Type|Props|TestFunctionAnything>} tests
+ * @param {Array<string | Props | TestFunctionAnything>} tests
  * @returns {AssertAnything}
  */
 function anyFactory(tests) {
@@ -220,8 +228,7 @@ function anyFactory(tests) {
 }
 
 /**
- * Assert each field in `test` is present in `node` and each values are strictly
- * equal.
+ * Turn an object into a test for a node with a certain fields.
  *
  * @param {Props} check
  * @returns {AssertAnything}
@@ -247,10 +254,9 @@ function propsFactory(check) {
 }
 
 /**
- * Convert a string into a function which checks a given node’s type
- * for said string.
+ * Turn a string into a test for a node with a certain type.
  *
- * @param {Type} check
+ * @param {string} check
  * @returns {AssertAnything}
  */
 function typeFactory(check) {
@@ -265,8 +271,7 @@ function typeFactory(check) {
 }
 
 /**
- * Convert a string into a function which checks a given node’s type
- * for said string.
+ * Turn a custom test into a test for a node that passes that test.
  *
  * @param {TestFunctionAnything} check
  * @returns {AssertAnything}
@@ -276,12 +281,18 @@ function castFactory(check) {
 
   /**
    * @this {unknown}
+   * @param {unknown} node
    * @param {Array<unknown>} parameters
    * @returns {boolean}
    */
-  function assertion(...parameters) {
-    // @ts-expect-error: spreading is fine.
-    return Boolean(check.call(this, ...parameters))
+  function assertion(node, ...parameters) {
+    return Boolean(
+      node &&
+        typeof node === 'object' &&
+        'type' in node &&
+        // @ts-expect-error: fine.
+        Boolean(check.call(this, node, ...parameters))
+    )
   }
 }
 

package.json

@@ -75,7 +75,7 @@
   },
   "remarkConfig": {
     "plugins": [
-      "preset-wooorm"
+      "remark-preset-wooorm"
     ]
   },
   "typeCoverage": {

test/main.js

@@ -94,7 +94,7 @@ test('unist-util-is', (t) => {
   t.test('should accept a test', (t) => {
     /**
      * @param {unknown} _
-     * @param {number|null|undefined} n
+     * @param {number | null | undefined} n
      * @returns {boolean}
      */
     function test(_, n) {
@@ -116,8 +116,8 @@ test('unist-util-is', (t) => {
     /**
      * @this {context}
      * @param {Node} a
-     * @param {number|null|undefined} b
-     * @param {Parent|null|undefined} c
+     * @param {number | null | undefined} b
+     * @param {Parent | null | undefined} c
      */
     function test(a, b, c) {
       t.equal(this, context)
@@ -142,8 +142,8 @@ test('unist-util-is', (t) => {
     /**
      * @this {context}
      * @param {Node} a
-     * @param {number|null|undefined} b
-     * @param {Parent|null|undefined} c
+     * @param {number | null | undefined} b
+     * @param {Parent | null | undefined} c
      * @returns {boolean}
      */
     function test(a, b, c) {