typescript.api

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 beta 6-6-2013

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(resolved) {
	
	if(!typescript.check(resolved)) {
	
		show_diagnostics(resolved);
	}
	else {
		
		typescript.compile(resolved, function(compiled) {
			
			if(!typescript.check(compiled)) {
			
				show_diagnostics (compiled);
			}
			else
			{			
				typescript.run(compiled, 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(resolved) { 

	for(var n in resolved) {
	
		console.log( resolved[n].path );
		
		console.log( resolved[n].content );
		
		for(var m in resolved[n].references) {
		
			console.log( resolved[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(resolved) { 

	if(typescript.check (resolved)) {
		
		typescript.compile(resolved, function(compiled) {
		
			if( typescript.check (compiled) ) {
			
				typescript.run(compiled, 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 sourceUnit = typescript.create("temp.ts", "console.log('hello world');");

typescript.compile([sourceUnit], function(compiled) {

	typescript.run(compiled, 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 sourceUnit = typescript.create("temp.ts", "var value:number = 123;");

typescript.compile([sourceUnit], function(compiled) {

	for(var n in compiled) {
	
		console.log(compiled[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(resolved){

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

typescript.build ( sources, callback )

Builds the supplied source files.

arguments

• sources - an array of input source filenames.
• callback - a callback containing errors and the compiled source.

example

The following will build the source file 'program.ts' and write the compiled code to the console.

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

typescript.build(['program.ts'], function(errors, output) {
	
	if(errors) {
		// iterate each error.
	}
	else {
		console.log(output);
	}
});

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 sourceUnit = typescript.create("temp.ts", "export var value:number = 123;");

typescript.compile([sourceUnit], function(compiled) {

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

typescript.sort ( units )

Will attempt to sort source units in order of dependency. If cyclic referencing occurs, the sort will return the units in order in which they are received.

arguments

• units - An array of source units to be sorted.
• returns - the sorted units in order of dependency.

example

The following will create a series of source units which reference each other as in the following graph. The units are first randomized and then sorted. The resulting sort will be the order of a, b, c, d, e, f.

/*
         [a]
        /   \
      [b]   [c]
     /   \ /   \
   [d]   [e]   [f]
*/
function shuffle(o) {  
    for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);
    return o;
};

var units = [
    typescript.create("a.ts", ""),

    typescript.create("b.ts", "/// <reference path='a.ts' />"),
    
    typescript.create("c.ts", "/// <reference path='a.ts' />"),
    
    typescript.create("d.ts", "/// <reference path='b.ts' />"),
    
    typescript.create("e.ts", "/// <reference path='b.ts' />\n/// <reference path='c.ts' />\n"),
    
    typescript.create("f.ts", "/// <reference path='c.ts' />"),
];

// shuffle
units = shuffle(units);

// sort
units = typescript.sort(units);

// display
for (var n in units)  {

    console.log(units[n].path);
}