Add generic type parameter to infer parameters

Author: wooorm

index.js

@@ -1,18 +1,24 @@
 /**
- * @typedef {import('unist').Parent} Parent
- * @typedef {import('unist').Node} Node
- *
+ * @typedef {import('unist').Parent} UnistParent
+ * @typedef {import('unist').Node} UnistNode
+ */
+
+/**
+ * @template {UnistParent} Parent
  * @callback Modifier
  *   Callback called for each `child` in `parent` later given to `modify`.
- * @param {Node} node
+ * @param {Parent['children'][number]} node
  *   Child of `parent`.
  * @param {number} index
  *   Position of `child` in `parent`.
  * @param {Parent} parent
  *   Parent node.
  * @returns {number|void}
  *   Position to move to next.
- *
+ */
+
+/**
+ * @template {UnistParent} Parent
  * @callback Modify
  *   Modify children of `parent`.
  * @param {Parent} node
@@ -27,15 +33,16 @@ import {arrayIterate} from 'array-iterate'
  * Wrap `modifier` to be called for each child in the nodes later given to
  * `modify`.
  *
- * @param {Modifier} modifier
+ * @template {UnistParent} Parent
+ * @param {Modifier<Parent>} modifier
  *   Callback called for each `child` in `parent` later given to `modify`.
- * @returns {Modify}
+ * @returns {Modify<Parent>}
  *   Modify children of `parent`.
  */
 export function modifyChildren(modifier) {
   return modify
 
-  /** @type {Modify} */
+  /** @type {Modify<UnistParent>} */
   function modify(parent) {
     if (!parent || !parent.children) {
       throw new Error('Missing children in `parent` for `modifier`')
@@ -48,7 +55,7 @@ export function modifyChildren(modifier) {
    * Pass the context as the third argument to `modifier`.
    *
    * @this {Parent}
-   * @param {Node} node
+   * @param {UnistNode} node
    * @param {number} index
    */
   function iteratee(node, index) {

index.test-d.ts

@@ -0,0 +1,61 @@
+import {expectError, expectType} from 'tsd'
+import type {Node, Parent, Literal} from 'unist'
+import {modifyChildren} from './index.js'
+
+/* eslint-disable @typescript-eslint/consistent-type-definitions */
+
+/* Setup */
+const sampleTree: Root = {
+  type: 'root',
+  children: [{type: 'heading', depth: 1, children: []}]
+}
+
+type Content = Flow | Phrasing
+
+interface Root extends Parent {
+  type: 'root'
+  children: Flow[]
+}
+
+type Flow = Blockquote | Heading | Paragraph
+
+interface Blockquote extends Parent {
+  type: 'blockquote'
+  children: Flow[]
+}
+
+interface Heading extends Parent {
+  type: 'heading'
+  depth: number
+  children: Phrasing[]
+}
+
+interface Paragraph extends Parent {
+  type: 'paragraph'
+  children: Phrasing[]
+}
+
+type Phrasing = Text | Emphasis
+
+interface Emphasis extends Parent {
+  type: 'emphasis'
+  children: Phrasing[]
+}
+
+interface Text extends Literal {
+  type: 'text'
+  value: string
+}
+
+/* Missing params. */
+expectError(modifyChildren())
+
+modifyChildren((node, _, parent: Emphasis) => {
+  expectType<Phrasing>(node)
+})
+
+modifyChildren((node, _, parent: Root) => {
+  expectType<Flow>(node)
+})
+
+/* eslint-enable @typescript-eslint/consistent-type-definitions */

package.json

@@ -44,13 +44,14 @@
     "remark-preset-wooorm": "^9.0.0",
     "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "tsd": "^0.24.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "xo": "^0.52.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"*.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",

readme.md

@@ -123,7 +123,7 @@ Call the bound [`modifier`][modifier] for each child in `parent`
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `Modifier` and `Modify`.
+It exports the additional types `Modifier<Parent>` and `Modify<Parent>`.
 
 ## Compatibility