ts-macros

ts-macros is a typescript transformer which allows you to create function macros that expand to javascript code during the transpilation phase of your program.

📖 Documentation 🎮 Playground ✍️ Examples

The Basics

All macro names must start with a dollar sign ($) and must be declared using the function keyword. Macros can then be called just like a normal function, but with a ! after it's name: $macro!(params). All the code inside of the macro is going to "expand" where the macro is called.

What you can do with ts-macros:

• Generate repetitive code
• Generate code conditionally, based on enviourment variables or other configuration files
• Generate types which you can use in your code (read more here)
• Create abstractions without the runtime cost

Usage

npm i --save-dev ts-macros

npm i --save-dev ts-patch

"compilerOptions": {
//... other options
"plugins": [
        { "transform": "ts-macros" }
    ]
}

const TsMacros = require("ts-macros").default;

options: {
      getCustomTransformers: program => {
        before: [TsMacros(program)]
      }
}

npm i --save-dev ts-node

"ts-node": {
    "compiler": "ts-patch/compiler"
  },
  "compilerOptions": {
    "plugins": [
        { "transform": "ts-macros" }
    ]
  }

Security

This library has 2 built-in macros ($raw and $comptime) which execute arbitrary code during transpile time. The code is not sandboxed in any way and has access to your file system and all node modules.

If you're transpiling an untrusted codebase which uses this library, make sure to set the noComptime option to true. Enabling it will replace all calls to these macros with null without executing the code inside them. It's always best to review all call sites to $$raw and $$comptime yourself before transpiling any untrusted codebases.

ttypescript/ts-patch:

"plugins": [
        { "transform": "ts-macros", "noComptime": true }
    ]

manually creating the factory:

TsMacros(program, { noComptime: true });

Contributing

ts-macros is being maintained by a single person. Contributions are welcome and appreciated. Feel free to open an issue or create a pull request at https://github.com/GoogleFeud/ts-macros.