@hippo-oss/dto-decorators

dto-decorators

DTO type decorators and factories.

Defines types for decorating DTO classes and a mechanism for composing multiple implementations of these decorators.

What Problem Does This Project Solve?

TypeScript applications must take special care at their boundaries to ensure that runtime data matches its type definitions. For example, many applications will extract JSON from an HTTP request might and (naively) cast this data to a TypeScript type:

const input = await request.json() as MyInputType

This approach, however, offers no guarantee that the input type actually matches the type declaration; a cast merely tells tsc that a type should be treated in a particular way.

A common solution to this mismatch is to perform runtime validation of a Data Transfer Object (DTO), thereby ensuring that the declared type of each data item matches its actual type.

const json = await request.json();
const input = validate(MyInputType, json);

Because TypeScript types lose their type information at runtime, the DTO strategy only works if some other layer instruments DTOs with runtime metadata. A common solution in this space is to use decorators to attach type information to class.

This approach is so popular, in fact, that there are many implementations end up using multiple decorator libraries, including:

• class-transformer
• class-validator
• @nestjs/swagger

This library aims to provide an implementation-agnostic decorator API that can be used to generate appropriate decorators across multiple library implementations without introducing rendundant decorator information.

Decorator Flavors

This library defines a set of types that can be used to produce implementation-specific decorator "flavors", including a noop implementation (provided in this library) and several others (provided in other libraries).

• class-decorators implements a flavor that uses class-transformer and class-validator to convert and validate DTO types.

• metadata-decorators implements a flavor that persists decorator metadata using reflect-metadata.

• deprecation-decorators implements a flavor that raises a system warnings when a deprecated property is set.

Decorator Composition

The real power of dto-decorators comes from composing these decorators flavors with each other -- or with implementations that use other third-party dependencies. Composition is as easy as:

import { composeDecoratorFactories } from '..';

const decorators = composeDecoratorFactories([
    MY_DECORATORS,
    SOME_OTHER_DECORATORS,
]);

const { IsInteger } = decorators;

```ts
class Example {

    @IsInteger({
        description: 'An example value',
    })
    public value!: number;
}

Available Decorators

The following decorators are supported:

Decorator	Description
IsBoolean	Declares a boolean value.
IsDate	Declares a Date value.
IsDateString	Declares an ISO 8601 date string.
IsEnum	Declares an enumerated value.
IsInteger	Declares an integer number.
IsNested	Declares a nested object type.
IsNumber	Declares a floating point number.
IsString	Declares a string.
IsUUID	Declares a UUID string.

Decorator Options

Decorators may be passed various options, depending on their type.

All options are optional expect where indicated.

Option	Decorator	Description
description	all	Description of the field; exposed in OpenAPI.
expose	all	Enables alternate name to be set for the field.
isArray	all	Designates an array of values.
name	all	Alternate name of the field; exposed in OpenAPI.
nullable	all	Whether the field can be set to null.
optional	all	Whether the field be set to undefined or omitted.
deprecated	all	Whether the field appears as deprecated
-----------------	--------------	---------------------------------------------------
format	IsDate	The OpenaPI date format; defaults to date-time.
-----------------	--------------	---------------------------------------------------
format	IsDateString	The OpenAPI date format; defaults to date.
-----------------	--------------	---------------------------------------------------
enum (required)	IsEnum	The enum type.
enumName	IsEnum	The enum name; required to correctly export OpenAPI
-----------------	--------------	---------------------------------------------------
maxValue	IsInteger	The maximum value of the field.
minValue	IsInteger	The minimum value of the field.
-----------------	--------------	---------------------------------------------------
type (required)	IsNested	The nested type.
-----------------	--------------	---------------------------------------------------
maxValue	IsNumber	The maximum value of the field.
minValue	IsNumber	The minimum value of the field.
-----------------	--------------	---------------------------------------------------
maxLength	IsString	The maximum length of the string.
minLength	IsString	The minimum length of the string.
pattern	IsString	A regex pattern for validating the string.
-----------------	--------------	---------------------------------------------------
version	IsUUID	The type of UUID.

Array Options

Any property can be declared as an array:

class Example {
   @IsString({
       isArray: true,
   })
   values!: string[];
}

The isArray option may be supplied as either the literal true or as ArraySizeOptions:

class Example {
   @IsString({
       isArray: {
           maxSize: 30,
           minSize: 0,
       },
   })
   values!: string[];
}

Enum Options

Enumerated types work pretty much as expected:

enum Color {
  Red = 'Red',
  Blue = 'Blue',
  Green = 'Green',
}

class Example {
   @IsEnum({
      enum: Color,
      enumName: 'Color',
   })
   color!: Color;
}

The enumName value is optional, but encouraged. Some library implementations will not be able to correctly correlate the same enum value across multiple usages without a unifying name.

Nested Options

Decorator values that use another object type should be decorated with IsNested:

class Child {
    @IsString()
    value!: string;
}

class Parent {
     @IsNested({
         type: Child,
     })
     child!: Child;
}

Every child type is expected to define at least one decorator field. Failure to do so may result in errors in some library implementations.