🚀 @tsvdec/core 🚀

🎩 TypeScript v5: Harness the power of TypeScript v5 decorators for type-safe validation.

🛠️ Extensible: Customize our library to fit your unique needs with ease.

🌍 i18n Support: Speak your users' language with built-in localization.

🔧 Adaptability: Seamless integration with existing TypeScript apps.

💻 Versatility: Works on both client and server-side.

TOC

- TOC
- Installation
- Supported Frameworks
- Documentation
- Contribution
- Future goals
- Examples
- Repository architecture

Installation

``bash
npm i @tsvdec/core
`

Supported Frameworks

- [x] view React implementation
- [ ] Angular
- [ ] Svelte
- [ ] Vue

Documentation

- @tsvdec/core

Contribution

To contribute, simply clone the main branch, commit changes to a local branch and open pull request.

Branch will be ready for merge after all CI tests pass and a review has been made.

Future goals

- [x] Implement strict type checking
- [x] Implement predefined decorator validators
- [x] Provide source code documentation
- [x] Implement concise tests for various scenarios
- [ ] Build implementation packages for popular front-end frameworks

Examples

A basic TypeScript form can look something like

`typescript
import { collection, ValidationEngine } from "@tsvdec/core";

/**
* This is an optional layer of abstraction if the class contains complex
* validation evaluations which shouldn't be registered as properties.
* In this example the "passwordsMatch" field isn't a settable property.
*/
export type UserFormFields = {
confirmPassword: string;
firstName: string;
lastName: string;
password: string;
url: string;
age: number;
};

export default class UserForm implements UserFormFields {
@collection.string.MinLength(5)
@collection.string.Required()
firstName!: string;

@collection.string.Required()
lastName!: string;

@collection.string.Required()
@collection.string.Password()
password!: string;

confirmPassword!: string;

@collection.string.URL()
url!: string;

@collection.number.ValueRange({ min: 18, max: 100 })
age!: number;

@collection.boolean.Truthy("Passwords must match")
get passwordsMatch(): boolean {
return this.password === this.confirmPassword;
}
}
`

And a sample value of type UserForm may look something like

`typescript
const dummy: Partial = {
firstName: "",
lastName: "",
password: "12345",
confirmPassword: "",
url: "",
age: 10,
};
`

Now we can inspect the errors of the given sample value

`typescript
const engine = new ValidationEngine(UserForm);
const { errors } = engine.validate(dummy);
console.log(JSON.stringify(errors, null, 2));
`

And the result is

`json
{
"firstName": ["Field is mandatory", "Field must contain at least 5 characters"],
"lastName": ["Field is mandatory"],
"password": ["Password must be at least 8 characters long"],
"url": [],
"age": ["Value must be greater than or equal to 18 and less than or equal to 100 but is 10"],
"passwordsMatch": ["Passwords must match"]
}
`

Repository architecture

The @tsvdec/core package is the backbone, providing core validation logic that's framework-agnostic. Features include:

- A decorator factory for easy integration with TypeScript
- Metadata management for dynamic behavior
- Localization support
- Built-in validators like Email, Required, etc.

The core package serves as the foundation for implementation libraries like @tsvdec/react, with future extensions planned for Angular, Vue, and Svelte. This modular design ensures that the core logic remains framework-agnostic, allowing for easy adaptability.

[comment]: # "### Comparison against similar solutions"
[comment]: #
[comment]: # "| Criteria | tdv-monorepo | Yup | React Hook Form | Validator.js | Formik |"
[comment]: # "| ----------------- | ------------ | ------ | --------------- | ------------ | ------ |"
[comment]: # "| Type Safety | ✅ | ❌ | 🟡[^1] | ❌ | ❌ |"
[comment]: # "| Syntax | ✅ | ❌ | ✅[^2] | ❌ | ❌ |"
[comment]: # "| Learning Curve | ✅ | 🟡[^3] | 🟡[^4] | 🟡[^5] | 🟡[^6] |"
[comment]: # "| Custom Validators | ✅ | 🟡[^7] | ✅ | 🟡[^8] | 🟡[^9] |"
[comment]: #
[comment]: # "- ✅: Fully supported and easy-to-use"
[comment]: # "- ❌: Not supported"
[comment]: # "- 🟡: Partial support"
[comment]: #
[comment]: # "[^1]: React Hook Form has good TypeScript support but doesn't integrate as seamlessly as tdv-monorepo`."
[comment]: # "[^2]: React Hook Form uses hooks, which are easy to use but different from native TypeScript decorators."
[comment]: # "[^3]: Yup requires learning its custom object schema, adding to the learning curve."
[comment]: # "[^4]: React Hook Form requires understanding of hooks, adding a slight learning curve."
[comment]: # "[^5]: Validator.js requires learning their API, which can be cumbersome."
[comment]: # "[^6]: Formik has its own ecosystem, making the learning curve steeper."
[comment]: # "[^7]: Yup allows for custom validation but within the confines of its own schema."
[comment]: # "[^8]: Validator.js allows for some customization but it's not straightforward."
[comment]: # "[^9]: Formik allows for custom validation but within its own framework."