@lumjs/core 1.19.0 → 1.20.0

package/lib/types/index.js

@@ -31,7 +31,7 @@ const
 const {root, unbound} = require('./root');
 
 // Advanced type checks.
-const {isInstance, isType, isa} = require('./isa');
+const {isInstance, isType, isArrayOf, isa} = require('./isa');
 
 // Error-throwing type checks.
 const {needObj, needType, needs} = require('./needs');
@@ -55,7 +55,7 @@ module.exports =
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
   isInstance, isType, isa, needObj, needType, needs, stringify,
-  doesDescriptorTemplate, ownCount,
+  doesDescriptorTemplate, ownCount, isArrayOf,
   console,
 }
 

package/lib/types/isa.js

@@ -1,5 +1,5 @@
 const {O, F, S} = require('./js');
-const {isObj} = require('./basics');
+const {isObj,isArray} = require('./basics');
 const TYPES = require('./typelist');
 
 /**
@@ -126,8 +126,8 @@ function processOptions(type, v)
  * @param {*} v - The value we're testing.
  * @param {...any} types - The types the value should be one of.
  * 
- * For each of the `types`, if it is a `string` we test with `isType()`,
- * if it is a `function` we test with `isInstance()`. 
+ * 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()`.
  * 
  * If it is an `object` and has an `is()` method, use that as the test.
  * 
@@ -139,7 +139,9 @@ function processOptions(type, v)
  *  - `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.
- *  - Anything else will be set as an option.
+ *  - `typeof: boolean`, If `true` use `typeof` instead of `isType()` for tests.
+ *  - `instanceof: boolean`, If `true` use `instanceof` instead of `isInstance()`.
+ *  - 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`
  * 
@@ -154,6 +156,8 @@ function isa(v, ...types)
     needProto: false,
     parsers: [DEFAULT_ISA_PARSER],
     process: processOptions,
+    typeof: false,
+    instanceof: false,
   }
 
   for (const type of types)
@@ -164,10 +168,12 @@ 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;     
     }
     else if (isObj(type))
@@ -181,3 +187,130 @@ function isa(v, ...types)
 }
 
 exports.isa = isa;
+
+/**
+ * Extended return value from `isArrayOf()`.
+ * 
+ * Used if the `opts.details` option was `true`.
+ * 
+ * @typedef module:@lumjs/core/types~IsArrayOfResult
+ * 
+ * @prop {boolean} pass - Did the `isArrayOf()` test pass?
+ * @prop {boolean} empty - Was the array empty?
+ * 
+ * @prop {object} [failed] Failure information;
+ * 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`.
+ * 
+ */
+
+/**
+ * See if every item in an Array passes an `isa()` test.
+ * 
+ * @param {(object|Array)} opts - Options for this test function.
+ * 
+ * If this argument is an `Array` it is assumed to be the
+ * `opts.value` named option.
+ * 
+ * @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?
+ * 
+ * @param  {...any} types - See {@link module:@lumjs/core/types.isa}.
+ * 
+ * All arguments other than `opts` are passed to `isa()` with each item
+ * from the `opts.value` array as the subject of the test.
+ * 
+ * @returns {(boolean|object)} Results of the test.
+ * 
+ * If `opts.details` was `true` this will be a
+ * {@link module:@lumjs/core/types~IsArrayOfResult} object.
+ *
+ * Otherwise it will be a simple `boolean` value indicating
+ * if the test passed or failed.
+ * 
+ * @alias module:@lumjs/core/types.isArrayOf
+ */
+function isArrayOf(opts, ...types)
+{
+  if (!isObj(opts)) return false; // Failure right off the bat!
+
+  if (Array.isArray(opts))
+  { // The array subject was passed.
+    opts = {value: opts};
+  }
+
+  let res; // Format depends on the options.
+
+  if (opts.details)
+  {
+    res = 
+    {
+      pass: false,
+      empty: false,
+      failed:
+      {
+        index: -1,
+        value: val,
+      }
+    }
+  }
+  else
+  {
+    res = false;
+  }
+
+  if (!isArray(opts.value)) return res;
+
+  if (opts.value.length === 0)
+  { // An empty array.
+    if (opts.details)
+    {
+      res.empty = true;
+    }
+
+    if (!opts.empty)
+    { // Empty arrays are failure unless `opts.empty` is true.
+      return res;
+    }
+  }
+  else
+  { // Run the tests on each item.
+    for (let i=0; i < opts.value.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 we made it here, we passed.
+  if (opts.details)
+  {
+    res.pass = true;
+    delete res.failed;
+  }
+  else
+  {
+    res = true;
+  }
+
+  return res;
+}
+
+exports.isArrayOf = isArrayOf;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "main": "lib/index.js",
   "exports":
   {