voodoo-ts aims to be a validation library with short syntax and a nice developer experience. This library is inspired by the class-validator package.
@Validator()
class UserDto {
username!: string;
email!: string;
description?: string;
itemsCollected: string[];
}
const result = validate(UserDto, {
username: 'Thanos',
email: 'thanos@example.com',
description: 'Purple dude',
itemCollected: ['Soul Stone'],
});
Validators use the type hints to verify your input data.
npm install @voodoo-ts/voodoo-ts
Create a file in your project
import { TransformerInstance } from '@voodoo-ts/voodoo-ts';
export const voodoo = TransformerInstance.withDefaultProject(); // Export the whole thing
export { Dto, transform, transformOrThrow, transformer } = voodoo.unwrap(); // Export decorator and transform function
withDefaultProject()
will use the tsconfig.json in your project root. If you want more control over
this you need to create a ts-morph Project
and configure it before passing it to the TransformerInstance
import { Dto, transform } from './your-created-file.ts';
@Dto()
class UserDto {
name!: string;
powerlevel!: number;
}
const result = await transform(UserDto, { name: 'Vegeta', powerlevel: 9001 });
if (result.success) {
// You can use result.object here
console.log(result.object);
} else {
// Handle errors yourself
}
const user = await transformOrThrow(UserDto, { name: 'Mordecai', powerlevel: 5 });
// If this point is reached, `user` will be a UserDto instance
Objects are validated before transforming. There is also a validate()
and validateOrThrow()
method which only validates objects. These will return the
incoming object untouched in result.object
.
Many type constructs are regcognized. Check Supported Syntax for reference.
Objects created by transform()
will never contain properties which are not defined in the Dto. By default validation fails if unknown properties are discovered.
You can change this by using transform(DtoClass, { some object }, { allowUnknownFields: true })
.
Be careful if you pass this to validate()
. This will not clean up unknown properties.
You either need to make sure this won't cause you problems or use transform()
@voodoo.Dto()
class UserDto {
username!: string;
alias?: string; // optional
level!: number;
isAdmin!: boolean;
}
@voodoo.Dto()
class UserDto {
username!: string;
email!: string;
}
@voodoo.Dto()
class AdminUserDto extends UserDto {
permissions!: string[];
}
enum TestEnum {
YES = 'yes',
NO = 'no',
}
@voodoo.Dto()
class Test {
enumProperty!: TestEnum;
}
@voodoo.Dto()
class Gauntlet {
infinityStones: string[];
powerupForEachInfinityStone: number[];
}
Arrays support basic types, nested validators & enums.
@voodoo.Dto()
class Test {
basicProperty!: number | string | boolean;
nullable!: number | null;
}
interface IAnimal {
animalName: string;
rating: number;
}
@voodoo.Dto()
class Food {
name!: string;
rating!: number;
}
@voodoo.Dto()
class User {
favoriteFood!: Food;
favoriteFoods!: Food[]; // Arrays are supported
favoriteFoodWithoutRating!: Omit<Food, 'rating'>; // Omit<T, U> is supported
favoriteFoodName!: Pick<Food, 'name'>; // Pick<T, U> is also supported
incompleteFoodData!: Partial<Food>;
favoriteAnimal!: IFavoriteAnimal; // Interfaces
favoriteDrink!: {
// Object literals
drinkName: string;
rating: number;
};
}
Self-referential structures are also possible
@voodoo.Dto()
class TreeNode {
name!: string;
children!: TreeNode[];
}
@voodoo.Dto()
class Test {
tuple!: [number, string];
}
@voodoo.Dto()
class Test {
record!: Record<string, number>;
}
voodoo-ts ships with some decorators to define constraints that can't be provided by type hints.
If you need something that can't be covered by these decorators, you can create your own using createAnnotationDecorator
. You can use the existing decorators as reference.
Generic decorator which takes a function as validation callback. API is work in progress.
Validates if a string can be parsed as number (including floats)
Validates if a string can be parsed as an integer.
Validates string or array length. If you have an array of strings you can use @ArrayLength(min, max?)
and StringLength(min, max?)
Validates if a number is between min and max.
Checks if a string consists of a list of numbers separated by separator
.
Validate a field only if the callback returned true
.
This allows you to get value for the field annoated with @From from a different field. You can use this to translate property names. For example:
@voodoo.Dto()
class Config {
@From('SOME_ENV_VAR')
settingFromSomeEnvVar!: string;
}
const config = transform(Config, process.env, { allowUnknownFields: true });
Under the hood ts-morph is used to analyze the class definitions. When the @Valdidator()
decorator is used, the call site's line number will be extracted from the call stack.
This information is used to locate the class definition in the source code. As far as I know this is the only way to make the link from runtime to compiletime. This approach is rather hacky and leads to a number of caveats (see "Caveats" section).
Since voodoo-ts uses static code analysis to enable much of it's goodies, it is necessary to ship your source code with your deployment (for now).
Because of this, it will not be usable in a browser environment. However, there might be solutions for this, but they will require some extra build steps.
You'll also need sourcemaps and sourcemap support. Tested ways to run applications using voodoo-ts are ts-node
and running tsc
and executing the compiled .js files. This might work with babel or other bundlers, but you need to make sure that sourcemaps are present and useable.
You must use the decorator syntax to annotate the class, so this
class Test {
foo!: number;
}
voodoo.Dto(Test);
won't work.
- Error formatting could be improved.
- Serialize dtos to remove the dependency on sources.