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

README.md

 # 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
 
@@ -31,12 +31,9 @@ Shapes must be:
 
 # 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
 - [ ] Add Gitlab CI config, or use TravisCI?
 - [ ] Publish to npm
-    - [ ] Add `.npmignore`
 - [ ] Make sure 'Goals' section is complete and accurate, add some links
 - [ ] Make sure `CONTRIBUTING.md` is filled-out
 

package.json

@@ -20,7 +20,7 @@
     "node:internals": "rollup -c tools/rollup.internals.js && node -r ./dist_tools/internals.js --inspect",
     "build:lib": "BABEL_ENV=build rollup -c",
     "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\"",
     "test:unit": "BABEL_ENV=test mocha -c -r mocha-setup.js \"./test/**/*.test.js\"",
     "test:unit:watch": "npm run test:unit -- -w",

src/lib/impl.js

@@ -11,7 +11,7 @@ import isBoolean from './validation/isBoolean';
 import isTypeset from './validation/isTypeset';
 import isShape from './validation/isShape';
 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_QUALIFIER, default as qualifiers} from './qualifiers';
@@ -20,7 +20,7 @@ import RtvSuccess from './RtvSuccess';
 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}
  *  API, as well as utilities for {@link rtvref.validator type validators}.
@@ -220,7 +220,7 @@ const fullyQualify = function(typeset, qualifier) {
     }
 
     // if a validator, it has an implied type of ANY
-    if (isValidator(typeset)) {
+    if (isCustomValidator(typeset)) {
       return [qualifier, types.ANY, typeset];
     }
 
@@ -255,7 +255,7 @@ const fullyQualify = function(typeset, qualifier) {
     } else if (isTypeArgs(rule)) {
       // args for curType since typeset is an array and object is not in first position
       fqts.push(rule);
-    } else if (isValidator(rule)) {
+    } else if (isCustomValidator(rule)) {
       // validator: ANY is implied type if none specified
       if (!curType) {
         curType = types.ANY;
@@ -396,8 +396,8 @@ const extractNextType = function(typeset, qualifier) {
  *  should be attributed to the subtype rather than the
  *  {@link rtvref.qualifiers.DEFAULT_QUALIFIER default qualifier}.
  * @see {@link rtvref.impl.check}
- * @see {@link rtvref.impl.checkShape}
- * @see {@link rtvref.impl.checkType}
+ * @see {@link rtvref.impl.checkWithShape}
+ * @see {@link rtvref.impl.checkWithType}
  */
 
 /**
@@ -412,8 +412,8 @@ const extractNextType = function(typeset, qualifier) {
  *  returned may contain references to objects in `given` depending on property
  *  types.
  * @see {@link rtvref.impl.check}
- * @see {@link rtvref.impl.checkShape}
- * @see {@link rtvref.impl.checkType}
+ * @see {@link rtvref.impl.checkWithShape}
+ * @see {@link rtvref.impl.checkWithType}
  * @throws {Error} If `current.path` or `override.path` is specified and not an array.
  */
 const _getCheckOptions = function(current = {}, override = {}) {
@@ -444,7 +444,7 @@ const _getCheckOptions = function(current = {}, override = {}) {
 
 /**
  * Checks a value using a single type.
- * @function rtvref.impl.checkType
+ * @function rtvref.impl.checkWithType
  * @param {*} value Value to check.
  * @param {rtvref.types.typeset} singleType Either a simple type name (one of
  *  {@link rtvref.types.types}), a {@link rtvref.types.shape_descriptor shape descriptor},
@@ -523,7 +523,7 @@ const checkWithType = function(value, singleType /*, options*/) {
 /**
  * Checks a value using a {@link rtvref.types.shape_descriptor shape descriptor} and
  *  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
  *  {@link rtvref.types.DEFAULT_OBJECT_TYPE default} object type.
  * @param {Object} shape Expected shape of the `value`. Must be an
@@ -546,27 +546,28 @@ const checkWithShape = function(value, shape /*, options*/) {
 
 /**
  * Checks a value using an Array typeset.
- * @function rtvref.impl.checkTypeset
+ * @function rtvref.impl.checkWithArray
  * @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`
  *  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.
  */
 // @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);
 
   // check for an array first since that's must faster than isTypeset()
-  if (!isArray(typeset) || !(options.isTypeset || isTypeset(typeset))) {
-    throw new Error(`Invalid Array typeset=${print(typeset)}`);
+  if (!isArray(array) || !(options.isTypeset || isTypeset(array))) {
+    throw new Error(`Invalid typeset in array=${print(array)}`);
   }
 
   options.isTypeset = true;
 
   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
   // NOTE: an Array typeset represents multiple possibilities for a type match
@@ -574,18 +575,18 @@ const checkWithArray = function(value, typeset /*, options*/) {
   // 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
   //  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
   while (subtype.length > 0) {
     // 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
-    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
       //  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,
       //  which matches any value
       // 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);
       }
 
@@ -611,19 +612,19 @@ const checkWithArray = function(value, typeset /*, options*/) {
 
   if (match) {
     // check for a validator at the end of the Array typeset and invoke it
-    const lastType = typeset[typeset.length - 1];
-    if (isValidator(lastType)) {
+    const lastType = array[array.length - 1];
+    if (isCustomValidator(lastType)) {
       try {
-        lastType(value, match, typeset);
+        lastType(value, match, array);
       } catch (cvErr) {
         // 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 {
     // 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());
@@ -652,7 +653,7 @@ const check = function(value, typeset /*, options*/) {
         return checkWithType(value, typeset, options);
       }
 
-      if (isValidator(typeset)) {
+      if (isCustomValidator(typeset)) {
         // custom validator: bare function implies the ANY type
         const match = types.ANY;
         const fqMatch = fullyQualify(match, options.qualifier);

src/lib/lib.jsdoc

+/**
+ * <h3>RTV.js Reference</h3>
+ *
+ * Members herein are _indirectly_ accessed and/or exposed through the
+ *  {@link rtv RTV.js Public Interface}.
+ *
+ * @namespace rtvref
+ */

src/lib/qualifiers.js

@@ -3,7 +3,7 @@
 import Enumeration from './Enumeration';
 
 /**
- * <h2>Qualifiers</h2>
+ * <h3>Qualifiers</h3>
  *
  * Qualifiers determine the degree at which a value must be of a given type.
  *
@@ -93,7 +93,7 @@ export const DEFAULT_QUALIFIER = REQUIRED;
  * - EXPECTED: Can be `null`.
  * - OPTIONAL: Can be either `undefined` or `null`.
  *
- * @function rtvref.qualifiers.checkBasicRules
+ * @function rtvref.qualifiers.nilPermitted
  * @param {*} v Value to check.
  * @param {string} [q] Validation qualifier. Defaults to
  *  {@link rtvref.qualifiers.REQUIRED 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
  * @type {rtvref.Enumeration}
  */

src/lib/types.js

@@ -3,7 +3,7 @@
 import Enumeration from './Enumeration';
 
 /**
- * <h2>Types</h2>
+ * <h3>Types</h3>
  * @namespace rtvref.types
  */
 
@@ -23,7 +23,7 @@ import Enumeration from './Enumeration';
  *   it produces an {@link rtvref.types.OBJECT object}, and __should be avoided__).
  * - `Symbol`
  *
- * @typedef {*} rtvref.types.primitives
+ * @typedef {void} rtvref.types.primitives
  * @see {@link rtvref.validation.isPrimitive}
  */
 
@@ -39,7 +39,7 @@ import Enumeration from './Enumeration';
  *  the qualifier used is `EXPECTED`; and it could be `undefined` if the qualifier
  *  used is `OPTIONAL`.
  *
- * @typedef {*} rtvref.types.rules
+ * @typedef {void} rtvref.types.qualifier_rules
  */
 
 /**
@@ -85,7 +85,7 @@ import Enumeration from './Enumeration';
  *  of at least 5 characters in length.
  *
  * 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}]`
  *  would fail to validate an empty string because the _implied_ qualifier
  *  is `REQUIRED`, and per {@link rtvref.types.STRING STRING} qualifier rules,
@@ -386,7 +386,7 @@ import Enumeration from './Enumeration';
  *  over network requests, perhaps embedded in JSON payloads, similar to
  *  {@link https://json-ld.org/ JSON-LD} schemas.
  *
- * <h4>Example: Object</h4>
+ * <h4>Typeset Example: Object</h4>
  *
  * <pre><code>const contactShape = {
  *   name: rtv.t.STRING, // required, non-empty, string
@@ -429,20 +429,20 @@ import Enumeration from './Enumeration';
  * }, walletShape); // OK
  * </code></pre>
  *
- * <h4>Example: String</h4>
+ * <h4>Typeset Example: String</h4>
  *
  * <pre><code>rtv.verify('foo', rtv.t.STRING); // OK
  * rtv.verify('foo', rtv.t.FINITE); // ERROR
  * </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
  * rtv.verify('foo', typeset); // OK
  * rtv.verify(1, typeset); // OK
  * </code></pre>
  *
- * <h4>Example: Function</h4>
+ * <h4>Typeset Example: Function</h4>
  *
  * <pre><code>const validator = (v) => {
  *   if (v % 10) {
@@ -454,7 +454,7 @@ import Enumeration from './Enumeration';
  * rtv.verify(120, [rtv.t.INT, validator]); // OK
  * </code></pre>
  *
- * <h4>Example: Alternate Qualifier</h4>
+ * <h4>Typeset Example: Alternate Qualifier</h4>
  *
  * <pre><code>const person = {
  *   name: rtv.t.STRING, // required, non-empty
@@ -544,7 +544,7 @@ import Enumeration from './Enumeration';
  *  {@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
  *  will help the developer determine why the custom validation failed.
- * @see {@link rtvref.validation.isValidator}
+ * @see {@link rtvref.validation.isCustomValidator}
  */
 
 // Creates a definition object.
@@ -713,7 +713,7 @@ const defs = {
    *
    * Arguments (optional): {@link rtvref.types.numeric_args}
    *
-   * @name rtvref.types.INT
+   * @name rtvref.types.SAFE_INT
    * @const {string}
    * @see {@link rtvref.qualifiers}
    * @see {@link rtvref.types.NUMBER}
@@ -809,7 +809,7 @@ const defs = {
    *  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.
    *
-   * <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.
    *
@@ -824,7 +824,7 @@ const defs = {
    *  to indicate what could be the equivalent: `[[]]`. The inner Array typeset
    *  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
    *  any value.
@@ -834,7 +834,7 @@ const defs = {
    * }
    * </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
    *  finite numbers of any value, or non-empty strings, or a mix of both.
@@ -844,7 +844,7 @@ const defs = {
    * }
    * </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.
    *
@@ -853,7 +853,7 @@ const defs = {
    * }
    * </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
    *  any value (nested typeset is not fully-qualified).
@@ -863,7 +863,7 @@ const defs = {
    * }
    * </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
    *  finite numbers of any value, or non-empty strings, or a mix of both
@@ -1210,9 +1210,13 @@ const defs = {
 export const DEFAULT_OBJECT_TYPE = defs.OBJECT.value;
 
 /**
- * Enumeration (`string -> string`) of __object__ {@link rtvref.types types}. These
- *  are all the types that describe values which are essentially maps of various
- *  keys to values.
+ * Enumeration (`string -> string`) of __object__ types:
+ *
+ * - {@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
  * @type {rtvref.Enumeration}
  */
@@ -1227,8 +1231,24 @@ export const objTypes = new Enumeration(function() {
 }(), 'objTypes');
 
 /**
- * Enumeration (`string -> string`) of {@link rtvref.types types} that accept
- *  arguments.
+ * Enumeration (`string -> string`) of types that accept 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
  * @type {rtvref.Enumeration}
  */
@@ -1243,7 +1263,35 @@ export const argTypes = new Enumeration(function() {
 }(), '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
  * @type {rtvref.Enumeration}
  */

src/lib/util.js

@@ -5,14 +5,13 @@
 //  this library.
 
 /**
- * RTV Utilities Module
- * @private
- * @namespace rtv.util
+ * <h3>RTV.js Utilities</h3>
+ * @namespace rtvref.util
  */
 
 /**
  * Pretty-print a value.
- * @function rtv.util.print
+ * @function rtvref.util.print
  * @param {*} printValue Value to print.
  * @returns {string} Pretty-printed value. It's not perfect and may not catch
  *  all types, but attempts to be good enough.

src/lib/validation/isAny.js

@@ -2,6 +2,11 @@
 
 import types from '../types';
 
+/**
+ * Validation Module: isAny
+ * @typedef {Module} rtvref.validation.isAny
+ */
+
 /**
  * Type: {@link rtvref.types.ANY ANY}
  * @const {string} rtvref.validation.isAny.type

src/lib/validation/isAnyObject.js

@@ -4,6 +4,11 @@ import {default as _isObject} from 'lodash/isObject';
 
 import types from '../types';
 
+/**
+ * Validation Module: isAnyObject
+ * @typedef {Module} rtvref.validation.isAnyObject
+ */
+
 /**
  * Type: {@link rtvref.types.ANY_OBJECT ANY_OBJECT}
  * @const {string} rtvref.validation.isAnyObject.type

src/lib/validation/isArray.js

@@ -4,6 +4,11 @@ import {default as _isArray} from 'lodash/isArray';
 
 import types from '../types';
 
+/**