docs: add guide for working with syntax trees in TypeScript

[ChristianMurphy]

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 provides an overview of the packages around the Unified ecosystem that makes working with syntax trees easier.
Specifically focusing on:

• The basic syntax tree types
• How to include syntax tree typings for a specific language
• How to traverse a syntax tree
• How to narrow generic Nodes to specific syntax types
• How to build a syntax tree

---

rendered version

---

📓 This does not cover how to type a Plugin in TypeScript or TypeScript+JSDoc, my current thought is that would be small enough and distinct enough to be recipe(s)

[ChristianMurphy]

/cc @remcohaszing @JounQin

[wooorm]

Great start! I think this covers the things that TS folks will wonder about and we can link to from issues.

Some initial small suggestions inline, then the following two points:

• Running npm install and npm run format will check grammar/spelling/punctuation and the like. One example is I see a couple long, complex sentences, that that should warn about. npm run generate should also work, without crawling, to preview the page.

• The code examples seem to not match this projects style. I have Atom set up to format with xo and prettier on save, so what I do is to save e.g. a .ts extension as example.ts, and copy the formatted result into the markdown.

---

Finally, there are many things yelling for attention in this guide currently: casing, links, headings, a lot of inline code, a lot of fenced code. In comparison, very few things are just plain prose. I think it’s good to pass through the text again to highlight the important parts (for the user, in each section) with inline code/links, and lowlight some other parts!

[JounQin]

Should we wait DefinitelyTyped/DefinitelyTyped#54413 first so that the guide could be better to use generic types?

[wooorm]

@JounQin What would that change in this guide?

[JounQin]

@wooorm Guide to use generic types for better Node#data type, Literal#value or Parent#children, etc.

// before
export interface StringLiteral extends Literal {
  value: string
}

// after
export interface StringLiteral extends Literal<string> {
}

// or
export type StringLiteral = Literal<string>

[wooorm]

Such, or similar, behavior is not mentioned in this guide, so I don’t see a need to wait for it?

As I understand it, 54413 focusses on unist and making it easier to create things like @types/mdast/@types/hast/@types/xast.
This guide focusses on how to use @types/mdast/@types/hast/@types/xast.

[JounQin]

It can also be used by end user for simple usage.

// before
declare const parent: Parent

const children = parent.children as Literal[] // error now

// after
declare const parent: Parent<Literal>

const children = parent.children // alreay `Literal[]`

[wooorm]

I don‘t see any practical reasons for end users to do that.

To repeat from the other threads, I don’t think end users should do that.
They’re supposed to use mdast/hast/xast types.

[wooorm]

On the conversation earlier between @JounQin and me: I can see some value in explaining how to type custom nodes. Especially with @remcohaszing new registry’s

[ChristianMurphy]

Running npm install and npm run format will check grammar/spelling/punctuation and the like. One example is I see a couple long, complex sentences, that that should warn about. npm run generate should also work, without crawling, to preview the page.

Done

The code examples seem to not match this projects style. I have Atom set up to format with xo and prettier on save, so what I do is to save e.g. a .ts extension as example.ts, and copy the formatted result into the markdown.

I checked the examples with prettier and XO using a new file and npm run format, they do appear to match your preferred code style as is? 🤔

Finally, there are many things yelling for attention in this guide currently: casing, links, headings, a lot of inline code, a lot of fenced code. In comparison, very few things are just plain prose. I think it’s good to pass through the text again to highlight the important parts (for the user, in each section) with inline code/links, and lowlight some other parts!

I'm confused by this.
There are too many things yelling for attention, and the solution is to add more of the things yelling for attention? 😅

I can see some value in explaining how to type custom nodes. Especially with @remcohaszing new registry’s

🤔 do you see this being a part of the basic syntax trees with TypeScript guide?
Or more being an advanced guide or a recipe?

[wooorm]

🤔 do you see this being a part of the basic syntax trees with TypeScript guide?
Or more being an advanced guide or a recipe?

Maybe. At least the discussions shows me that there’s something somewhere we should explain.
While not very common, remark + micromark extensions are a thing.
And custom nodes are useful in certain cases, whether it’s remark/rehype/etc.

There are too many things yelling for attention, and the solution is to add more of the things yelling for attention? 😅

I mean to lowlight most, and highlight less. But definitely highlight certain important parts.
e.g., I think `Node` and such could be code in certain cases, but after a while just using the word node is fine.

[wooorm]

I checked the examples with prettier and XO using a new file and npm run format, they do appear to match your preferred code style as is? 🤔

Specifically I saw the indent at 4 instead of 2 spaces?
And some double quote use, instead of single quotes

[ChristianMurphy]

I mean to lowlight most, and highlight less. But definitely highlight certain important parts.
e.g., I think Node and such could be code in certain cases, but after a while just using the word node is fine.

Updated to lessen amount of inline type and Node highlights.

Specifically I saw the indent at 4 instead of 2 spaces?
And some double quote use, instead of single quotes

Updated in 0119321 and b4423ee, double quotes remain in jsx examples as prettier/xo appear to still prefer them in that context.

[wooorm]

Nice! I’ll do another whole review tomorrow!

[ChristianMurphy]

To @JounQin's points in #36 (comment) and #36 (comment) I see both of those potentially having value.

My intent with this first guide is focused more on people interested in adopting unified with remark.
It shows how to use unified, remark, mdast, etc but don't go much into how to customize them or publish a utility/module.

I could see several related topic focused more on maintaining or customizing unified, having their own recipes or guides.
Including but not limited to:

• Publishing a pure TS unified plugin
• Publishing a JSDoc based unified plugin
• Adding custom node types
• Testing plugin/syntax tree typings

[ChristianMurphy]

Another idea, I'm not quite sure where to slot this in the guide, would be covering some recommended tsconfig.json options.
In particular:

• "module": "es6" and "moduleResolution": "node" are needed to work with ESM
• "strict": true while not required, helps find more potential issues
• "allowJs": true and "checkJs": true are needed for TypeScript in JSDoc mode

[wooorm]

Nice!!!

Alright, I did a pass of the whole document.
I do think my suggestions are useful compared to the current text, but they’re perfect: please take them and amend them where appropriate

[ChristianMurphy]

#36 (comment), closing this in favor of #37