@travetto/transformer

Transformation

Functionality for AST transformations, with transformer registration, and general utils

Install: @travetto/transformer

npm install @travetto/transformer

This module provides support for enhanced AST transformations, and declarative transformer registration, with common patterns to support all the transformers used throughout the framework. Transformations are located by support/transformer.<name>.ts as the filename.

The module is primarily aimed at extremely advanced usages for things that cannot be detected at runtime. The Registry module already has knowledge of all classes and fields, and is able to listen to changes there. Many of the modules build upon work by some of the foundational transformers defined in Registry, Schema and Dependency Injection. These all center around defining a registry of classes, and associated type information.

Because working with the Typescript API can be delicate (and open to breaking changes), creating new transformers should be done cautiously.

Custom Transformer

Below is an example of a transformer that upper cases all class, method and param declarations. This will break any code that depends upon it as we are redefining all the identifiers at compile time.

Code: Sample Transformer - Upper case all declarations

import * as ts from 'typescript';

import { OnProperty, TransformerState, OnMethod, OnClass, TransformerId } from '@travetto/transformer';

export class MakeUpper {

  static [TransformerId] = '@trv:transformer-test';

  @OnProperty()
  static handleProperty(state: TransformerState, node: ts.PropertyDeclaration): ts.PropertyDeclaration {
    if (!state.source.fileName.includes('doc/src')) {
      return node;
    }
    return state.factory.updatePropertyDeclaration(
      node,
      [],
      node.modifiers,
      node.name.getText().toUpperCase(),
      undefined,
      node.type,
      node.initializer ?? state.createIdentifier('undefined')
    );
  }

  @OnClass()
  static handleClass(state: TransformerState, node: ts.ClassDeclaration): ts.ClassDeclaration {
    if (!state.source.fileName.includes('doc/src')) {
      return node;
    }
    return state.factory.updateClassDeclaration(
      node,
      [],
      node.modifiers,
      state.createIdentifier(node.name!.getText().toUpperCase()),
      node.typeParameters,
      node.heritageClauses,
      node.members
    );
  }

  @OnMethod()
  static handleMethod(state: TransformerState, node: ts.MethodDeclaration): ts.MethodDeclaration {
    if (!state.source.fileName.includes('doc/src')) {
      return node;
    }
    return state.factory.updateMethodDeclaration(
      node,
      [],
      node.modifiers,
      undefined,
      state.createIdentifier(node.name.getText().toUpperCase()),
      undefined,
      node.typeParameters,
      node.parameters,
      node.type,
      node.body
    );
  }
}

Note: This should be a strong indicator that it is very easy to break code in unexpected ways.