typescript.api

A compiler as a service api enabling nodejs developers to resolve, compile, reflect and run typescript 0.9 source files.

install

npm install typescript.api

compiler version

TypeScript 0.9 alpha

quick start

registering typescript extension

The following will register the *.ts extension with require(). When calls to require() are made to *.ts files, any source resolution and/or compilation errors will be written out to the console by default.

If resolution or compilation errors do exist, the call to require() will return an empty object.

require("typescript.api").register();

var program = require("./program.ts");

manual compilation

The following is an example of using the api to compile a source file named 'program.ts'.

The process will first resolve 'program.ts' and all its referenced sources files. The resolved sources (units) then checked prior to being sent to the compiler for compilation. Once compiled, the compilation is checked again for problems prior to being run.

var typescript = require("typescript.api");

// show diagnostic errors.
function show_diagnostics (units) {

	for(var n in units) {
	
		for(var m in units[n].diagnostics) {
		
			console.log( units[n].diagnostics[m].toString() );
		}
	}
}

typescript.resolve(['./program.ts'], function(units) {
	
	if(!typescript.check(units)) {
	
		show_diagnostics(units);
	}
	else {
		
		typescript.compile(units, function(compilation) {
			
			if(!typescript.check(compilation)) {
			
				show_diagnostics (compilation);
			}
			else
			{			
				typescript.run(compilation, null, function(context) {
				
					 // exports are available on the context...
				});
			}
		});
	}
});

reference

typescript.resolve (sources, callback)

Will resolve source units by traversing each source files reference element.

arguments

• sources - A filename, or a array of filenames to resolve.
• callback(units) - A callback with the resolved units.

example

The following will resolve 'program.ts' and log each referenced source file to the console.

var typescript = require("typescript.api");

typescript.resolve(["program.ts"], function(units) { 

	for(var n in units) {
	
		console.log( units[n].path );
		
		console.log( units[n].content );
		
		for(var m in units[n].references) {
		
			console.log( units[n].references[m] )
			
		}
	}
});

typescript.check (units)

Checks source units for diagnostic errors.

arguments

• units - units to be checked.
• returns - true if ok.

example

The following example will check if both a resolve() and compile() is successful.

var typescript = require("typescript.api");

typescript.resolve(["program.ts"], function(units) { 

	if(typescript.check (units)) {
		
		typescript.compile(units, function(compilation) {
		
			if( typescript.check (compilation) ) {
			
				typescript.run(compilation, null, function(context) {
					
				});
			}
		});
	}
});

typescript.create ( filename, code )

Will create a unit from the supplied filename and source code.

arguments

• filename - A filename that other units can reference.
• code - The source code for this unit.

example

The following will create a unit. and send to the compiler for compilation. The compilation is then run.

var typescript = require("typescript.api");

var unit = typescript.create("temp.ts", "console.log('hello world');");

typescript.compile([unit], function(compilation) {

	typescript.run(compilation, null, function(context) { 
		
		// will output hello world..
	});
	
});

typescript.compile ( units, callback )

Compiles source units.

arguments

• units - An array of source units.
• callback - A callback that passes the compiled output.

example

The following will first create and compile a unit, and compiled source is written to the console.

var typescript = require("typescript.api");

var unit = typescript.create("temp.ts", "var value:number = 123;");

typescript.compile([unit], function(compilation) {

	for(var n in compilation){
	
		console.log(compilation[n].content);
	}
});

typescript.reflect ( compilation, callback )

Reflects compilation AST and produces meta data about the modules, classes, methods and variables contained within the compilation.

arguments

• units - The compilation to be reflected.
• callback - A callback that passes the reflected metadata.

example

The following will resolve the source file 'program.ts', compile it, then reflect its meta data to the console as a JSON string.

var typescript = require("typescript.api");

typescript.resolve(['program.ts'], function(units){

	typescript.compile(units, function(compilation) {
		
		typescript.reflect(compilation, function(reflection) {
			
			var json = JSON.stringify(reflection, null, ' ');
			
			console.log(json);
		});
	});
});

typescript.run ( compilation, sandbox, callback )

Runs a compilation.

arguments

• compilation - The compilation to be run.
• sandbox - A sandbox. pass null to inherit the current sandbox.
• callback - A callback that passes a context containing any exported variables and function.

example

The following will first create and compile a unit, then send it off for compilation.

var typescript = require("typescript.api");	

var unit = typescript.create("temp.ts", "export var value:number = 123;");

typescript.compile([unit], function(compilation) {

	typescript.run(compilation, null, function(context) { 
	
		console.log(context.value);
		
	});
});