ttypescript

What is ttypescript?

ttypescript is a TypeScript transformer tool that allows you to customize the TypeScript compiler by adding custom transformers. It provides a way to extend the TypeScript compiler's capabilities, enabling you to modify the Abstract Syntax Tree (AST) during the compilation process.

What are ttypescript's main functionalities?

Custom Transformer

This feature allows you to create custom transformers that can modify the TypeScript AST during the compilation process. The code sample demonstrates how to create a simple transformer that visits each node in the AST.

const ttypescript = require('ttypescript');
const ts = require('typescript');

function myTransformer(context) {
  return (sourceFile) => {
    function visitor(node) {
      // Custom transformation logic
      return ts.visitEachChild(node, visitor, context);
    }
    return ts.visitNode(sourceFile, visitor);
  };
}

const options = { transformers: { before: [myTransformer] } };
ttypescript.transpileModule('const x: number = 42;', options);

Integration with TypeScript Compiler

This feature demonstrates how to integrate ttypescript with the TypeScript compiler to create a program and emit the compiled output. It also shows how to handle diagnostics and errors during the compilation process.

const ttypescript = require('ttypescript');
const ts = require('typescript');

const program = ttypescript.createProgram(['./src/index.ts'], {});
const emitResult = program.emit();

const allDiagnostics = ts.getPreEmitDiagnostics(program).concat(emitResult.diagnostics);

allDiagnostics.forEach(diagnostic => {
  if (diagnostic.file) {
    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
    console.log(`${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`);
  } else {
    console.log(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
  }
});

Other packages similar to ttypescript

babel-plugin-transform-typescript

babel-plugin-transform-typescript is a Babel plugin that allows you to transform TypeScript code using Babel. It provides similar functionality to ttypescript in terms of transforming TypeScript code, but it is integrated into the Babel ecosystem rather than the TypeScript compiler.

ts-morph

ts-morph is a library for working with the TypeScript compiler API. It provides a higher-level abstraction over the TypeScript compiler API, making it easier to manipulate TypeScript code. While ttypescript focuses on custom transformers, ts-morph provides a more comprehensive set of tools for working with TypeScript code.

typescript-transform-paths

typescript-transform-paths is a TypeScript transformer that rewrites module paths based on the paths defined in the tsconfig.json file. It provides a specific transformation capability, whereas ttypescript allows for more general-purpose custom transformations.

README

ttypescript

What it is

Currently TypeScript doesn't support custom transformers in the tsconfig.json, but supports it programmatically.

And there is no way to compile your files using custom transformers using tsc command.

TTypescript (Transformer TypeScript) solves this problem by patching on the fly the compile module to use transformers from tsconfig.json.

Instead of tsc and tsserver, use ttsc and ttsserver wrappers. This wrappers try to use locally installed typescript first.

No version lock-ins - typescript used as peer dependency.

How to install

npm i ttypescript -D

ttypescript uses your installed typescript in your node_modules

How to use

tsconfig.json

Set a transformer path to the tsconfig.json in compilerOptions section plugin array:

{
    "compilerOptions": {
        "plugins": [
            { "transform": "transformer-module" },
        ]
    }
}

plugin entries described in PluginConfig:

export interface PluginConfig {
    /**
     * Path to transformer or transformer module name
     */
    transform?: string;

    /**
     * The optional name of the exported transform plugin in the transform module.
     */
    import?: string;

    /**
     * Plugin entry point format type, default is program
     */
    type?: 'program' | 'config' | 'checker' | 'raw' | 'compilerOptions';

    /**
     * Should transformer applied after all ones
     */
    after?: boolean;

    /**
     * Should transformer applied for d.ts files, supports from TS2.9
     */
    afterDeclarations?: boolean;
    /**
     * any other properties provided to the transformer as config argument
     * */
    [options: string]: any;
}

You just need to add the transform block with optional import, type, after, afterDeclarations and plugin-related options.

transform can accept npm module or local file path (.ts or .js) related to tsconfig.json

PluginConfig.type

Because currently transformers can run only programmatically, most of them use factory wrapper with different signatures. For the possible to work with any of them you can specify type in the plugin config.

By default will be used a program type.

program

If the transformer has a factory signature using program as first argument:

(program: ts.Program, config?: PluginConfig) => ts.TransformerFactory
where 
ts.TransformerFactory = (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile

Plugin config entry: { "transform": "transformer-module" }.

config

For the signature with transformer's config:

(config: PluginConfig) => ts.TransformerFactory

Plugin config entry: { "transform": "transformer-module", type: "config" }.

checker

For the signature with ts.TypeChecker:

(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory

Plugin config entry: { "transform": "transformer-module", type: "checker" }.

raw

For the signature without factory wrapper:

ts.TransformerFactory

Plugin config entry: { "transform": "transformer-module", type: "raw" }.

compilerOptions

(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory

Plugin config entry: { "transform": "transformer-module", type: "compilerOptions" }.

{
    "compilerOptions": {
        "plugins": [
            { "transform": "transformer-module", "someOption1": 123, "someOption2": 321 },
            { "transform": "./transformers/my-transformer.ts" },
            { "transform": "transformer-module", "after": true },
            { "transform": "transformer-module", "afterDeclarations": true },
            { "transform": "transformer-module", "type": "ls" }
        ]
    },
}

Command line

Like usual tsc, all arguments work the same way.

ttsc

ts-node

ts-node --compiler ttypescript index.ts
or
ts-node -C ttypescript index.ts

Parcel

Just install a parcel plugin

npm i parcel-plugin-ttypescript

Webpack

    {
        test: /\.(ts|tsx)$/,
        loader: require.resolve('awesome-typescript-loader'),
        // or
        loader: require.resolve('ts-loader'),
        options: {
            compiler: 'ttypescript'
        }
    }

Rollup

// rollup.config.js
import ttypescript from 'ttypescript'
import tsPlugin from 'rollup-plugin-typescript2'

export default {
    // ...
    plugins: [
        // ...
        tsPlugin({
            typescript: ttypescript
        })
    ]
}

VS Code

If you want to compile your project with VS Code task runner you need to overwrite the config typescript.tsdk to path of the installed ttypescript:

"typescript.tsdk": "/usr/local/lib/node_modules/ttypescript/lib",
or 
"typescript.tsdk": "node_modules/ttypescript/lib",

Jest, ts-jest

module.exports = {
  // [...]
  globals: {
    'ts-jest': {
      compiler: 'ttypescript'
    }
  }
};

or in package.json

{
  "jest": {
    "globals": {
      "ts-jest": {
        "compiler": "ttypescript"
      }
    }
  }
}

Transformers

You can use transformers written in ts or js

// transformer1-module
import * as ts from 'typescript';
export default function(program: ts.Program, pluginOptions: {}) {
    return (ctx: ts.TransformationContext) => {
        return (sourceFile: ts.SourceFile) => {
            function visitor(node: ts.Node): ts.Node {
                // if (ts.isCallExpression(node)) {
                //     return ts.createLiteral('call');
                // }
                return ts.visitEachChild(node, visitor, ctx);
            }
            return ts.visitEachChild(sourceFile, visitor, ctx);
        };
    };
}

Examples of transformers

{ "transform": "ts-optchain/transform" }

{transform: "typescript-is/lib/transform-inline/transformer"}

{transform: "ts-transformer-keys/transformer"}

{transform: "ts-transformer-enumerate/transformer"}

{transform: "ts-transform-graphql-tag/dist/transformer"}

{transform: "ts-transform-img/dist/transform", type: "config"}

{transform: "ts-transform-css-modules/dist/transform", type: "config"}

{transform: "ts-transform-react-intl/dist/transform", import: "transform", type: "config"}

{transform: "ts-nameof", type: "raw"}

{transform: "typescript-transform-jsx" }

{transform: "typescript-transform-paths" }

{transform: "typescript-transform-macros" }

{transform: "ts-transformer-minify-privates" }

{transform: "typescript-plugin-styled-components", type: "config"}

{ "transform": "@zoltu/typescript-transformer-append-js-extension" }

Tutorial how to write a typescript transformer

Example

An example project is in the example directory

License

MIT License