{"id":15493461,"url":"https://github.com/sinclairzx81/typescript.api","last_synced_at":"2025-04-22T19:47:37.313Z","repository":{"id":8275185,"uuid":"9764443","full_name":"sinclairzx81/typescript.api","owner":"sinclairzx81","description":"A typescript 0.9 compiler as a service api for nodejs.","archived":false,"fork":false,"pushed_at":"2013-10-02T05:18:47.000Z","size":2452,"stargazers_count":27,"open_issues_count":9,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-19T11:12:09.263Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinclairzx81.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-30T05:09:43.000Z","updated_at":"2022-01-02T06:05:20.000Z","dependencies_parsed_at":"2022-08-07T01:00:14.409Z","dependency_job_id":null,"html_url":"https://github.com/sinclairzx81/typescript.api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairzx81%2Ftypescript.api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairzx81%2Ftypescript.api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairzx81%2Ftypescript.api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairzx81%2Ftypescript.api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinclairzx81","download_url":"https://codeload.github.com/sinclairzx81/typescript.api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250312209,"owners_count":21409992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T08:06:50.229Z","updated_at":"2025-04-22T19:47:37.289Z","avatar_url":"https://github.com/sinclairzx81.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# typescript.api\n\nA compiler as a service api enabling nodejs developers to programatically resolve, compile, reflect and run typescript 0.9 source files in memory.\n\n## install\n\n```javascript\nnpm install typescript.api\n```\n\n## compiler version\n\nTypeScript 0.9.1-1\n\n## quick start\n\n### registering typescript extension\n\nThe following will register the *.ts extension with require(). When calls to require() are made\nto *.ts files, any source resolution and/or compilation errors will be written out to the console\nby default.\n\nIf resolution or compilation errors do exist, the call to require() will return an empty object.\n\n```javascript\nrequire(\"typescript.api\").register();\n\nvar program = require(\"./program.ts\");\n```\n### overview\n\n* [manual compilation](#manual_compilation)\n* [declarations](#declarations)\n\n### units\n\n* [source unit](#source_unit)\n* [compiled unit](#compiled_unit)\n\n### methods\n\n* [reset](#reset)\n* [register](#register)\n* [create](#create)\n* [resolve](#resolve)\n* [compile](#compile)\n* [check](#check)\n* [run](#run)\n* [sort](#sort)\n\n\u003ca name=\"manual_compilation\" /\u003e\n### manual compilation\n\nThe following is an example of using the api to compile a source file named 'program.ts'. \n\nThe process will first resolve 'program.ts' and all its referenced sources files. The resolved \nsources array (resolved) are then checked prior to being sent to the compiler for compilation. Once compiled,\nthe compilation is checked again for problems prior to being run.\n\n```javascript\nvar tsapi = require(\"typescript.api\");\n\n// show diagnostic errors.\nfunction show_diagnostics (units) {\n\n\tfor(var n in units) {\n\n\t\tfor(var m in units[n].diagnostics) {\n\n\t\t\tconsole.log( units[n].diagnostics[m].toString() );\n\t\t}\n\t}\n}\n\ntsapi.resolve(['./program.ts'], function(resolved) {\n\n\tif(!tsapi.check(resolved)) {\n\n\t\tshow_diagnostics(resolved);\n\n\t}\n\telse {\n\t\n\t\ttsapi.compile(resolved, function(compiled) {\n\n\t\t\tif(!tsapi.check(compiled)) {\n\n\t\t\t\tshow_diagnostics (compiled);\n\t\t\t}\n\t\t\telse\n\t\t\t{\t\t\t\n\t\t\t\ttsapi.run(compiled, null, function(context) {\n\n\t\t\t\t\t // exports are available on the context...\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\t}\n});\n```\n\n\u003ca name=\"declarations\" /\u003e\n### declarations\n\nIt is important to note that the typescript.api does not automatically reference any declarations (such as lib.d.ts) for compilation. \nBecause of this, you will need to reference the appropriate *.d.ts required by your application for compilation. This is unlike the \ntsc command line compiler which will, by default reference the lib.d.ts declaration if not stated otherwise. (see --noLib option). \n\nIn the context of nodejs, the dom declarations declared in lib.d.ts are unnessasary and dramatically slow compilation times. The\ntypescript.api splits these declarations out to provide suitable environment declarations that you can reference in your project.\n\nThe typescript.api comes bundled with following declarations:\n\n```javascript\n// ecma api + html dom declarations (suitable for browser development)\n[node_modules]/typescript.api/decl/lib.d.ts \n\n// ecma api + node.d.ts declarations (suitable for nodejs development)\n[node_modules]/typescript.api/decl/node.d.ts\n\n// ecma api only.\n[node_modules]/typescript.api/decl/ecma.d.ts \n\n// typescript.api declarations.\n[node_modules]/typescript.api/decl/typescript.api.d.ts\n```\n\nIt is recommended that developers copy the appropriate declarations suitable for their environment into their project structure and\nreference them accordingly. \n\nFor a full definition of this api, see  [typescript.api.d.ts](https://github.com/sinclairzx81/typescript.api/blob/master/src/resources/typescript.api.d.ts)\n\nFor other additional declarations, see the [definitely typed](https://github.com/borisyankov/DefinitelyTyped) project.\n\n## units\n\n\u003ca name=\"source_unit\" /\u003e\n### source unit\n\nThe typescript.api accepts source units for compilation. A source unit consists of the following properties: \n\n```javascript\n\nsourceUnit = {\n\n\tpath          : string,   // (public) the path of this source unit.\n\n\tcontent       : string,   // (public) the typescript source of this unit.\n\n\tremote        : boolean,  // (public) if this source file is loaded over http.\n\n\treferences    : Function  // (public) returns an array of references for this source unit.\n\n\tdiagnostics   : [object], // (public) compilation errors for this unit. 0 length if none.\n};\n\n```\n\nnote: For manually creating source units, see [create](#create)\n\nnote: For loading source units from disk. see [resolve](#resolve)\n\n\u003ca name=\"compiled_unit\" /\u003e\n### compiled unit\n\nA compiled unit is the output from a [compilation](#compile). A compiled unit consists of the following properties:\n\n```javascript\n\ncompiledUnit = {\n\n\tpath          : string,   // (public) the path of this unit.\n\n\tcontent       : string,   // (public) the javascript source of this unit.\n\n\treferences    : string[], // (public) an array of references for this unit.\n\n\tdiagnostics   : [object], // (public) compilation errors for this unit. 0 length if none.\n\n\tast           : object,   // (public) AST for this unit.\n\n\tsourcemap     : string,   // (public) The sourcemap for this unit.\n\n\tdeclaration   : string,   // (public) The declaration file for this unit.\n\n\tscript        : object,   // (public) reflected metadata for this unit.\n};\n\n```\n\n## methods\n\n\u003ca name=\"reset\" /\u003e\n### reset (options)\n\nResets the compiler. Optionally allows the caller to set compiler options.  \n\n```javascript\t\n\nvar tsapi = require(\"typescript.api\")\n\ntsapi.reset()\n```\n\nAdditionally, It is possible to specify reset with the following options. all of which are optional.\n\n```javascript\n\nvar tsapi = require(\"typescript.api\")\n\ntsapi.reset({\n\n    languageVersion          : \"EcmaScript5\", // (default)EcmaScript5 | EcmaScript3\n\n    moduleGenTarget\t\t\t : \"Synchronous\", // (default)Synchronous | ASynchronous\n\n    removeComments\t\t\t : true,          // (default) true\n\n    generateDeclarationFiles : false,\t\t  // (default) false\n\n    mapSourceFiles           : false,         // (default) false\n\n\tnoImplicitAny            : false,         // (default) false\n\n\tallowBool                : false,         // (default) false\n\n\toutputMany               : true           // (default) true\n\n})\n\n```\n\n\u003ca name=\"register\" /\u003e\n### typescript.register ()\n\nThe register() method will register the typescript file extension with nodejs require(). When using this \nmethod, the api will automatically JIT compile your typescript source code on first request and cache \nfor subsequent requests. \n\n```javascript\n\n//---------------------------------\n// program.ts\n//---------------------------------\n\nexport var message:string = 'hello world';\n\n//---------------------------------\n// app.js\n//---------------------------------\n\nrequire('typescript.api').register();\n\nvar program = require('./program.ts');\n\nconsole.log(program.message); // hello world\n```\n\n\n\u003ca name=\"resolve\" /\u003e\n### resolve (sources, callback)\n\nThe typescript.api resolve function will resolve source units needed for compilation and return them\nin order of dependancy, it does this by scanning each files reference element. \n\nspecial note: the resolve method will be unable to resolve source units if your code contains circular \nreferences. for example, if file0.ts references file1.ts, and file1.ts references file0.ts, then this would\nbe considered a circular reference. in these instances, the resolve() method will return the source units \nfound in order of discovery, and no additional dependency resolution will occur. \n\n__arguments__\n\n* sources - A filename, or a array of filenames to resolve. \n* callback(units) - A callback which passes the resolved source units.\n\n__example__\n\nThe following will resolve 'program.ts' and log each referenced source file to \nthe console.\n\n```javascript\nvar tsapi = require(\"typescript.api\");\n\ntsapi.resolve([\"program.ts\"], function(resolved) { \n\n\tfor(var n in resolved) {\n\n\t\tconsole.log( resolved[n].path ); // the source files path\n\t\t\n\t\tconsole.log( resolved[n].content ); // the source files content (typescript)\n\t\t\n\t\tfor(var m in resolved[n].references) {\n\t\t\n\t\t\tconsole.log( resolved[n].references[m] ) // paths to referenced source files.\n\t\t\t\n\t\t}\n\t}\n});\n```\n\u003ca name=\"check\" /\u003e\n### check (units)\n\nA utility method to check for errors in either resolved or compiled units.\n\n__arguments__\n\n* units   - units to be checked. \n* returns - true if ok. \n\n__example__\n\nThe following example will check if both a resolve() and compile() is successful.\n\n```javascript\nvar tsapi = require(\"typescript.api\");\n\ntsapi.resolve([\"program.ts\"], function(resolved) { \n\n\tif( tsapi.check (resolved)) { // check here for reference errors.\n\t\t\n\t\ttsapi.compile(resolved, function(compiled) {\n\t\t\n\t\t\tif( tsapi.check (compiled) ) { // check here for syntax and type errors.\n\t\t\t\n\t\t\t\ttsapi.run(compiled, null, function(context) {\n\t\t\t\t\t\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\t}\n});\n```\n\n\u003ca name=\"create\" /\u003e\n### create ( filename, code )\n\nCreates a source unit from a string. \n\n__arguments__\n\n* filename - A filename that other units may reference.\n* code\t   - The source code for this unit.\n\n__returns__\n\n* unit\t   - A source unit.\n\n__example__\n\nThe following will create a unit. and send to the compiler for compilation. \nThe compilation is then run.\n\n```javascript\nvar tsapi = require(\"typescript.api\");\n\nvar sourceUnit = tsapi.create(\"temp.ts\", \"export var message = 'hello world'\");\n\ntsapi.compile([sourceUnit], function(compiled) {\n\n\ttsapi.run(compiled, null, function(context) { \n\t\t\n\t\tconsole.log(context.message); // outputs hello world\n\t})\n})\n\n```\n\n\u003ca name=\"compile\" /\u003e\n### compile ( units, callback )\n\ncompiles source units. \n\n__arguments__\n\n* units\t   - An array of source units. \n* callback - A callback that passed the compiled output.\n\n__example__\n\nThe following will first create and compile a unit, and compiled source is\nwritten to the console.\n\n```javascript\n\nvar tsapi = require(\"typescript.api\");\n\nvar sourceUnit = tsapi.create(\"temp.ts\", \"var value:number = 123;\");\n\ntsapi.compile([sourceUnit], function(compiled) {\n\n\tfor(var n in compiled) {\n\t\n\t\tconsole.log(compiled[n].content);\n\t}\n});\n```\n\n\u003ca name=\"run\" /\u003e\n### run ( compiledUnits, sandbox, callback )\n\nexecutes compiled units within a nodejs vm and returns a context containing exported members.\n\n__arguments__\n\n* compiledUnits - compiled source units - (obtained from a call to compile)\n* sandbox\t    - A sandbox. pass null to inherit the current sandbox. code in executed in nodejs vm.\n* callback      - A callback that passes a context containing any exported variables and function.\n\n__example__\n\nThe following will first create and compile a unit, then send it off\nfor compilation.\n\n```javascript\n\nvar tsapi = require(\"typescript.api\");\t\n\nvar sourceUnit = tsapi.create(\"temp.ts\", \"export var value:number = 123\")\n\ntsapi.compile([sourceUnit], function(compiled) {\n\n\ttsapi.run(compiled, null, function(context) { \n\t\n\t\tconsole.log(context.value) // outputs 123\n\n\t})\n})\n```\n\n\u003ca name=\"sort\" /\u003e\n### sort ( units )\n\nWill attempt to sort source units in order of dependency. If cyclic referencing\noccurs, the sort will return the units in order in which they are received.\n\n__arguments__\n\n* units - An array of source units to be sorted.\n* returns - the sorted units in order of dependency.\n\n__example__\n\nThe following will create a series of source units which reference each other\nas in the following graph. The units are first randomized and then sorted. The \nresulting sort will be the order of a, b, c, d, e, f. \n\n```javascript\n/*\n         [a]\n        /   \\\n      [b]   [c]\n     /   \\ /   \\\n   [d]   [e]   [f]\n*/\nfunction shuffle(o) {  \n    for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);\n    return o;\n};\n\nvar tsapi = require(\"typescript.api\")\n\nvar units = [\n    tsapi.create(\"a.ts\", \"\"),\n    tsapi.create(\"b.ts\", \"/// \u003creference path='a.ts' /\u003e\"),\n    tsapi.create(\"c.ts\", \"/// \u003creference path='a.ts' /\u003e\"),\n    tsapi.create(\"d.ts\", \"/// \u003creference path='b.ts' /\u003e\"),\n    tsapi.create(\"e.ts\", \"/// \u003creference path='b.ts' /\u003e\\n/// \u003creference path='c.ts' /\u003e\\n\"),\n    tsapi.create(\"f.ts\", \"/// \u003creference path='c.ts' /\u003e\"),\n];\n\n// shuffle\nunits = shuffle(units);\n\n// sort\nunits = tsapi.sort(units);\n\n// display\nfor (var n in units)  {\n\n    console.log(units[n].path);\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinclairzx81%2Ftypescript.api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinclairzx81%2Ftypescript.api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinclairzx81%2Ftypescript.api/lists"}