ts-transformer-keys

A TypeScript custom transformer which enables to obtain keys of given type.

Requirement

TypeScript >= 2.4.1

How to use this package

This package exports 2 functions. One is keys which is used in TypeScript codes to obtain keys of given type, while the other is a TypeScript custom transformer which is used to compile the keys function correctly.

How to use keys

1import { keys } from 'ts-transformer-keys';
2
3interface Props {
4  id: string;
5  name: string;
6  age: number;
7}
8const keysOfProps = keys<Props>();
9
10console.log(keysOfProps); // ['id', 'name', 'age']

How to use the custom transformer

Unfortunately, TypeScript itself does not currently provide any easy way to use custom transformers (See https://github.com/Microsoft/TypeScript/issues/14419). The followings are the example usage of the custom transformer.

webpack (with ts-loader or awesome-typescript-loader)

See examples/webpack for detail.

1// webpack.config.js
2const keysTransformer = require('ts-transformer-keys/transformer').default;
3
4module.exports = {
5  // ...
6  module: {
7    rules: [
8      {
9        test: /\.ts$/,
10        loader: 'ts-loader', // or 'awesome-typescript-loader'
11        options: {
12          // make sure not to set `transpileOnly: true` here, otherwise it will not work
13          getCustomTransformers: program => ({
14              before: [
15                  keysTransformer(program)
16              ]
17          })
18        }
19      }
20    ]
21  }
22};
23

Rollup (with rollup-plugin-typescript2)

See examples/rollup for detail.

1// rollup.config.js
2import resolve from 'rollup-plugin-node-resolve';
3import typescript from 'rollup-plugin-typescript2';
4import keysTransformer from 'ts-transformer-keys/transformer';
5
6export default {
7  // ...
8  plugins: [
9    resolve(),
10    typescript({ transformers: [service => ({
11      before: [ keysTransformer(service.getProgram()) ],
12      after: []
13    })] })
14  ]
15};

ttypescript

See examples/ttypescript for detail. See ttypescript's README for how to use this with module bundlers such as webpack or Rollup.

1// tsconfig.json
2{
3  "compilerOptions": {
4    // ...
5    "plugins": [
6      { "transform": "ts-transformer-keys/transformer" }
7    ]
8  },
9  // ...
10}

ts-jest

See examples/ts-jest for details. In order to use this transformer with ts-jest, you need to add a wrapper around it like this:

1// ts-jest-keys-transformer.js
2const keysTransformer = require('ts-transformer-keys/transformer').default;
3const name = 'my-key-transformer';
4const version = 1;
5const factory = (cs) => (ctx) => keysTransformer(cs.program)(ctx);
6// For ts-jest 26 use:
7// const factory = (cs) => (ctx) => keysTransformer(cs.tsCompiler.program)(ctx);
8
9module.exports = { name, version, factory };

And add it in jest.config.js like this:

1  globals: {
2    'ts-jest': {
3      // relative path to the ts-jest-keys-transformer.js file
4      astTransformers: { before: ['src/react/ts-jest-keys-transformer.js'] },
5    },
6  },

Note: ts-jest 26.4.2 does not work with this transformer (fixed in ts-jest 26.4.3). Also, for versions smaller than 26.2, you need to provide the transformer in an array instead, like this: astTransformers: { before: ['src/react/ts-jest-keys-transformer.js'] }

TypeScript API

See test for detail. You can try it with $ npm test.

1const ts = require('typescript');
2const keysTransformer = require('ts-transformer-keys/transformer').default;
3
4const program = ts.createProgram([/* your files to compile */], {
5  strict: true,
6  noEmitOnError: true,
7  target: ts.ScriptTarget.ES5
8});
9
10const transformers = {
11  before: [keysTransformer(program)],
12  after: []
13};
14const { emitSkipped, diagnostics } = program.emit(undefined, undefined, undefined, false, transformers);
15
16if (emitSkipped) {
17  throw new Error(diagnostics.map(diagnostic => diagnostic.messageText).join('\n'));
18}

As a result, the TypeScript code shown here is compiled into the following JavaScript.

1"use strict";
2Object.defineProperty(exports, "__esModule", { value: true });
3var ts_transformer_keys_1 = require("ts-transformer-keys");
4var keysOfProps = ["id", "name", "age"];
5console.log(keysOfProps); // ['id', 'name', 'age']

Note

• The keys function can only be used as a call expression. Writing something like keys.toString() results in a runtime error.
• keys does not work with a dynamic type parameter, i.e., keys<T>() in the following code is converted to an empty array([]).

1class MyClass<T extends object> {
2  keys() {
3    return keys<T>();
4  }
5}

License

MIT