![image](logo.png)

# Tspoon
[![npm version](https://badge.fury.io/js/tspoon.svg)](https://www.npmjs.com/package/tspoon)
[![Build Status](https://travis-ci.org/wix/tspoon.svg?branch=master)](https://travis-ci.org/wix/tspoon)

AST visitors for [Typescript](https://github.com/Microsoft/TypeScript).

[API Reference](http://wix.github.io/tspoon/typedoc/index.html)

### What Tspoon does

Typescript transpilation is usually `source -> AST -> target`.
Tspoon uses [Typescript's compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API)
to allow pluggable pieces of logic (called ```visitor```) to modify the
[AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) before invoking
the Typescript transpiler. The process will look like this `source -> AST -visitors-> AST -> target`.
This technique enables early optimizations and error detection for custom
language features.

In addition, Tspoon's validation api supports pre-validation code changes,
allowing the developer to bypass otherwise unavoidable TypeScript diagnostics.


## Users Documentation
Simple examples can be found [here](https://github.com/wix/tspoon/tree/master/examples/poc)
and [here](https://github.com/wix/tspoon/tree/master/examples/readme).

## Getting started
 Install tspoon using npm.

 `npm install tspoon`

Currently, Tspoon exposes only a programmatic API. Meaning, it is used
by other javacript code invoking it's `transpile` and `validate` methods.
#### tspoon.transpile(content, config)
content is a string containing the code to transpile, and config defines
the visitors and transpilation parameters.
The result is an instance of the TranspilerOutput interface, containing
the transpiled code, a source map describing all changes done to the code,
the diagnostics generated by the visitors and Typescript, and whether the
operation failed or not.

```typescript
// from src/transpile.ts
interface TranspilerOutput {
	code: string,
	sourceMap: RawSourceMap,
	diags: ts.Diagnostic[],
	halted: boolean
}
```

```javascript
var tspoon = require('tspoon');
// from examples/poc/build.js
var config = {
    sourceFileName: 'src.ts',
    visitors: ... // insert visitors here
};
var sourceCode = fs.readFileSync(...);
var transpilerOut = tspoon.transpile(sourceCode, config);
...
fs.writeFileSync(path.join(__dirname, 'src.js'), transpilerOut.code, {encoding:'utf8'});
```
#### tspoon.validate()
Documentation pending writing

### How to write a visitor

A visitor is an instance of the visitor interface:

```typescript
// from src/visitor.ts
interface Visitor {
	filter(node: ts.Node) : boolean;
	visit(node: ts.Node, context: VisitorContext, traverse: (...visitors: Visitor[]) => void): void;
}
```

Consider for example the following visitor:

```javascript
// from examples/poc/deletePrivate.js
{
	filter(node){
		return node.kind === ts.SyntaxKind.PropertyDeclaration
			&& node.modifiers
			&& node.modifiers.some(function(m){
				return m.kind === ts.SyntaxKind.PrivateKeyword;
			});
	},
	visit(node, context, traverse) {
		context.replace(node.getStart(), node.getEnd(), '');
		context.reportDiag(node, ts.DiagnosticCategory.Message, 'deleted field "' + node.getText()+'"', false);
	}
}
```
This visitor only operates on nodes representing property declarations
which have the ```private``` modifier. When such a node is encountered,
it is deleted from the source code, and a diagnostic message notifying
the delete action is emitted.

### Visitor Composition

The code transformations often happens on multiple levels of the AST. For
example, one needs to traverse all class declarations, but the actual
transformation is performed on the respective syntax subtree (e.g. method
bodies). In order to achieve this, TSpoon lets you to execute a visitor
from another visitor:

```javascript
var visitor = {
    filter(node) {
        return node.kind === ts.SyntaxKind.ClassDeclaration;
    },

    visit(node, context, traverse) {
        traverse([{
            filter(node) {
                return node.kind === ts.SyntaxKind.Block;
            },

            visit(node, context, travers) {
                context.replace(node.getStart(), node.getEnd(), '');
            }
        }]);
    }
}
```

(This example will remove execution blocks within classes.)

## Developer Documentation

### how to build and test locally from source
Clone this project locally.
Then, at the root folder of the project, run:
```shell
npm install
npm test
```
### how to run local continous test feedback
At the root folder of the project, run:
```shell
npm start
```
Then, open your browser at http://localhost:8080/webtest.bundle
and see any changes you make in tests or code reflected in the browser

### Versioning
Currently Tspoon is in alpha mode. As such, it does not respect semver.

# License
We use a custom license, see ```LICENSE.md```