typescript.api
Advanced tools
A compiler as a service api enabling nodejs developers to programatically resolve, compile, reflect and run typescript 0.9 source files.
A compiler as a service api enabling nodejs developers to programatically resolve, compile, reflect and run typescript 0.9 source files.
npm install typescript.api
TypeScript 0.9
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");
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 array (resolved) are 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...
});
}
});
}
});
The following are options available on the typescript compiler.
var typescript = require("typescript.api");
// enables remote resolution of source files over http. false by default.
typescript.allowRemote = false;
// the javascript language version to target. EcmaScript3 | EcmaScript5
typescript.languageVersion = "EcmaScript5";
// CommonJS or AMD module profiles, Synchronous | Asynchronous. Synchronous is the default.
typescript.moduleTarget = "Synchronous";
It is important to note that the typescript.api does not automatically reference any declarations (such as lib.d.ts) for compilation. Because of this, you will need to reference the appropriate *.d.ts required by your application for compilation. This is unlike the tsc command line compiler which will, by default reference the lib.d.ts declaration if not stated otherwise. (see --nolib option).
In the context of nodejs, the dom declarations declared in lib.d.ts are unnessasary and dramatically slow compilation times. The typescript.api splits these declarations out to provide suitable environment declarations that you can reference in your project.
The typescript.api comes bundled with following declarations:
// ecma api + html dom declarations (suitable for browser development)
[node_modules]/typescript.api/decl/lib.d.ts
// ecma api + node.d.ts declarations (suitable for nodejs development)
[node_modules]/typescript.api/decl/node.d.ts
// ecma api only.
[node_modules]/typescript.api/decl/ecma.d.ts
It is recommended that developers copy the appropriate declarations suitable for their environment into their project structure and reference them accordingly.
For other additional declarations, see https://github.com/borisyankov/DefinitelyTyped.
The typescript.api accepts source units for compilation. A source unit consists of the following properties:
sourceUnit = {
path : string, // (public) the path of this source unit.
content : string, // (public) the typescript source of this unit.
remote : boolean, // (public) if this source file is loaded over http.
references : Function // (public) returns an array of references for this source unit.
diagnostics : [object], // (public) compilation errors for this unit. 0 length if none.
};
note: For manually creating source units, see create
note: For loading source units from disk. see resolve
### compiled unitA compiled unit is the output from a compilation. A compiled unit consists of the following properties:
compiledUnit = {
path : string, // (public) the path of this unit.
content : string, // (public) the javascript source of this unit.
references : Function // (public) returns an array of references for this unit.
diagnostics : [object], // (public) compilation errors for this unit. 0 length if none.
ast : object, // (public) AST for this unit.
declaration : string, // (public) The declaration source for this unit.
sourcemap : string, // (public) The sourcemap for this unit.
reflection : object, // (public) The units reflected members.
};
Will resolve source units by traversing each source files reference element. The result will be an ordered (in order of dependancy) array of source units.
arguments
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 ); // the source files path
console.log( resolved[n].content ); // the source files content (typescript)
for(var m in resolved[n].references) {
console.log( resolved[n].references[m] ) // paths to referenced source files.
}
}
});
Utility method to check if a source or compiled unit has errors.
arguments
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)) { // check here for reference errors.
typescript.compile(resolved, function(compiled) {
if( typescript.check (compiled) ) { // check here for syntax and type errors.
typescript.run(compiled, null, function(context) {
});
}
});
}
});
Creates a source unit from a string.
arguments
returns
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", "export var message = 'hello world'");
typescript.compile([sourceUnit], function(compiled) {
typescript.run(compiled, null, function(context) {
console.log(context.message); // outputs hello world
});
});
Compiles source units.
arguments
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);
}
});
A quick means of building a typescript source file(s) and producing the compiled source code as a string.
arguments
example
The following will build the source file 'program.ts' and write the compiled code and declaration output to the console.
var typescript = require("typescript.api");
typescript.build_source(['program.ts'], function(errors, sourcecode, declaration) {
if(errors) {
for(var n in errors) {
console.log( errors[n].toString() );
}
}
else {
console.log(declaration);
console.log(sourcecode);
}
});
Runs a compilation.
arguments
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); // outputs 123
});
});
Resets the compiler.
var typescript = require("typescript.api");
typescript.reset();
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
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);
}
FAQs
A compiler as a service api enabling nodejs developers to programatically resolve, compile, reflect and run typescript 0.9 source files in memory.
We found that typescript.api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.