TOC

• Installation
• Documentation
• Contribution
• Future goals
• Supported frameworks
• Examples
• Repository architecture
• Comparison against similar solutions

Installation

npm i tdv-core

Supported Frameworks

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

Documentation

• tdv-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

import { collection, ValidationEngine } from "tdv-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

const dummy: Partial<UserFormFields> = {
  firstName: "",
  lastName: "",
  password: "12345",
  confirmPassword: "",
  url: "",
  age: 10,
};

Now we can inspect the errors of the given sample value

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

And the result is

{
  "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 tdv-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 tdv-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.

Comparison against similar solutions

| Criteria | tdv-monorepo | Yup | React Hook Form | Validator.js | Formik | | ----------------- | ------------ | ------ | --------------- | ------------ | ------ | | Type Safety | ✅ | ❌ | 🟡[^1] | ❌ | ❌ | | Syntax | ✅ | ❌ | ✅[^2] | ❌ | ❌ | | Learning Curve | ✅ | 🟡[^3] | 🟡[^4] | 🟡[^5] | 🟡[^6] | | Custom Validators | ✅ | 🟡[^7] | ✅ | 🟡[^8] | 🟡[^9] |

• ✅: Fully supported and easy-to-use
• ❌: Not supported
• 🟡: Partial support

[^1]: React Hook Form has good TypeScript support but doesn't integrate as seamlessly as tdv-monorepo. [^2]: React Hook Form uses hooks, which are easy to use but different from native TypeScript decorators. [^3]: Yup requires learning its custom object schema, adding to the learning curve. [^4]: React Hook Form requires understanding of hooks, adding a slight learning curve. [^5]: Validator.js requires learning their API, which can be cumbersome. [^6]: Formik has its own ecosystem, making the learning curve steeper. [^7]: Yup allows for custom validation but within the confines of its own schema. [^8]: Validator.js allows for some customization but it's not straightforward. [^9]: Formik allows for custom validation but within its own framework.