@resourge/schema

@resourge/schema package is a comprehensive schema validation package tailored for developers working with diverse data schemas in modern applications. Designed with simplicity and efficiency in mind, @resourge/schema provides a set of utilities to effortlessly validate data against predefined schemas, ensuring accuracy, consistency, and compliance with specified standards.

Features

• Build with typescript.
• Easy to use in both javascript, node and deno.
• Extremely fast and versatile.
• OnlyOnTouch to validate values "only on touch" (values that were changed between last and new validation).
• Offers a complete collection of validations (email, postalCode, etc...).
• Custom methods (test and asyncTest) easy to implement and use.
• 100% coverage.
• Includes validation for countries postal codes and phone numbers.

Table of Contents

• Installation
• How it was done
• Benchmark
• Usage
• Rules
• Object
• String
• Number
• Array
• Date
• Boolean
• Compile
• Validate
• Default Message
• Documentation
• Contributing
• License
• Contact

Installation

Install using Yarn:

yarn add @resourge/schema

or NPM:

npm install @resourge/schema --save

How it was done

Beneath the surface, @resourge/schema meticulously constructs the validation framework solely through the Function constructor, entirely free from any user input. It's crucial to emphasize this distinction from the potential risks associated with Functions generated from user input, in this scenario, no user input factors into the creation process.

Think of @resourge/schema as akin to a developer meticulously crafting the validation structure with hand-coded if-else statements and loops. Every element of the structure is meticulously crafted as if the developer manually wrote each condition and iteration.

Benchmark

Benchmarks to compare with other schemas validators (the performance can variate slightly depending on the machine).

Benchmark

@resourge/schema x 18,634,802 ops/sec ±1.30%  (93 runs sampled)
Fast Validator   x  1,632,544 ops/sec ±0.50%  (92 runs sampled)
joi              x    182,179 ops/sec ±1.15%  (93 runs sampled)
zod              x     52,358 ops/sec ±0.86%  (89 runs sampled)
Yup              x      8,573 ops/sec ±4.42%  (81 runs sampled)
Fastest is  [ '@resourge/schema' ]

HeavyBenchmark (done with an array with 10 000 items)

@resourge/schema x 2,594    ops/sec ±0.80% (86 runs sampled)
Fast Validator   x   227    ops/sec ±0.96% (82 runs sampled)
joi              x    32.28 ops/sec ±2.86% (55 runs sampled)
zod              x    21.99 ops/sec ±1.58% (40 runs sampled)
Yup              x    15.65 ops/sec ±2.47% (43 runs sampled)
Fastest is  [ '@resourge/schema' ]

Would you like to try?

git clone https://github.com/resourge/schema.git
cd schema
npm install
npm run bench

Usage

import { array, object, string } from '@resourge/schemas';

type User = {
  name: string
  age: number
  hobbies: string[]
}

const user: User = {
  name: 'Rimuru',
  age: 39,
  location: {
    city: 'Tempest',
    address: 'Tempest',
    postalCode: '4000-000',
    country: 'Tempest'
  },
  hobbies: [
	'Read',
	'Nothing'
  ]	
}

const schema = object<User>({
  name: string().min(5).required(),
  age: number().min(18).required(),
  hobbies: array(string()).min(1).required(),
}).compile();

const schemaErrors = schema.validate(user)
const isValidUser = schema.isValid(user)

object

object is used to define schemas for validating objects.

Parameters

• schemas: An object containing validation schemas for object properties.
• message (optional): A custom error message template for object validation failures.

Methods

Object schema

Example

Once you have created a schema using the object function, you can chain various validation methods to define your validation rules. For example:

import { object, string, number } from '@resourge/schema';

const userSchema = object({
    name: string().required("Name is required"),
    age: number().min(18, "Age must be at least 18").max(100, "Age must be less than or equal to 100"),
    email: string().email("Invalid email address")
})
.compile();

userSchema.validate({
    name: "John Doe",
    age: 25,
    email: "[e-mail]"
});

In this example, the schema validates that the object:

• Has a name property that is required.
• Has an age property that is at least 18 and less than or equal to 100.
• Has an email property that is a valid email address.

string

string is used to define validation rules for string values. You can chain multiple validation methods to create complex validation logic.

Parameters

• message (optional)(string): Overrides the default error message for validation rules.

Methods

string schema

Example

Once you have created a schema using the string function, you can chain various validation methods to define your validation rules. For example:

import { string } from '@resourge/schema';

string()
    .min(5, "Minimum length should be 5 characters")
    .max(10, "Maximum length should be 10 characters")
    .pattern(/[a-zA-Z]+/, "Should contain only alphabetic characters")
	.compile();

In this example, the schema validates that the string:

• Has a minimum length of 5 characters.
• Has a maximum length of 10 characters.
• Contains only alphabetic characters.

number

number is used to define validation rules for numbers values. You can chain multiple validation methods to create complex validation logic.

Parameters

• message (optional)(string): Overrides the default error message for validation rules.

Methods

number schema

Example

Once you have created a schema using the number function, you can chain various validation methods to define your validation rules. For example:

import { string } from '@resourge/schema';

number()
    .min(0, "Value should be greater than or equal to 0")
    .max(100, "Value should be less than or equal to 100")
    .integer("Value should be an integer")
    .positive("Value should be positive")
	.compile();

In this example, the schema validates that the number:

• Is greater than or equal to 0.
• Is less than or equal to 100.
• Is an integer.
• Is positive.

array

array is used to define validation rules for array's. You can chain multiple validation methods to create complex validation logic.

Parameters

• message (optional)(string): Overrides the default error message for validation rules.

Methods

array schema

Example

Once you have created a schema using the array function, you can chain various validation methods to define your validation rules. For example:

import { array } from '@resourge/schema';

// Create an array schema for validating arrays of objects
const arraySchema = array({
    id: number().positive("ID must be a positive number"),
    name: string().required("Name is required"),
    email: string().email("Invalid email address")
}).compile();

// Example data to validate
const users = [
    { id: 1, name: "John Doe", email: "[e-mail]" },
    { id: -2, name: "Alice", email: "alice@example" }, // Invalid email
    { id: 3, name: "Bob", email: "[e-mail]" }
];

// Validate the array of users
const validationResult = arraySchema.validate(users);

if (validationResult.isValid) {
    console.log("All users are valid!");
} else {
    console.log("Validation errors:");
    console.log(validationResult.errors);
}

In this example, the schema validates:

• Each object must have a:
  • Positive id.
  • Non-empty name property of type string.
  • Valid email address in the email property.

date

date is used to define validation rules for dates. You can chain multiple validation methods to create complex validation logic.

Parameters

• message (optional)(string): Overrides the default error message for validation rules.

Methods

dates schema

Example

Once you have created a schema using the date function, you can chain various validation methods to define your validation rules. For example:

import { date } from '@resourge/schema';

// Create a date schema for validating arrays of objects
const dateSchema = date()
.minDate(new Date("2024-01-01"), "Date must be after 2024-01-01")
.maxDate(new Date("2024-12-31"), "Date must be before 2024-12-31")
.compile();

// Example data to validate
const eventDate = new Date("2024-06-15");

// Validate the date
const validationResult = dateSchema.validate(eventDate);

if (validationResult.isValid) {
    console.log("Event date is valid!");
} else {
    console.log("Validation errors:");
    console.log(validationResult.errors);
}

In this example, the schema validates:

• Each object must have a:
  • The date must be after January 1, 2024.
  • The date must be before December 31, 2024.

boolean

boolean is used to define validation rules for dates. You can chain multiple validation methods to create complex validation logic.

Parameters

• message (optional)(string): Overrides the default error message for validation rules.

Methods

boolean schema

Example

Once you have created a schema using the boolean function, you can chain various validation methods to define your validation rules. For example:

import { boolean } from '@resourge/schema';

// Create a boolean schema for validating boolean values
const booleanSchema = boolean();

// Example data to validate
const isEnabled = true;

// Validate the boolean value
const validationResult = booleanSchema.validate(isEnabled);

if (validationResult.isValid) {
    console.log("Boolean value is valid!");
} else {
    console.log("Validation errors:");
    console.log(validationResult.errors);
}

In this example, the schema validates:

• Each object must have a:
  • The value must be a boolean (true or false).

Compile

compile is responsible for compiling the validation rules into executable code. The compiled code is then used to validate input data against the defined schema. (it's recommended to use in every schema. Otherwise isValid and validate will call it).

Parameters

compile(config?: CompileConfig): this

• config (optional): An object containing configuration options for compilation.
  • debug (optional): A boolean flag indicating whether to log the validation structure for debugging purposes. Default is false.
  • defaultNullable (optional): A boolean flag indicating whether to make nullable default in the schemas. Default is undefined.
  • defaultOptional (optional): A boolean flag indicating whether to make optional default in the schemas. Default is undefined.
  • messages (optional): An object containing custom messages to be used during validation.
  • onlyOnTouch (optional): A boolean flag indicating whether to make onlyOnTouch default in the schemas.

Example

import { object } from '@resourge/schema';

// Compile the schema with default configuration
object().compile();

// Compile the schema with custom configuration
object().compile({
  debug: true,
  defaultNullable: true,
  messages: {
    required: 'This field is required.',
    notNullable: 'This field cannot be null.'
  }
});

Validate

validate is responsible for validating input data against the compiled schema. It returns an array of errors if any validation errors are encountered.

Usage

validate(value: Input, onlyOnTouch?: OnlyOnTouch<Input>): SchemaError[] | Promise<SchemaError[]>

Parameters

• value: The input data to be validated against the schema.
• onlyOnTouch (optional): An array of keys that inform the schema if a value was touched. Works only with the onlyOnTouch feature of the schema.

Example

import { array, object, string } from '@resourge/schemas';

const schema = object({
  username: string().required(),
  age: number().min(20).required()
  email: string().email().required()
}).compile();

const inputData = {
  username: 'John',
  age: 30,
  email: '[e-mail]'
};

const errors = schema.validate(inputData);
if (errors.length > 0) {
  console.log('Validation errors:', errors);
} else {
  console.log('Validation successful');
}

isValid

isValid is responsible for validating input data against the compiled schema and returning a boolean indicating whether the data is valid or not.

Usage

isValid(value: Input, onlyOnTouch?: OnlyOnTouch<Input>): Promise<boolean> | boolean

Parameters

• value: The input data to be validated against the schema.
• onlyOnTouch (optional): An array of keys that inform the schema if a value was touched. Works only with the onlyOnTouch feature of the schema.

Example

import { array, object, string } from '@resourge/schemas';

const schema = object({
  username: string().required(),
  age: number().min(20).required()
  email: string().email().required()
}).compile();

const inputData = {
  username: 'John',
  age: 30,
  email: '[e-mail]'
};

schema.isValid(inputData).then((isValid) => {
  if (isValid) {
    console.log('Input data is valid');
  } else {
    console.log('Input data is not valid');
  }
});

Default messages

@resourge/schema, by default, has default messages. This message can be changed globally.

const customMinMessage = 'Custom min message';

setupDefaultMessage({
  //... rest of translations
  string: {
    min: () => customMinMessage
  }
})

const schema = string()
.min(10)
.compile();

Documentation

For comprehensive documentation and usage examples, visit the schema documentation.

Contributing

Contributions to @resourge/schema are welcome! To contribute, please follow the contributing guidelines.

License

@resourge/schema is licensed under the MIT License.

Contact

For questions or support, please contact the maintainers:

• GitHub: Resourge