artifacthealth/tsreflect-compiler

Generate TypeScript declaration files in JSON format for runtime type information.

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.

NOTE! Currently, there are not any plans to support any version of TypeScript beyond 1.4. If in the future the TypeScript compiler supports an extensible emitter, this project will be picked up again.

Installation

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

npm install tsreflect-compiler

Usage

node lib/tsreflect-compiler.js hello.ts

Example Output

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"
                }
            ]
        }
    ]
}

Custom Annotations

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
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Grunt Plug-in

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.

Gulp Plug-in

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.

CommonJS Module

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.

Documentation

• compile
• CompilerOptions
• CompilerHost
• Diagnostic
• DiagnosticCategory

compile(filenames, options, host)

Compile specified TypeScript files to generate JSON declaration files. Returns an array of diagnostic information if any errors occur.

Parameters

• filenames string[] - The files to compile.
• options CompilerOptions - The compiler options to use.
• host CompilerHost - Optional. The compiler host to use.

Returns: Diagnostic[]

CompilerOptions Interface

---

Compiler options.

• noLib
• noCheck
• out
• outDir
• suppressImplicitAnyIndexErrors
• noImplicitAny
• removeComments
• libPath
• removeAccessors
• removeAnnotations
• removePrivates
• removeTypesOnPrivates
• ignoreAnnotation

noLib

If true, the default library is not automatically added to the compile list.

Type: boolean

noCheck

If true, type checks are not run. This marginally improves compile time. Only use this option if your TypeScript already compiles correctly.

Type: boolean

out

Specifies a single file to compile all TypeScript to. This is ignored for external modules.

Type: string

outDir

Specifies the output directory.

Type: string

suppressImplicitAnyIndexErrors

Suppress errors that are raised when the index operator is used on an object that does not have an index defined on it's type.

Type: boolean

noImplicitAny

Warn on expressions and declarations with an implied any type

Type: boolean

removeComments

If true, JsDoc description is not included in output. Default is false.

Type: boolean

libPath

Path to the lib.d.json file relative to compiler javascript source.

Type: string

removeAccessors

Do not emit property accessor declarations.

Type: boolean

removeAnnotations

Do not emit custom annotations in output.

Type: boolean

removePrivates

Do not emit private class member declarations.

Type: boolean

removeTypesOnPrivates

Do not emit type information for private class members.

Type: boolean

ignoreAnnotation

Controls whether or not annotations with a given name are ignored.

CompilerHost Interface

---

The compiler host. Allows for control over the interaction of compiler with the file system.

• readFile
• writeFile

readFile(filename, onError)

Reads a file synchronously.

Parameters

• filename string - The full path to the file.
• onError - Callback called synchronously to indicate if an error occurred when reading the file. Passed a single argument containing the error message as a string.

Returns: string

writeFile(filename, data, writeByteOrderMark, onError)

Writes a file synchronously.

Parameters

• filename string - The full path to the file.
• data string - The data to write.
• writeByteOrderMark boolean - Indicates if the byte order mark should be written.
• onError - Callback called synchronously to indicate if an error occurred when writing the file. Passed a single argument containing the error message as a string.

Returns: void

Diagnostic Interface

---

Diagnostic information.

• filename
• line
• character
• messageText
• category
• code

filename

The name of that file that contains the error.

Type: string

line

The line number of the error.

Type: number

character

The character offset of the error.

Type: number

messageText

The error message text.

Type: string

category

The category of the error.

Type: DiagnosticCategory

code

The error code.

Type: number

DiagnosticCategory Enumeration

---

Enumeration describing type of Diagnostic.

• Warning
• Error
• Message