Improve generic types

[rossng]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

This PR improves the JSDoc types that come with unist-util-map.

The existing type of map is not generic. This is fine if you just want to map Nodes to Nodes, but painful if you want to do typesafe mapping of (e.g.) hast-specific node types in your TypeScript code. I came across this scenario while I was working on addressing some bugs in the rehype-twemojify plugin.

This PR updates the type of map to the following effective type:

function map<OutputNode extends Node<any> = Node<Data>, InputNode extends Node<any> = OutputNode>(tree: InputNode, iteratee: MapFunction<OutputNode, InputNode>): OutputNode

[rossng]

Thanks for the review 🙂 - I've applied your suggestions.

[wooorm]

The new behavior should be tested with tsd. Examples:

• https://github.com/syntax-tree/unist-util-visit/blob/main/index.test-d.ts
• https://github.com/syntax-tree/hast-util-is-element/blob/main/index.test-d.ts

It might be easier for generics to write a d.ts file manually, and use them in the JavaScript code. Examples:

• https://github.com/syntax-tree/unist-util-visit/blob/main/complex-types.d.ts
• https://github.com/syntax-tree/mdast-util-math/blob/main/complex-types.d.ts

[wooorm]

this one’s broken? (it apparently already was?)

[rossng]

The new behavior should be tested with tsd. Examples:

* https://github.com/syntax-tree/unist-util-visit/blob/main/index.test-d.ts

* https://github.com/syntax-tree/hast-util-is-element/blob/main/index.test-d.ts

It might be easier for generics to write a d.ts file manually, and use them in the JavaScript code. Examples:

* https://github.com/syntax-tree/unist-util-visit/blob/main/complex-types.d.ts

* https://github.com/syntax-tree/mdast-util-math/blob/main/complex-types.d.ts

Hmm, fair point. I did find it pretty tricky to get the types right with just JSDoc, and I'm still not totally happy. I'll take another pass at this later.

[rossng]

I spent some more time looking at this and came to the conclusion that it is extraordinarily difficult to type this function correctly. As such, I'm going to close this PR.

Here's about as far as I got. I just can't find a way to make the output type of the mapping function dependent on the input type - and I'm not 100% sure that it's actually possible.

/**
 * Function called with a node to produce a new node.
 *
 * @param node Current node being processed
 * @param index Index of `node`, or `null`
 * @param parent Parent of `node`, or `null`
 * @returns {OutputNode} Node to be used in the new tree. Its children are not used: if the original node has children, those are mapped.
 */
type MapFunction<
  InputNode extends Node<any> = Node,
  OutputNode extends Node<any> = Node
> = (
  node: InputNode,
  index: number | null,
  parent: Parent<InputNode> | null
) => OutputNode

type Foo<
  RootNode extends Node<any>,
  OutputNode extends Node<any>,
  MapFunctionAccumulator = MapFunction<RootNode, OutputNode>
> = RootNode extends Parent<infer InputChildNode>
  ? OutputNode extends Parent<infer OutputChildNode>
    ? MapFunctionAccumulator extends MapFunction<
        InputChildNode,
        OutputChildNode
      >
      ? MapFunctionAccumulator
      : Foo<
          InputChildNode,
          OutputChildNode,
          MapFunctionAccumulator & MapFunction<InputChildNode, OutputChildNode>
        >
    : MapFunction<RootNode, OutputNode>
  : MapFunction<RootNode, OutputNode>

[wooorm]

Yeah, this stuff can get really complex. And also slow. Not for the faint of heart. ;)
Thanks for trying your hand at this!