Version: 5.0.0

Objects

rtv : object

RTV.js Public Interface

Provides the externally-facing API. It wraps the implementation, adding a bit of syntactic sugar, and adds the configuration facilities.

rtvref : object

RTV.js Reference

Members herein are indirectly accessed and/or exposed through the RTV.js Public Interface.

rtv : object

RTV.js Public Interface

Provides the externally-facing API. It wraps the implementation, adding a bit of syntactic sugar, and adds the configuration facilities.

Kind: global namespace

rtv.types : Enumeration

Enumeration of types.

For convenience, each type is also available directly from this module, e.g. STRING, FINITE, etc.

The Enumeration can be used to perform additional validations (e.g. types.verify('foo') would throw because “foo” is not a valid type), however whether the type is referenced as STRING or types.STRING makes no difference to typeset validation.

Kind: static property of rtv
Read only: true

rtv.qualifiers : Enumeration

Enumeration of qualifiers.

For convenience, each qualifier is also available directly from this module, e.g. EXPECTED, OPTIONAL, etc.

The Enumeration can be used to perform additional validations (e.g. qualifiers.verify('x') would throw because “x” is not a valid qualifier), however whether the qualifier is referenced as EXPECTED or qualifiers.EXPECTED` makes no difference to typeset validation.

Kind: static property of rtv
Read only: true

rtv.version : string

Library version.

Kind: static property of rtv
Read only: true

rtv.config : object

RTV.js Configuration

Kind: static namespace of rtv

config.enabled : boolean

Globally enables or disables verify and check. When set to false, these methods are no-ops and always return success.

Use this to enable code optimization when building source with a bundler that supports tree shaking, like Rollup or Webpack.

The following plugins can redefine the statement rtv.config.enabled as false prior to code optimizations that remove unreachable code:

Enabled Example: Rollup

By conditionally calling verify based on the state of enabled, a bundler can be configured to completely remove the code from a production build.

Given this module code snippet:

...

if (rtv.config.enabled) {
 rtv.verify(jsonResult, expectedShape);
}

rtv.config.enabled && rtv.verify(jsonResult, expectedShape); // a bit shorter

...

And using this rollup.config.js snippet:

const replacePlugin = require('rollup-plugin-replace');

module.exports = {
  ...
  plugins: [
    // invoke this plugin _before_ any other plugins
    replacePlugin({
      'rtv.config.enabled': JSON.stringify(false)
    }),
    ...
  ]
};

You could also define your own global to achieve the same result:

...
DO_TYPE_CHECKS && rtv.verify(...);

const replacePlugin = require('rollup-plugin-replace');

module.exports = {
  ...
  plugins: [
    // invoke this plugin _before_ any other plugins
    replacePlugin({
      DO_TYPE_CHECKS: JSON.stringify(false)
    }),
    ...
  ]
};

The code in the module snippet above would be completely removed from the build’s output, thereby removing any rtv.js overhead from production.

If you’re using Webpack, be sure to also not explicitly mark the rtvjs module as an external when disabling RTV.js: Doing so will result in the module always being required as an external, even when tree shaking eliminates all the code that comes from it.

Kind: static property of config
See

rtv.isTypeset()

Determines if a value is a typeset.

Kind: static method of rtv
See: isTypeset

rtv.fullyQualify()

Fully-qualifies a given typeset.

Kind: static method of rtv
See: fullyQualify

rtv.RtvSuccess()

Reference to the RtvSuccess class/constructor.

This can be used to determine, for example, if the result of rtv.check() is the success indicator: if (result instanceof rtv.RtvSuccess) ... Note that both RtvSuccess and RtvError have a valid: boolean property which you can also use to easily test for success or failure.

Kind: static method of rtv
See: RtvSuccess

rtv.RtvError()

Reference to the RtvError class/constructor.

This is useful if you need to determine whether an Error is an RtvError using the instanceof operator: if (err instanceof rtv.RtvError) ...

Kind: static method of rtv
See: RtvError

rtv.check(value, typeset, [options]) ⇒ RtvSuccess | RtvError

Checks a value against a typeset for compliance.

Kind: static method of rtv
Returns: RtvSuccess | RtvError - Success indicator if the value is compliant to the shape; RtvError if not. Unlike verify(), an exception is not thrown if the value is non-compliant.

Since both RtvSuccess (returned when the check succeeds) as well as RtvError (returned when the check fails) have a valid: boolean property in common, it’s easy to test for success/failure like this: if (rtv.check(2, rtv.FINITE).valid) {...}.

NOTE: This method always returns a success indicator if RTV.js is currently disabled.
Throws:

  • Error If typeset is not a valid typeset.

See

Param Type Description
value \* Value to check.
typeset typeset Expected shape of (or typeset describing) the value. A shape is a kind of typeset. Normally, this is a shape descriptor.
[options] type\_validator\_context\_options Configuration options.

rtv.verify(value, typeset, [options]) ⇒ RtvSuccess

Requires a value to be compliant to a shape.

NOTE: This method always returns a success indicator if RTV.js is currently disabled.

Kind: static method of rtv
Returns: RtvSuccess - Success indicator IIF the value is compliant to the shape. Otherwise, an RtvError is thrown.
Throws:

  • RtvError If the value is not compliant to the shape.
  • Error If typeset is not a valid typeset.

See

Param Type Description
value \* Value to check.
typeset typeset Expected shape of (or typeset describing) the value. A shape is a kind of typeset. Normally, this is a shape descriptor.
[options] type\_validator\_context\_options Configuration options.

rtvref : object

RTV.js Reference

Members herein are indirectly accessed and/or exposed through the RTV.js Public Interface.

Kind: global namespace

rtvref.Enumeration

Kind: static class of rtvref

new Enumeration(map, [name])

Simple enumeration type. Own-properties on an instance are the keys in the specified map, with their associated values. Key names cannot start with “$”.

const state = new Enumeration({
  READY: 1,
  RUNNING: 2,
  STOPPED: 3,
  COMPLETE: 4
});

state.RUNNING; // 2
state.verify(3); // 3 (returns the value since found in enumeration)
state.verify(5); // ERROR thrown
state.check(3); // 3 (same as verify(3) since found in enumeration)
state.check(5); // undefined (silent failure)
state.$values; // [1, 2, 3, 4] (special non-enumerable own-property)

Throws:

  • Error If map is falsy or empty.
  • Error If map has a key that maps to undefined.
  • Error If map contains a duplicate value.
  • Error If map has a key that is a restricted property (starts with “$”).
Param Type Description
map Object.<String, \*> Object mapping keys to values. Values cannot be undefined.
[name] string Friendly name used to identify this enumeration, especially in validation error messages.

enumeration.$name : string

Friendly name (not necessarily unique among all enumeration instances) used to identify this enumeration, especially in validation error messages. Empty string if not specified during construction.

Note that this own-property is non-enumerable on purpose. Enumerable properties on this instance are the keys in this enumeration.

Kind: instance property of Enumeration
Read only: true

enumeration.$values : Array.<String>

List of enumeration values. Values are references to values in this enumeration.

Note that this own-property is non-enumerable on purpose. Enumerable properties on this instance are the keys in this enumeration.

Kind: instance property of Enumeration
Read only: true

enumeration.check(value) ⇒ \* | undefined

Checks if a value is in this enumeration.

Kind: instance method of Enumeration
Returns: \* | undefined - The specified value if it is in this enumeration, or undefined if not. An exception is not thrown if the value is not in this enumeration.
See: verify

Param Type Description
value \* Value to check. Cannot be undefined.

enumeration.verify(value, [silent]) ⇒ \*

Validates a value as being in this enumeration. Throws an exception if the value is not in this enumeration, unless silent is true.

Kind: instance method of Enumeration
Returns: \* - The specified value if it is in this enumeration, or undefined if silent is true and the value is not in this enumeration.
Throws:

  • Error If not silent and the value is not in this enumeration.

See: check

Param Type Default Description
value \*   Value to check. Cannot be undefined.
[silent] boolean false If truthy, returns undefined instead of throwing an exception if the specified value is not in this enumeration.

enumeration.toString() ⇒ string

A string representation of this Enumeration.

Kind: instance method of Enumeration
Returns: string - String representation.

rtvref.RtvError ⇐ JS\_Error

Kind: static class of rtvref
Extends: JS\_Error

new RtvError(value, typeset, path, mismatch, [rootCause])

Runtime Verification Error Indicator

Describes a failed runtime verification of a value against a given shape or typeset (note that a shape is a type of typeset).

Throws:

  • Error If typeset, path, or mismatch is invalid.
Param Type Description
value \* The value being verified.
typeset typeset The typeset used for verification.
path Array.<string> The path deep into value where the failure occurred. An empty array signifies the root (top-level) value that was checked.
mismatch fully\_qualified\_typeset The fully-qualified typeset that resulted in the failed validation. This is normally the fully-qualified version of typeset, but could be a subtype if typeset is an Array typeset or a shape descriptor.
[rootCause] RtvError | Error Custom Validator error, if the RtvError is a result of a failed custom validation and the validator threw an exception; or some other nested error that was the root cause for the failed validation.

rtvError.valid : boolean

Flag indicating the validation failed. Always false.

Kind: instance property of RtvError
Read only: true
See: valid

rtvError.value : \*

Value that failed verification against the typeset.

Kind: instance property of RtvError
Read only: true

rtvError.typeset : typeset

Reference to the typeset used for verification.

Kind: instance property of RtvError
Read only: true

rtvError.path : Array.<string>

Path from value to the nested property that caused the failure.

Note that paths into collections such as HASH_MAP or ES6 structures such as MAP, where it’s possible to specify arguments to verify keys vs values, will have elements with special prefixes to differentiate whether the path points to a key (“key={key-name}”) or a value (“valueKey={key-name}”).

For example, given the has map {hello: 'world'}, if all keys were supposed to be numerical, then the path for the validation error would be ["key=hello"], indicating that the problem occurred with the key named “hello”, not the associated value.

If, however, keys could be anything, but values had to be numerical, then the path would be ["valueKey=hello"], indicating that the problem occurred with the value associated to the key rather than the key itself.

SECURITY

Some collection types, such as MAP and SET, can have actual objects as keys or elements, and these are used (in JSON-stringified form) as part of the error path. If these objects happen to contain sensitive information, that information may end-up in the path, and the path gets included in this error’s message property, which may get logged by your systems.

Other object types where keys can technically be any string value could also contain sensitive information depending on how these keys are defined. These keys will also end-up in the path that gets included in this error’s message property.

It is YOUR responsibility to exercise necessary caution when validating data structures containing sensitive data.

Kind: instance property of RtvError
Read only: true

rtvError.mismatch : fully\_qualified\_typeset

Fully-qualified typeset that caused the validation error (i.e. the mismatched subtype). This will be a subset/subtype of the typeset, and possibly of a nested typeset within it, expressing only the direct cause of the error.

For example, of typeset is [[rtv.STRING]] (a required array of required strings), and value is ['a', 2], this property would be [rtv.REQUIRED, rtv.STRING] because the validation error would ultimately have been caused by the nested rtv.STRING typeset.

Remember that the fully-qualified typeset would be [rtv.REQUIRED, rtv.ARRAY, {$: [rtv.REQUIRED, rtv.STRING]}], which demonstrates that [rtv.REQUIRED, rtv.STRING] is indeed a subset/subtype.

Kind: instance property of RtvError
Read only: true

rtvError.rootCause : Error | undefined

Validation error thrown by a Custom Validator, which resulted in this RtvError. undefined if this error was not the result of a failed custom validation. If the custom validator throws an error, this will be a reference to the error it threw; otherwise, it’ll be a generic Error generated by the library.

Kind: instance property of RtvError
Read only: true

rtvError.toString() ⇒ string

A string representation of this instance.

Kind: instance method of RtvError
Returns: string - String representation.

rtvref.RtvSuccess

Kind: static class of rtvref

new RtvSuccess(params)

Runtime Verification Success Indicator

Describes a successful runtime verification of a value against a given shape or typeset (note that a shape is a type of typeset).

Param Type Description
params Object  
params.mvv \* Minimum Viable Value representing the smallest version of the original value checked that satisfies the original Typeset against which it was checked. See the mvv property for more information.

rtvSuccess.valid : boolean

Flag indicating the validation succeeded. Always true.

Kind: instance property of RtvSuccess
Read only: true
See: valid

rtvSuccess.mvv : \*

Minimum Viable Value (MVV). If the original value checked is one that can be deeply checked (see list below of supported types), this is essentially a representation (stressing it is not necessarily a clone) of the original value, filtered by removing any parts of it that were not specifically checked (i.e. extra properties in an object that were not included in a shape, however deep it was nested, even in the key of a Map). Otherwise, it’s a reference to the original value.

Validating this value (instead of the original value) against the same Typeset would yield the same successful result.

This property is most useful when checking a plain array or object (e.g. JSON API response) against an expected shape when the shape you care about is much smaller than the payload itself. Once the the check is complete, keep the minimum viable value instead of the larger original payload to reduce the overall memory footprint of your code.

The following types are deeply checked and so will produce an MVV, but note the stated exceptions to types that are not plain objects ({}) or arrays ([]):

  • ARRAY: Note that none of the ARRAY_args except for the typeset ($) are used, which means items won’t be removed if the array is longer than a stated length or max length.
  • PLAIN_OBJECT
  • OBJECT: Interpreted as an object ({}).
  • CLASS_OBJECT: Interpreted as an object ({}).
  • HASH_MAP: Interpreted as an object ({}).
  • ANY_OBJECT: Interpreted as an object ({}) because it’s essentially treated as one when it’s being checked.
  • MAP: Interpreted as the native Map type.
  • SET: Interpreted as the native Set type.

All other types will be referenced, not interpreted.

NOTE: The MVV will based on the Typeset that validates the original value. If you use an Array Typeset with multiple possibilities for an object value to check (e.g. [OBJECT, { $: { foo: NUMBER } }, OBJECT, { $: { bar: STRING } }]), the resulting MVV will use the matching sub-Typeset. Checking { foo: 1, bar: 'a' } would result in { foo: 1 } as the MVV because OBJECT, { $: { foo: NUMBER } } is the first sub-Typeset in the list, and so the first match.

Kind: instance property of RtvSuccess
Read only: true

rtvSuccess.toString() ⇒ string

A string representation of this instance.

Kind: instance method of RtvSuccess
Returns: string - String representation.

rtvref.impl : object

RTV.js Implementation

Provides the internal implementation for the externally-facing RTV API, as well as utilities for type validators.

Kind: static namespace of rtvref

impl.getQualifier(typeset) ⇒ string

Get the qualifier given any kind of typeset.

The typeset’s validity is not checked. The function attempts to get a qualifier, and defaults to the default qualifier if it cannot.

Kind: static method of impl
Returns: string - The applicable qualifier for the specified typeset, which is assumed to be valid.

Param Type Description
typeset typeset The typeset in question.

impl.toTypeset(type, [qualifier], [args], [fullyQualified]) ⇒ typeset

Convert a type, qualifier, and args into a typeset.

While the qualifier, args, and fullyQualified parameters are all optional and may be omitted, their order must be maintained: If needed, the qualifier must always be before args, and args before fullyQualified. Parameters with undefined values will be ignored.

Kind: static method of impl
Returns: typeset - The simplest typeset that represents the combination of the specified type, qualifier, and args, unless fullyQualified was set to true, in which case it’ll always be an array typeset and fully-qualified.
Throws:

  • Error If type, qualifier, or args is invalid.
Param Type Default Description
type string   A single type from types.
[qualifier] string | Object | boolean "rtvref.qualifiers.DEFAULT_QUALIFIER" Optional qualifier from qualifiers. Can also be either the args parameter, or the fullyQualified parameter if the default qualifier is being used.
[args] Object | boolean   Optional type arguments. If specified, this parameter must be an object, however the properties of the object are not validated against the specified type (i.e. they are not guaranteed to be valid for that type). Can also be the fullyQualified parameter if type arguments aren’t applicable.
[fullyQualified] boolean false If truthy, the generated typeset will always be fully-qualified. Otherwise, it’ll be the simplest typeset possible.

impl.fullyQualify(typeset, [qualifier]) ⇒ fully\_qualified\_typeset

Fully-qualifies a typeset, shallow (i.e. the first level only; nested typesets are not fully-qualified).

This function does not modify the input typeset.

Kind: static method of impl
Returns: fully\_qualified\_typeset - A new, fully-qualified typeset representing the input typeset. Only the first/immediate level of the input typeset is fully-qualified. The new array returned contains references to elements within the input typeset.
Throws:

  • Error If typeset or qualifier is not a valid.
Param Type Description
typeset typeset Typeset to fully-qualify.
[qualifier] qualifiers Optional qualifier to be used. If the typeset is a simple type, a shape, or a custom validator that was cherry-picked out of a typeset whose qualifier should be used instead of the default one. If typeset is an Array typeset, specifying this parameter will override the typeset’s qualifier (otherwise, its own qualifier will be used).

impl.extractNextType(typeset, [qualifier]) ⇒ typeset | Array

Extracts (modifies) the next complete type from an Array typeset.

For example, if the given typeset is [EXPECTED, STRING, {string_args}, FINITE], the returned array would be [EXPECTED, STRING, {string_args}] and typeset would then be [FINITE].

Kind: static method of impl
Returns: typeset | Array - The extracted Array typeset as a new Array, which is a sub-type of the given typeset. This sub-typeset is not necessarily fully-qualified. If typeset was an empty array, an empty array is returned (which is the only case where an invalid Array typeset is tolerated, so that this function is easy to use in loops, checking for the stopping condition where the returned sub-typeset is empty).
Throws:

  • Error If typeset is not empty and not a valid Array typeset.
  • Error If qualifier is specified but not valid.
Param Type Description
typeset typeset | Array An Array typeset from which to extract the next complete type. This Array will be modified. Can also be an empty array (which is not a valid typeset, but is tolerated; see the return value for more information).
[qualifier] qualifiers | boolean Optional, and can either be a valid qualifier, true, or false. <h4>Parameter is specified, and is a qualifier</h4> If a qualifier is not found in typeset, this qualifier will be used to qualify the returned sub-type Array typeset. If a qualifier is found in typeset, this parameter is ignored. If a qualifier is not found in typeset and this parameter is specified, then this qualifier will be used to qualify the returned sub-type Array typeset. Examples: - typeset = [EXPECTED, STRING, FINITE]; - extractNextType(typeset, REQUIRED) === [EXPECTED, STRING], typeset === [FINITE] - extractNextType(typeset) === [FINITE], typeset === [] - typeset = [FINITE]; - extractNextType(typeset, EXPECTED) === [EXPECTED, FINITE] <h4>Parameter is specified, and is a boolean</h4> If true, the qualifier, if any, will be included in the returned sub-type Array typeset. If false, the qualifier, if any, will be ignored. Examples: - extractNextType([STRING], true) === [STRING] - extractNextType([REQUIRED, STRING], true) === [EXPECTED, STRING] - extractNextType([REQUIRED, STRING], false) === [STRING]

impl.checkWithType(value, singleType, [context]) ⇒ RtvSuccess | RtvError

Checks a value using a single type.

Kind: static method of impl
Returns: RtvSuccess | RtvError - A success indicator if the value is compliant to the type; an error indicator if not.
Throws:

  • Error If singleType is not a valid simple type or single type.
  • Error If the specified context is not valid.

See: types

Param Type Description
value \* Value to check.
singleType string | Array | Object Either a simple type name (one of types), a shape descriptor, or an Array typeset which represents a single type. In the string/simple case, the default qualifier is assumed. In the shape descriptor case, the default object type is assumed. In the Array case, the qualifier is optional, and a type, along with args, if any, is expected (e.g. [type], [qualifier, type], [type, args], or [qualifier, type, args]). Note that the type may be implied if the shorthand notation is being used for an ARRAY, or if the default object type is being implied for a shape, e.g. [{foo: rtv.STRING}]. NOTE: A custom validator is not considered a valid single type. It’s also considered a separate type if it were passed-in via an Array, e.g. [STRING, validator], which would violate the fact that singleType should be one type, and therefore cause an exception to be thrown.
[context] type\_validator\_context | undefined Additional context for the check. If falsy, a new context will be created for all downstream checks using value as the original value, and undefined as the parent.

impl.checkWithShape(value, shape, [context]) ⇒ RtvSuccess | RtvError

Checks a value using a shape descriptor and ensure the value’s type is the default object type.

Kind: static method of impl
Returns: RtvSuccess | RtvError - A success indicator if the value is compliant to the shape; an error indicator if not.
Throws:

  • Error If shape is not an OBJECT.
  • Error If the specified context is not valid.
Param Type Description
value Object Value to check. Must be of the default object type.
shape Object Expected shape of the value. Must be an OBJECT.
[context] type\_validator\_context | undefined Additional context for the check. If falsy, a new context will be created for all downstream checks using value as the original value, and an empty/root path.

impl.checkWithArray(value, arrayTs, [context]) ⇒ RtvSuccess | RtvError

Checks a value using an Array typeset.

Kind: static method of impl
Returns: RtvSuccess | RtvError - Success indicator if the value is compliant to the typeset; error indicator otherwise. An exception is not thrown if the value is non-compliant.
Throws:

  • Error If typeset is not a valid Array typeset.
  • Error If the specified context is not valid.
Param Type Description
value \* Value to check.
arrayTs Array The Array typeset to check against.
[context] type\_validator\_context | undefined Additional context for the check. If falsy, a new context will be created for all downstream checks using value as the original value, and an empty/root path.

impl.check(value, typeset, [context]) ⇒ RtvSuccess | RtvError

Checks a value against a typeset.

Kind: static method of impl
Returns: RtvSuccess | RtvError - Success indicator if the value is compliant to the typeset; error indicator otherwise. An exception is not thrown if the value is non-compliant.
Throws:

  • Error If typeset is not a valid typeset.
  • Error If the specified context is not valid.
Param Type Description
value \* Value to check.
typeset typeset Expected shape/type of the value.
[context] type\_validator\_context | undefined Additional context for the check. If falsy, a new context will be created for all downstream checks using value as the original value, and an empty/root path.

rtvref.qualifiers : object

Qualifiers

Qualifiers determine the degree at which a value must be of a given type.

Kind: static namespace of rtvref

qualifiers.REQUIRED

Required qualifier: The value must be of the expected type. Depending on the type, additional requirements may be enforced.

Unless otherwise stated in type-specific rules, this qualifier does not permit the value to be null or undefined.

Note the fact the value cannot be undefined implicitly requires a shape’s property to be defined somewhere its prototype chain (if it weren’t, then its value would be undefined, violating the requirements). For example, the shape {name: [EXPECTED, STRING]} would require the name property to exist and not be undefined, but would permit it to be null or even an empty string.

See specific type for additional rules.

Kind: static property of qualifiers
See

qualifiers.EXPECTED

Expected qualifier: The value should be of the expected type. Depending on the type, additional requirements may be enforced.

Unless otherwise stated in type-specific rules, this qualifier does not permit the value to be undefined, but does permit it to be null.

Note the fact the value cannot be undefined implicitly requires a shape’s property to be defined somewhere its prototype chain (if it weren’t, then its value would be undefined, violating the requirements). For example, the shape {name: [EXPECTED, STRING]} would require the name property to exist and not be undefined, but would permit it to be null or even an empty string.

See specific type for additional rules.

Kind: static property of qualifiers
See

qualifiers.OPTIONAL

Optional qualifier: The value may be of the expected type. Depending on the type, additional requirements may be enforced.

Unless otherwise stated in type-specific rules, this qualifier permits a the value to be null as well as undefined.

Note the fact the value can be undefined implies it does not require a shape’s property to be defined anywhere in its prototype chain.

See specific type for additional rules.

Kind: static property of qualifiers
See: types

qualifiers.TRUTHY

Truthy qualifier: If the value is truthy, it must be of the expected type. Depending on the type, additional requirements may be enforced.

Think of this qualifier as, “if truthy, the value is required to be of the specified type.”

Unless otherwise stated in type-specific rules, this qualifier does permit the value to be any falsy value.

Note the fact the value can be undefined implies it does not require a shape’s property to be defined anywhere in its prototype chain.

See specific type for additional rules.

Kind: static property of qualifiers
See: types

qualifiers.qualifiers : Enumeration

Enumeration (string -> string) of all qualifiers:

Kind: static property of qualifiers

qualifiers.DEFAULT_QUALIFIER : string

Default qualifier: REQUIRED

Kind: static constant of qualifiers

qualifiers.valuePermitted(v, [q]) ⇒ boolean

Convenience function to check if a value is permitted under basic qualifier rules:

  • REQUIRED: Cannot be any falsy value, including undefined and null.
  • EXPECTED: Can be null.
  • OPTIONAL: Can be either undefined or null.
  • TRUTHY: Can be any falsy value.

Kind: static method of qualifiers
Returns: boolean - true if the value is falsy and the specific value is permitted by the basic qualifier’s rules; false otherwise.

For example,

  • valuePermitted(null, REQUIRED) === false
  • valuePermitted(null, EXPECTED) === true
  • valuePermitted(1, *) === false because the value 1 is not any of the permitted falsy values for any qualifier
  • valuePermitted(false, OPTIONAL) === false because the value false is not permitted by OPTIONAL
Param Type Description
v \* Value to check.
[q] string Validation qualifier. Defaults to REQUIRED.

qualifiers.restricted_values : void

Restricted Values

Qualifiers impose restrictions on certain JavaScript values. Currently, the list of restricted values is the same as the list of JavaScript’s falsy values. This may change in the future if more qualifiers are added.

See the documentation for each qualifier to know which of these values they permit or restrict.

Kind: static typedef of qualifiers
See: valuePermitted

rtvref.types : object

Types

Kind: static namespace of rtvref

types.objTypes : Enumeration

Enumeration (string -> string) of object types:

Kind: static property of types

types.argTypes : Enumeration

Enumeration (string -> string) of types that accept arguments:

Kind: static property of types

types.types : Enumeration

Enumeration (string -> string) of all types:

Kind: static property of types

types.ANY : string

The any type is special in that it allows anything, which includes null and undefined values. Because of this, it’s the most liberal in terms of types as well as in its interaction with qualifiers. A more specific type should be used whenever possible to ensure a higher degree of confidence in the value being validated.

Any rules per qualifiers:

  • REQUIRED: Can be any value, including null and undefined.
  • EXPECTED: Same rules as REQUIRED.
  • OPTIONAL: Same rules as EXPECTED.
  • TRUTHY: Same rules as OPTIONAL.

Since this type removes the property’s need for existence in the prototype chain, it renders the verification moot (i.e. the property of this type might as well not be included in a shape descriptor unless a custom validator is being used to do customized verification.

Kind: static constant of types
See: qualifiers

types.NULL : string

Null rules per qualifiers: Must be the null primitive.

Use this special type to explicitly test for a null value. For example, a shape’s property may be required to be null under certain circumstances.

Kind: static constant of types
See: qualifiers

types.STRING : string

String rules per qualifiers:

  • REQUIRED: Must be a non-empty string, unless an argument allows it.
  • EXPECTED | OPTIONAL: May be an empty string, unless an argument disallows it. Note that the value null (for EXPECTED and OPTIONAL) or undefined (for OPTIONAL) will not be subject to any restrictions imposed by arguments (i.e. the arguments will be ignored; for example, rtv.verify(null, [EXPECTED, STRING, {min: 1}]) would pass verification because null is permitted with EXPECTED).
  • TRUTHY: May be an empty string regardless of arguments, since an empty string is falsy, and this qualifier permits all falsy values. Therefore, rtv.verify("", [TRUTHY, STRING, {min: 1}]) would still pass verification because an empty string is permitted with TRUTHY.

In all cases, the value must be a string primitive. Note that new String('hello') !== 'hello' because the former is an object, not a string.

Arguments (optional): STRING_args

Kind: static constant of types
See: qualifiers

types.BOOLEAN : string

Boolean rules per qualifiers: Must be a boolean primitive. Note that new Boolean(true) !== true because the former is an object, not a boolean.

Kind: static constant of types
See: qualifiers

types.SYMBOL : string

Symbol rules per qualifiers: Must be a symbol primitive.

Arguments (optional): SYMBOL_args.

Kind: static constant of types
See: qualifiers

types.NUMBER : string

Number rules per qualifiers:

  • REQUIRED: Cannot be NaN, but could be +Infinity, -Infinity.
  • EXPECTED OPTIONAL: Could be NaN, +Infinity, -Infinity.
  • TRUTHY: Could be NaN (since that is a falsy value), +Infinity, -Infinity.

In all cases, the value must be a number primitive. Note that new Number(1) !== 1 because the former is an object, not a number.

An number is not guaranteed to be a safe integer.

Arguments (optional): numeric_args

Kind: static constant of types
See

types.FINITE : string

Finite rules per qualifiers: Cannot be NaN (unless the qualifier is TRUTHY), +Infinity, -Infinity. The value can be either an integer, or a floating point number. It must also be a number primitive.

A finite number is not guaranteed to be a safe integer.

Arguments (optional): numeric_args

Kind: static constant of types
See

types.INT : string

Int rules per qualifiers: Must be a finite number, an integer, and a number primitive. NaN, however, is permitted if the qualifier is TRUTHY.

An integer is not guaranteed to be a safe integer.

Arguments (optional): numeric_args

Kind: static constant of types
See

types.SAFE_INT : string

Int rules per qualifiers: Must be a finite number, a safe integer, and a number primitive. NaN, however, is permitted if the qualifier is TRUTHY.

An integer is safe if it’s an IEEE-754 double precision number which isn’t the result of a rounded unsafe integer. For example, 2^53 - 1 is safe, but 2^53 is not because 2^53 + 1 would be rounded to 2^53.

Arguments (optional): numeric_args

Kind: static constant of types
See

types.FLOAT : string

Float rules per qualifiers: Must be a finite floating point number, and a number primitive. Per IEEE 754, zero (0) is considered a float. Note that NaN is permitted if the qualifier is TRUTHY.

Arguments (optional): numeric_args

Kind: static constant of types
See

types.FUNCTION : string

Function rules per qualifiers: Must be a function.

Kind: static constant of types
See: qualifiers

types.REGEXP : string

RegExp rules per qualifiers: Must be a RegExp instance.

Kind: static constant of types
See

  • qualifiers
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp

types.DATE : string

Date rules per qualifiers: Must be a Date instance.

Kind: static constant of types
See

  • qualifiers
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date

types.ERROR : string

Error rules per qualifiers: Must be an Error instance, which includes TypeError, RangeError, ReferenceError, etc.

Kind: static constant of types
See

  • qualifiers
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error

types.PROMISE : string

Promise rules per qualifiers: Must be a Promise instance.

Kind: static constant of types
See

  • qualifiers
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

types.ARRAY : string

Array rules per qualifiers: Must be an Array. Empty arrays are permitted, unless arguments prevent them.

Arguments (optional): ARRAY_args. Note that the ARRAY type must be specified when using arguments (i.e. the shorthand notation cannot be used).

When describing arrays, either shorthand or full notation may be used. In the shorthand notation, the ARRAY type isn’t necessary, but it’s only possible to specify the Array typeset to use to validate each array element, and arguments can’t be specified. In the fully-qualified notation, the ARRAY type is required, but the Array typeset must be moved into the typeset argument (along with any other argument necessary).

NOTE: It’s important to realize that arrays (as in the JavaScript Array type) are essentially nested Array typesets. They represent a set of types that will be used to validate each element of an array using a short-circuit OR conjunction, looking for the first type that matches.

Array Example: Simple array

The value property must be an array (possibly empty) of any type of value.

{
  value: [ARRAY]
}

NOTE: Since arrays are, in reality, nested Array typesets, and since an empty array is an invalid Array typeset, it’s not possible to use the shorthand notation to indicate what could be the equivalent: [[]]. The inner Array typeset would be deemed invalid.

Array Example: Shorthand notation

The value property must be an array (possibly empty) of finite numbers of any value.

{
  value: [[FINITE]]
}

Array Example: Shorthand, mixed types

The value property must be either a boolean; or an array (possibly empty) of finite numbers of any value, or non-empty strings, or a mix of both.

{
  value: [BOOLEAN, [FINITE, STRING]]
}

Array Example: Fully-qualified notation, no typeset

The value property must be a non-empty array of any type of value.

{
  value: [REQUIRED, ARRAY, {min: 1}]
}

Array Example: Fully-qualified notation

The value property must be an array (possibly empty) of finite numbers of any value (nested typeset is not fully-qualified).

{
  value: [REQUIRED, ARRAY, {$: [FINITE]}]
}

Array Example: Fully-qualified, mixed types

The value property must be either a boolean; or an array (possibly empty) of finite numbers of any value, or non-empty strings, or a mix of both (nested typeset is not fully-qualified).

{
  value: [REQUIRED, BOOLEAN, ARRAY, {$: [FINITE, STRING]}]
}

Kind: static constant of types
See: qualifiers

types.ANY_OBJECT : string

An any object is anything that is not a primitive, which means it includes the Array type, as well as functions and arguments, and other JavaScript object types. To test for an array, use the ARRAY type. To test for a function, use the FUNCTION type.

The following values are considered any objects:

  • {}
  • new Object()
  • new (function() {}) | new (class {})() (class instance) (also see CLASS_OBJECT)
  • new String('')
  • new Boolean(true)
  • new Number(1)
  • [] (also see ARRAY)
  • new Array() (also see ARRAY)
  • /re/ (also see REGEXP)
  • new RegExp('re') (also see REGEXP)
  • new Date() (also see DATE)
  • new Error() (also see ERROR)
  • new Promise() (also see PROMISE)
  • function(){} (also see FUNCTION)
  • arguments (function arguments)
  • new Map() (also see MAP)
  • new WeakMap() (also see WEAK_MAP)
  • new Set() (also see SET)
  • new WeakSet() (also see WEAK_SET)

Primitive values are not considered any objects, especially when the qualifier is REQUIRED. Note that typeof null === 'object' in JavaScript; the ANY_OBJECT type allows testing for this undesirable fact.

Any object rules per qualifiers:

  • REQUIRED: Per the lists above.
  • EXPECTED: null is allowed.
  • OPTIONAL: undefined is allowed.

Arguments (optional): shape_object_args

Kind: static constant of types
See

types.OBJECT : string

An object is one that extends from JavaScript.Object (i.e. an instance of something that extends from Object) and is not a function, array, regular expression, DATE, function arguments object, map, weak map, set, weak set, nor a primitive.

This is the default (imputed) type for shape descriptors, which means the object itself (the value being tested), prior to being checked against its shape, will be tested according to this type.

The following values are considered objects:

  • {}
  • new Object()
  • new (function() {}) | new (class {})() (class instance) (also see CLASS_OBJECT)

The following values are not considered objects:

  • new String('')
  • new Boolean(true)
  • new Number(1)
  • [] (also see ARRAY)
  • new Array() (also see ARRAY)
  • /re/ (also see REGEXP)
  • new RegExp('re') (also see REGEXP)
  • new Date() (also see DATE)
  • new Error() (also see ERROR)
  • new Promise() (also see PROMISE)
  • function(){} (also see FUNCTION)
  • arguments (function arguments)
  • new Map() (also see MAP)
  • new WeakMap() (also see WEAK_MAP)
  • new Set() (also see SET)
  • new WeakSet() (also see WEAK_SET)
  • all primitives

Object rules per qualifiers:

  • REQUIRED: Per the lists above.
  • EXPECTED: null is allowed.
  • OPTIONAL: undefined is allowed.

Arguments (optional): shape_object_args

Kind: static constant of types
See

types.PLAIN_OBJECT : string

A plain object is one that is created directly from the Object constructor, whether using new Object() or the literal {}.

The following values are considered plain objects:

  • {}
  • new Object()

The following values are not considered plain objects:

  • new (function() {}) | new (class {})() (class instance) (also see CLASS_OBJECT)
  • new String('')
  • new Boolean(true)
  • new Number(1)
  • [] (also see ARRAY)
  • new Array() (also see ARRAY)
  • /re/ (also see REGEXP)
  • new RegExp('re') (also see REGEXP)
  • new Date() (also see DATE)
  • new Error() (also see ERROR)
  • new Promise() (also see PROMISE)
  • function(){} (also see FUNCTION)
  • arguments (function arguments)
  • new Map() (also see MAP)
  • new WeakMap() (also see WEAK_MAP)
  • new Set() (also see SET)
  • new WeakSet() (also see WEAK_SET)
  • all primitives

Plain object rules per qualifiers:

  • REQUIRED: Per the lists above.
  • EXPECTED: null is allowed.
  • OPTIONAL: undefined is allowed.

Arguments (optional): shape_object_args

Kind: static constant of types
See

types.CLASS_OBJECT : string

A class object is one that is created by invoking the new operator on a function (other than a primitive type function), generating a new object, commonly referred to as a class instance. This object’s prototype (__proto__) is a reference to that function’s prototype and has a constructor property that is === to the function.

The following values are considered class objects:

  • new (function() {}) | new (class {})() (tip: use the ctor argument to test for a specific class)

The following values are not considered class objects:

  • {}
  • new Object()
  • new String('')
  • new Boolean(true)
  • new Number(1)
  • [] (also see ARRAY)
  • new Array() (also see ARRAY)
  • /re/ (also see REGEXP)
  • new RegExp('re') (also see REGEXP)
  • new Date() (also see DATE)
  • new Error() (also see ERROR)
  • new Promise() (also see PROMISE)
  • function(){} (also see FUNCTION)
  • arguments (function arguments)
  • new Map() (also see MAP)
  • new WeakMap() (also see WEAK_MAP)
  • new Set() (also see SET)
  • new WeakSet() (also see WEAK_SET)
  • all primitives

Class object rules per qualifiers:

  • REQUIRED: Per the lists above.
  • EXPECTED: null is allowed.
  • OPTIONAL: undefined is allowed.

Arguments (optional): shape_object_args

Kind: static constant of types
See

types.HASH_MAP : string

A simple OBJECT that is treated as a hash map with an expected set of keys (forcibly strings due to the nature of the native JavaScript Object type) and values. Keys are own-properties only, and can be described using a regular expression. Values can be described using a typeset. Empty maps are permitted.

Map object rules per qualifiers: Same as OBJECT rules.

Arguments (optional): collection_args

Kind: static constant of types
See

types.MAP : string

An ES6 map supports any value as its keys, unlike a HASH_MAP that only supports strings. Keys can be described using a regular expression (if they are strings), and values can be described using a typeset. Empty maps are permitted by default.

Map rules per qualifiers: Must be a Map instance.

Arguments (optional): collection_args

Kind: static constant of types
See

types.WEAK_MAP : string

An ES6 weak map supports any object as its keys, unlike a HASH_MAP that only supports strings, and a MAP that supports any type of value.

Weak map rules per qualifiers: Must be a WeakMap instance.

Kind: static constant of types
See

types.SET : string

An ES6 set is a collection of unique values without associated keys. Values can be described using a typeset. Empty sets are permitted by default.

Set rules per qualifiers: Must be a Set instance.

Arguments (optional): collection_args

Kind: static constant of types
See

types.WEAK_SET : string

An ES6 weak set is a collection of weakly held unique objects without associated keys.

Weak set rules per qualifiers: Must be a WeakSet instance.

Kind: static constant of types
See

types.JSON : string

JSON rules per qualifiers: Must be a JSON value:

Since this type checks for any valid JSON value, empty string and null values are permitted, even when the typeset is qualified as REQUIRED. Therefore, the REQUIRED qualifier has the same effect as the EXPECTED qualifier.

Also note that if the qualifier is OPTIONAL or TRUTHY, then undefined will be a permitted value, even though it is not a JSON value.

Kind: static constant of types
See: qualifiers

types.DEFAULT_OBJECT_TYPE : string

Default object type: OBJECT. This type is associated with an un-qualified shape descriptor.

Kind: static constant of types

types.primitives : void

Primitives

In RTV.js (as in ECMAScript 2015), a primitive is considered one of the following types:

  • undefined
  • null
  • string (note that new String('s') does not produce a primitive, it produces an object, and should be avoided).
  • boolean (note that new Boolean(true) does not produce a primitive, it produces an object, and should be avoided).
  • number (note that new Number(1) does not produce a primitive, it produces an object, and should be avoided).
  • Symbol

Kind: static typedef of types
See: isPrimitive

types.falsy_values : void

Falsy Values

In JavaScript, a falsy value means any one of these values which, when tested in a logical operation like &&, ||, or an IF statement, evaluates to false:

  • undefined
  • null
  • false
  • 0
  • ""
  • NaN

Kind: static typedef of types
See: isFalsy

types.qualifier_rules : void

Rules Per Qualifiers

Qualifiers state basic rules. Unless otherwise stated, every type herein abides by those basic rules. Each type will also impose additional rules specific to the type of value it represents.

For example, while the FINITE type states that the value must not be NaN, +Infinity, nor -Infinity; it could be null if the qualifier used is EXPECTED; and it could be undefined if the qualifier used is OPTIONAL.

Kind: static typedef of types

types.shape_descriptor : Object

Shape Descriptor

Describes the shape (i.e. interface) of an object as a map of properties to typesets. Each typeset indicates whether the property is required, expected, or optional, using qualifiers, along with possible types. Only own-enumerable properties of the shape are considered part of the shape.

When a value is checked or verified against a given shape, properties on the value that are not part of the shape are ignored (this is to stay true to the concept of an interface whereby an object may have other functionality, but remains compatible or usable as long as it meets the specified contract as a subset of its properties and methods). If successfully checked/verified, the value is guaranteed to provide the properties described in the shape, and each property is guaranteed to be assigned to a value of at least one type described in each property’s typeset.

The shape descriptor itself must be an OBJECT. An empty shape descriptor is valid, but will result in nothing being verified on the value, other than whether its type is the default object type.

NOTE: A shape is simply a specific type of typeset since a typeset can come in the form of multiple value types, including an object which represents a shape.

Kind: static typedef of types
See

types.type_arguments : Object

Type Arguments

Some types will accept, or may even expect, one or more arguments. Each type will specify whether it has arguments, and if they’re optional or required. Arguments are specified as a single object immediately following a type in an Array typeset (i.e. an Array must be used as the typeset in order to provide arguments for a type).

An arguments object immediately follows its type in a typeset, such as [PLAIN_OBJECT, {$: {hello: STRING}}]. This would specify the value must be a plain object with a shape that includes a property named ‘hello’, that property being a required string. Another example would be [STRING, {min: 5}], which would require a string of at least 5 characters in length.

Since qualifiers may affect how a value is validated against a type, qualifier rules will take precedence over any argument specified, unless otherwise stated in the type’s qualifier rules or arguments spec.

Kind: static typedef of types
See: isTypeArgs

types.STRING_args : Object

String Arguments

Kind: static typedef of types
See: STRING
Properties

Name Type Description
[oneOf] string | Array.<string> An exact string to match (===). Can also be a list of strings, one of which must be an exact match. An empty string is allowed, and will override the normal rules of the REQUIRED qualifier which would otherwise require a non-empty string as the value. The list may contain an empty string. An empty list will be ignored. This argument is ignored if exp is specified.
[partial] string A partial value to match (must be somewhere within the string). Ignored if not a string, an empty string, or oneOf or exp is specified. min and max take precedence over this argument (min/max will be validated first, then a partial match will be attempted).
[min] number Minimum inclusive length. Defaults to 1 for a REQUIRED string, and 0 for an EXPECTED or OPTIONAL string. Ignored if oneOf or exp is specified, or min is not a FINITE number >= 0.
[max] number Maximum inclusive length. Negative means no maximum. Ignored if oneOf or exp is specified, max is not a FINITE number, or max is less than min. Defaults to -1 (unlimited length). Can be set to zero to require a zero-length string.
[exp] string A string-based regular expression describing the string. For example, to require a string of numbers with a minimum length of 1, the following expression could be used: "^\\d+$".
[expFlags] string A string specifying any flags to use with the regular expression specified in exp. Ignored if falsy or if exp is not specified. See the RegExp#flags parameter for more information.

types.SYMBOL_args : Object

Symbol Arguments

Kind: static typedef of types
See: SYMBOL
Properties

Name Type Description
[oneOf] symbol | Array.<symbol> An exact symbol to match (===). Can also be a list of symbols, one of which must be an exact match. Values to match are ignored if they are not symbols. An empty list will be ignored.

types.numeric_args : Object

Numeric Value Arguments

Applicable to all numeric types:

Kind: static typedef of types
See

Properties

Name Type Description
[oneOf] number | Array.<number> An exact number to match (===). Can also be a list of numbers, one of which must be an exact match. An empty list will be ignored. Values to match are ignored if they are not within normal range of the type (e.g. for NUMBER, could be +Infinity, or even NaN if the qualifier is not REQUIRED; but these values would be ignored by FINITE since they aren’t part of the FINITE range), or not numbers at all. Note that 0 and NaN are permitted when the qualifier is TRUTHY even if they aren’t part of the list or aren’t the single match.
[min] number Minimum inclusive value. Ignored if oneOf is specified, min is NaN, or min is not within normal range of the type. Note that 0 is permitted when the qualifier is TRUTHY even if the minimum does not permit it.
[max] number Maximum inclusive value. Ignored if oneOf is specified, max is NaN, max is not within normal range of the type, or max is less than min. Note that 0 is permitted when the qualifier is TRUTHY even if the minimum does not permit it.

types.shape_object_args : Object

Shape Object Arguments

Applicable to all object types that may have a shape:

Kind: static typedef of types
See

Properties

Name Type Description
[$] Object The shape descriptor describing the expected interface of the value being verified. If not specified, none of the value’s properties will be verified, and the exact flag (as well as the exactShapes verification option) will be ignored. NOTE: Any properties in the shape itself that are undefined will be ignored. This facilitates merging shapes with destructuring when combining shapes into larger ones. Applies to all shape object types.
[ctor] function A reference to a constructor function. If specified, the class object (instance) must have this class function in its inheritance chain such that <class_object> instanceof ctor === true. Note that this property is not serializable to JSON. Ignored if not a function. Applies to: CLASS_OBJECT.
[exact] boolean If true, this will restrict the immediate object being verified to having the exact set of own-properties as those specified on the shape. By default, additional own-properties on the object are ignored. In other words, the object must always have all of the shape’s properties, but (by default) it may also have additional properties that are not in the shape. Setting exact: true would cause the verification to fail if the object has more properties than those specified in the shape. If specified, whether true or false, this flag overrides the exactShapes option for the verification for this shape only. Nested shapes will not be affected. The exactShapes flag that may be set in the verification’s context options via a call to check or verify. NOTE: If this flag is true and the shape is empty, it will restrict the object being verified to an empty object (i.e. no own-properties). NOTE: If this flag is true and the shape is not specified, the flag will be ignored, not verifying the value being checked has any specific own-properties. Applies to all shape object types.

types.ARRAY_args : Object

Array Arguments

Kind: static typedef of types
See: ARRAY
Properties

Name Type Description
[$] typeset The typeset which every value in the array must match. Defaults to ANY which means any value will match.
[length] number Exact length. Ignored if not a FINITE number >= 0.
[min] number Minimum inclusive length. Ignored if length is specified, or min is not a FINITE number >= 0. Defaults to 0.
[max] number Maximum inclusive length. Negative means no maximum. Ignored if length is specified, max is not a FINITE number, or max is less than min. Defaults to -1 (unlimited).

types.collection_args : Object

Collection Arguments

Describes the keys and values in a collection-based object, which is one of the following types:

  • HASH_MAP (NOTE: only own-enumerable properties are considered part of this collection type)
  • MAP
  • SET (with some exceptions)

For example, the following arguments both verify a collection of 3-letter string keys (upper- or lowercase) to finite numbers:

  • {keyExp: '[a-z]{3}', keyFlags: 'i', $values: FINITE}
  • {keyExp: '[a-zA-Z]{3}', $values: FINITE}

Note that ARRAY is not included in this list because the array type has special syntax for describing the type of its items. See ARRAY_args instead.

The WEAK_MAP and WEAK_SET types do not apply because, due to their nature, their elements cannot be iterated.

Kind: static typedef of types
See

Properties

Name Type Description
[length] number The exact number of elements required in the collection. A negative value allows for any number of entries. Zero requires an empty collection. Ignored if not a FINITE number. Applies to: All collection types.
[$keys] typeset A typeset describing each key in the collection. If the type is HASH_MAP, this argument is ignored due to the nature of its JavaScript Object-based implementation which requires that all keys be non-empty strings. Applies to: MAP.
[keyExp] string A string-based regular expression describing the names of keys found in the collection. By default, there are no restrictions on key names. Ignored if the key type is not STRING, as specified in $keys (when $keys is applicable to the collection type). For example, to require numerical keys, the following expression could be used: "^\\d+$". Applies to: HASH_MAP, MAP.
[keyFlags] string A string specifying any flags to use with the regular expression specified in keyExp. Ignored if falsy, or if keyExp is not specified or irrelevant. See the RegExp#flags parameter for more information. Applies to: HASH_MAP, MAP.
[$values] typeset A typeset describing each value in the collection. If specified, all values must match this typeset (but the collection is not required to have any elements to be considered valid, unless length is specified). If not specified, no validation is performed on values. For example, to require arrays of non-empty string values as values in the collection, the following typeset could be used: [[types.STRING]]. Applies to: All collection types.
[deep] boolean If true, the property value being tested does not match the $values typeset, and the property value is a hash map, then verification will recurse into the property value and will attempt to verify its properties against the typeset in $values. If false (default), the property value must match the $values typeset. Applies to: HASH_MAP.

types.typeset : Object | string | Array | function

Typeset

Describes the possible types for a given value. It can be any one of the following JavaScript types:

  • Object: For the root or a nested shape descriptor of implied OBJECT type (unless paired with a specific object type like PLAIN_OBJECT, for example, when using the Array notation, e.g. [PLAIN_OBJECT, {...}]). If the object is empty (has no properties), nothing will be verified (anything will pass).
  • String: For a single type, such as FINITE for a finite number. Must be one of the types defined in types.
  • Function: For a custom validator that will verify the value of the property using custom code. Since the Array form is not being used (only the validator is being provided), it’s always invoked immediately. Since a type is not provided, the ANY type is implied.
  • Array: For multiple type possibilities, optionally qualified, using a short-circuit OR conjunction, which means the value of the property being described must match at least one of the types listed, but not all. Matching is done in a short-circuit fashion, from the first to the last element in the typeset. If a simpler type is a more likely match, it’s more performant to specify it first/earlier in the typeset to avoid a match attempt on a nested shape or Array.
    • Cannot be an empty Array.
    • A given type may be included more than once in the typeset. This allows for greater composition. The first-matched will win. [STRING, {oneOf: 'foo'}, STRING] would validate both 'foo' and 'bar' because the second occurrence of STRING is not restricted to any specific value.
    • An Array is necessary to qualify the typeset as not required (see Typeset Qualifiers below).
    • An Array is necessary if a type needs or requires arguments.
    • If the first element is an Object (or second, if a qualifier is provided, and this, in a typeset that is not fully-qualified), it’s treated as a nested shape descriptor describing an object of the default object type. To include a shape descriptor at any other position within the array, it must be preceded by a type, even if the default object type is being used (i.e. OBJECT must be specified as the type). For example, all these typesets are equivalent (and equivalent to just {name: STRING} as the typeset): [{name: STRING}], [REQUIRED, {name: STRING}], and [REQUIRED, OBJECT, {$: {name: STRING}}], describing an object that has a name property which is a non-empty string. Changing it to [STRING, {$: {name: STRING}}], however, does not mean, “a non-empty string, or an object with a name property which is a non-empty string”. In this case, the object arguments {$: {name: STRING}} would be treated as STRING arguments, which is likely not the intent. The arguments would have to be preceded by an object type (e.g. OBJECT, PLAIN_OBJECT, etc.) to have them interpreted as in the former “OR” case.
    • If an element is an Array (any position), it’s treated as a nested list with an implied ARRAY type, e.g. [BOOLEAN, [STRING, FINITE]] would describe a property that should be a boolean, or an array of non-empty strings or finite numbers. See the ARRAY type reference for more information on shorthand and full notations.
    • If an element is a Function, it must be the last element in the Array and will be treated as a custom validator. Only one validator can be specified for a given typeset (additional validators may appear in nested typesets).

Typeset Qualifiers

All typesets use an implied REQUIRED qualifier unless otherwise specified. To qualify a typeset, a qualifier may be specified as the first element in the Array form (if specified, it must be the first element). For example, {note: [EXPECTED, STRING]} would describe an object with a ‘note’ property that is an expected, but not required, string, which could therefore be either empty or even null. The Array form must be used in order to qualify a typeset as other than required, and the qualifier applies to all immediate types in the typeset (which means each nested typeset can have its own qualifier).

JSON Serialization

ALL typesets should be fully JSON-serializable (via JSON.stringify() and JSON.parse()) with the following unavoidable exceptions:

Those exceptions are due to the fact that these represent functions, and functions are not serializable to JSON. They will be ignored in the stringification process, unless a custom replacer is provided which, somehow (up to you), handles them.

This could, among other possibilities, enable the transmission of typesets over network requests, perhaps embedded in JSON payloads, similar to JSON-LD schemas.

Typeset Example: Object

const contactShape = {
  name: rtv.STRING, // required, non-empty, string
  tags: [rtv.ARRAY, [rtv.STRING]], // required array of non-empty strings
  // tags: [[rtv.STRING]], // same as above, but using shortcut array format
  details: { // required nested object of type `OBJECT` (default)
    birthday: [rtv.EXPECTED, rtv.DATE] // Date (could be null)
  },
  notes: [rtv.OPTIONAL, rtv.STRING, function(value) { // optional string...
    if (value && !value.test(/^[A-Z].+\.$/)) {
      throw new Error('Note must start with a capital letter, end with a ' +
          period, and have something in between, if specified.');
    }
  }]
};

const contact = {
  name: 'John Doe',
  tags: ['colleagues', 'sports'],
  details: {
    birthday: null // not specified
  }
};

rtv.verify(contact, contactShape); // OK

const walletShape = {
  contacts: [[contactShape]], // list of contacts using nested shape
  address: {
    street: rtv.STRING
    // ...
  },
  money: rtv.FINITE
};

rtv.verify({
  contacts: [contact],
  address: {street: '123 Main St'},
  money: 100
}, walletShape); // OK

Typeset Example: String

rtv.verify('foo', rtv.STRING); // OK
rtv.verify('foo', rtv.FINITE); // ERROR

Typeset Example: Array

const typeset = [rtv.STRING, rtv.FINITE]; // non-empty string, or finite number
rtv.verify('foo', typeset); // OK
rtv.verify(1, typeset); // OK

Typeset Example: Function

const validator = (v) => {
  if (v % 10) {
    throw new Error('Number must be a factor of 10.');
  }
};

rtv.verify(100, validator); // OK
rtv.verify(120, [rtv.INT, validator]); // OK

Typeset Example: Alternate Qualifier

const person = {
  name: rtv.STRING, // required, non-empty
  age: [rtv.OPTIONAL, rtv.FINITE, (v) => { // 18 or older, if specified
    if (v < 18) {
      throw new Error('Must be 18 or older.');
    }
  }]
};
rtv.verify({name: 'Bob'}, person); // OK
rtv.verify({name: ''}, person); // ERROR
rtv.verify({name: 'Steve', age: 17}, person); // ERROR
rtv.verify({name: 'Steve', age: null}, person); // OK

Kind: static typedef of types

types.fully_qualified_typeset : Array

Fully-Qualified Typeset

A typeset expressed without any shortcut notations or implied/default types to make it easier to parse, especially as the match parameter given to a custom validator. A fully-qualified typeset always uses the array notation, and has a single qualifier as its first element, followed by at least one type, and at most one validator.

For example:

  • STRING -> [REQUIRED, STRING]
  • {note: STRING} -> [REQUIRED, OBJECT, {$: {note: [REQUIRED, STRING]}}]
  • [[FINITE]] -> [REQUIRED, ARRAY, {$: [REQUIRED, FINITE]}]
  • (v) => if (!v) { throw new Error(); } -> [REQUIRED, ANY, (v) => if (!v) { throw new Error(); }]

Kind: static typedef of types

types.custom_validator ⇒ \*

Custom Validator

A function used as a typeset, or as a subset to a typeset, to provide custom verification of the value being verified.

A typeset may only have one validator, and the validator is only called if the value being verified was verified by at least one type in the typeset. The validator must be the last element within the typeset (if the typeset is an array, and a validator is needed). The validator must also be specified after the qualifier in a typeset Array.

The validator is invoked immediately after the first type match, but only if a type match is made. If the typeset is not fully-qualified and does not explicitly specify a type, the ANY type is implied, which will match any value, which means the validator will always be called.

NOTE about qualifiers: Validators will be invoked regardless of the qualifier. If the typeset’s qualifier is EXPECTED, the validator must handle null values. If the qualifier is OPTIONAL, the validator must handle undefined and null values. Also note that a value of null or undefined, if permitted by the qualifier, will always be type-matched to the first type in the typeset because all types allow these values for their related qualifiers.

There is one disadvantage to using a custom validator: It cannot be serialized via JSON, which means it cannot be easily transmitted or persisted. One option would be to customize the serialization to JSON by serializing the validator to a special object with properties that would inform the deserialization process on how to reconstruct the validator dynamically. There may also be a way to persist the function’s code, but that would require the use of the unsafe eval() function to later reconstitute it as an actual function.

Kind: static typedef of types
Returns: \* - Either undefined or a truthy value to pass the verification, or a falsy value to fail it. The validator may also throw an Error to fail the verification.

If a falsy value (other than undefined) is returned, an Error will be generated and included in the resulting RtvError as its failure property, as well as part of its message.

While undefined is falsy, it’s also the result of a function that did not return anything, which is interpreted as indicating the validator found no fault with the value.

It’s recommend to throw an Error with a helpful message rather than simply returning a falsy value to fail the verification.
Throws:

  • Error (Optional) If the validation fails. This error will fail the overall verification, and will be included in the resulting RtvError as its failure property, as well as part of its message.

    Although not required, it’s recommended to throw an error with a message that will help the developer determine why the custom validation failed, while avoiding exposing any sensitive information that may be found in the value (such as passwords).

See: isCustomValidator

Param Type Description
value \* The value being verified. This value differs from context.originalValue in that it is the value currently being verified, closest to the custom validator itself, e.g. the value of element in an array, as opposed to the array itself, or the value of a property in an object, as opposed to the object itself.
match Array A fully-qualified typeset describing the sub-type within the typeset parameter that matched, resulting in the custom validator being called (if no sub-types matched, it would not get called). For example, if the typeset used for verification was [PLAIN_OBJECT, {$: {note: STRING}}, validator], this parameter would be a new Array typeset [REQUIRED, PLAIN_OBJECT, {$: {note: STRING}}], and the typeset parameter would be a reference to the original [PLAIN_OBJECT, {$: {note: STRING}}, validator]. If the verification typeset was [STRING, FINITE, validator] and FINITE matched, this parameter would be [REQUIRED, FINITE] and the typeset parameter would be a reference to the original [STRING, FINITE, validator]. If the verification typeset was [{message: STRING}, validator] and the shape matched, this parameter would be [REQUIRED, OBJECT, {$: {message: STRING}}] (because of the default object type) and the typeset parameter would be a reference to the original [{message: STRING}, validator]. If the verification typeset was simply validator (just the validator itself), this parameter would be [REQUIRED, ANY] (because of the implied ANY type) and the typeset would be a reference to the original validator.
typeset typeset Reference to the typeset used for verification. Note the typeset may contain nested typeset(s), and may be part of a larger parent typeset (though there would be no reference to the parent typeset, if any).
context type\_validator\_context Additional context for the validation.

rtvref.util : object

RTV.js Utilities

Kind: static namespace of rtvref

util.print(printValue, printOptions) ⇒ string

Pretty-print a value.

Kind: static method of util
Returns: string - Pretty-printed value. It’s not perfect and may not catch all types, but attempts to be good enough.

Param Type Default Description
printValue \*   Value to print.
printOptions Object   Print options.
[printOptions.isTypeset] boolean false true if the value being printed is a typeset; false otherwise.

util.hasOwnProp(obj, prop) ⇒ boolean

Safely determines if a property is an own-property of an object.

Kind: static method of util
Returns: boolean - true if it is; false otherwise. Also false if obj is falsy.

Param Type Description
obj Object Object to check. Can be falsy.
prop string Own-property to check.

rtvref.validation : object

RTV.js Validation

This namespace provides type validations which verify values to be of the types defined in this library. If permitted values differ between qualifiers, the validation must only permit the REQUIRED values. Validations strictly check for types; they do not consider type arguments or qualifiers like type validators do.

Validations may also check for pseudo-types, such as the isTypeset validation verifying a value as a typeset, which is not an actual type.

Every validation module must provide the following interface:

Validations are meant to be leaf modules. They should not import other modules other than types and other validations. Validation modules should be named as is<Type> such that their default export is named is<Type>.

NOTE: Where possible, validations should use the other validations rather than third-party code (e.g. isTypeset.js needs to check for objects, so it should use the isObject.js validation rather than ‘lodash/isObject’, and let isObject.js decide the best way to check a value as being an ‘object’ as defined by this library in rtvref.types.OBJECT). This way, it makes it much easier to change the definition of a type later on.

Kind: static namespace of rtvref

validation.method(value) ⇒ boolean

Type Validation Method

Verifies a value is of a certain type.

Kind: static method of validation
Returns: boolean - true if the value matches the type; false otherwise.

Param Type Description
value \* The value to validate.

validation.isAny : Module

Validation Module: isAny

Kind: static typedef of validation

isAny.type : string

Type: ANY

Kind: static constant of isAny

isAny.check(v) ⇒ boolean

Validation for the ANY type.

Kind: static method of isAny
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isAnyObject : Module

Validation Module: isAnyObject

Kind: static typedef of validation

isAnyObject.type : string

Type: ANY_OBJECT

Kind: static constant of isAnyObject

isAnyObject.check(v) ⇒ boolean

Validation for the ANY_OBJECT type.

Kind: static method of isAnyObject
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isArray : Module

Validation Module: isArray

Kind: static typedef of validation

isArray.type : string

Type: ARRAY

Kind: static constant of isArray

isArray.check(v) ⇒ boolean

Validation for the ARRAY type.

Kind: static method of isArray
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isBoolean : Module

Validation Module: isBoolean

Kind: static typedef of validation

isBoolean.type : string

Type: BOOLEAN

Kind: static constant of isBoolean

isBoolean.check(v) ⇒ boolean

Validation for the BOOLEAN type.

Determines if a value is a boolean literal only (i.e. a primitive). It does not validate new Boolean(true), which is an object that is a boolean.

Kind: static method of isBoolean
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isClassObject : Module

Validation Module: isClassObject

Kind: static typedef of validation

isClassObject.type : string

Type: CLASS_OBJECT

Kind: static constant of isClassObject

isClassObject.check(v) ⇒ boolean

Validation for the CLASS_OBJECT type.

Kind: static method of isClassObject
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isCustomValidator : Module

Validation Module: isCustomValidator

Kind: static typedef of validation

isCustomValidator.type : string

Type: undefined, custom validator pseudo-type.

Kind: static constant of isCustomValidator

isCustomValidator.check(v) ⇒ boolean

Determines if a value is a custom validator.

Kind: static method of isCustomValidator
Returns: boolean - true if it is; false otherwise.

Param Type Description
v \* Value to validate.

validation.isDate : Module

Validation Module: isDate

Kind: static typedef of validation

isDate.type : string

Type: DATE

Kind: static constant of isDate

isDate.check(v) ⇒ boolean

Validation for the DATE type.

Kind: static method of isDate
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isError : Module

Validation Module: isError

Kind: static typedef of validation

isError.type : string

Type: ERROR

Kind: static constant of isError

isError.check(v) ⇒ boolean

Validation for the ERROR type.

Kind: static method of isError
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isFalsy : Module

Validation Module: isFalsy

Kind: static typedef of validation

isFalsy.type : string

Type: undefined, falsy value pseudo-type.

Kind: static constant of isFalsy

isFalsy.check(v) ⇒ boolean

Determines if a value is a JavaScript falsy value.

Kind: static method of isFalsy
Returns: boolean - true if it is; false otherwise.

Param Type Description
v \* Value to validate.

validation.isFinite : Module

Validation Module: isFinite

Kind: static typedef of validation

isFinite.type : string

Type: FINITE

Kind: static constant of isFinite

isFinite.check(v) ⇒ boolean

Validation for the FINITE type.

Determines if a value is a finite number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of isFinite
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isFloat : Module

Validation Module: isFloat

Kind: static typedef of validation

isFloat.type : string

Type: FLOAT

Kind: static constant of isFloat

isFloat.check(v) ⇒ boolean

Validation for the FLOAT type.

Determines if a value is a floating point literal only (i.e. a primitive). It does not validate new Number(1.5), which is an object that is a number.

Kind: static method of isFloat
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isFunction : Module

Validation Module: isFunction

Kind: static typedef of validation

isFunction.type : string

Type: FUNCTION

Kind: static constant of isFunction

isFunction.check(v) ⇒ boolean

Validation for the FUNCTION type.

Kind: static method of isFunction
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isHashMap : Module

Validation Module: isHashMap

Kind: static typedef of validation

isHashMap.type : string

Type: HASH_MAP

Kind: static constant of isHashMap

isHashMap.check(v) ⇒ boolean

Validation for the HASH_MAP type.

Kind: static method of isHashMap
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isInt : Module

Validation Module: isInt

Kind: static typedef of validation

isInt.type : string

Type: INT

Kind: static constant of isInt

isInt.check(v) ⇒ boolean

Validation for the INT type.

Determines if a value is an integer literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of isInt
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isJson : Module

Validation Module: isJson

Kind: static typedef of validation

isJson.type : string

Type: JSON

Kind: static constant of isJson

isJson.check(v) ⇒ boolean

Validation for the JSON type.

Kind: static method of isJson
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isMap : Module

Validation Module: isMap

Kind: static typedef of validation

isMap.type : string

Type: MAP

Kind: static constant of isMap

isMap.check(v) ⇒ boolean

Validation for the MAP type.

Kind: static method of isMap
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isNull : Module

Validation Module: isNull

Kind: static typedef of validation

isNull.type : string

Type: NULL

Kind: static constant of isNull

isNull.check(v) ⇒ boolean

Validation for the NULL type.

Kind: static method of isNull
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isNumber : Module

Validation Module: isNumber

Kind: static typedef of validation

isNumber.type : string

Type: NUMBER

Kind: static constant of isNumber

isNumber.check(v) ⇒ boolean

Validation for the NUMBER type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number, neither does it validate NaN.

Kind: static method of isNumber
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isObject : Module

Validation Module: isObject

Kind: static typedef of validation

isObject.type : string

Type: OBJECT

Kind: static constant of isObject

isObject.check(v) ⇒ boolean

Validation for the OBJECT type.

Kind: static method of isObject
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isPlainObject : Module

Validation Module: isPlainObject

Kind: static typedef of validation

isPlainObject.type : string

Type: PLAIN_OBJECT

Kind: static constant of isPlainObject

isPlainObject.check(v) ⇒ boolean

Validation for the PLAIN_OBJECT type.

Kind: static method of isPlainObject
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isPrimitive : Module

Validation Module: isPrimitive

Kind: static typedef of validation

isPrimitive.type : string

Type: undefined, primitive pseudo-type.

Kind: static constant of isPrimitive

isPrimitive.check(v) ⇒ boolean

Determines if a value is a JavaScript primitive.

Kind: static method of isPrimitive
Returns: boolean - true if it is; false otherwise.

Param Type Description
v \* Value to validate.

validation.isPromise : Module

Validation Module: isPromise

Kind: static typedef of validation

isPromise.type : string

Type: PROMISE

Kind: static constant of isPromise

isPromise.check(v) ⇒ boolean

Validation for the PROMISE type.

Kind: static method of isPromise
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isRegExp : Module

Validation Module: isRegExp

Kind: static typedef of validation

isRegExp.type : string

Type: REGEXP

Kind: static constant of isRegExp

isRegExp.check(v) ⇒ boolean

Validation for the REGEXP type.

Kind: static method of isRegExp
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isSafeInt : Module

Validation Module: isSafeInt

Kind: static typedef of validation

isSafeInt.type : string

Type: SAFE_INT

Kind: static constant of isSafeInt

isSafeInt.check(v) ⇒ boolean

Validation for the SAFE_INT type.

Determines if a value is an integer literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of isSafeInt
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isSet : Module

Validation Module: isSet

Kind: static typedef of validation

isSet.type : string

Type: SET

Kind: static constant of isSet

isSet.check(v) ⇒ boolean

Validation for the SET type.

Kind: static method of isSet
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isShape : Module

Validation Module: isShape

Kind: static typedef of validation

isShape.type : string

Type: undefined, shape pseudo-type.

Kind: static constant of isShape

isShape.check(v) ⇒ boolean

Determines if a value is a shape.

Kind: static method of isShape
Returns: boolean - true if it is; false otherwise.

Param Type Description
v \* Value to validate.

validation.isString : Module

Validation Module: isString

Kind: static typedef of validation

isString.type : string

Type: STRING

Kind: static constant of isString

isString.check(v, [options]) ⇒ boolean

Validation for the STRING type.

Determines if a value is a string literal only (i.e. a primitive), including an empty string. It does not validate new String('value'), which is an object that is a string.

Kind: static method of isString
Returns: boolean - true if validated; false otherwise.

Param Type Default Description
v \*   Value to validate.
[options] Object   Validation options.
[options.allowEmpty] boolean false If truthy, empty strings are permitted.

validation.isSymbol : Module

Validation Module: isSymbol

Kind: static typedef of validation

isSymbol.type : string

Type: SYMBOL

Kind: static constant of isSymbol

isSymbol.check(v) ⇒ boolean

Validation for the SYMBOL type.

Kind: static method of isSymbol
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isTypeArgs : Module

Validation Module: isTypeArgs

Kind: static typedef of validation

isTypeArgs.type : string

Type: undefined, type arguments pseudo-type.

Kind: static constant of isTypeArgs

isTypeArgs.check(v) ⇒ boolean

Determines if a value is a type arguments object.

Kind: static method of isTypeArgs
Returns: boolean - true if it is; false otherwise.

Param Type Description
v \* Value to validate.

validation.isTypeset : Module

Validation Module: isTypeset

Kind: static typedef of validation

isTypeset.type : string

Type: undefined, typeset pseudo-type.

Kind: static constant of isTypeset

isTypeset.check(v, [options]) ⇒ boolean

Determines if a value is a typeset.

Kind: static method of isTypeset
Returns: boolean - true if it is; false otherwise.
See: typeset

Param Type Default Description
v \*   Value to validate.
[options] Object   Validation options.
[options.deep] boolean false If truthy, deeply-validates any nested typesets. Note that typesets in nested shapes are also deeply-validated.
[options.fullyQualified] boolean false If truthy, the typeset must be fully-qualified to be valid.
[options.rootCause] string | undefined   (Output property) If an options object is specified, this property will be added and set to a failure message IIF the validation fails.

validation.isWeakMap : Module

Validation Module: isWeakMap

Kind: static typedef of validation

isWeakMap.type : string

Type: WEAK_MAP

Kind: static constant of isWeakMap

isWeakMap.check(v) ⇒ boolean

Validation for the WEAK_MAP type.

Kind: static method of isWeakMap
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

validation.isWeakSet : Module

Validation Module: isWeakSet

Kind: static typedef of validation

isWeakSet.type : string

Type: WEAK_SET

Kind: static constant of isWeakSet

isWeakSet.check(v) ⇒ boolean

Validation for the WEAK_SET type.

Kind: static method of isWeakSet
Returns: boolean - true if validated; false otherwise.

Param Type Description
v \* Value to validate.

rtvref.validator : object

RTV.js Type Validators

This namespace provides validators for each supported type, capable of fully validating a value against that type. Validators differ from type validations provided by the validation module in that validators verify a value against a single, specific type, considering qualifiers as well as type arguments.

Every validator module must provide the following interface:

Validator modules should be named as val<Type> such that their default export is named val<Type>.

There can only be one validator for any given type. Where possible, each validator should use applicable type validations rather than third-party code (e.g. lodash) to ensure that the semantics of each type is properly interpreted. If the validator introduces an entirely new type, then it should use whatever means necessary to properly identify the type which it validates.

Kind: static namespace of rtvref

validator.type_validator(value, qualifier, args, context) ⇒ RtvSuccess | RtvError

Type Validator Function

NOTE: A validator must always give precedence to qualifier rules for the type it’s validating, over any arguments specified. For example,

NOTE: A validator must support all its qualifier rules, including proper handling of null values when EXPECTED and undefined values when OPTIONAL, in addition to any type-specific qualifier rules. For example, the STRING type permits empty strings when not REQUIRED.

Kind: static method of validator
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
value \* The value to validate.
qualifier string The validation qualifier from the immediate typeset in which the pertaining type was specified. Validators should always explicitly default to REQUIRED to maintain consistent behavior.
args Object The arguments object, if any/applicable, for the type being validated. For example, string args in a typeset such as [rtv.STRING, {min: 5}] (a required string of at least 5 characters in length).
context type\_validator\_context Additional context for the validation.

validator.validator_config(settings)

Type Validator Configuration Function

This function is called to provide the type validator with access to internal utilities.

Kind: static method of validator

Param Type Description
settings validator\_config\_settings Configuration settings.

validator.valAny : Module

Validator Module: valAny

Kind: static typedef of validator

valAny.type : string

Type: ANY

Kind: static constant of valAny

valAny.config(settings)

Configuration Function

Kind: static method of valAny

Param Type Description
settings validator\_config\_settings Configuration settings.

valAny.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the ANY type.

Kind: static method of valAny
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valAnyObject : Module

Validator Module: valAnyObject

Kind: static typedef of validator

valAnyObject.type : string

Type: ANY_OBJECT

Kind: static constant of valAnyObject

valAnyObject.config(settings)

Configuration Function

Kind: static method of valAnyObject

Param Type Description
settings validator\_config\_settings Configuration settings.

valAnyObject.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the ANY_OBJECT type.

Kind: static method of valAnyObject
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] shape\_object\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valArray : Module

Validator Module: valArray

Kind: static typedef of validator

valArray.type : string

Type: ARRAY

Kind: static constant of valArray

valArray.config(settings)

Configuration Function

Kind: static method of valArray

Param Type Description
settings validator\_config\_settings Configuration settings.

valArray.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the ARRAY type.

Kind: static method of valArray
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] ARRAY\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valBoolean : Module

Validator Module: valBoolean

Kind: static typedef of validator

valBoolean.type : string

Type: BOOLEAN

Kind: static constant of valBoolean

valBoolean.config(settings)

Configuration Function

Kind: static method of valBoolean

Param Type Description
settings validator\_config\_settings Configuration settings.

valBoolean.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the BOOLEAN type.

Determines if a value is a boolean literal only (i.e. a primitive). It does not validate new Boolean(true), which is an object that is a boolean.

Kind: static method of valBoolean
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valClassObject : Module

Validator Module: valClassObject

Kind: static typedef of validator

valClassObject.type : string

Type: CLASS_OBJECT

Kind: static constant of valClassObject

valClassObject.config(settings)

Configuration Function

Kind: static method of valClassObject

Param Type Description
settings validator\_config\_settings Configuration settings.

valClassObject.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the CLASS_OBJECT type.

Kind: static method of valClassObject
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] shape\_object\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valDate : Module

Validator Module: valDate

Kind: static typedef of validator

valDate.type : string

Type: DATE

Kind: static constant of valDate

valDate.config(settings)

Configuration Function

Kind: static method of valDate

Param Type Description
settings validator\_config\_settings Configuration settings.

valDate.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the DATE type.

Kind: static method of valDate
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valError : Module

Validator Module: valError

Kind: static typedef of validator

valError.type : string

Type: ERROR

Kind: static constant of valError

valError.config(settings)

Configuration Function

Kind: static method of valError

Param Type Description
settings validator\_config\_settings Configuration settings.

valError.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the ERROR type.

Kind: static method of valError
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valFinite : Module

Validator Module: valFinite

Kind: static typedef of validator

valFinite.type : string

Type: FINITE

Kind: static constant of valFinite

valFinite.config(settings)

Configuration Function

Kind: static method of valFinite

Param Type Description
settings validator\_config\_settings Configuration settings.

valFinite.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the FINITE type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of valFinite
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valFloat : Module

Validator Module: valFloat

Kind: static typedef of validator

valFloat.type : string

Type: FLOAT

Kind: static constant of valFloat

valFloat.config(settings)

Configuration Function

Kind: static method of valFloat

Param Type Description
settings validator\_config\_settings Configuration settings.

valFloat.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the FLOAT type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1.5), which is an object that is a number.

Kind: static method of valFloat
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valFunction : Module

Validator Module: valFunction

Kind: static typedef of validator

valFunction.type : string

Type: FUNCTION

Kind: static constant of valFunction

valFunction.config(settings)

Configuration Function

Kind: static method of valFunction

Param Type Description
settings validator\_config\_settings Configuration settings.

valFunction.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the FUNCTION type.

Kind: static method of valFunction
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valHashMap : Module

Validator Module: valHashMap

Kind: static typedef of validator

valHashMap.type : string

Type: HASH_MAP

Kind: static constant of valHashMap

valHashMap.config(settings)

Configuration Function

Kind: static method of valHashMap

Param Type Description
settings validator\_config\_settings Configuration settings.

valHashMap.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the HASH_MAP type.

Kind: static method of valHashMap
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] collection\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valInt : Module

Validator Module: valInt

Kind: static typedef of validator

valInt.type : string

Type: INT

Kind: static constant of valInt

valInt.config(settings)

Configuration Function

Kind: static method of valInt

Param Type Description
settings validator\_config\_settings Configuration settings.

valInt.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the INT type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of valInt
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valJson : Module

Validator Module: valJson

Kind: static typedef of validator

valJson.type : string

Type: JSON

Kind: static constant of valJson

valJson.config(settings)

Configuration Function

Kind: static method of valJson

Param Type Description
settings validator\_config\_settings Configuration settings.

valJson.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the JSON type.

Kind: static method of valJson
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valMap : Module

Validator Module: valMap

Kind: static typedef of validator

valMap.type : string

Type: MAP

Kind: static constant of valMap

valMap.config(settings)

Configuration Function

Kind: static method of valMap

Param Type Description
settings validator\_config\_settings Configuration settings.

valMap.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the MAP type.

Kind: static method of valMap
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] collection\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valNull : Module

Validator Module: valNull

Kind: static typedef of validator

valNull.type : string

Type: NULL

Kind: static constant of valNull

valNull.config(settings)

Configuration Function

Kind: static method of valNull

Param Type Description
settings validator\_config\_settings Configuration settings.

valNull.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the NULL type.

Kind: static method of valNull
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valNumber : Module

Validator Module: valNumber

Kind: static typedef of validator

valNumber.type : string

Type: NUMBER

Kind: static constant of valNumber

valNumber.config(settings)

Configuration Function

Kind: static method of valNumber

Param Type Description
settings validator\_config\_settings Configuration settings.

valNumber.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the NUMBER type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of valNumber
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valObject : Module

Validator Module: valObject

Kind: static typedef of validator

valObject.type : string

Type: OBJECT

Kind: static constant of valObject

valObject.config(settings)

Configuration Function

Kind: static method of valObject

Param Type Description
settings validator\_config\_settings Configuration settings.

valObject.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the OBJECT type.

Kind: static method of valObject
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] shape\_object\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valPlainObject : Module

Validator Module: valPlainObject

Kind: static typedef of validator

valPlainObject.type : string

Type: PLAIN_OBJECT

Kind: static constant of valPlainObject

valPlainObject.config(settings)

Configuration Function

Kind: static method of valPlainObject

Param Type Description
settings validator\_config\_settings Configuration settings.

valPlainObject.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the PLAIN_OBJECT type.

Kind: static method of valPlainObject
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] shape\_object\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valPromise : Module

Validator Module: valPromise

Kind: static typedef of validator

valPromise.type : string

Type: PROMISE

Kind: static constant of valPromise

valPromise.config(settings)

Configuration Function

Kind: static method of valPromise

Param Type Description
settings validator\_config\_settings Configuration settings.

valPromise.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the PROMISE type.

Kind: static method of valPromise
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valRegExp : Module

Validator Module: valRegExp

Kind: static typedef of validator

valRegExp.type : string

Type: REGEXP

Kind: static constant of valRegExp

valRegExp.config(settings)

Configuration Function

Kind: static method of valRegExp

Param Type Description
settings validator\_config\_settings Configuration settings.

valRegExp.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the REGEXP type.

Kind: static method of valRegExp
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valSafeInt : Module

Validator Module: valSafeInt

Kind: static typedef of validator

valSafeInt.type : string

Type: SAFE_INT

Kind: static constant of valSafeInt

valSafeInt.config(settings)

Configuration Function

Kind: static method of valSafeInt

Param Type Description
settings validator\_config\_settings Configuration settings.

valSafeInt.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the SAFE_INT type.

Determines if a value is a number literal only (i.e. a primitive). It does not validate new Number(1), which is an object that is a number.

Kind: static method of valSafeInt
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valSet : Module

Validator Module: valSet

Kind: static typedef of validator

valSet.type : string

Type: SET

Kind: static constant of valSet

valSet.config(settings)

Configuration Function

Kind: static method of valSet

Param Type Description
settings validator\_config\_settings Configuration settings.

valSet.validate(v, [q], [args], [context]) ⇒ RtvSuccess | RtvError

Validator for the SET type.

Kind: static method of valSet
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] collection\_args Type arguments.
[context] type\_validator\_context Validation context.

validator.valString : Module

Validator Module: valString

Kind: static typedef of validator

valString.type : string

Type: STRING

Kind: static constant of valString

valString.config(settings)

Configuration Function

Kind: static method of valString

Param Type Description
settings validator\_config\_settings Configuration settings.

valString.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the STRING type.

Determines if a value is a string literal only (i.e. a primitive). It does not validate new String('value'), which is an object that is a string.

Kind: static method of valString
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] STRING\_args Type arguments.

validator.valSymbol : Module

Validator Module: valSymbol

Kind: static typedef of validator

valSymbol.type : string

Type: SYMBOL

Kind: static constant of valSymbol

valSymbol.config(settings)

Configuration Function

Kind: static method of valSymbol

Param Type Description
settings validator\_config\_settings Configuration settings.

valSymbol.validate(v, [q], [args]) ⇒ RtvSuccess | RtvError

Validator for the SYMBOL type.

Kind: static method of valSymbol
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.
[args] numeric\_args Type arguments.

validator.valWeakMap : Module

Validator Module: valWeakMap

Kind: static typedef of validator

valWeakMap.type : string

Type: WEAK_MAP

Kind: static constant of valWeakMap

valWeakMap.config(settings)

Configuration Function

Kind: static method of valWeakMap

Param Type Description
settings validator\_config\_settings Configuration settings.

valWeakMap.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the WEAK_MAP type.

Kind: static method of valWeakMap
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.valWeakSet : Module

Validator Module: valWeakSet

Kind: static typedef of validator

valWeakSet.type : string

Type: WEAK_SET

Kind: static constant of valWeakSet

valWeakSet.config(settings)

Configuration Function

Kind: static method of valWeakSet

Param Type Description
settings validator\_config\_settings Configuration settings.

valWeakSet.validate(v, [q]) ⇒ RtvSuccess | RtvError

Validator for the WEAK_SET type.

Kind: static method of valWeakSet
Returns: RtvSuccess | RtvError - An RtvSuccess if valid; RtvError if not.

Param Type Description
v \* Value to validate.
[q] string Validation qualifier. Defaults to REQUIRED.

validator.type_validator_context_options : Object

Type Validator Context Options

General options for configuring the behavior of one or more validators invoked during a check or verification based on the specified typeset. All validators will receive these options.

Validator-specific options are known as type arguments and are specified inline within a typeset.

Kind: static typedef of validator
Properties

Name Type Description
[exactShapes] boolean If true, any shape encountered, top-level or nested, unless specifically configured not to, will require that the related object’s own-properties be exactly those specified in the shape, no more, no less, as long as a shape is specified. By default, extra properties on the object (i.e. not in the shape) being verified are ignored. If a shape isn’t specified on a given object-related typeset, this flag will be ignored for that typeset. This flag can be overridden on an individual shape basis with the shape’s exact argument.

validator.type_validator_context : Object

Type Validator Context

This object provides important information to a type validator, including a custom validator, about the context of the current validation check.

For example, a call to rtv.verify({foo: 1}, {foo: validator}) would provide the following context to the invoked validator:

{
  originalValue: {foo: 1},
  parent: {foo: 1},
  parentKey: 'foo'
}
// and here, the validator's `value` parameter would be set to 1.

Kind: static typedef of validator
Properties

Name Type Description
originalValue \* The original/first value given to rtv.check() or rtv.verify().
parent Object | Array | Map | Set | undefined Reference to the immediate parent of the property or element being validated. For example, if we have this object: <pre>const foods = { fruits: ['apple', 'orange', 'banana'], vegetables: ['celery', 'cucumber', 'kale'] } </pre> and we validate it with the following typeset: <pre>[rtv.HASH_MAP, { keyExp: '\\w+', $values: [[rtv.STRING, (value, match, typeset, context) => { // called for each element of both arrays value; // 'apple', 'orange', ..., 'cucumber', 'kale' context.originalValue; // `foods` context.parent; // first `fruits`, then `vegetables` }]] }] </pre> we see (in the comments) how originalValue and parent differ. parent gives more immediate context than originalValue does since it changes as the validation digs into the object hierarchy. parent will be undefined if the custom validator is placed at the top top of the typeset since there is no parent to reference in that case. For example: <pre>[ rtv.HASH_MAP, { keyExp: '\\w+', $values: [[rtv.STRING]] }, (value, match, typeset, context) => { // called once for the hash map itself value; // `foods` context.originalValue; // `foods` context.parent; // `undefined` } ] </pre>
parentKey \* Reference to the key/index in the parent that is being validated. The associated value is provided as the first parameter to the custom validator. parentKey differs depending on the type of parent: - Set: undefined since Sets do not have indexes. Use the value parameter provided to the custom validator as the key into the parent in this case. - Map: When validating keys, always undefined. Use the value parameter provided to the custom validator to know which key is being validated. When validating values, parentKey will be any value that is a valid key in a Map. - Object (i.e. HASH_MAP): string, the key name. - Array: number, the element’s index. - undefined: undefined.
[options] type\_validator\_context\_options Configuration options.

validator.validator_config_settings : Object

Type Validator Configuration Settings

The settings provided to the configuration function.

Kind: static typedef of validator
Properties

Name Type Description
impl impl Reference to the impl module.