typings: visitor typings for remark-stringify

[ChristianMurphy]

Subject of the feature

Give visitors a type safe way to depend on super types of unist node

Problem

In this example

function gap(this: unified.Processor) {
  const Compiler = this.Compiler as typeof remarkStringify.Compiler
  const visitors = Compiler.prototype.visitors
  const original = visitors.heading

  visitors.heading = heading

  function heading(this: unified.Processor, node: Node, parent?: Parent) {
    // FIXME: remove need for explicit 'as' casting
    const headingNode = node as (Node & {depth: number})
    return (
      (headingNode.depth === 2 ? '\n' : '') +
      original.apply(this, [node, parent])
    )
  }
}

const plugin: unified.Attacher = gap

to get a HeadingNode from the visitor it needs to be cast as (Node & {depth: number}).
Which reduces the type safety since any property can be added in the {} block and typescript will accept it.

Expected behaviour

header should automatically of type HeaderNode

function gap(this: unified.Processor) {
  const Compiler = this.Compiler as typeof remarkStringify.Compiler
  const visitors = Compiler.prototype.visitors
  const original = visitors.heading

  visitors.heading = heading

  function heading(this: unified.Processor, node: HeaderNode, parent?: Parent) {
    return (
      (headingNode.depth === 2 ? '\n' : '') +
      original.apply(this, [node, parent])
    )
  }
}

const plugin: unified.Attacher = gap

This should be safe, because the visitors are staticly defined ahead of time.

remark/packages/remark-stringify/lib/compiler.js

Lines 37 to 63 in acada43

	proto.visitors = {
	root: require('./visitors/root'),
	text: require('./visitors/text'),
	heading: require('./visitors/heading'),
	paragraph: require('./visitors/paragraph'),
	blockquote: require('./visitors/blockquote'),
	list: require('./visitors/list'),
	listItem: require('./visitors/list-item'),
	inlineCode: require('./visitors/inline-code'),
	code: require('./visitors/code'),
	html: require('./visitors/html'),
	thematicBreak: require('./visitors/thematic-break'),
	strong: require('./visitors/strong'),
	emphasis: require('./visitors/emphasis'),
	break: require('./visitors/break'),
	delete: require('./visitors/delete'),
	link: require('./visitors/link'),
	linkReference: require('./visitors/link-reference'),
	imageReference: require('./visitors/image-reference'),
	definition: require('./visitors/definition'),
	image: require('./visitors/image'),
	footnote: require('./visitors/footnote'),
	footnoteReference: require('./visitors/footnote-reference'),
	footnoteDefinition: require('./visitors/footnote-definition'),
	table: require('./visitors/table'),
	tableCell: require('./visitors/table-cell')
	}

[ChristianMurphy]

This is a continuation of #383 (comment)

Some previously discussed solutions

---

One option would be a generic.
Something like

  interface Transformer<I extends Node = Node, O extends Node = Node> {
    (
      node: I,
      file: VFileCompatible,
      next?: (error: Error | null, tree: O, file: VFile) => {}
    ): Error | O | Promise<O>
  }

Which would guarantee that the input and the output are a super type of a unist Node.
But could not guarantee that type I matches what the previous plugin output, meaning it would be possible for JavaScript errors to slip through the typings.

---

Another would be to add a generic to Processor, and set that generic to a union of all types for the give language.
For example

type AllUnifiedTypes = Node | Parent
const unifiedProcessor = unified<Settings, AllUnifiedTypes>

type AllRemarkTypes = List | ListItem | Table | ...
const remarkProcessor = unified<Settings, AllRemarkTypes>

But then there would be the question of how do plugins participate in the supported node typings?
And how are transitions between languages, like mdast to hast, handled?

[wooorm]

@ChristianMurphy Is this actionable, and useful enough?

[ChristianMurphy]

Actionable, yes.
Useful, a bit.
This got a lot easier to work around, now that unist-util-is has typings.
It would still be nice to have here, save an extra step.

[wooorm]

We don’t have visitors anymore, so I’ll close this. Type changes can be done to mdast-util-to-markdown.