Commit 42a42cff authored by Stefan Cameron's avatar Stefan Cameron

Beautify and fix the API documentation

*   Fix INT -> SAFE_INT

*   Remove completed TODOs

*   Clarify example titles

*   Fix missing rtvref.validation and rtvref.validator docs

    Also rename `validation/isValidator -> validation/isCustomValidator`
    to avoid confusion between custom validators in typesets, and
    type validators in the library.

*   Clarify rtv.t and rtv.q enumerations

*   Clean-up the rtv interface
parent 843493cc
Pipeline #30937713 passed with stages
in 16 minutes and 23 seconds
This source diff could not be displayed because it is too large. You can view the blob instead.
# RTV.js # RTV.js
__Runtime Type Verification Isomorphic JavaScript Library__ Runtime Verification Library for browsers and Node.js.
This library runs equally well in modern browsers and on the server with Node.js. This library is isomorphic: It runs equally well in modern browsers and on the server with Node.js.
# Goals # Goals
...@@ -31,12 +31,9 @@ Shapes must be: ...@@ -31,12 +31,9 @@ Shapes must be:
# TODO # TODO
- [ ] Implement the library...
- [ ] Debug the generated docs (including private docs), checking for broken links...
- [ ] Unit tests must be run both in the browser and in Node.js -- in the browser via Gitlab CI - [ ] Unit tests must be run both in the browser and in Node.js -- in the browser via Gitlab CI
- [ ] Add Gitlab CI config, or use TravisCI? - [ ] Add Gitlab CI config, or use TravisCI?
- [ ] Publish to npm - [ ] Publish to npm
- [ ] Add `.npmignore`
- [ ] Make sure 'Goals' section is complete and accurate, add some links - [ ] Make sure 'Goals' section is complete and accurate, add some links
- [ ] Make sure `CONTRIBUTING.md` is filled-out - [ ] Make sure `CONTRIBUTING.md` is filled-out
......
...@@ -20,7 +20,7 @@ ...@@ -20,7 +20,7 @@
"node:internals": "rollup -c tools/rollup.internals.js && node -r ./dist_tools/internals.js --inspect", "node:internals": "rollup -c tools/rollup.internals.js && node -r ./dist_tools/internals.js --inspect",
"build:lib": "BABEL_ENV=build rollup -c", "build:lib": "BABEL_ENV=build rollup -c",
"build": "npm run clean && npm run build:lib", "build": "npm run clean && npm run build:lib",
"docs": "jsdoc2md -f \"src/**/*.js\" -f \"src/**/*.jsdoc\" --separators > API.md", "docs": "jsdoc2md -f \"src/**/*.js\" -f \"src/**/*.jsdoc\" --heading-depth 1 > API.md",
"lint": "eslint ./*.js \"src/**/*.js\" \"test/**/*.js\" \"tools/**/*.js\"", "lint": "eslint ./*.js \"src/**/*.js\" \"test/**/*.js\" \"tools/**/*.js\"",
"test:unit": "BABEL_ENV=test mocha -c -r mocha-setup.js \"./test/**/*.test.js\"", "test:unit": "BABEL_ENV=test mocha -c -r mocha-setup.js \"./test/**/*.test.js\"",
"test:unit:watch": "npm run test:unit -- -w", "test:unit:watch": "npm run test:unit -- -w",
......
...@@ -11,7 +11,7 @@ import isBoolean from './validation/isBoolean'; ...@@ -11,7 +11,7 @@ import isBoolean from './validation/isBoolean';
import isTypeset from './validation/isTypeset'; import isTypeset from './validation/isTypeset';
import isShape from './validation/isShape'; import isShape from './validation/isShape';
import isTypeArgs from './validation/isTypeArgs'; import isTypeArgs from './validation/isTypeArgs';
import isValidator from './validation/isValidator'; import isCustomValidator from './validation/isCustomValidator';
import {DEFAULT_OBJECT_TYPE, argTypes, default as types} from './types'; import {DEFAULT_OBJECT_TYPE, argTypes, default as types} from './types';
import {DEFAULT_QUALIFIER, default as qualifiers} from './qualifiers'; import {DEFAULT_QUALIFIER, default as qualifiers} from './qualifiers';
...@@ -20,7 +20,7 @@ import RtvSuccess from './RtvSuccess'; ...@@ -20,7 +20,7 @@ import RtvSuccess from './RtvSuccess';
import RtvError from './RtvError'; import RtvError from './RtvError';
/** /**
* <h2>RTV Implementation Module</h2> * <h3>RTV.js Implementation</h3>
* *
* Provides the internal implementation for the externally-facing {@link rtv RTV} * Provides the internal implementation for the externally-facing {@link rtv RTV}
* API, as well as utilities for {@link rtvref.validator type validators}. * API, as well as utilities for {@link rtvref.validator type validators}.
...@@ -220,7 +220,7 @@ const fullyQualify = function(typeset, qualifier) { ...@@ -220,7 +220,7 @@ const fullyQualify = function(typeset, qualifier) {
} }
// if a validator, it has an implied type of ANY // if a validator, it has an implied type of ANY
if (isValidator(typeset)) { if (isCustomValidator(typeset)) {
return [qualifier, types.ANY, typeset]; return [qualifier, types.ANY, typeset];
} }
...@@ -255,7 +255,7 @@ const fullyQualify = function(typeset, qualifier) { ...@@ -255,7 +255,7 @@ const fullyQualify = function(typeset, qualifier) {
} else if (isTypeArgs(rule)) { } else if (isTypeArgs(rule)) {
// args for curType since typeset is an array and object is not in first position // args for curType since typeset is an array and object is not in first position
fqts.push(rule); fqts.push(rule);
} else if (isValidator(rule)) { } else if (isCustomValidator(rule)) {
// validator: ANY is implied type if none specified // validator: ANY is implied type if none specified
if (!curType) { if (!curType) {
curType = types.ANY; curType = types.ANY;
...@@ -396,8 +396,8 @@ const extractNextType = function(typeset, qualifier) { ...@@ -396,8 +396,8 @@ const extractNextType = function(typeset, qualifier) {
* should be attributed to the subtype rather than the * should be attributed to the subtype rather than the
* {@link rtvref.qualifiers.DEFAULT_QUALIFIER default qualifier}. * {@link rtvref.qualifiers.DEFAULT_QUALIFIER default qualifier}.
* @see {@link rtvref.impl.check} * @see {@link rtvref.impl.check}
* @see {@link rtvref.impl.checkShape} * @see {@link rtvref.impl.checkWithShape}
* @see {@link rtvref.impl.checkType} * @see {@link rtvref.impl.checkWithType}
*/ */
/** /**
...@@ -412,8 +412,8 @@ const extractNextType = function(typeset, qualifier) { ...@@ -412,8 +412,8 @@ const extractNextType = function(typeset, qualifier) {
* returned may contain references to objects in `given` depending on property * returned may contain references to objects in `given` depending on property
* types. * types.
* @see {@link rtvref.impl.check} * @see {@link rtvref.impl.check}
* @see {@link rtvref.impl.checkShape} * @see {@link rtvref.impl.checkWithShape}
* @see {@link rtvref.impl.checkType} * @see {@link rtvref.impl.checkWithType}
* @throws {Error} If `current.path` or `override.path` is specified and not an array. * @throws {Error} If `current.path` or `override.path` is specified and not an array.
*/ */
const _getCheckOptions = function(current = {}, override = {}) { const _getCheckOptions = function(current = {}, override = {}) {
...@@ -444,7 +444,7 @@ const _getCheckOptions = function(current = {}, override = {}) { ...@@ -444,7 +444,7 @@ const _getCheckOptions = function(current = {}, override = {}) {
/** /**
* Checks a value using a single type. * Checks a value using a single type.
* @function rtvref.impl.checkType * @function rtvref.impl.checkWithType
* @param {*} value Value to check. * @param {*} value Value to check.
* @param {rtvref.types.typeset} singleType Either a simple type name (one of * @param {rtvref.types.typeset} singleType Either a simple type name (one of
* {@link rtvref.types.types}), a {@link rtvref.types.shape_descriptor shape descriptor}, * {@link rtvref.types.types}), a {@link rtvref.types.shape_descriptor shape descriptor},
...@@ -523,7 +523,7 @@ const checkWithType = function(value, singleType /*, options*/) { ...@@ -523,7 +523,7 @@ const checkWithType = function(value, singleType /*, options*/) {
/** /**
* Checks a value using a {@link rtvref.types.shape_descriptor shape descriptor} and * Checks a value using a {@link rtvref.types.shape_descriptor shape descriptor} and
* ensure the value's type is the default object type. * ensure the value's type is the default object type.
* @function rtvref.impl.checkShape * @function rtvref.impl.checkWithShape
* @param {Object} value Value to check. Must be of the * @param {Object} value Value to check. Must be of the
* {@link rtvref.types.DEFAULT_OBJECT_TYPE default} object type. * {@link rtvref.types.DEFAULT_OBJECT_TYPE default} object type.
* @param {Object} shape Expected shape of the `value`. Must be an * @param {Object} shape Expected shape of the `value`. Must be an
...@@ -546,27 +546,28 @@ const checkWithShape = function(value, shape /*, options*/) { ...@@ -546,27 +546,28 @@ const checkWithShape = function(value, shape /*, options*/) {
/** /**
* Checks a value using an Array typeset. * Checks a value using an Array typeset.
* @function rtvref.impl.checkTypeset * @function rtvref.impl.checkWithArray
* @param {*} value Value to check. * @param {*} value Value to check.
* @param {rtvref.types.typeset} typeset The Array typeset to check against. * @param {Array} array The Array {@link rtvref.types.typeset typeset} to check
* against.
* @returns {(rtvref.RtvSuccess|rtvref.RtvError)} Success indicator if the `value` * @returns {(rtvref.RtvSuccess|rtvref.RtvError)} Success indicator if the `value`
* is compliant to the `typeset`; error indicator otherwise. An exception is * is compliant to the `typeset`; error indicator otherwise. An exception is
* __not__ thrown if the `value` is non-compliant. * __not__ thrown if the `value` is non-compliant.
* @throws {Error} If `typeset` is not a valid Array typeset. * @throws {Error} If `typeset` is not a valid Array typeset.
*/ */
// @param {rtvref.impl._checkOptions} [options] (internal parameter) // @param {rtvref.impl._checkOptions} [options] (internal parameter)
const checkWithArray = function(value, typeset /*, options*/) { const checkWithArray = function(value, array /*, options*/) {
const options = _getCheckOptions(arguments.length > 2 ? arguments[2] : undefined); const options = _getCheckOptions(arguments.length > 2 ? arguments[2] : undefined);
// check for an array first since that's must faster than isTypeset() // check for an array first since that's must faster than isTypeset()
if (!isArray(typeset) || !(options.isTypeset || isTypeset(typeset))) { if (!isArray(array) || !(options.isTypeset || isTypeset(array))) {
throw new Error(`Invalid Array typeset=${print(typeset)}`); throw new Error(`Invalid typeset in array=${print(array)}`);
} }
options.isTypeset = true; options.isTypeset = true;
let match; // @type {(rtvref.types.fully_qualified_typeset|undefined)} let match; // @type {(rtvref.types.fully_qualified_typeset|undefined)}
const qualifier = options.qualifier || getQualifier(typeset); const qualifier = options.qualifier || getQualifier(array);
// consider each type in the typeset until we find one that matches the value // consider each type in the typeset until we find one that matches the value
// NOTE: an Array typeset represents multiple possibilities for a type match // NOTE: an Array typeset represents multiple possibilities for a type match
...@@ -574,18 +575,18 @@ const checkWithArray = function(value, typeset /*, options*/) { ...@@ -574,18 +575,18 @@ const checkWithArray = function(value, typeset /*, options*/) {
// NOTE: due to the isTypeset check above, we can assume that each 'type' is // NOTE: due to the isTypeset check above, we can assume that each 'type' is
// a SHALLOW-valid typeset (meaning, if it's an Array typeset, we cannot // a SHALLOW-valid typeset (meaning, if it's an Array typeset, we cannot
// assume that itself is valid because the isTypeset check was just shallow) // assume that itself is valid because the isTypeset check was just shallow)
const typesetCopy = typeset.concat(); // shallow clone so we can modify the array locally const typesetCopy = array.concat(); // shallow clone so we can modify the array locally
let subtype = extractNextType(typesetCopy, false); // exclude qualifier we already have let subtype = extractNextType(typesetCopy, false); // exclude qualifier we already have
while (subtype.length > 0) { while (subtype.length > 0) {
// check for the validator, which will always come alone, and since the validator // check for the validator, which will always come alone, and since the validator
// must be at the end of an Array typeset, it also signals the end of all subtypes // must be at the end of an Array typeset, it also signals the end of all subtypes
if (subtype.length === 1 && isValidator(subtype[0])) { if (subtype.length === 1 && isCustomValidator(subtype[0])) {
// if we reach the validator (which must be the very last element) in this // if we reach the validator (which must be the very last element) in this
// loop, none of the types matched, unless the validator is the only // loop, none of the types matched, unless the validator is the only
// type in the typeset, at which point it gets an implied type of ANY, // type in the typeset, at which point it gets an implied type of ANY,
// which matches any value // which matches any value
// NOTE: we have to test the original typeset for the ANY condition // NOTE: we have to test the original typeset for the ANY condition
if (typeset.length === 1 || (typeset.length === 2 && qualifiers.check(typeset[0]))) { if (array.length === 1 || (array.length === 2 && qualifiers.check(array[0]))) {
match = fullyQualify(types.ANY, qualifier); match = fullyQualify(types.ANY, qualifier);
} }
...@@ -611,19 +612,19 @@ const checkWithArray = function(value, typeset /*, options*/) { ...@@ -611,19 +612,19 @@ const checkWithArray = function(value, typeset /*, options*/) {
if (match) { if (match) {
// check for a validator at the end of the Array typeset and invoke it // check for a validator at the end of the Array typeset and invoke it
const lastType = typeset[typeset.length - 1]; const lastType = array[array.length - 1];
if (isValidator(lastType)) { if (isCustomValidator(lastType)) {
try { try {
lastType(value, match, typeset); lastType(value, match, array);
} catch (cvErr) { } catch (cvErr) {
// invalid in spite of the match since the validator said no // invalid in spite of the match since the validator said no
err = new RtvError(value, typeset, options.path, fullyQualify(typeset, qualifier), cvErr); err = new RtvError(value, array, options.path, fullyQualify(array, qualifier), cvErr);
} }
} }
// else, valid, since we have a match // else, valid, since we have a match
} else { } else {
// no match // no match
err = new RtvError(value, typeset, options.path, fullyQualify(typeset, qualifier)); err = new RtvError(value, array, options.path, fullyQualify(array, qualifier));
} }
return err || (new RtvSuccess()); return err || (new RtvSuccess());
...@@ -652,7 +653,7 @@ const check = function(value, typeset /*, options*/) { ...@@ -652,7 +653,7 @@ const check = function(value, typeset /*, options*/) {
return checkWithType(value, typeset, options); return checkWithType(value, typeset, options);
} }
if (isValidator(typeset)) { if (isCustomValidator(typeset)) {
// custom validator: bare function implies the ANY type // custom validator: bare function implies the ANY type
const match = types.ANY; const match = types.ANY;
const fqMatch = fullyQualify(match, options.qualifier); const fqMatch = fullyQualify(match, options.qualifier);
......
/**
* <h3>RTV.js Reference</h3>
*
* Members herein are _indirectly_ accessed and/or exposed through the
* {@link rtv RTV.js Public Interface}.
*
* @namespace rtvref
*/
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
import Enumeration from './Enumeration'; import Enumeration from './Enumeration';
/** /**
* <h2>Qualifiers</h2> * <h3>Qualifiers</h3>
* *
* Qualifiers determine the degree at which a value must be of a given type. * Qualifiers determine the degree at which a value must be of a given type.
* *
...@@ -93,7 +93,7 @@ export const DEFAULT_QUALIFIER = REQUIRED; ...@@ -93,7 +93,7 @@ export const DEFAULT_QUALIFIER = REQUIRED;
* - EXPECTED: Can be `null`. * - EXPECTED: Can be `null`.
* - OPTIONAL: Can be either `undefined` or `null`. * - OPTIONAL: Can be either `undefined` or `null`.
* *
* @function rtvref.qualifiers.checkBasicRules * @function rtvref.qualifiers.nilPermitted
* @param {*} v Value to check. * @param {*} v Value to check.
* @param {string} [q] Validation qualifier. Defaults to * @param {string} [q] Validation qualifier. Defaults to
* {@link rtvref.qualifiers.REQUIRED REQUIRED}. * {@link rtvref.qualifiers.REQUIRED REQUIRED}.
...@@ -117,7 +117,12 @@ export const nilPermitted = function(v, q = REQUIRED) { ...@@ -117,7 +117,12 @@ export const nilPermitted = function(v, q = REQUIRED) {
}; };
/** /**
* Enumeration (`string -> string`) of {@link rtvref.qualifiers qualifiers}. * Enumeration (`string -> string`) of all qualifiers:
*
* - {@link rtvref.qualifiers.REQUIRED REQUIRED}
* - {@link rtvref.qualifiers.EXPECTED EXPECTED}
* - {@link rtvref.qualifiers.OPTIONAL OPTIONAL}
*
* @name rtvref.qualifiers.qualifiers * @name rtvref.qualifiers.qualifiers
* @type {rtvref.Enumeration} * @type {rtvref.Enumeration}
*/ */
......
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
import Enumeration from './Enumeration'; import Enumeration from './Enumeration';
/** /**
* <h2>Types</h2> * <h3>Types</h3>
* @namespace rtvref.types * @namespace rtvref.types
*/ */
...@@ -23,7 +23,7 @@ import Enumeration from './Enumeration'; ...@@ -23,7 +23,7 @@ import Enumeration from './Enumeration';
* it produces an {@link rtvref.types.OBJECT object}, and __should be avoided__). * it produces an {@link rtvref.types.OBJECT object}, and __should be avoided__).
* - `Symbol` * - `Symbol`
* *
* @typedef {*} rtvref.types.primitives * @typedef {void} rtvref.types.primitives
* @see {@link rtvref.validation.isPrimitive} * @see {@link rtvref.validation.isPrimitive}
*/ */
...@@ -39,7 +39,7 @@ import Enumeration from './Enumeration'; ...@@ -39,7 +39,7 @@ import Enumeration from './Enumeration';
* the qualifier used is `EXPECTED`; and it could be `undefined` if the qualifier * the qualifier used is `EXPECTED`; and it could be `undefined` if the qualifier
* used is `OPTIONAL`. * used is `OPTIONAL`.
* *
* @typedef {*} rtvref.types.rules * @typedef {void} rtvref.types.qualifier_rules
*/ */
/** /**
...@@ -85,7 +85,7 @@ import Enumeration from './Enumeration'; ...@@ -85,7 +85,7 @@ import Enumeration from './Enumeration';
* of at least 5 characters in length. * of at least 5 characters in length.
* *
* Since {@link rtvref.qualifiers qualifiers} may affect how a value is validated * Since {@link rtvref.qualifiers qualifiers} may affect how a value is validated
* against a type, {@link rtvref.types.rules qualifier rules} always take * against a type, {@link rtvref.types.qualifier_rules qualifier rules} always take
* __precedence__ over any argument specified. For example, `[STRING, {min: 0}]` * __precedence__ over any argument specified. For example, `[STRING, {min: 0}]`
* would fail to validate an empty string because the _implied_ qualifier * would fail to validate an empty string because the _implied_ qualifier
* is `REQUIRED`, and per {@link rtvref.types.STRING STRING} qualifier rules, * is `REQUIRED`, and per {@link rtvref.types.STRING STRING} qualifier rules,
...@@ -386,7 +386,7 @@ import Enumeration from './Enumeration'; ...@@ -386,7 +386,7 @@ import Enumeration from './Enumeration';
* over network requests, perhaps embedded in JSON payloads, similar to * over network requests, perhaps embedded in JSON payloads, similar to
* {@link https://json-ld.org/ JSON-LD} schemas. * {@link https://json-ld.org/ JSON-LD} schemas.
* *
* <h4>Example: Object</h4> * <h4>Typeset Example: Object</h4>
* *
* <pre><code>const contactShape = { * <pre><code>const contactShape = {
* name: rtv.t.STRING, // required, non-empty, string * name: rtv.t.STRING, // required, non-empty, string
...@@ -429,20 +429,20 @@ import Enumeration from './Enumeration'; ...@@ -429,20 +429,20 @@ import Enumeration from './Enumeration';
* }, walletShape); // OK * }, walletShape); // OK
* </code></pre> * </code></pre>
* *
* <h4>Example: String</h4> * <h4>Typeset Example: String</h4>
* *
* <pre><code>rtv.verify('foo', rtv.t.STRING); // OK * <pre><code>rtv.verify('foo', rtv.t.STRING); // OK
* rtv.verify('foo', rtv.t.FINITE); // ERROR * rtv.verify('foo', rtv.t.FINITE); // ERROR
* </code></pre> * </code></pre>
* *
* <h4>Example: Array</h4> * <h4>Typeset Example: Array</h4>
* *
* <pre><code>const typeset = [rtv.t.STRING, rtv.t.FINITE]; // non-empty string, or finite number * <pre><code>const typeset = [rtv.t.STRING, rtv.t.FINITE]; // non-empty string, or finite number
* rtv.verify('foo', typeset); // OK * rtv.verify('foo', typeset); // OK
* rtv.verify(1, typeset); // OK * rtv.verify(1, typeset); // OK
* </code></pre> * </code></pre>
* *
* <h4>Example: Function</h4> * <h4>Typeset Example: Function</h4>
* *
* <pre><code>const validator = (v) => { * <pre><code>const validator = (v) => {
* if (v % 10) { * if (v % 10) {
...@@ -454,7 +454,7 @@ import Enumeration from './Enumeration'; ...@@ -454,7 +454,7 @@ import Enumeration from './Enumeration';
* rtv.verify(120, [rtv.t.INT, validator]); // OK * rtv.verify(120, [rtv.t.INT, validator]); // OK
* </code></pre> * </code></pre>
* *
* <h4>Example: Alternate Qualifier</h4> * <h4>Typeset Example: Alternate Qualifier</h4>
* *
* <pre><code>const person = { * <pre><code>const person = {
* name: rtv.t.STRING, // required, non-empty * name: rtv.t.STRING, // required, non-empty
...@@ -544,7 +544,7 @@ import Enumeration from './Enumeration'; ...@@ -544,7 +544,7 @@ import Enumeration from './Enumeration';
* {@link rtvref.RtvError#failure failure} property, as well as part of its * {@link rtvref.RtvError#failure failure} property, as well as part of its
* `message`. Therefore, it's recommended to throw an error with a message that * `message`. Therefore, it's recommended to throw an error with a message that
* will help the developer determine why the custom validation failed. * will help the developer determine why the custom validation failed.
* @see {@link rtvref.validation.isValidator} * @see {@link rtvref.validation.isCustomValidator}
*/ */
// Creates a definition object. // Creates a definition object.
...@@ -713,7 +713,7 @@ const defs = { ...@@ -713,7 +713,7 @@ const defs = {
* *
* Arguments (optional): {@link rtvref.types.numeric_args} * Arguments (optional): {@link rtvref.types.numeric_args}
* *
* @name rtvref.types.INT * @name rtvref.types.SAFE_INT
* @const {string} * @const {string}
* @see {@link rtvref.qualifiers} * @see {@link rtvref.qualifiers}
* @see {@link rtvref.types.NUMBER} * @see {@link rtvref.types.NUMBER}
...@@ -809,7 +809,7 @@ const defs = { ...@@ -809,7 +809,7 @@ const defs = {
* They represent a set of types that will be used to validate each element * 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. * of an array using a short-circuit OR conjunction, looking for the first type that matches.
* *
* <h4>Example: Simple array</h4> * <h4>Array Example: Simple array</h4>
* *
* The `value` property must be an array (possibly empty) of any type of value. * The `value` property must be an array (possibly empty) of any type of value.
* *
...@@ -824,7 +824,7 @@ const defs = { ...@@ -824,7 +824,7 @@ const defs = {
* to indicate what could be the equivalent: `[[]]`. The inner Array typeset * to indicate what could be the equivalent: `[[]]`. The inner Array typeset
* would be deemed _invalid_. * would be deemed _invalid_.
* *
* <h4>Example: Shorthand notation</h4> * <h4>Array Example: Shorthand notation</h4>
* *
* The `value` property must be an array (possibly empty) of finite numbers of * The `value` property must be an array (possibly empty) of finite numbers of
* any value. * any value.
...@@ -834,7 +834,7 @@ const defs = { ...@@ -834,7 +834,7 @@ const defs = {
* } * }
* </code></pre> * </code></pre>
* *
* <h4>Example: Shorthand, mixed types</h4> * <h4>Array Example: Shorthand, mixed types</h4>
* *
* The `value` property must be either a boolean; or an array (possibly empty) of * 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. * finite numbers of any value, or non-empty strings, or a mix of both.
...@@ -844,7 +844,7 @@ const defs = { ...@@ -844,7 +844,7 @@ const defs = {
* } * }
* </code></pre> * </code></pre>
* *
* <h4>Example: Fully-qualified notation, no typeset</h4> * <h4>Array Example: Fully-qualified notation, no typeset</h4>
* *
* The `value` property must be a non-empty array of any type of value. * The `value` property must be a non-empty array of any type of value.
* *
...@@ -853,7 +853,7 @@ const defs = { ...@@ -853,7 +853,7 @@ const defs = {
* } * }
* </code></pre> * </code></pre>
* *
* <h4>Example: Fully-qualified notation</h4> * <h4>Array Example: Fully-qualified notation</h4>
* *
* The `value` property must be an array (possibly empty) of finite numbers of * The `value` property must be an array (possibly empty) of finite numbers of
* any value (nested typeset is not fully-qualified). * any value (nested typeset is not fully-qualified).
...@@ -863,7 +863,7 @@ const defs = { ...@@ -863,7 +863,7 @@ const defs = {
* } * }
* </code></pre> * </code></pre>
* *
* <h4>Example: Fully-qualified, mixed types</h4> * <h4>Array Example: Fully-qualified, mixed types</h4>
* *
* The `value` property must be either a boolean; or an array (possibly empty) of * 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 * finite numbers of any value, or non-empty strings, or a mix of both
...@@ -1210,9 +1210,13 @@ const defs = { ...@@ -1210,9 +1210,13 @@ const defs = {
export const DEFAULT_OBJECT_TYPE = defs.OBJECT.value; export const DEFAULT_OBJECT_TYPE = defs.OBJECT.value;
/** /**
* Enumeration (`string -> string`) of __object__ {@link rtvref.types types}. These * Enumeration (`string -> string`) of __object__ types:
* are all the types that describe values which are essentially maps of various *
* keys to values. * - {@link rtvref.types.ANY_OBJECT ANY_OBJECT}
* - {@link rtvref.types.OBJECT OBJECT}
* - {@link rtvref.types.PLAIN_OBJECT PLAIN_OBJECT}
* - {@link rtvref.types.CLASS_OBJECT CLASS_OBJECT}
*
* @name rtvref.types.objTypes * @name rtvref.types.objTypes
* @type {rtvref.Enumeration} * @type {rtvref.Enumeration}
*/ */
...@@ -1227,8 +1231,24 @@ export const objTypes = new Enumeration(function() { ...@@ -1227,8 +1231,24 @@ export const objTypes = new Enumeration(function() {
}(), 'objTypes'); }(), 'objTypes');
/** /**
* Enumeration (`string -> string`) of {@link rtvref.types types} that accept * Enumeration (`string -> string`) of types that accept arguments:
* arguments. *
* - {@link rtvref.types.STRING STRING}
* - {@link rtvref.types.SYMBOL SYMBOL}
* - {@link rtvref.types.NUMBER NUMBER}
* - {@link rtvref.types.FINITE FINITE}
* - {@link rtvref.types.INT INT}
* - {@link rtvref.types.SAFE_INT SAFE_INT}
* - {@link rtvref.types.FLOAT FLOAT}
* - {@link rtvref.types.ARRAY ARRAY}
* - {@link rtvref.types.ANY_OBJECT ANY_OBJECT}
* - {@link rtvref.types.OBJECT OBJECT}
* - {@link rtvref.types.PLAIN_OBJECT PLAIN_OBJECT}
* - {@link rtvref.types.CLASS_OBJECT CLASS_OBJECT}
* - {@link rtvref.types.HASH_MAP HASH_MAP}
* - {@link rtvref.types.MAP MAP}
* - {@link rtvref.types.SET SET}
*
* @name rtvref.types.argTypes * @name rtvref.types.argTypes
* @type {rtvref.Enumeration} * @type {rtvref.Enumeration}
*/ */
...@@ -1243,7 +1263,35 @@ export const argTypes = new Enumeration(function() { ...@@ -1243,7 +1263,35 @@ export const argTypes = new Enumeration(function() {
}(), 'argTypes'); }(), 'argTypes');
/** /**
* Enumeration (`string -> string`) of all {@link rtvref.types types}. * Enumeration (`string -> string`) of all types:
*
* - {@link rtvref.types.ANY ANY}
* - {@link rtvref.types.NULL NULL}
* - {@link rtvref.types.STRING STRING}
* - {@link rtvref.types.BOOLEAN BOOLEAN}
* - {@link rtvref.types.SYMBOL SYMBOL}
* - {@link rtvref.types.NUMBER NUMBER}
* - {@link rtvref.types.FINITE FINITE}
* - {@link rtvref.types.INT INT}
* - {@link rtvref.types.SAFE_INT SAFE_INT}
* - {@link rtvref.types.FLOAT FLOAT}
* - {@link rtvref.types.FUNCTION FUNCTION}
* - {@link rtvref.types.REGEXP REGEXP}
* - {@link rtvref.types.DATE DATE}
* - {@link rtvref.types.ERROR ERROR}
* - {@link rtvref.types.PROMISE PROMISE}
* - {@link rtvref.types.ARRAY ARRAY}
* - {@link rtvref.types.ANY_OBJECT ANY_OBJECT}
* - {@link rtvref.types.OBJECT OBJECT}
* - {@link rtvref.types.PLAIN_OBJECT PLAIN_OBJECT}
* - {@link rtvref.types.CLASS_OBJECT CLASS_OBJECT}
* - {@link rtvref.types.HASH_MAP HASH_MAP}
* - {@link rtvref.types.MAP MAP}
* - {@link rtvref.types.WEAK_MAP WEAK_MAP}
* - {@link rtvref.types.SET SET}
* - {@link rtvref.types.WEAK_SET WEAK_SET}
* - {@link rtvref.types.JSON JSON}
*
* @name rtvref.types.types * @name rtvref.types.types
* @type {rtvref.Enumeration} * @type {rtvref.Enumeration}
*/ */
......
...@@ -5,14 +5,13 @@ ...@@ -5,14 +5,13 @@
// this library. // this library.
/** /**
* RTV Utilities Module * <h3>RTV.js Utilities</h3>
* @private * @namespace rtvref.util
* @namespace rtv.util
*/ */
/** /**
* Pretty-print a value. * Pretty-print a value.
* @function rtv.util.print * @function rtvref.util.print
* @param {*} printValue Value to print. * @param {*} printValue Value to print.
* @returns {string} Pretty-printed value. It's not perfect and may not catch * @returns {string} Pretty-printed value. It's not perfect and may not catch
* all types, but attempts to be good enough. * all types, but attempts to be good enough.
......
...@@ -2,6 +2,11 @@ ...@@ -2,6 +2,11 @@
import types from '../types'; import types from '../types';
/**
* Validation Module: isAny
* @typedef {Module} rtvref.validation.isAny
*/
/** /**
* Type: {@link rtvref.types.ANY ANY} * Type: {@link rtvref.types.ANY ANY}
* @const {string} rtvref.validation.isAny.type * @const {string} rtvref.validation.isAny.type
......
...@@ -4,6 +4,11 @@ import {default as _isObject} from 'lodash/isObject'; ...@@ -4,6 +4,11 @@ import {default as _isObject} from 'lodash/isObject';
import types from '../types'; import types from '../types';
/**
* Validation Module: isAnyObject
* @typedef {Module} rtvref.validation.isAnyObject
*/
/** /**
* Type: {@link rtvref.types.ANY_OBJECT ANY_OBJECT} * Type: {@link rtvref.types.ANY_OBJECT ANY_OBJECT}
* @const {string} rtvref.validation.isAnyObject.type * @const {string} rtvref.validation.isAnyObject.type
......
...@@ -4,6 +4,11 @@ import {default as _isArray} from 'lodash/isArray'; ...@@ -4,6 +4,11 @@ import {default as _isArray} from 'lodash/isArray';
import types from '../types'; import types from '../types';
/**