Validup 🛡️

This is a library to create domain specific validators.

🚧 Work in Progress

Validup is currently under active development and is not yet ready for production.

Table of Contents

• Features
• Installation
• Usage
• Concepts
  • Errors
  • Mounting
  • Nesting
  • Groups
• API
• License

Features

• ✨ Simple API
• 🌐 Works in any (Node.Js, browser & workers) environment
• ❌ Dedicated errors for different scenarios
• 🚀 Nesting of Validators and Containers
• 🎭 Easy integrate third-party validators/sanitizers (zod, validator.js, ...)

Installation

npm install validup --save

Usage

A validator is an (async) function to validate (and modify) any piece of information. Each validator receives a context containing the actual value, key (aka path), ...

import {
    Validator, 
    ValidatorContext,
    ValidupValidatorError
} from 'validup';

const isString: Validator = (ctx: ValidatorContext) => {
    if (typeof ctx.value !== 'string') {
        throw new ValidupValidatorError({
            message: `The validator for ${ctx.path} expected a string as input.`,
            expected: 'string',
            path: ctx.path
        })
    }
    
    return ctx.value;
}

This validator can than be mounted on a specific path to a container. A mount path can either be a regular string or a glob pattern.

import { Container } from 'validup';

const container = new Container();
container.mount('foo', isString);

const output = await container.run({
    foo: 'bar',
    bar: 'baz'
});

console.log(output);
// { foo: 'bar' }

[!NOTE] The container run method throws an error if an error occurred during the execution of a validator.

Concepts

Errors

During the execution of a validator, a ValidupValidatorError or ValidupNestedError can be thrown. A ValidupNestedError bundles multiple ValidupValidationErrors.

When the execution of a Container fails, the container will always throw a ValidupNestedError. Unknown errors will be converted to a ValidupValidatorError.

Mounting

🚧 Work in Progress ...

Nesting

🚧 Work in Progress

Groups

When mounting a validator or container, it is possible to restrict the execution to explicit execution groups.

import { Container } from 'validup';

const container = new Container();
container.mount('id', { group: ['update', 'delete'] }, isString);
container.mount('name', { group: ['craete', 'update', 'delete']}, isString);

const output = await container.run(
    {
        id: 'xxx',
        name: 'foo'
    }, 
    {
        group: 'create'
    }
 );

console.log(output);
// { name: 'foo' }

In this example the output will only contain the value of the key name. The reason for this is, that the id key is not registered for the create group.

[!NOTE] To always execute a mounted container/validator do not specify any group or use the * group.

API

Validator

type Validator = (ctx: ValidatorContext) => Promise<unknown> | unknown;

ValidatorContext

type ValidatorContext = {
    /**
     * The expanded mount path in the current container.
     */
    path: string,
    /**
     * The unexpanded mount path in the current container.
     */
    pathRaw: string,
    /**
     * The global mount path of the parent container.
     */
    pathAbsolute: string,
    /**
     * The actual value, which should be validated.
     */
    value: unknown,
    /**
     * The input data of the current container.
     */
    data: Record<string, any>
};

License

Made with 💚

Published under MIT License.