@d3vtool/validator v1.1.6

DevTool Validator

A Schema validation library.

• Validator

Installation

You can install the package using npm or yarn:

npm

npm install @d3vtool/validator

yarn

yarn add @d3vtool/validator

Validator Examples

1. String Validation

import { Validator, ValidationError, type VInfer } from "@d3vtool/validator";

const usernameSchema = Validator.string().minLength(5);

type Username = VInfer<typeof usernameSchema>;

const username: Username = "popHero83";

const errors = usernameSchema.validateSafely(username)

console.log(errors);

// or

try {
  usernameSchema.validate(username);
} catch(err: unknown) {
  if(err instanceof ValidationError) {
    // do something with it
    console.log(err);
  }
}

2. Number Validation

import { Validator, ValidationError, type VInfer } from "@d3vtool/validator";

const phoneSchema = Validator.number().requiredLength(10);

type Phone = VInfer<typeof phoneSchema>;

const phone: Phone = 1234567890;

const errors = phoneSchema.validateSafely(phone)

console.log(errors);

// or

try {
  phoneSchema.validate(phone);
} catch(err: unknown) {
  if(err instanceof ValidationError) {
    // do something with it
    console.log(err);
  }
}

3. Boolean Validation

import { Validator, ValidationError, type VInfer } from "@d3vtool/validator";

const vSchema = Validator.boolean(
  "Custom error message" // Optional argument for a custom error message.
);

type vSchema = VInfer<typeof vSchema>;

// Performs strict type validation to ensure the value is a boolean.
// If strict mode is not enabled, any truthy value will be considered true.
vSchema.strict();

const errors = vSchema.validateSafely("string"); // false
console.log(errors);

// or

try {
  vSchema.validate(phone);
} catch(err: unknown) {
  if(err instanceof ValidationError) {
    // do something with it
    console.log(err);
  }
}

4. Array Validation

import { Validator, ValidationError, type VInfer } from "@d3vtool/validator";

const arraySchema = Validator.array<string[]>() // type must be provided for type inference later.
  .minLength(2)
  .maxLength(5)
  .requiredLength(3)
  .notEmpty()
  .includes([1, 2, 3]);

type ArrayType = VInfer<typeof arraySchema>;

const myArray: ArrayType = [1, 2, 3];

const errors = arraySchema.validateSafely(myArray);

console.log(errors);

// or

try {
  arraySchema.validate(myArray);
} catch (err: unknown) {
  if (err instanceof ValidationError) {
    // do something with it
    console.log(err);
  }
}

Methods

minLength(length: number, error: string)

Ensures the array has a minimum length.

• Arguments:
  • length - The minimum length the array must have.
  • error - The error message to return if validation fails (default: 'The length of the array passed does not have min-length: '${length}'.').

maxLength(length: number, error: string)

Ensures the array has a maximum length.

• Arguments:
  • length - The maximum length the array can have.
  • error - The error message to return if validation fails (default: 'The length of the array passed does not have max-length: '${length}'.').

requiredLength(length: number, error: string)

Ensures the array has an exact length.

• Arguments:
  • length - The exact length the array must have.
  • error - The error message to return if validation fails (default: 'The length of the array passed does not have required-length: '${length}'.').

notEmpty(error: string)

Ensures the array is not empty.

• Arguments:
  • error - The error message to return if validation fails (default: 'Array passed in is empty').

transform<F>(fn: transformerFn<T[], F>)

Transforms the array before validation.

• Arguments:
  • fn - The transformer function to apply to the array.
  • Returns: The updated array validator.

includes(oneOfvalue: T | T[], strict: boolean, error: string)

Ensures the array includes a specified value or values.

• Arguments:
  • oneOfvalue - A single value or an array of values to check for inclusion.
  • strict - If true, all values must be included (every); if false, only one must be included (some).
  • error - The error message to return if validation fails (default: 'The provided value is not present in the one-of-value/s: '${oneOfvalue}'.').

optional()

Makes the array optional.

• Returns: The updated array validator.

ref(propertyName: string, error: string)

References another property for validation.

• Arguments:
  • propertyName - The name of the property to reference.
  • error - The error message to return if validation fails (default: 'The provided value is invalid or does not meet the expected criteria.').

custom(fn: ValidatorFn, error: string)

Adds a custom validation function.

• Arguments:
  • fn - The custom validation function which passes a value and must return boolean.
  • error - The error message to return if validation fails.

5. Simple Object Validation

import { Validator, ObjectValidationError, type VInfer } from "@d3vtool/validator";

const schema = Validator.object({
  name: Validator.string().minLength(5),
  email: Validator.string().email(),
});

type schema = VInfer<typeof schema>;

const schemaObj: schema = {
  name: "Sudhanshu",
  email: "email@email.abc"
}

const errors = schema.validateSafely(schemaObj);
console.log(errors);

// or

try {
  schema.validate(schemaObj);
} catch(err: unknown) {
  if(err instanceof ObjectValidationError) {
    // do something with it
    console.log(err);
  }
}

6. optional()

import { Validator, ObjectValidationError, type VInfer } from "@d3vtool/validator";

const schema = Validator.object({
  name: Validator.string().minLength(5), // name is required with a minimum length of 5
  email: Validator.string().email().optional(), // email is optional
});

type schema = VInfer<typeof schema>;

const schemaObj: schema = {
  name: "Sudhanshu",
  email: "email@email.abc", // This is valid, but email can also be omitted
};

const errors = schema.validateSafely(schemaObj);
console.log(errors); // Should show no errors

// or
try {
  schema.validate(schemaObj);
} catch(err: unknown) {
  if(err instanceof ObjectValidationError) {
    // do something with it
    console.log(err);
  }
}

// Example with email missing
const schemaObjWithoutEmail: schema = {
  name: "Sudhanshu",
  // email is omitted, which is allowed because it's optional
};

const errorsWithoutEmail = schema.validateSafely(schemaObjWithoutEmail);
console.log(errorsWithoutEmail); // Should show no errors as email is optional

// or 

try {
  schema.validate(schemaObjWithoutEmail);
} catch(err: unknown) {
  if(err instanceof ObjectValidationError) {
    // do something with it
    console.log(err);
  }
}

Explanation:

1. name field: This field is required, and it must be a string with a minimum length of 5 characters.
2. email field: This field is optional due to .optional(). If it's provided, it must be a valid email address; if not, the validation will still pass without errors.

Example Behavior:

1. If both name and email are provided, the validation will pass.
2. If only name is provided and email is omitted, the validation will still pass because email is marked as optional.

7. .custom(fn) Function [ string | number | array ] validators

import { Validator, ObjectValidationError, type VInfer } from "@d3vtool/validator";

const schema = Validator.object({
  name: Validator.string().custom((value: string) => {
    return value.length >= 5
  }, "minimum length of 5 required"), // name is required with a minimum length of 5
  email: Validator.string().email()
});

type schema = VInfer<typeof schema>;

const schemaObj: schema = {
  name: "Sudhanshu",
  email: "email@email.abc", // This is valid, but email can also be omitted
};

const errors = schema.validateSafely(schemaObj);
console.log(errors); // Should show no errors

// or
try {
  schema.validate(schemaObj);
} catch(err: unknown) {
  if(err instanceof ObjectValidationError) {
    // do something with it
    console.log(err);
  }
}

Explanation:

1. name field: This field is required, and it must be a string with a minimum length of 5 characters, the .custom(fn) fn takes a 'function' as an arg and should return boolean value.

8. Object Validation with Optional, Custom Fn and Self-Referencing Fields.

import { Validator, ObjectValidationError, type VInfer } from "@d3vtool/validator";

const schema = Validator.object({
  name: Validator.number().custom((value: string) => {
    return value.length >= 5
  }, "minimum length of 5 required"),
  email: Validator.string().email(),
  password: Validator.string().password().minLength(8),
  confirmPassword: Validator.string().ref("password").getInstanceBack().optional(),
});

type schema = VInfer<typeof schema>;

const schemaObj: schema = {
  name: 12345,
  email: "email@email.abc",
  password: "securepassword123",
  confirmPassword: "securepassword123", // Optional, but must match password if provided
}

const errors = schema.validateSafely(schemaObj);

// or

try {
  schema.validate(schemaObj);
} catch(err: unknown) {
  if(err instanceof ObjectValidationError) {
    // do something with it
    console.log(err);
  }
}

Explanation:

• name: The name field must be a number and have a minimum value of 5.
• email: The email field must be a valid email address.
• password: The password field must be at least 8 characters long and a valid password format.
• confirmPassword: The confirmPassword field is optional but, if provided, must match the value of the password field (using ref("password")).

In this example, the validateSafely function will check the provided schemaObj and return any validation errors, ensuring that confirmPassword (if present) matches password.