Documentation request: Nodes, Types, and Symbols primer
- 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
Assessment
This issue has not been assessed yet.