Class-based sanitization in TypeScript using decorators


300.1.24 years ago4 years agoMinified + gzip package size for @hollowverse/class-sanitizer in KB


hollowverse/class-sanitizer Build Status

Allows to use decorator and non-decorator based sanitization in your Typescript classes. Internally uses validator.js to make sanitization.


npm install @hollowverse/class-sanitizer --save


Create your class and put some sanity decorators on its properties you want to sanitize:

import { sanitize, Trim, Rtrim, Blacklist } from 'class-sanitizer';

export class Post {
  @Trim() title: string;

  text: string;

let post1 = new Post();
post1.title = ' Hello world ';
post1.text = '1. this is a great (2) post about hello 3 world.';

// now post will look like this:
// Post {
// title: "Hello world",
// text: ". this is a great  post about hello  world"
// }

Custom sanitization classes

If you have custom sanity logic you want to use as annotations you can do it this way:

  1. First create a file, lets say LetterReplacer.ts, and create there a new class:

    import { SanitizerInterface, SanitizerConstraint } from 'class-sanitizer';
    export class LetterReplacer implements SanitizerInterface {
      sanitize(text: string): string {
        return text.replace(/o/g, 'w');

    Your class must implement SanitizerInterface interface and its sanitize method, which defines sanitization logic.

  2. Then you can use your new sanitization constraint in your class:

    import { Sanitize } from 'class-sanitizer';
    import { LetterReplacer } from './LetterReplacer';
    export class Post {
      @Sanitize(LetterReplacer) title: string;

    Here we set our newly created LetterReplacer sanitization constraint for Post.title.

  3. Now you can use sanitizer as usual:

    import { sanitize } from 'class-sanitizer';

Using service container

Sanitizer supports service container in the case if want to inject dependencies into your custom sanity constraint classes. Here is example how to integrate it with typedi:

import { Container } from 'typedi';
import { Sanitizer } from 'class-sanitizer';

// do this somewhere in the global application level:
let sanitizer = Container.get(Sanitizer);
sanitizer.container = Container;

// now everywhere you can inject `Sanitizer` class which will go from the container
// also you can inject classes using constructor injection into your custom sanitizers.

Manual sanitization

There are several methodw in the Sanitizer that allows to perform non-decorator based sanitization:

import Sanitizer from 'class-sanitizer';

Sanitizer.blacklist(str, chars);
Sanitizer.ltrim(str, chars);
Sanitizer.normalizeEmail(str, isLowercase);
Sanitizer.rtrim(str, chars);
Sanitizer.stripLow(str, keepNewLines);
Sanitizer.toBoolean(input, isStrict);
Sanitizer.toInt(input, radix);
Sanitizer.trim(str, chars);
Sanitizer.whitelist(str, chars);

Sanitization decorators

Decorator Description
@Blacklist(chars: RegExp) Remove characters that appear in the blacklist.
@Escape() Replace <, >, &, ', " and / with HTML entities.
@Ltrim() Trim characters from the left-side of the input.
@NormalizeEmail() Canonicalize an email address.
@Rtrim() Trim characters from the right-side of the input.
@StripLow() Remove characters with a numerical value < 32 and 127, mostly control characters.
@ToBoolean(isStrict?: boolean) Convert the input to a boolean. Everything except for '0', 'false' and '' returns true. In strict mode only '1' and 'true' return true.
@ToDate() Convert the input to a date, or null if the input is not a date.
@ToFloat() Convert the input to a float.
@ToInt() Convert the input to an integer, or NaN if the input is not an integer.
@ToString() Convert the input to a string.
@Trim(chars?: string[]) Trim characters (whitespace by default) from both sides of the input. You can specify chars that should be trimmed.
@Whitelist(chars: RegExp) Remove characters that do not appear in the whitelist.* The characters are used in a RegExp and so you will need to escape some chars, e.g. whitelist(input, '\[\]').
@ToUpperCase() (self-explanatory)
@ToLowerCase() (self-explanatory)


Take a look at the tests for more examples of usages.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.