@drupe/vldt v1.0.0

vldt

Precompiled deep object validation

Installation

npm i @drupe/vldt

Usage

import vldt from '@drupe/vldt'

vldt(rule)

Compile a rule to an invalidation function.

const invalidate = vldt({foo: String})

• rule <rule> - The rule to compile.
• invalidate <function> - The invalidation function.

vldt.condition(rule)

Compile a rule to a condition function.

const condition = vldt.condition({foo: String})

condition({foo: 'bar'}) // returns true
condition(42) // returns false

• rule <rule> - The rule to compile.
• condition <function> - The condition function that returns true if the object, passed with the first argument is valid, otherwise false.

vldt.assert(rule, message)

Compile a rule to an assertion function that throws an error if an invalid object is passed to it.

const assert = vldt.assert({foo: String})

assert({foo: 'bar'}) // does nothing
assert({foo: 42}) // throws vldt.ValidationError

• rule <rule> - The rule to compile.
• message <string> - The error message. (Context information will be appended)
• assert <function> - The assertion function. + throws <vldt.ValidationError> - If the object passed with the first argument is invalid.

Rules

A rule can be any combination of the rule types below.

Compared values

null, undefined, <boolean>, <number> and <string> rules must equal the tested object strictly.

null only matches: null
42 only matches: 42, but not '42'

Functions with prototype (Classes)

Tested objects must be an instance of the rule.

String matches: 'foo'
TypeError matches: new TypeError()

This is tested using the instanceof operator except for the following rules:

Arrow functions (Invalidation Functions)

Arrow functions are considered compiled invalidation functions.

Arrays (Tuples)

Arrays as rules are treated like tuples that match arrays with the same length and order of elements.

[String, Number]
	matches: ['foo', 42],
	but not [42, 'foo']

Objects

Objects as rules are used to validate object fields. The tested object must have no extra fields. Missing fields are treated as undefined.

{foo: String}
	matches: {foo: 'bar'},
	but not: 42, {foo: 42}, {foo: 'bar', bar: 42}

{foo: vldt.or(Number, undefined)}
	matches: {foo: 42}, {foo: undefined} and {}

Regular Expressions

Objects are tested against regular expression rules.

/foo/
	matches: 'foo, bar',
	but not: 'bar', 42

vldt.predicate(match)

Compile a simple condition to an invalidation function.

const invalidate = vldt.predicate(n => n > 42)
	matches: 127,
	but not: 7

• match <function> - The condition which takes the object to test as argument and must return a truthy value if the object is valid.
• invalidate <function> - The invalidation function.

vldt.and(...rules)

Compile multiple rules to an invalidation function where each rule must match.

const invalidate = vldt.and(Number, vldt.predicate(n => n > 42))
	matches: 127,
	but not: 7, 'foo'

• rules <...rule> - The rules to compile.
• invalidate <function> - The invalidation function.

vldt.or(...rules)

Compile multiple rules to an invalidation function where any rule must match.

const invalidate = vldt.or(Number, String)
	matches: 42, 'foo'

• rules <...rule> - The rules to compile.
• invalidate <function> - The invalidation function.

vldt.every(rule)

Compile a rule to validate each element of an array.

const invalidate = vldt.every(String)
	matches: ['foo', 'bar'],
	but not: ['foo', 42], 42

• rule <rule> - The rule to compile.
• invalidate <function> - The invalidation function.

vldt.some(rule)

Compile a rule to validate at least one element of an array.

const invalidate = vldt.some(String)
	matches: ['foo', 42],
	but not: [7, 42], 42

• rule <rule> - The rule to compile.
• invalidate <function> - The invalidation function.

vldt.sparse(rule)

Compiles an object rule that allows extra fields.

{foo: String}
	matches: {foo: 'bar'}, {foo: 'bar', bar: 42}
	but not: 42, {foo: 42}

Invalidation Functions

Each rule is compiled to an invalidation function that determines which part of an object is invalid. If an object is invalid, the function must return an array (the context) with field names or array indexes that points to the invalid part of that object. If the return value is falsy, the object is considered valid.

function invalidate(obj, ctx = []) {
	// If 'obj.b[42]' is invalid:
	return ctx.concat('b', 42)

	// If 'obj' itself is invalid:
	return ctx
}