Change types to base what is returned on tree

Previously, to define what `filter` returned could only be done through
a TypeScript type parameter:

```js
// This used to work but no longer!
const result = filter<Heading>(tree, 'heading')
expectType<Heading | null>(result)
```

This did not look at `tree` at all (even if `tree` was hast, and as `Heading` is
mdast, it would yield `Heading | null`).
It also made it impossible to narrow types in JS.

Given that more and more of unist and friends is now strongly typed, we can
expect `tree` to be some kind of implementation of `Node` rather than the
abstract `Node` interface itself.
This commit changes to perform the test (`'heading'`) in the type system
and actually narrow down whether the inpu value matches `tree` or not.

This gives us:

```js
// This now works:
const tree: Root = {/* … */}

const result1 = filter(tree, () => Math.random() > 0.5)
expectType<Root | null>(result1)

const result2 = filter(tree, 'heading')
expectType<null>(result2)

const result3 = filter(tree, 'root')
expectType<Root>(result2)
```

Author: wooorm

.gitignore

@@ -1,5 +1,6 @@
-.DS_Store
-*.d.ts
-*.log
 node_modules/
 coverage/
+.DS_Store
+index.d.ts
+test.d.ts
+*.log

complex-types.d.ts

@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type {Node, Parent} from 'unist'
+
+type MatchesOne<Value, Check> =
+  // Is this a node?
+  Value extends Node
+    ? // No test.
+      Check extends null
+      ? Value
+      : // No test.
+      Check extends undefined
+      ? Value
+      : // Function test.
+      Check extends Function
+      ? Check extends (value: any) => value is infer Inferred
+        ? Value extends Inferred
+          ? Value
+          : null
+        : // This test function isn’t a type predicate.
+          Value | null
+      : // String (type) test.
+      Value['type'] extends Check
+      ? Value extends {type: Check}
+        ? Value
+        : Value | null
+      : // Partial test.
+      Value extends Check
+      ? Value
+      : null
+    : null
+
+export type Matches<Value, Check> =
+  // Is this a list?
+  Check extends any[]
+    ? MatchesOne<Value, Check[keyof Check]>
+    : MatchesOne<Value, Check>
+
+/* eslint-enable @typescript-eslint/ban-types */

index.js

@@ -1,12 +1,7 @@
-import {convert} from 'unist-util-is'
-
 /**
  * @typedef {import('unist').Node} Node
  * @typedef {import('unist').Parent} Parent
- *
- * @typedef {import('unist-util-is').Type} Type
- * @typedef {import('unist-util-is').Props} Props
- * @typedef {import('unist-util-is').TestFunctionAnything} TestFunctionAnything
+ * @typedef {import('unist-util-is').Test} Test
  */
 
 /**
@@ -16,25 +11,32 @@ import {convert} from 'unist-util-is'
  * @property {boolean} [cascade=true] Whether to drop parent nodes if they had children, but all their children were filtered out.
  */
 
+import {convert} from 'unist-util-is'
+
 const own = {}.hasOwnProperty
 
+/**
+ * Create a new tree consisting of copies of all nodes that pass test.
+ * The tree is walked in preorder (NLR), visiting the node itself, then its head, etc.
+ *
+ * @param tree Tree to filter.
+ * @param options Configuration (optional).
+ * @param test is-compatible test (such as a type).
+ * @returns Given `tree` or `null` if it didn’t pass `test`.
+ */
 export const filter =
   /**
    * @type {(
-   *  (<T extends Node>(node: Node, options: FilterOptions, test: T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>>) => T|null) &
-   *  (<T extends Node>(node: Node, test: T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>>) => T|null) &
-   *  ((node: Node, options: FilterOptions, test?: null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => Node|null) &
-   *  ((node: Node, test?: null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => Node|null)
+   *  (<Tree extends Node, Check extends Test>(node: Tree, options: FilterOptions, test: Check) => import('./complex-types').Matches<Tree, Check>) &
+   *  (<Tree extends Node, Check extends Test>(node: Tree, test: Check) => import('./complex-types').Matches<Tree, Check>) &
+   *  (<Tree extends Node>(node: Tree, options?: FilterOptions) => Tree)
    * )}
    */
   (
     /**
-     * Create a new tree consisting of copies of all nodes that pass test.
-     * The tree is walked in preorder (NLR), visiting the node itself, then its head, etc.
-     *
-     * @param {Node} tree Tree to filter
+     * @param {Node} tree
      * @param {FilterOptions} options
-     * @param {null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>} test is-compatible test (such as a type)
+     * @param {Test} test
      * @returns {Node|null}
      */
     function (tree, options, test) {

index.test-d.ts

@@ -1,13 +1,59 @@
-import {Node} from 'unist'
 import {expectType, expectError} from 'tsd'
-import {Heading} from 'mdast'
+import {Node} from 'unist'
+import {Root, Heading, Paragraph} from 'mdast'
 import {filter} from './index.js'
 
+const root: Root = {type: 'root', children: []}
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+const justANode = {type: 'whatever'} as Node
+const headingOrParagraph = {
+  type: 'paragraph',
+  children: []
+} as Heading | Paragraph
+/* eslint-enable @typescript-eslint/consistent-type-assertions */
+
 expectError(filter())
-expectType<Node | null>(filter({type: 'root'}))
-expectType<Node | null>(filter({type: 'root'}, 'root'))
-expectType<Node | null>(filter({type: 'root'}, {}, 'root'))
-expectError(filter({type: 'root'}, {notAnOption: true}, 'root'))
-expectType<Node | null>(filter({type: 'root'}, {cascade: false}, 'root'))
-expectType<Heading | null>(filter<Heading>({type: 'root'}, 'heading'))
-expectError(filter<Heading>({type: 'root'}, 'notAHeading'))
+expectType<Root>(filter(root))
+expectType<Root>(filter(root, 'root'))
+expectType<Root>(filter(root, {}, 'root'))
+expectError(filter(root, {notAnOption: true}, 'root'))
+expectType<Root>(filter(root, {cascade: false}, 'root'))
+expectType<null>(filter(root, 'heading'))
+expectType<null>(filter(root, {cascade: false}, 'notAHeading'))
+
+// Vague types.
+expectType<Heading | Paragraph>(filter(headingOrParagraph))
+expectType<Paragraph | null>(filter(headingOrParagraph, 'paragraph'))
+expectType<null>(filter(headingOrParagraph, 'notAHeading'))
+expectType<Heading | null>(
+  filter(headingOrParagraph, {cascade: false}, 'heading')
+)
+
+expectType<Heading | Paragraph | null>(
+  filter(headingOrParagraph, {cascade: false}, () => Math.random() > 0.5)
+)
+
+expectType<Heading | null>(
+  filter(
+    headingOrParagraph,
+    {cascade: false},
+    (node: Node): node is Heading => node.type === 'heading'
+  )
+)
+
+// Abstract types.
+// These don’t work well.
+// Use strict nodes types.
+expectType<Node>(filter(justANode))
+expectType<null>(filter(justANode, '???'))
+expectType<null>(filter(justANode, {cascade: false}, '???'))
+expectType<Node | null>(
+  filter(justANode, {cascade: false}, () => Math.random() > 0.5)
+)
+expectType<null>(
+  filter(
+    justANode,
+    {cascade: false},
+    (node: Node): node is Heading => node.type === 'heading'
+  )
+)

package.json

@@ -29,12 +29,14 @@
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
+    "complex-types.d.ts",
     "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "@types/unist": "^2.0.0",
-    "unist-util-is": "^5.0.0"
+    "unist-util-is": "^5.0.0",
+    "unist-util-visit-parents": "^5.0.0"
   },
   "devDependencies": {
     "@types/mdast": "^3.0.0",
@@ -53,7 +55,7 @@
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"*.d.ts\" && tsc && tsd && type-coverage",
+    "build": "rimraf \"{index,test}.d.ts\" && tsc && tsd && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
@@ -78,6 +80,11 @@
   "typeCoverage": {
     "atLeast": 100,
     "detail": true,
-    "strict": true
+    "strict": true,
+    "ignoreCatch": true,
+    "#": "needed `any`s",
+    "ignoreFiles": [
+      "complex-types.d.ts"
+    ]
   }
 }