- Notifications
You must be signed in to change notification settings - Fork23
A repo containing notes about the TypeScript Compiler codebase
License
CC-BY-4.0, MIT licenses found
Licenses found
microsoft/TypeScript-Compiler-Notes
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This repo is a corpus of notes from many engineers over time on different systems inside the TypeScript codebase. It is not meant as a "one true" source of authoritative documentation for the TypeScript compiler API, but as a way to ease contributions to themicrosoft/TypeScript repo.
If you're already familiar with the TypeScript codebase and want to help out, we're open to external folks sending PRs improving or adding areas!
If you are completely new to the TypeScript codebase, this YouTube video covers all of the major systems involved in converting files to JavaScript, and type-checking types which will provide a high level guide to what you may be interested in focusing on:
If you are really short on time, here is a quick overview of the compilation process.
The process starts with preprocessing.The preprocessor figures out what files should be included in the compilation by following references (/// <reference path=... /> tags,require andimport statements).
The parser then generates ASTNodes.These are just an abstract representation of the user input in a tree format.ASourceFile object represents an AST for a given file with some additional information like the file name and source text.
The binder then passes over the AST nodes and generates and bindsSymbols.OneSymbol is created for each named entity.There is a subtle distinction but several declaration nodes can name the same entity.That means that sometimes differentNodes will have the sameSymbol, and eachSymbol keeps track of its declarationNodes.For example, aclass and anamespace with the same name canmerge and will have the sameSymbol.The binder also handles scopes and makes sure that eachSymbol is created in the correct enclosing scope.
Generating aSourceFile (along with itsSymbols) is done through calling thecreateSourceFile API.
So far,Symbols represent named entities as seen within a single file, but several declarations can merge multiple files, so the next step is to build a global view of all files in the compilation by building aProgram.
AProgram is a collection ofSourceFiles and a set ofCompilerOptions.AProgram is created by calling thecreateProgram API.
From aProgram instance aTypeChecker can be created.TypeChecker is the core of the TypeScript type system.It is the part responsible for figuring out relationships betweenSymbols from different files, assigningTypes toSymbols, and generating any semanticDiagnostics (i.e. errors).
The first thing aTypeChecker will do is to consolidate all theSymbols from differentSourceFiles into a single view, and build a single Symbol Table by "merging" any commonSymbols (e.g.namespaces spanning multiple files).
After initializing the original state, theTypeChecker is ready to answer any questions about the program.Such "questions" might be:
- What is the
Symbolfor thisNode? - What is the
Typeof thisSymbol? - What
Symbols are visible in this portion of the AST? - What are the available
Signatures for a function declaration? - What errors should be reported for a file?
TheTypeChecker computes everything lazily; it only "resolves" the necessary information to answer a question.The checker will only examineNodes/Symbols/Types that contribute to the question at hand and will not attempt to examine additional entities.
AnEmitter can also be created from a givenProgram.TheEmitter is responsible for generating the desired output for a givenSourceFile; this includes.js,.jsx,.d.ts, and.js.map outputs.
From there, you can start in theFirst Steps to Contributing to the TypeScript Repo consult theGlossary or dive directly into the./codebase/ or./systems/ folders.
One of the best places to ask questions is in the 'compiler-internals-and-api' channel of theTypeScript Community Discord.
- Learn how TypeScript works by reading themini-TypeScript implementation
- Basarat's guide to the Compiler Internals
- Recommended link for learning how compilers work:https://c9x.me/compile/bib/
If you learn better by seeing how big features are added to TypeScript, here are a few big well-scoped Pull Requests:
- Unions -microsoft/TypeScript#824
- Type Aliases -microsoft/TypeScript#957
- Async Functions -microsoft/TypeScript#3078
- TSX -microsoft/TypeScript#3564
- Intersection Types -microsoft/TypeScript#3622
- String Literal Types -microsoft/TypeScript#5185
- JS in TS -microsoft/TypeScript#5266
- Using JSDoc to extract types -microsoft/TypeScript#6024
- Nullable types -microsoft/TypeScript#7140
- Control Flow Analysis -microsoft/TypeScript#8010
- Mapped Types -microsoft/TypeScript#12114
- Rest Types -microsoft/TypeScript#13470
- Strict Functions -microsoft/TypeScript#18654
- Unknown -microsoft/TypeScript#24439
- Optional Chaining -microsoft/TypeScript#33294
- Node ESM Support -microsoft/TypeScript#45884
This project welcomes contributions and suggestions. Most contributions require you to agree to aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant usthe rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to providea CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructionsprovided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQ orcontactopencode@microsoft.com with any additional questions or comments.
Microsoft and any contributors grant you a license to the Microsoft documentation and other contentin this repository under theCreative Commons Attribution 4.0 International Public License,see theLICENSE file, and grant you a license to any code in the repository under theMIT License, see theLICENSE-CODE file.
Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentationmay be either trademarks or registered trademarks of Microsoft in the United States and/or other countries.The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks.Microsoft's general trademark guidelines can be found athttp://go.microsoft.com/fwlink/?LinkID=254653.
Privacy information can be found athttps://privacy.microsoft.com/en-us/
Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents,or trademarks, whether by implication, estoppel or otherwise.
About
A repo containing notes about the TypeScript Compiler codebase
Resources
License
CC-BY-4.0, MIT licenses found
Licenses found
Code of conduct
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Releases
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors8
Uh oh!
There was an error while loading.Please reload this page.