Have ideas to improve npm?Join in the discussion! »

    tspoon
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.460 • Public • Published

    image

    Tspoon

    npm version Build Status

    AST visitors for Typescript.

    API Reference

    What Tspoon does

    Typescript transpilation is usually source -> AST -> target. Tspoon uses Typescript's compiler API to allow pluggable pieces of logic (called visitor) to modify the AST 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 and here.

    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.

    // from src/transpile.ts
    interface TranspilerOutput {
        code: string,
        sourceMap: RawSourceMap,
        diags: ts.Diagnostic[],
        halted: boolean
    }
    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:

    // 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:

    // 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:

    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:

    npm install
    npm test

    how to run local continous test feedback

    At the root folder of the project, run:

    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

    Keywords

    none

    Install

    npm i tspoon

    DownloadsWeekly Downloads

    821

    Version

    1.0.460

    License

    SEE LICENSE IN LICENSE.md

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar