@lumjs/core 1.21.0 → 1.23.0

package/lib/types/isa.js

@@ -1,9 +1,13 @@
+"use strict";
+
 const {O, F, S} = require('./js');
-const {isObj,isArray} = require('./basics');
+const {isObj,isArray,isIterable,notNil} = require('./basics');
 const TYPES = require('./typelist');
+const def = require('./def');
 
 /**
  * See if a value is an instance of a class.
+ * @deprecated Just use `instanceof` directly, this function is unnecessary.
  * @param {*} v - The value we're testing.
  * @param {function} f - The constructor/class we want.
  * @param {boolean} [needProto=false] If true, the `v` must have a `prototype`.
@@ -23,7 +27,7 @@ function isInstance(v, f, needProto=false)
   // Everything passed.
   return true;
 }
- 
+
 exports.isInstance = isInstance;
 
 /**
@@ -38,6 +42,7 @@ exports.isInstance = isInstance;
  * this function does not count `null` as a valid `object`. 
  * 
  * @param {*} v - The value we're testing. 
+ * 
  * @returns {boolean} If the value was of the desired type.
  * @alias module:@lumjs/core/types.isType
  */
@@ -52,12 +57,12 @@ function isType(type, v)
   { // A type-specific test.
     return TYPES.tests[type](v);
   }
-  else 
+  else
   { // No type-specific tests.
     return (typeof v === type);
   }
 }
- 
+
 exports.isType = isType;
 
 // Default options parser.
@@ -127,7 +132,8 @@ function processOptions(type, v)
  * @param {...any} types - The types the value should be one of.
  * 
  * For each of the `types`, by default if it is a `string` 
- * we test with `isType()`, if it is a `function` we test with `isInstance()`.
+ * we test with `isType()`, if it is a `function` we see if `v`
+ * is either an instance of the type or a sub-class of it.
  * 
  * If it is an `object` and has an `is()` method, use that as the test.
  * 
@@ -138,9 +144,9 @@ function processOptions(type, v)
  *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
  *  - `parsers: function`, Add another options parser function.
  *  - `process: function`, A one-time set-up function.
- *  - `test: function`, Pass the `v` to this test and return `true` if it passes.
- *  - `typeof: boolean`, If `true` use `typeof` instead of `isType()` for tests.
- *  - `instanceof: boolean`, If `true` use `instanceof` instead of `isInstance()`.
+ *  - `test: function`, Pass the `v` to this and return `true` if it passes.
+ *  - `instanceof: boolean`, If `true` use `instanceof` *instead of* `isInstance()`.
+ *     As of version `1.22`, this defaults to `true`.
  *  - Anything else will be set as an option that may be used by other parsers.
  * 
  * Any other type value will only match if `v === type`
@@ -156,8 +162,7 @@ function isa(v, ...types)
     needProto: false,
     parsers: [DEFAULT_ISA_PARSER],
     process: processOptions,
-    typeof: false,
-    instanceof: false,
+    instanceof: true,
   }
 
   for (const type of types)
@@ -168,13 +173,25 @@ function isa(v, ...types)
     // With that out of the way, let's go!
     if (typeof type === S)
     { // A string is passed to isType()
-      if (opts.typeof && typeof v === type) return true;
       if (isType(type, v)) return true;
     }
     else if (typeof type === F)
     { // A function is passed to isInstance()
-      if (opts.instanceof && v instanceof type) return true;
-      if (isInstance(v, type, opts.needProto)) return true;     
+      if (typeof v === F)
+      { // See if it is a sub-class.
+        if (type.isPrototypeOf(v)) return true;
+      }
+      else
+      { // See if it is an instance.
+        if (opts.instanceof)
+        { // Simple test, is default now.
+          if (v instanceof type) return true;
+        }
+        else
+        { // Old test, will be removed in the future.
+          if (isInstance(v, type, opts.needProto)) return true;
+        }
+      }
     }
     else if (isObj(type))
     { // Objects can be additional tests, or options.
@@ -189,128 +206,583 @@ function isa(v, ...types)
 exports.isa = isa;
 
 /**
- * Extended return value from `isArrayOf()`.
+ * Extended return value from any test powered by the `OfTest` class.
  * 
- * Used if the `opts.details` option was `true`.
+ * Used if `rules.details` was set to `true`.
  * 
- * @typedef module:@lumjs/core/types~IsArrayOfResult
+ * @typedef module:@lumjs/core/types.OfTestResult
  * 
- * @prop {boolean} pass - Did the `isArrayOf()` test pass?
- * @prop {boolean} empty - Was the array empty?
+ * @prop {boolean} pass  - Did the test pass?
+ * @prop {boolean} empty - Was the list empty?
  * 
  * @prop {object} [failed] Failure information;
- * Only addedd if `pass` is false.
+ * Only addedd if `pass` is `false`.
  * 
- * @prop {number} failed.index - Index of item that caused the failure.
- * Will be set to `-1` if the `opts.value` argument is not an Array, 
- * or if the array is empty and `opts.empty` was not set to `true`.
- * 
- * @prop {mixed} failed.value - The item that caused the failure.
- * Will be the `opts.value` itself if `failed.index` is `-1`.
+ * Will be the {@link module:@lumjs/core/types.OfTest.state.at}
+ * property from the underlying `OfTest` instance.
+ * See the documentation for that property for further details.
  * 
  */
 
 /**
- * See if every item in an Array passes an `isa()` test.
+ * A special class used for testing the contents of containers.
  * 
- * @param {(object|Array)} opts - Options for this test function.
+ * Used by the `is[List|Array|Map]Of()` methods, this class
+ * abstracts out most of the common functionality of those tests.
+ *
+ * @alias module:@lumjs/core/types.OfTest
  * 
- * If this argument is an `Array` it is assumed to be the
- * `opts.value` named option.
+ * @prop {boolean} valid - Does `rules.value` pass the validity test?
+ * @prop {object}  rules - Rules passed to the constructor.
+ * @prop {object}  state - Contains the current state of the tests.
+ * @prop {Array}   vtype - Value type tests.
+ * @prop {?Array}  ktype - Key/index type tests; `null` if unused.
  * 
- * @param {Array} opts.value - The actual Array value to test.
- * @param {boolean} [opts.details=false] Return detailed test results?
- * @param {boolean} [opts.empty=false] Does an empty array pass the test?
+ * @prop {mixed} target  - An alias to the `rules.value` property.
  * 
- * @param  {...any} types - See {@link module:@lumjs/core/types.isa}.
+ * @prop {mixed} rules.value - Should be the container we are testing.
+ * May be `null` if no valid `rules` were passed.
  * 
- * All arguments other than `opts` are passed to `isa()` with each item
- * from the `opts.value` array as the subject of the test.
+ * @prop {boolean} [rules.details=false] Use detailed result objects?
  * 
- * @returns {(boolean|object)} Results of the test.
+ * If `true` the `pass` and `fail` dynamic result properties will return
+ * {@link module:@lumjs/core/types.OfTestResult} objects. 
+ * 
+ * If `false` (default), the results will be simple `boolean` values.
+ * 
+ * @prop {boolean} [rules.empty=false] Are empty containers valid?
  * 
- * If `opts.details` was `true` this will be a
- * {@link module:@lumjs/core/types~IsArrayOfResult} object.
+ * Determines the return value of the `empty()` method.
+ * 
+ * Should be used by the calling test function to determine if the
+ * test should return a `pass` or `fail` value on an empty container.
  *
- * Otherwise it will be a simple `boolean` value indicating
- * if the test passed or failed.
+ * @prop {boolean} state.empty - Has the container been marked empty?
  * 
- * @alias module:@lumjs/core/types.isArrayOf
+ * @prop {object} state.at - Info about the last value tested.
+ * Will be used as the `failed` property in the `OfTestResult` object.
+ * 
+ * @prop {mixed} state.at.index - Index/Key of the last value tested.
+ * 
+ * For `isArrayOf()` and `isListOf()` this will always be a `number`.
+ * 
+ * For `isMapOf()` this will be set to the _key_ of each item in the map,
+ * and so may be any type of value. 
+ * 
+ * This will be set to `-1` if no value has been tested yet,
+ * which will always be the case for empty or invalid containers.
+ * 
+ * @prop {mixed} state.at.value - The last value that was tested.
+ * 
+ * Will be the `rules.value` itself if no value has been tested yet,
+ * which will always be the case for empty or invalid containers.
+ * 
+ * @prop {boolean} [state.at.key] Was it the key test that failed?
+ * Only included if `ktype` is not `null`.
  */
-function isArrayOf(opts, ...types)
+class OfTest
 {
-  if (!isObj(opts)) return false; // Failure right off the bat!
+  /**
+   * Create an `OfTest` instance. 
+   * 
+   * Unless you are creating a custom test function similar to the built-in
+   * `is*Of()` methods you'll never need to create an instance of this.
+   * It's documented here for the potential of advanced tests.
+   * 
+   * @param {function} valid - A validity test for the `rules.value`.
+   * 
+   * This will be used to set the value of the `this.valid` property.
+   * 
+   * @param {object} rules - Object to set as the `this.rules` property.
+   * 
+   * If `valid(rules)` returns `true` then the `rules` will be 
+   * changed to `{value: rules}`. This is a short-cut so that
+   * the containers can be passed directly if default rules are okay.
+   * 
+   * If this is NOT an object, then the `rules` will be changed to
+   * `{value: null}`, which should ensure that `this.valid` is `false`.
+   * 
+   * See the class property description for the supported optional values.
+   * 
+   * @param {object} rules.value - The container being tested.
+   * 
+   * @param {?Array} valueTypes - An array of type tests for the values.
+   * 
+   * Will be set as the `this.vtype` property.
+   *
+   * If `null` (only applicable if `keyTypes` is NOT `null`), then the
+   * value type tests will be skipped.
+   * 
+   * See {@link module:@lumjs/core/types.isa} for details on the tests.
+   * 
+   * @param {?Array} [keyTypes=null] Array of type tests for the _key/index_.
+   * 
+   * Will be set as the `this.ktype` property.
+   * 
+   * Uses `isa()` just like `valueTypes`. Is only needed in very specific
+   * cases, such as `isMapOf()` as `Map` objects may have any kind of key.
+   * If `null` (default), no tests against the keys will be done.
+   * 
+   * @throws {TypeError} If any of the parameters is not valid.
+   * @throws {RangeError} If both `valueTypes` and `keyTypes` are `null`.
+   * 
+   */
+  constructor(valid, rules, valueTypes, keyTypes=null)
+  {
+    if (typeof valid !== F)
+    {
+      throw new TypeError("Invalid OfTest validator");
+    }
 
-  if (Array.isArray(opts))
-  { // The array subject was passed.
-    opts = {value: opts};
-  }
+    if (valueTypes !== null && !isArray(valueTypes))
+    {
+      throw new TypeError("Invalid valueTypes array");
+    }
 
-  let res; // Format depends on the options.
+    if (keyTypes !== null && !isArray(keyTypes))
+    {
+      throw new TypeError("Invalid keyTypes array");
+    }
 
-  if (opts.details)
-  {
-    res = 
+    if (valueTypes === null && keyTypes === null)
+    {
+      throw new RangeError("Both valueTypes and keyTypes are null");
+    }
+
+    if (valid(rules))
+    { // The container was sent instead of rules.
+      rules = {value: rules};
+      this.valid = true;
+    }
+    else if (isObj(rules))
+    {
+      this.valid = valid(rules.valid);
+    }
+    else
+    { // That's gonna be a no from me.
+      rules = {value: null};
+      this.valid = false;
+    }
+
+    this.vtype = valueTypes;
+    this.ktype = keyTypes;
+    this.rules = rules;
+    this.state =
     {
-      pass: false,
       empty: false,
-      failed:
+      at:
       {
         index: -1,
-        value: val,
+        value: rules.value,
+      },
+    }
+
+    if (keyTypes !== null)
+    {
+      this.state.at.key = false;
+    }
+
+    // A shortcut for tests.
+    this.target = rules.value;
+
+  } // constructor()
+
+  /**
+   * Run `isa()` tests on the next item.
+   * 
+   * @param {*} key - `state.at.index` will be set to this
+   * 
+   * If `this.ktype` was set (via the `keyTypes` constructor argument),
+   * then the `key` will be tested for validity against those tests using
+   * the `isa()` function.
+   * 
+   * @param {*} val - `state.at.value` will be set to this
+   * 
+   * The `val` will be tested for validity against the `this.vtype` tests
+   * (via the `valueTests` constructor argument) using the `isa()` function.
+   * 
+   * @returns {boolean} Was the `val` (and the `key` if applicable) valid?
+   */
+  test(key, val)
+  {
+    this.state.at.index = key;
+    this.state.at.value = val;
+
+    if (this.ktype)
+    {
+      const keyOk = isa(key, ...this.ktype);
+      if (!keyOk)
+      {
+        this.state.at.key = true;
+        return false;
       }
     }
+
+    return isa(val, ...this.vtype);
   }
-  else
+
+  /**
+   * Mark `this.state.empty` as `true`
+   * 
+   * @returns {boolean} `this.rules.empty`;
+   * determines if the test should be considered a `pass` or `fail`
+   * upon being marked `empty`.
+   */
+  empty()
   {
-    res = false;
+    this.state.empty = true;
+    return !!this.rules.empty;
   }
 
-  if (!isArray(opts.value)) return res;
+  /**
+   * A dynamic getter property that returns a _passed_ test result.
+   * @returns {(object|boolean)} Depends on `this.rules.details` value.
+   */
+  get pass()
+  {
+    if (this.rules.details)
+    {
+      const empty = this.state.empty;
+      return {pass: true, empty};
+    }
+
+    return true;
+  }
 
-  if (opts.value.length === 0)
-  { // An empty array.
-    if (opts.details)
+  /**
+   * A dynamic getter property that returns a _failed_ test result.
+   * @returns {(object|boolean)} Depends on `this.rules.details` value.
+   */
+  get fail()
+  {
+    if (this.rules.details)
     {
-      res.empty = true;
+      const {empty, at: failed} = this.state;
+      return {pass: false, empty, failed};
     }
 
-    if (!opts.empty)
-    { // Empty arrays are failure unless `opts.empty` is true.
-      return res;
+    return false;
+  }
+
+}
+
+exports.OfTest = OfTest;
+
+/**
+ * A nested class representing an explicit set of rules for `OfTest`.
+ * 
+ * Not really needed for anything except for `isPlainObjectOf()` function.
+ * 
+ * @alias module:@lumjs/core/types.OfTest.Rules
+ */
+class OfTestRules
+{
+  /**
+   * Define the Rules
+   * 
+   * @param {mixed} value - Sets `rules.value`
+   * @param {object} [opts] Optional rules
+   * @param {boolean} [opts.empty=false] Sets `rules.empty`
+   * @param {boolean} [opts.details=false] Sets `rules.details`
+   *  
+   */
+  constructor(value, opts)
+  {
+    this.value   = value;
+    this.empty   = opts.empty   ?? false;
+    this.details = opts.details ?? false;
+  }
+}
+
+def(OfTest, 'Rules', OfTestRules);
+
+/**
+ * See if every item in an `Array` passes an `isa()` test.
+ * 
+ * Uses the {@link module:@lumjs/core/types.OfTest} class.
+ * This implementation works explicitly with `Array` objects only.
+ * 
+ * @param {(object|Array)} rules - Rules for this test function.
+ * 
+ * If this argument is an `Array` it is assumed to be the
+ * `rules.value` named option.
+ * 
+ * @param {Array} rules.value - The actual Array object to test.
+ * 
+ * @param  {...any} types - See {@link module:@lumjs/core/types.isa}.
+ * 
+ * All arguments other than `rules` are passed to `isa()` with each item
+ * from the `rules.value` object as the subject of the test.
+ * 
+ * @returns {(boolean|object)} Results of the test.
+ * 
+ * If `rules.details` was `true` this will be a
+ * {@link module:@lumjs/core/types~OfTestResult} object.
+ *
+ * Otherwise it will be a simple `boolean` value indicating
+ * if the test passed or failed.
+ * 
+ * @alias module:@lumjs/core/types.isArrayOf
+ */
+function isArrayOf(rules, ...types)
+{
+  // Build an OfTest instance.
+  const test = new OfTest(isArray, rules, types);
+
+  if (!test.valid) 
+  { // Test was invalid right off the bat.
+    return test.fail;
+  }
+
+  const target = test.target;
+
+  if (target.length === 0)
+  { // Array is empty.
+    if (!test.empty())
+    { // `opts.empty` was not `true`
+      return test.fail;
     }
   }
   else
   { // Run the tests on each item.
-    for (let i=0; i < opts.value.length; i++)
+    for (let i=0; i < target.length; i++)
     {
-      const vi = opts.value[i];
-  
-      if (opts.details)
-      {
-        res.failed.index = i;
-        res.failed.value = vi;
-      }
-  
-      if (!isa(vi, ...types))
-      { // An item did not pass the test.
-        return res;
+      if (!test.test(i, target[i]))
+      { // The test failed.
+        return test.fail;
       }
     }
   }
 
   // If we made it here, we passed.
-  if (opts.details)
+  return test.pass;
+}
+
+exports.isArrayOf = isArrayOf;
+
+/**
+ * See if every item in an Iterable list passes an `isa()` test.
+ * 
+ * Uses the {@link module:@lumjs/core/types.OfTest} class.
+ * This implementation works with any kind of `Iterable` object.
+ * 
+ * @param {(object|Iterable)} rules - Rules for this test function.
+ * 
+ * If this argument is an `Iterable` object it is assumed to be the
+ * `rules.value` named option.
+ * 
+ * @param {Iterable} rules.value - The actual list object for the tests.
+ * 
+ * @param  {...any} types - See {@link module:@lumjs/core/types.isa}.
+ * 
+ * All arguments other than `rules` are passed to `isa()` with each item
+ * from the `rules.value` object as the subject of the test.
+ * 
+ * @returns {(boolean|object)} Results of the test.
+ * 
+ * If `rules.details` was `true` this will be a
+ * {@link module:@lumjs/core/types~OfTestResult} object.
+ *
+ * Otherwise it will be a simple `boolean` value indicating
+ * if the test passed or failed.
+ * 
+ * @alias module:@lumjs/core/types.isListOf
+ */
+function isListOf(rules, ...types)
+{
+  // Build an OfTest instance.
+  const test = new OfTest(isIterable, rules, types);
+
+  if (!test.valid) 
+  { // Test was invalid right off the bat.
+    return test.fail;
+  }
+
+  let i = 0;
+  for (const val of test.target)
   {
-    res.pass = true;
-    delete res.failed;
+    if (!test.test(i++, val))
+    { // The test failed.
+      return test.fail;
+    }
+  }
+
+  if (i === 0)
+  { // List was empty.
+    if (!test.empty())
+    { // `opts.empty` was not `true`
+      return test.fail;
+    }
+  }
+
+  // If we made it here, we passed.
+  return test.pass;
+}
+
+exports.isListOf = isListOf;
+
+const isMap = v => (v instanceof Map);
+
+/**
+ * See if every key/value pair in a Map passes an `isa()` test.
+ * 
+ * Uses the {@link module:@lumjs/core/types.OfTest} class.
+ * This implementation works with only `Map` objects.
+ * 
+ * Unlike `isArrayOf()` and `isListOf()`, this function does not
+ * have a variable argument list. It has only **3** arguments,
+ * and all of them are mandatory!
+ * 
+ * @param {(object|Map)} rules - Rules for this test function.
+ * 
+ * If this argument is a `Map` object it is assumed to be the
+ * `rules.value` named option.
+ * 
+ * @param {Map} rules.value - The actual list object for the tests.
+ * 
+ * @param  {?Array} keyTypes - Types the _keys_ must be one of.
+ * 
+ * If anything other than an `Array` or `null` is passed here, 
+ * it will be wrapped in an `Array`.
+ * 
+ * @param {?Array} valTypes - Types the _values_ must be one of.
+ * 
+ * If anything other than an `Array` or `null` is passed here, 
+ * it will be wrapped in an `Array`.
+ * 
+ * @returns {(boolean|object)} Results of the test.
+ * 
+ * If `rules.details` was `true` this will be a
+ * {@link module:@lumjs/core/types~OfTestResult} object.
+ *
+ * Otherwise it will be a simple `boolean` value indicating
+ * if the test passed or failed.
+ * 
+ * @alias module:@lumjs/core/types.isListOf
+ */
+function isMapOf(rules, keyTypes, valTypes)
+{
+  if (notNil(keyTypes) && !isArray(keyTypes))
+  {
+    keyTypes = [keyTypes];
+  }
+
+  if (notNil(valTypes) && !isArray(valTypes))
+  {
+    valTypes = [valTypes];
+  }
+
+  const test = new OfTest(isMap, rules, valTypes, keyTypes);
+
+  if (!test.valid) 
+  { // Test was invalid right off the bat.
+    return test.fail;
+  }
+
+  if (test.target.size === 0)
+  { // Map is empty.
+    if (!test.empty())
+    { // `opts.empty` was not `true`
+      return test.fail;
+    }
   }
   else
   {
-    res = true;
+    for (const [key,val] of test.target)
+    {
+      if (!test.test(key,val))
+      {
+        return test.fail;
+      }
+    }
   }
 
-  return res;
+  // We made it, yay!
+  return test.pass;
 }
 
-exports.isArrayOf = isArrayOf;
+exports.isMapOf = isMapOf;
+
+const isntRules = v => (isObj(v) && !(v instanceof OfTestRules));
+
+/**
+ * See if all enumerable property values in an `object` pass an `isa()` test.
+ * 
+ * Uses the {@link module:@lumjs/core/types.OfTest} class.
+ * This implementation works with any _plain_ objects.
+ * 
+ * There is a special function called `rules(value, opts)` defined on this
+ * test function that will return an instance of the `OfTest.Rules` class,
+ * passing all parameters along to the constructor.
+ * 
+ * @param {object} rules - Rules for this test function.
+ * 
+ * If this argument is anything other than a `OfTest.Rules` instance,
+ * it is assumed to be the `rules.value` named option.
+ * 
+ * If you want to set any of the optional rules, you can use the `rules()`
+ * helper function mentioned above to return a `OfTest.Rules` instance:
+ * 
+ * ```js
+ * const opts = {details: true, empty: true}; // Example rules.
+ * const isValid = isObjOf(isObjOf.rules(value, opts), type1, type2, ...);
+ * ```
+ * 
+ * @param {Iterable} rules.value - The actual list object for the tests.
+ * 
+ * @param  {...any} types - See {@link module:@lumjs/core/types.isa}.
+ * 
+ * All arguments other than `rules` are passed to `isa()` with each item
+ * from the `rules.value` object as the subject of the test.
+ * 
+ * @returns {(boolean|object)} Results of the test.
+ * 
+ * If `rules.details` was `true` this will be a
+ * {@link module:@lumjs/core/types~OfTestResult} object.
+ *
+ * Otherwise it will be a simple `boolean` value indicating
+ * if the test passed or failed.
+ * 
+ * @alias module:@lumjs/core/types.isObjOf
+ */
+function isPlainObjectOf(rules, ...types)
+{
+  // Build an OfTest instance.
+  const test = new OfTest(isntRules, rules, types);
+
+  if (!test.valid) 
+  { // Test was invalid right off the bat.
+    return test.fail;
+  }
+
+  const target = test.target;
+  const keys = Object.keys(target);
+
+  if (keys.length === 0)
+  { // Object had no enumerable properties.
+    if (!test.empty())
+    { // `opts.empty` was not `true`
+      return test.fail;
+    }
+  }
+  else
+  { // There are properties to check.
+    for (const key of keys)
+    {
+      if (!test.test(key, target[key]))
+      { // The test failed.
+        return test.fail;
+      }
+    }
+  }
+
+  // If we made it here, we passed.
+  return test.pass;
+}
+
+def(isPlainObjectOf, 'rules', function()
+{
+  return new OfTestRules(...arguments);
+});
+
+exports.isObjOf = isPlainObjectOf;