The TsReflect compiler is a modified version of the TypeScript 1.4 compiler that emits JSON declaration files containing type information for your TypeScript source files. The JSON declaration files are similar to the .d.ts declaration files that TypeScript generates. However, the JSON format allows for easier loading of type information at runtime. Additionally, the compiler leverages JsDoc comments to add custom annotations to TypeScript. See the Custom Annotations section below for more information.

On the Node platform, JSON declaration files may be consumed using the tsreflect module.

The TsReflect Compiler can be installed using the Node Package Manager (npm):

npm install tsreflect-compiler

node lib/tsreflect-compiler.js hello.ts

Below is an example of a simple global class declaration for a Calculator class containing a single method add. For more example output, take a look at the JSON declaration file generated for lib.core.d.ts.

{
	"declares": [
		{
			"kind": "class",
			"name": "Calculator",
			"members": [
				{
					"kind": "method",
					"name": "add",
					"parameters": [
						{
							"name": "x",
							"type": "number"
						},
						{
							"name": "y",
							"type": "number"
						}
					],
					"returns": "number"
				}
			]
		}
	]
}

The TsReflect Compiler leverages JsDoc comments to add custom annotations to TypeScript. Similar to java annotations or C# attributes custom annotations allow for metadata to be added to TypeScript source code and then included in the JSON declaration files that the TsReflect Compiler generates.

Custom annotation work alongside standard JsDoc annotations. The TsReflect compiler will ignore all standard JsDoc annotations. The tsreflect.config.json file in the lib/ directory contains a list of ignored annotations. This list can be modified to suite your needs.

For example, custom annotations can be used to add JPA-style annotations to classes for an ORM:

/**
 * An entity for a Customer.
 * @entity
 * @table "customers"
 */
class Customer {

    /** @id */
    id: number;

    /**
     * The name of the customer.
     * @column name: "customer_name", length: 255
     */
    name: string;
}

The above TypeScript generates the following JSON declaration output:

{
	"declares": [
		{
			"kind": "class",
			"name": "Customer",
			"description": "An entity for a Customer.",
			"annotations": [
				{
					"name": "entity",
					"value": true
				},
				{
					"name": "table",
					"value": "customers"
				}
			],
			"members": [
				{
					"kind": "field",
					"name": "id",
					"type": "number",
					"annotations": [
						{
							"name": "id",
							"value": true
						}
					]
				},
				{
					"kind": "field",
					"name": "name",
					"type": "string",
					"description": "The name of the customer.",
					"annotations": [
						{
							"name": "column",
							"value": {
								"name": "customer_name",
								"length": 255
							}
						}
					]
				}
			]
		}
	]
}

There is a Grunt plug-in available for the TsReflect compiler to allow for generating JSON declaration files as part of a Grunt build process. See the grunt-tsreflect project.

There is a Gulp plug-in available for the TsReflect compiler to allow for generating JSON declaration files as part of a Gulp build process. See the gulp-tsreflect project.

The TsReflect compiler can be included as a CommonJS module in a NodeJS application. A typescript declaration file tsreflect-compiler.d.ts is included in the lib directory. Below is an example of executing the compiler from a TypeScript program.

/// <reference path="./lib/tsreflect-compiler.d.ts" />
import compiler = require("tsreflect-compiler");

var options = {
    outDir: 'build/'
}
var diagnostics = compiler.compile("./hello.ts", options);

Executing the code above will generate a file called hello.d.json in the build directory. Any errors will be returned as an array and assigned to the diagnostics variable.

• compile
• CompilerOptions
• CompilerHost
• Diagnostic
• DiagnosticCategory