Getting started

To install Deepkit's runtime type system two packages are needed: The Deepkit Type Compiler and the Deepkit Type package itself. The type compiler is a TypeScript transformer that generates runtime type information from TypeScript types. The type package contains the runtime virtual machine and type annotations as well as many useful functions for working with types.

Installation

npm install --save @deepkit/type
npm install --save-dev @deepkit/type-compiler typescript ts-node

Runtime type information is not generated by default. It must be set "reflection": true in the tsconfig.json file to enable it.

If decorators are to be used, "experimentalDecorators": true must be enabled in tsconfig.json. This is not strictly necessary to work with @deepkit/type, but necessary for certain functions of other Deepkit libraries and in Deepkit Framework.

File: tsconfig.json

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "es6",
    "moduleResolution": "node",
    "experimentalDecorators": true
  },
  "reflection": true
}

Write your first code with runtime type information:

File: app.ts

import { cast, MinLength, ReflectionClass } from '@deepkit/type';

interface User {
    username: string & MinLength<3>;
    birthDate?: Date;
}

const user = cast<User>(User, {
    username: 'Peter',
    birthDate: '2010-10-10T00:00:00Z'
});
console.log(user);

const reflection = ReflectionClass.from(User);
console.log(reflection.getProperty('username').type);

And run it with ts-node:

./node_modules/.bin/ts-node app.ts

Interactive Example

Type compiler

TypeScript itself does not allow to configure the type compiler via a tsconfig.json. It is necessary to either use the TypeScript compiler API directly or a build system like Webpack with ts-loader. To save this inconvenient way for Deepkit users, the Deepkit type compiler automatically installs itself in node_modules/typescript once @deepkit/type-compiler is installed (this is done via NPM install hooks). This makes it possible for all build tools that access the locally installed TypeScript (the one in node_modules/typescript) to automatically have the type compiler enabled. This makes tsc, Angular, webpack, ts-node, and some other tools automatically work with the deepkit type compiler.

If the type compiler could not be successfully installed automatically (for example because NPM install hooks are disabled), this can be done manually with the following command:

node_modules/.bin/deepkit-type-install

Note that deepkit-type-install must be run if the local typescript version has been updated (for example, if the typescript version in package.json has changed and npm install is run).

Webpack

If you want to use the type compiler in a webpack build, you can do so with the ts-loader package (or any other typescript loader that supports transformer registration).

File: webpack.config.js

const typeCompiler = require('@deepkit/type-compiler');

module.exports = {
  entry: './app.ts',
  module: {
    rules: [
      {
        test: /\.tsx?$/,
          use: {
            loader: 'ts-loader',
            options: {
              //this enables @deepkit/type's type compiler
              getCustomTransformers: (program, getProgram) => ({
                before: [typeCompiler.transformer],
                afterDeclarations: [typeCompiler.declarationTransformer],
              }),
            }
          },
          exclude: /node_modules/,
       },
    ],
  },
}