Declarative Type Validator

Provides runtime type validation functionality for class methods and functions.

Usage

Most of the time, using a decorator is the most convenient way to apply type
checking to a class method:

``js
import { validateTypesAsync } from "@twilio/declarative-type-validator";

class TestClass {
@validateTypes("number")
someMethod(value) {
console.log(value is a number: ${value});
}
}
`

Or if it is an async method, you could use an async version of the decorator, in
which case the type error will be thrown as a rejected promise:

`js
import { validateTypesAsync } from "@twilio/declarative-type-validator";

class TestClass {
@validateTypesAsync("number")
async someMethod(value) {
console.log(value is a number: ${value});
}
}
`

Each argument passed into the decorator should be a valid rule that corresponds
to the respective argument of the method being decorated. If an argument
requires more than one check, you can pass an array of rules which will get
applied following the OR logic:

`js
import { validateTypesAsync } from "@twilio/declarative-type-validator";

class TestClass {
@validateTypes(["number", "string"])
someMethod(value) {
console.log(value is either a number or a string: ${value});
}

@validateTypes("string", ["number", "boolean"])
someOtherMethod(value, secondValue) {
console.log(value is a string: ${value});
console.log(secondValue is either a number or a boolean: ${secondValue});
}
}
`

Since constructors can't be decorated the same way that normal methods can,
you could utilize the validateConstructorTypes decorator (applied to the
class itself, as opposed to the constructor method) to apply argument validation
to the constructor:

`js
import { validateConstructorTypes } from "@twilio/declarative-type-validator";

@validateConstructorTypes("string", ["number", "boolean"])
class TestClass {
constructor(value, secondValue) {
console.log(value is a string: ${value});
console.log(secondValue is either a number or a boolean: ${secondValue});
}
}
`

For functions outside of classes, you can utilize runtimeTypeValidation
function instead. It accepts two arguments, first being the array of rules (each
element of the array corresponding to an array of rules for the respective
argument), with the second being the arguments to validate.

Here's an example of the two methods from previous example rewritten using the
runtimeTypeValidation function:

`js
import { runtimeTypeValidation } from "@twilio/declarative-type-validator";

function someFunction(value) {
runtimeTypeValidation([[type("number")]], [value]);

console.log(value is a number: ${value});
}

function someOtherFunction(value, secondValue) {
runtimeTypeValidation(
[[type("string")], [type("number", "boolean")]],
[value, secondValue]
);

console.log(value is a string: ${value});
console.log(secondValue is either a number or a boolean: ${secondValue});
}
`

Rules

Type validator comes with a few prebuilt rules. They come in two shapes: rule
factories and rule constants.

Rule factories are functions which generate an object describing the validation
rule. Every single rule factory accepts one or multiple arguments. The rule
factories are:

* type
* literal
* custom
* objectSchema
* array

Rule constants are pre-made rule objects which don't require any parameters.
The rule constants are:

* nonEmptyString
* nonNegativeInteger
* pureObject

$3

Validates against either a primitive type (typeof x) or a constructor
function (instanceof x). If multiple arguments are passed, then they will be
applied following the OR logic.

#### Note

Using the type rule factory itself could be omitted if a string representing a
primitive type or a constructor function is passed as a rule itself.

#### Examples

##### Single primitive type

`js
@validateTypes(type("number"))
// OR
@validateTypes("number")
`

##### Multiple primitive types for the same argument

`js
@validateTypes(["number", "string"])
// OR
@validateTypes(type("number", "string"))
// OR
@validateTypes([type("number"), type("string")])
`

##### Single constructor function (class)

`js
@validateTypes(FormData)
`

##### Multiple constructor functions (classes) for the same argument

`js
@validateTypes([FormData, Blob])
// OR
@validateTypes(type(FormData, Blob))
// OR
@validateTypes([type(FormData), type(Blob)])
`

$3

Validates against a literal value (compared using the strict equality operator
===). If multiple arguments are passed, then they will be applied following
the OR logic.

#### Examples

##### Single literal

`js
@validateTypes(literal("foobar"))
`

##### Multiple literals for the same argument

`js
@validateTypes(literal("foobar", 15))
// OR
@validateTypes([literal("foobar"), literal(15)])
`

$3

Validates against a custom rule. The custom rule is represented as a function
that returns a tuple of type [boolean, string] where the boolean is whether
the check has passed and the string is the description of the rule. The value
to validate gets passed as the first argument.

If multiple arguments are passed to the custom rule, then they will be applied
following the OR logic.

#### Examples

##### Validate that a number is greater than 15

`js
@validateTypes(
custom((value) => [
typeof value === "number" && value > 15,
"a number greater than 15",
])
)
`

$3

Validates a non-empty string.

#### Example

`js
@validateTypes(nonEmptyString)
`

$3

Validates a non-negative integer. I.E., it should contain no decimal point and
be greater than or equal to 0.

#### Example

`js
@validateTypes(nonNegativeInteger)
`

$3

Validates an object that is not null and is not an array.

#### Example

`js
@validateTypes(pureObject)
`

$3

Validates an object against a schema. The first argument is a short description
of the object (which will appear in runtime type errors) with the second
argument being the schema itself. The rule will validates every key of the
schema object against a rule (or a set of rules) defined as values.

#### Examples

##### A simple object schema

`js
@validateTypes(
objectSchema("network configuration", {
port: "number",
protocol: literal("http", "https"),
retries: custom((value) => [
typeof value === "number" && value > 0 && value < 16,
"a value between 0 (exclusive) and 15 (inclusive)"
])
})
)
`

##### A nested object schema

`js
@validateTypes(
objectSchema("root object", {
foo: ["boolean", "number"],
bar: objectSchema("child object", {
baz: "number",
}),
})
)
`

$3

Validates an array. The first argument is the description of the expected items
in the plural form (E.G.: "items" or "numbers"). The second argument is the rule
(or an array of rules, if there are multiple) that each element of the array
should conform to.

#### Examples

##### An array of numbers

`js
@validateTypes(array("numbers", "number"))
`

##### An array of numbers and/or strings

`js
@validateTypes(array("numbers and/or strings", ["number", "string"]))
`

##### An array of arrays of numbers

`js
@validateTypes(array("arrays of numbers", array("numbers", "number")))
``