ts2typebox

Creating TypeBox code from Typescript types.

Cli tool which leverages the awesome typebox-codegen package by sinclairzx81.

Installation

npm i -g ts2typebox

Use Case

You got a typescript project with types already lying around and are looking for a quick and easy way to get validations and JSON schemas based on them.
You prefer leveraging typescript to define your data types and to generate your validators and/or JSON schemas.

Usage

The cli can be used with ts2typebox --input <fileName> --output <fileName>, or by simply running ts2typebox. The input defaults to "types.ts" and the output to "generated-types.ts" relative to the current working directory. For more see cli usage.

Examples

//
// Let's start with a simple type
//

export type Person = {
  age: number;
  name: string;
};

//
// Which becomes
//

import { Type, Static } from "@sinclair/typebox";

export type Person = Static<typeof Person>;
export const Person = Type.Object({
  age: Type.Number(),
  name: Type.String(),
});

//
// Similarly, with an interface
//

export interface IPerson {
  age: number;
  name: string;
}

//
// Which becomes
//

import { Type, Static } from "@sinclair/typebox";

export type IPerson = Static<typeof IPerson>;
export const IPerson = Type.Object({
  age: Type.Number(),
  name: Type.String(),
});

//
// Let's add some more complicated types. What about unions and intersections?
//

export type T = { x: number } & { y: number };
export type U = { x: number } | { y: number };

//
// Which becomes
//

import { Type, Static } from "@sinclair/typebox";

export type T = Static<typeof T>;
export const T = Type.Intersect([
  Type.Object({
    x: Type.Number(),
  }),
  Type.Object({
    y: Type.Number(),
  }),
]);

export type U = Static<typeof U>;
export const U = Type.Union([
  Type.Object({
    x: Type.Number(),
  }),
  Type.Object({
    y: Type.Number(),
  }),
]);

//
// Nice! But I will need some JSON schema options here and there, which can't be
// expressed in typescript at all...
// No worries, simply use jsdoc in your types!
//
/**
 * @minimum 100
 * @maximum 200
 * @multipleOf 2
 * @default 150
 * @description "it's a number" - strings must be quoted
 * @foobar "should support unknown props"
 */
export type T = number;

//
// Which becomes
//

import { Type, Static } from "@sinclair/typebox";

export type T = Static<typeof T>;
export const T = Type.Number({
  minimum: 100,
  maximum: 200,
  multipleOf: 2,
  default: 150,
  description: "it's a number",
  foobar: "should support unknown props",
});

//
// Well, what if I don't like that the generated type and value has the same
// name?! No worries, you can define your own transformation functions!
// So that this..
//

export type Person = {
  age: number;
  name: string;
};

//
// Can easily become
//

import { Type, Static } from "@sinclair/typebox";

export type PersonType = Static<typeof PersonSchema>;
export const PersonSchema = Type.Object({
  age: Type.Number(),
  name: Type.String(),
});

//
// Sounds great! But I have many comments in my Typescript types and I want to
// use them as source of truth for my code. Can this be done..?
// Yup! We can start with this...
//

export type Person = {
  /**
   * @minimum 18
   */
  age: number;
  /**
   * @description full name of the person
   */
  name: string;
};

//
// And end up only generating the JSON schema/TypeBox values.
//

export const PersonSchema = Type.Object({
  age: Type.Number({ minimum: 18 }),
  name: Type.String({ description: "full name of the person" }),
});

//
// For an example of programmatic usage check out the examples folder.
//

For hands on examples, you can follow the simple snippets stored inside the examples folder. For a more complete set of examples (every feature is tested) you can take a look at the tests inside this repo for the programmatic usage and inside the tests in @sinclair/typebox-codegen repo for the typegen.

cli usage

The following text is the output that will be displayed when you issue ts2typebox -h or ts2typebox --help.