dsherret / dsherret/ts-morph

Documentation request: Nodes, Types, and Symbols primer

Open
#1,302 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
6.2k
Forks
238
Avg merge
2m
Merged PRs (30d)
1

Description

**Is your feature request related to a problem? Please describe.**

I'm new to ts-morph (I found out about it this week). I didn't even know it existed to solve a few problems I've had for a few weeks. I've never worked with the TypeScript compiler API directly. So I'm finding myself a bit lost trying to figure out what these various artifacts are and how to navigate from one to the others, and use them.

For instance, I kept seeing `Symbol` in `node_modules/ts-morph/lib/ts-morph.d.ts`, and I was confused for hours, thinking it literally meant [Symbol from ECMAScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). It has a totally different meaning here.

**Describe the solution you'd like**

Could someone (I'm willing, but not knowledgeable enough) add a short primer page somewhere under Navigation explaining what these three classes (`Node`, `Type` and `Symbol`) are, and in particular how to go from one to the others at a high level? Examples would be very nice.

For instance, I just discovered that two `Node` instances can point to the same `Type` instance. This makes sense, but I didn't know whether it would be that way or not.

When writing up this issue, I discovered [TypeScript's Compiler Glossary](https://github.com/microsoft/TypeScript-Compiler-Notes/blob/main/GLOSSARY.md), which might've also cleared up some things. Providing a link from this project back to that page is probably a good idea.

One particular use case I have is with mapped types:
```typescript
// Some interface I imported from elsewhere.
interface NumberStringType {
repeatForward(s: string, n: number): string;
repeatBack(n: number, s: string): string;

type: string;

// ... several other methods I don't control
}

/*
type Parameters any> = T extends (...args: infer P) => any ? P : never;
type ReturnType any> = T extends (...args: any) => infer R ? R : any;
*/

type ExtendedObjectType = {
[K in keyof T]: T[K] extends (...args: infer P) => infer R ?
(extra: E, ...args: P) => R :
T[K]
}

export type ExtendedNumberStringType = ExtendedObjectType;
```

I've been trying to figure out how to extract the properties, with full method signatures, of `ExtendedNumberStringType`. I want to _see_ the `extra` argument in place along with the other arguments, in the `repeatForward` and `repeatBack` methods.

Please note that while I am trying to learn how to use ts-morph, my goal here is not to get these answers just for myself, but to get it written down so others can learn about it too.

**Describe alternatives you've considered**

I started this whole mess by looking at TypeScript-eslint's parser project, and I got pretty far. Then I bumped into the mapped types and realized that I'd have to basically reimplement key parts of TypeScript's type checking... or I could just ask for help working with the TypeScript compiler API. So [I did that on Discord](https://discord.com/channels/508357248330760243/640177429775777792/991729666593402881)... and they introduced me to ts-morph. This project could actually solve a couple other use cases I have as well (generating TypeScript code).

Side note: ts-morph comes up a lot in the TypeScript Community Discord. I'd suggest requesting a community channel specifically for ts-morph as well, perhaps under Tooling.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.