Help needed on how to type custom rehype plugin

[jnahumphreys]

Hi,

I'm having trouble understanding how to correctly type a custom rehype plugin. I've read through the docs, specifically the use of the <Plugin> generic, but it is not working as I expected.

I've looked through many rehype and remark plugins to try and understand how to do this, I have also reviewed existing discussions, including here) - I am now reaching out to the community for help as I've exhausted all other avenues.

Below is my current plugin implementation, I've had to resort to typing the exported plugin rehypeListHeadings, however I suspect this should be typed using the Plugin generic exported from unified.

Thanks in advance

import { visit } from "unist-util-visit";
import { headingRank } from "hast-util-heading-rank";
import { heading } from "hast-util-heading";
import { VFileWithOutput } from "unified";
import { toString } from "hast-util-to-string";
import type { Element, Root } from "hast";
import type { Data } from "unist";

export interface HeadingData {
  level: number | null;
  id: string | null;
  value: string;
}

function getHeadingsData(tree: Root) {
  const headingData: HeadingData[] = [];

  visit(tree, "element", (node: Element) => {
    if (heading(node)) {
      const headingId = node.properties?.id;

      headingData.push({
        level: headingRank(node),
        id: headingId ? headingId.toString() : null,
        value: toString(node),
      });
    }
  });

  return headingData;
}

function rehypeListHeadings(): (
  tree: Root,
  file: VFileWithOutput<Data>
) => void {
  return (tree, file) => {
    file.data.headings = getHeadingsData(tree);
  };
}

export { rehypeListHeadings };

[wooorm]

1. plugins use default exports, not named exports: export default function rehypeListHeadings
2. your suspicion is right, the type of your plugin is import('unified').Plugin<void[], Root>
3. If you had options, the type would be import('unified').Plugin<[Options?], Root>

[jnahumphreys]

@wooorm Thanks for the prompt reply (and hint on the default export), really appreciated!

I think I may had misunderstood the docs, I was typing my plugin as follows, TypeScript reports errors for the return function parameters.

Is this the incorrect way to use the <Plugin> generic to type my plugin?

// rest of code truncated but as per above example
import type { Root } from "hast";
import { Plugin } from "unified";

function rehypeListHeadings(): Plugin<void[], Root> {
  return (tree, file) => {
    file.data.headings = getHeadingsData(tree);
  };
}

[wooorm]

I think TS written like that means that the return value is such a plugin. Which it isn’t.
Arrow functions allow types:

const someRehypePlugin: Plugin<void[], Root> = () => { …

The generic is the preferred way. But sometimes TS can infer things well enough:

function rehypeListHeadings() {
  return (tree: Root, file: VFile) => {
    file.data.headings = getHeadingsData(tree);
  };
}

[jnahumphreys]

Now it makes sense; indeed, I thought the returned function was the plugin (hence using the generic there)!

Thanks again for all you help.

[remcohaszing]

I prefer to use the Plugin type as stated by @wooorm, but I would like to add that the following alternative works too:

import { Root } from 'hast'
import { Transformer } from 'unified'

function rehypeListHeadings(): Transformer<Root> {
  return (tree, file) => {}
}

[jnahumphreys]

@remcohaszing - Thanks, went with that option in the end - a good compromise for me and a lot cleaner