cheap-di-ts-transform

• Installation
• What is it
• How to use:
  • Transform options
  • Webpack + ts-loader
  • ts-node
  • ts-jest
  • Vite + @rollup/plugin-typescript

Installation

npm i cheap-di-ts-transform --save-dev

What is it

Typescript code transformer. It produces constructor dependencies information to be able to use Dependency Injection approach with cheap-di package

// no constructors => no depdendencies
abstract class Logger {
  abstract debug: (message: string) => void;
}


// no constructors => no depdendencies
class ConsoleLogger extends Logger {
  debug(message: string) {
    console.log(message);
  }
}


// has constructor => has depdendencies => leads to code generation 
class Service {
  constructor(public logger: Logger) {}

  doSome() {
    this.logger.debug('Hello world!');
  }
}
/** cheap-di-ts-transform will add folowing code:
 * @example
 * import cheap_di_1 from 'cheap-di';
 * try {
 *   cheap_di_1.saveConstructorMetadata(Service, Logger);
 * } catch (error: unknown) {
 *   console.warn(error);
 * }
 * */

// somewhere
import { container } from 'cheap-di';

container.registerImplementation(ConsoleLogger).as(Logger);

const service = container.resolve(Service);
console.log(service instanceof Service); // true
console.log(service.logger instanceof ConsoleLogger); // true
console.log(service.doSome()); // 'Hello world!'

more examples:

// no constructors => no depdendencies
class JustSomeClass {}


class Example1 {
  // string (as well as any non-class parameters) will interpreted as 'unknown' dependency
  constructor(name: string) {}
}
/** cheap-di-ts-transform will add folowwing code:
 * @example
 * import cheap_di_1 from 'cheap-di';
 * try {
 *   cheapDi.saveConstructorMetadata(Example1, 'unknown');
 * } catch (error: unknown) {
 *   console.warn(error);
 * }
 * */


interface MyInterface {
  //
}

class Example2 {
  constructor(
    service: Service,
    some: number, // 'unknown'
    example1: Example1,
    foo: boolean, // 'unknown'
    logger: Logger,
    bar: { data: any }, // 'unknown'
    callback: () => void, // 'unknown'
    myInterface: MyInterface  // 'unknown'
  ) {} 
}
/** cheap-di-ts-transform will add folowwing code:
 * @example
 * import cheap_di_1 from 'cheap-di';
 * try {
 *   cheapDi.saveConstructorMetadata(Example2, Service, "unknown", Example1, "unknown", Logger, "unknown", unknown, "unknown");
 * } catch (error: unknown) {
 *   console.warn(error);
 * }
 * */

in case when you import class from somewhere:

import { SomeClass } from 'some-package';
/** cheap-di-ts-transform will add folowwing code:
 * @example
 * import cheap_di_1 from 'cheap-di';
 * import * as some_package_for_cheap_di_1 from 'some-package';
 * const { SomeClass: SomeClass_1 } = some_package_for_cheap_di_1;
 * */

class Example3 {
  constructor(service: SomeClass) {}
}
/** cheap-di-ts-transform will add folowwing code:
 * @example
 * try {
 *   cheap_di_1.saveConstructorMetadata(Example3, SomeClass_1);
 * } catch (error: unknown) {
 *   console.warn(error);
 * }
 * */

How to use

Transform options

| name | value by default | description | |--------------------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | debug | false | gets node names if you want to debug transformation | | addDetailsToUnknownParameters | false | adds primitive types information of class parameters, to debug if something went wrong, instead of just unknown you will get something like primitive /<parameter-name>/ :string | | logRegisteredMetadata | false | adds console.debug call before saveConstructorMetadata function call. Useful to get debug information traced. You will see this information at runtime in console | | errorsLogLevel | "warn" | used in try-catch statements to log registration errors |

Webpack + ts-loader

[!WARNING] The transformer does not work properly when used together with fork-ts-checker-webpack-plugin. If you have any thoughts on why is it and/or how we can fix it, please open the issue with details.

// webpack.config.ts
import path from 'path';
import { transformer } from 'cheap-di-ts-transform';

const tsconfigFilePath = path.join(__dirname, 'tsconfig.json');

const config = {
  // ...
  module: {
    rules: [
      // ...
      {
        loader: 'ts-loader',
        test: /\.ts$/,
        options: {
          getCustomTransformers: (program) => ({
            before: [
              transformer(
                { program },
                {
                  // options are optional
                  debug: false,
                  addDetailsToUnknownParameters: false,
                  logRegisteredMetadata: false,
                  errorsLogLevel: "warn",
                }
              ),
            ],
          }),
          configFile: tsconfigFilePath,
        },
      },
    ],
  },
};

export default config;

ts-node

You may use the transformer in nodejs, but in this case you need to use a compiler like ts-patch.

tsconfig.json

{
  "compilerOptions": {
    // [...]
    "plugins": [
      {
        "transform": "cheap-di-ts-transform",
        // all options are optional
        "debug": false,
        "addDetailsToUnknownParameters": false,
        "logRegisteredMetadata": false,
        "errorsLogLevel": "warn",
      }
    ]
  },
  "ts-node": {
    "compiler": "ts-patch/compiler"
  }
}

ts-jest

{
  // [...]
  "transform": {
    "^.+\\.ts?$": [
      "ts-jest",
      {
        "astTransformers": {
          "before": [
            {
              "path": "cheap-di-ts-transform",
              // all options are optional
              "options": {
                "debug": false,
                "addDetailsToUnknownParameters": false,
                "logRegisteredMetadata": false,
                "errorsLogLevel": "warn",
              }
            }
          ]
        }
      }
    ]
  }
}

Vite + @rollup/plugin-typescript

// vite.config.ts
import { defineConfig } from 'vite';
import typescript from '@rollup/plugin-typescript';
import { transformer } from 'cheap-di-ts-transform';

export default defineConfig({
  plugins: [
    // ...
    typescript({
      transformers: {
        before: [
          {
            type: 'program',
            factory: (program) =>
              transformer(
                { program },
                {
                  // (optional) debugging options
                  debug: true,
                  addDetailsToUnknownParameters: true,
                  logRegisteredMetadata: true,
                  errorsLogLevel: 'debug',
                }
              ),
          },
        ],
      },
    }),
  ],
});

Helpful links

• TypeScript AST Viewer