types: revist transformer typescript interface

[ChristianMurphy]

Subject of the feature

Update the Transformer interface to better reflect the types being passed in.

Problem

Transformer expects to receive exactly a unist Node

unified/types/index.d.ts

Lines 296 to 316 in e408747

	/**
	* Transformers modify the syntax tree or metadata of a file. A transformer is a function which is invoked each time a file is passed through the transform phase.
	* If an error occurs (either because it’s thrown, returned, rejected, or passed to `next`), the process stops.
	*
	* The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers.
	*
	* @param node Node or tree to be transformed
	* @param file File associated with node or tree
	* @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`.
	* @returns
	* - `Error` — Can be returned to stop the process
	* - `Node` — Can be returned and results in further transformations and `stringify`s to be performed on the new tree
	* - `Promise` — If a promise is returned, the function is asynchronous, and must be resolved (optionally with a `Node`) or rejected (optionally with an `Error`)
	*/
	interface Transformer {
	(
	node: Node,
	file: VFile,
	next?: (error: Error | null, tree: Node, file: VFile) => {}
	): Error | Node | Promise<Node>
	}

When in most cases parsers will return a RootNode which extends ParentNode which adds an extra children attribute that Node does not expect.

remark ran into a similar issue to this with the visitor interface, see remarkjs/remark#426

Expected behaviour

Ideally avoid requiring as casting the node parameter.

Alternatives

1. do nothing, casting may be an okay option
2. use a generic <T extends Node> to guarantee the incoming node is a super type of Node, though it may or may not reflect the correct super type.
3. Allow Processor to accept a generic of all possible types (E.G. all mdast nodes) and pass that generic type union in (Open question: How would plugins add new types to the union?)
4. Other ideas?

[ChristianMurphy]

After trying out unist-util-visit with type predicates.
I'm leaning towards not changing this.
unist-util-visit and unist-util-is (along with the many other utilities) can provide easy ways to manipulate the Node/tree without sacrificing type safety.