joi-class-decorators

Integrate your Joi validation schema definitions directly into your type/DTO classes with convenient decorators.

• Installation
  • Peer dependencies
• Usage
• Reference
  • Validation groups
    • Built-in group: DEFAULT
  • getClassSchema(typeClass, opts?: { group? }) (alias: getTypeSchema())
  • @JoiSchema() property decorator
    • @JoiSchema(joiSchema)
    • @JoiSchema(groups[], joiSchema)
    • @JoiSchema(nestedType, customizeSchemaCallback?)
    • @JoiSchema(groups[], nestedType, customizeSchemaCallback?)
    • @JoiSchema([nestedType], customizeArraySchemaCallback?, customizeSchemaCallback?)
    • @JoiSchema(groups[], [nestedType], customizeArraySchemaCallback?, customizeSchemaCallback?)
  • @JoiSchemaOptions() class decorator
    • @JoiSchemaOptions(Joi.Options)
    • @JoiSchemaOptions(groups[], Joi.options)
  • @JoiSchemaExtends(type) class decorator
  • @JoiSchemaCustomization() class decorator
    • @JoiSchemaCustomization(customizeSchemaCallback)
    • @JoiSchemaCustomization(groups[], customizeSchemaCallback)
  • Class inheritance

Installation

npm install --save joi-class-decorators

Peer dependencies

npm install --save joi@^17 reflect-metadata@^0.1

Usage

Annotate your type/DTO classes with property and options decorators, then obtain the computed schema for use in validation.

import { JoiSchema, JoiSchemaOptions, getClassSchema } from 'joi-class-decorators';
import * as Joi from 'joi';

@JoiSchemaOptions({
  allowUnknown: false,
})
export class BookDto {
  @JoiSchema(Joi.string().required())
  @JoiSchema(['CREATE'], Joi.string().required())
  @JoiSchema(['UPDATE'], Joi.string().optional())
  name!: string;

  @JoiSchema(Joi.string().required())
  @JoiSchema(['CREATE'], Joi.string().required())
  @JoiSchema(['UPDATE'], Joi.string().optional())
  author!: string;

  @JoiSchema(Joi.number().optional())
  publicationYear?: number;
}

const schema = getClassSchema(BookDto);
Joi.assert(
  {
    name: 'Interesting Times',
    author: 'Terry Pratchett',
    publicationYear: 1994,
  },
  schema,
);

const updateSchema = getClassSchema(BookDto, { group: 'UPDATE' });
Joi.assert(
  {
    name: 'Interesting Times',
  },
  updateSchema,
);

Reference

Validation groups

Groups can be used to annotate a property (@JoiSchema) or class (@JoiSchemaOptions) with different schemas/options for different use cases without having to define a new type.

A straightforward use case for this is a type/DTO that behaves slightly differently when creating or updating a ressource. Have a look at the example in the Usage section.

Built-in group: DEFAULT

The DEFAULT symbol is the default "group" assigned under the hood to any schema defined on a property, or any options defined on a class, if a group is not explicitely specified.

In the following example, both declarations have the same effect:

import { DEFAULT } from 'joi-class-decorators';

@JoiSchemaOptions({
  allowUnknown: false,
})
class ImplicitDefaultGroupDto {
  @JoiSchema(Joi.string().required())
  name!: string;
}

@JoiSchemaOptions([DEFAULT], {
  allowUnknown: false,
})
class ExplicitDefaultGroupDto {
  @JoiSchema([DEFAULT], Joi.string().required())
  name!: string;
}

getClassSchema(typeClass, opts?: { group? }) (alias: getTypeSchema())

This function can be called to obtain the Joi schema constructed from typeClass. Nothing is cached.

A group can be passed to construct the schema for a specific group (together with the groups specified in @JoiSchema() etc.).

This function makes possible advanced uses such as the following:

class ThrillerDto {
  @JoiSchema(Joi.number().required())
  thrill!: number;
}

class RomanceDto {
  @JoiSchema(Joi.number().optional())
  romance?: number;
}

class AuthorDto {
  @JoiSchema(Joi.alternatives(getTypeSchema(ThrillerDto), getTypeSchema(RomanceDto)))
  booksRatings: ThrillerDto | RomanceDto;
}

@JoiSchema() property decorator

Define a schema on a type (class) property. Properties with a schema annotation are used to construct a full object schema.

Example

class BookDto {
  @JoiSchema(Joi.string().required())
  name!: string;

  @JoiSchema(Joi.string().required())
  author!: string;

  @JoiSchema(Joi.number().optional())
  publicationYear?: number;
}

Will construct the following equivalent Joi schema:

Joi.object().keys({
  name: Joi.string().required(),
  author: Joi.string().required(),
  publicationYear: Joi.number.optional(),
});

@JoiSchema(joiSchema)

Assign the passed Joi schema to the decorated property for the DEFAULT group.

Example

class BookDto {
  @JoiSchema(Joi.string().optional())
  name?: string;
}

@JoiSchema(groups[], joiSchema)

Assign the passed Joi schema to the decorated property for the passed groups.

Example

class BookDto {
  @JoiSchema(['CREATE'], Joi.string().required())
  name!: string;
}

@JoiSchema(nestedType, customizeSchemaCallback?)

Assign the full schema constructed from the passed nestedType to the decorated property, for the DEFAULT group.

The nested schema is constructed using the same method as other schemas, e.g. non-decorated properties are not used in constructing the schema.

If the optional customizeSchemaCallback is provided, it will be called with the constructed schema to allow customization, e.g. .options(), .required() and so on.

Example

class AuthorDto {
  @JoiSchema(BookDto, schema => schema.required())
  firstBook!: BookDto;
}

@JoiSchema(groups[], nestedType, customizeSchemaCallback?)

Assign the full schema constructed from the passed nestedType to the decorated property, for the passed groups.

Example

class AuthorDto {
  @JoiSchema(['UPDATE'], BookDto, schema => schema.optional())
  firstBook?: BookDto;
}

@JoiSchema([nestedType], customizeArraySchemaCallback?, customizeSchemaCallback?)

Assign a Joi.array(), with the full schema constructed from the passed nestedType as .item(), to the decorated property, for the DEFAULT group.

The nested schema is constructed using the same method as other schemas, e.g. non-decorated properties are not used in constructing the schema.

If customizeArraySchemaCallback is provided, it will be called with the constructed outer schema - the .array() schema - to allow customization, e.g. .options(), .required() and so on.

If customizeSchemaCallback is provided, it will be called with the constructed inner schema - the one passed to .item() - to allow customization, e.g. .options(), .required() and so on.

Example

class AuthorDto {
  @JoiSchema([BookDto], arraySchema => arraySchema.required(), schema => schema.optional())
  books!: BookDto[];
}

Note that this is mainly a convenience type, as it is equivalent to:

class AuthorDto {
  @JoiSchema(BookDto, schema => Joi.array().items(schema.optional()).required())
  books!: BookDto[];
}

@JoiSchema(groups[], [nestedType], customizeArraySchemaCallback?, customizeSchemaCallback?)

Assign a Joi.array(), with the full schema constructed from the passed nestedType as .item(), to the decorated property, for the passed groups.

Example

class AuthorDto {
  @JoiSchema(
    ['UPDATE'],
    [BookDto],
    arraySchema => arraySchema.optional().default([]),
    schema => schema.optional(),
  )
  books!: BookDto[];
}

@JoiSchemaOptions() class decorator

Assign the passed Joi options to be passed to .options() on the full constructed schema.

Example

@JoiSchemaOptions({
  allowUnknown: false,
})
class BookDto {
  @JoiSchema(Joi.string().optional())
  name?: string;
}

@JoiSchemaOptions(Joi.Options)

Assign the passed Joi options to the decorated class for the DEFAULT group.

Example

@JoiSchemaOptions({
  allowUnknown: false,
})
class BookDto {
  @JoiSchema(Joi.string().optional())
  name?: string;
}

@JoiSchemaOptions(groups[], Joi.options)

Assign the passed Joi options to the decorated class for the passed groups.

Example

@JoiSchemaOptions(['CREATE'], {
  allowUnknown: false,
})
class BookDto {
  @JoiSchema(['CREATE'], Joi.string().optional())
  name?: string;
}

@JoiSchemaExtends(type) class decorator

Specify an alternative extended class for schema construction. type must be a class constructor.

This decorator is useful for cases where the actual parent class in the prototype chain is not the class that has been decorated with @JoiSchema() etc., possibly as a result of some other transformation, as with @nestjs/graphql's OmitType().

The following example illustrates the behavior:

// Given this parent class
class BookDto {
  @JoiSchema(Joi.string().required())
  name!: string;
}

// These two examples generate the same schema (containing both name and thrill keys)
// 1.
class ThrillerDto extends BookDto {
  @JoiSchema(Joi.number().optional())
  thrill?: number;
}
// 2.
@JoiSchemaExtends(BookDto)
class ThrillerDto {
  @JoiSchema(Joi.number().optional())
  thrill?: number;
}

For an actual use case, consider the following example for a @nestjs/graphql InputType, where OmitType() creates a new internal class on which it tacks on all the properties from Book, but without applying any decorators. Without @JoiSchemaExtends(), no decorated properties from Book would be present in the final schema:

// Does not work as expected
@InputType()
export class CreateBookInput extends OmitType(Book, ['id'], InputType) {
  @JoiSchema(Joi.string())
  @Field()
  extraArg?: string;
}

// Works as expected
@InputType()
@JoiSchemaExtends(Book)
export class CreateBookInput extends OmitType(Book, ['id'], InputType) {
  @JoiSchema(Joi.string())
  @Field()
  extraArg?: string;

@JoiSchemaCustomization() class decorator

This decorator takes a customization function which is called with the full and final constructed class (type) schema and uses the return value (which should be a schema) in subsequent steps.

This covers cases such as:

@JoiSchemaCustomization(schema => schema.or('label', 'description'))
class BookDto {
  @JoiSchema(Joi.string().required())
  label!: string;

  @JoiSchema(Joi.string().required())
  description!: string;
}

Notes

• This theoretically allows for a complete replacement of the schema. Your customization function could simply return a new schema such as Joi.string('hello'), though it is unclear what the applications of this are (perhaps conditional cases, though this is covered in part by groups and Joi's built-in conditionals)
• For extending types, callbacks are called for a parent before a child type.

@JoiSchemaCustomization(customizeSchemaCallback)

Assign the passed customization callback to the decorated class for the DEFAULT group.

Example: see example above

@JoiSchemaCustomization(groups[], customizeSchemaCallback)

Assign the passed customization callback to the decorated class for the passed group(s).

Example

@JoiSchemaCustomization(['CREATE'], schema => schema.or('label', 'description'))
class BookDto {
  @JoiSchema(Joi.string().required())
  label!: string;

  @JoiSchema(Joi.string().required())
  description!: string;
}

Class inheritance

Both @JoiSchema() and @JoiSchemaOptions() work with class inheritance.

@JoiSchemaOptions({
  allowUnknown: false,
})
class BookDto {
  @JoiSchema(Joi.string().required())
  name!: string;
}

@JoiSchemaOptions({
  allowUnknown: true,
})
class ExtendedBookDto extends BookDto {
  @JoiSchema(Joi.string().optional())
  author?: string;
}

Will construct the following equivalent Joi schema for ExtendedBookDto:

Joi.object()
  .keys({
    name: Joi.string().required(),
    author: Joi.string().optional(),
  })
  .options({
    allowUnknown: true,
  });