typescript-compiler-docs

UPDATE : we have offical docs now! : https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API

A work in progress documentation of how the TypeScript compiler works.

Running tests

Best way I have found is to :

./node_modules/mocha/bin/mocha -R dot -g nodeModules --colors  -t 20000 built/local/run.js

The official greping jake runtests test=nodeModules didn't work (though test=project does work).

Also see : https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md

Baselines And use jake diff with beyond compare. set DIFF=C:\Program Files (x86)\Beyond Compare 3\BComp.exe Its just a folder compare between baselines/local and baselines/reference

Useful PRs with Insight

Missing try block with a catch / finally

https://github.com/Microsoft/TypeScript/pull/262/files Parser : Gives information about the isStatement function. If that function returns then parseStatement will get called which must return some type of Statement. In this case we are going to return a TryStatement from a utility parseCatchOrFinallyBlocksMissingTryStatement function. These utility (parse-) functions apparently prepare the AST for the emitter by creating (createNode function) and finishing Nodes (finishNode function).

Parsing logic for Object Literals

https://github.com/Microsoft/TypeScript/pull/273/files Parser : parseObjectLiteral is used to parse object literals. parseDelimitedList is used to parse the properties of object literals.

Reference tag lookup

https://github.com/Microsoft/TypeScript/pull/365/files Changed to load extensionless reference tags (.d.ts and .ts)

Fast compilation on watch

microsoft/TypeScript#324 Basically create a copy of the program and update it based on changes. Mostly inside tc.ts the recompile function.

Language Service

Initial port of the language service

microsoft/TypeScript#303

Pull model for contextual types

microsoft/TypeScript#330 getContextualType function by anders

Emitter

The class emit

https://github.com/Microsoft/TypeScript/pull/331/files change the order of this emit in class body. emitClassDeclaration

Emitter / checker for .d.ts files

microsoft/TypeScript#414 Declaration file needs to always emit typeof function/static function instead of emitting signature

File extension for emit different from '.js'

Ability to modify the output filename extension microsoft/TypeScript#425

Checker

Change the order in which the functions are checked in overloads

microsoft/TypeScript#378

 interface A { (x: string): void }
 interface B { (x: 'foo'): string }
 var b: B;
 b('foo') // <- here overloads should be processed as [(x:'foo'): string, (x: string): void]

Tutorials

hacking it to add a documentation emitter http://www.codeproject.com/Articles/635280/TypeScript-Compiler-Documentation-Output

More language service

An overview of a file in terms of lexical structure : microsoft/TypeScript#534

Various Classifer

microsoft/TypeScript#1477 (comment)

Walking the syntax Tree

Uses the ts.forEachChild exported from the parser. Helpful information from this comment. Note how the Node is augmented by services here

Demo : http://blog.ctaggart.com/2015/01/typescript-14-ast-from-nodejs.html

Things on nodes only get written once

microsoft/TypeScript#1514 (comment)

Some Terminal nodes are not in the AST

They can be "rehydrated" on demand using the sourcetext by calling getChildren() microsoft/TypeScript#1514 (comment)

Formatting your documents

In the language service microsoft/TypeScript#1651 (comment)

• getFormattingEditsForRange
• getFormattingEditsAfterKeystroke
• getFormattingEditsForDocument for getFormattingEditsForDocument once you've gotten the appropriate edits ranges, you can easily apply them in reverse and fix up the original source text.

Once you have them you can apply them in reverse : microsoft/TypeScript#1651 (comment)

function formatCode(orig: string, changes: TextChange[]): string {
    var result = orig;

    for (var i = changes.length - 1; i >= 0; i--) {
        var change = changes[i];
        var head = result.slice(0, change.span.start);
        var tail = result.slice(change.span.start + change.span.length)
        result = head + change.newText + tail;
    }

    return result;
}

Demo : http://blog.ctaggart.com/2015/01/format-typescript-with-v14-language.html There is also smart indentation alone: microsoft/TypeScript#1754

Support JSX

You can convert JSX to JavaScript using the API from : https://www.npmjs.com/package/react-tools JSX Specification : http://facebook.github.io/jsx/ How to augment: facebook/react#759 (comment)

Skipped tokens by the new foreachchild AST traversal

microsoft/TypeScript#1728 (comment)

Program vs. Language Service

languageService and program are very similar in principal. Which you use depends on your scenario.

program is great if you just want emit / linting, the os related features can be provided with a compilerHost generated with a simple call to createCompilerHost. Examples : https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#a-minimal-compiler and https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#traversing-the-ast-with-a-little-linter

languageService is great if want something like a full blown IDE support.

More on the difference:

microsoft/TypeScript#1786 (comment)

a singe LanguageService object does not map to a single Program object, it actually maps to a set of them. A Program is an immutable object, the LanguageService on the other hand handles changes. under the covers, the LanguageService, on every change, creates a new Program instance to map to the current context, but uses the previous Program instance's unchanged SourceFiles to save computation. If the LanguageService was just an extension over Program, you would need to create a new LanguageService object on every change.

Expand the list of files knows by language service

LanguageService.getProgram().getSourceFiles() More https://github.com/Microsoft/TypeScript/commit/9628191a1476bc0dbdb28bfd30b840656ffc26a3#commitcomment-9490325

Langauge service is just a wrapper on program and a thin one :

e.g. getQuickInfoAtPosition and getCompletionsAtPosition microsoft/TypeScript#2105 (comment)

Useful blog post on using program

http://www.scottlogic.com/blog/2015/01/20/typescript-compiler-api.html

Why the compielr AST is different from Mozilla AST

microsoft/TypeScript#1690 (comment)

Formatting JSX

https://github.com/Microsoft/TypeScript/pull/4330/files smartformatter.ts + test

Incremental parsing call stack insight

microsoft/TypeScript#7310 about currentNode and canReuseNode https://github.com/Microsoft/TypeScript/blob/release-1.8/src/compiler/parser.ts#L1463

How to tell a const / let declaration

microsoft/TypeScript#22681 (comment)