@lumjs/core 1.19.0 → 1.21.0

package/lib/observable.js

@@ -4,11 +4,11 @@ const {duplicateAll: clone} = require('./obj/copyall');
 const lock = Object.freeze;
 
 /**
- * Make an object support the *Observable* API.
+ * Make a target object (or function) support the *Observable* API.
  *
  * Adds `on()`, `off()`, `one()`, and `trigger()` methods.
  * 
- * @param {object} el - The object we are making observable.
+ * @param {(object|function)} el - The target we are making observable.
  * @param {object} [opts] Options that define behaviours.
  * @param {string} [opts.wildcard='*'] The event name used as a wildcard. 
  * 
@@ -78,13 +78,29 @@ const lock = Object.freeze;
  * 
  * @param {string} [opts.addre] If set, add a method with this name
  * to the `el` object, which is a function that can re-build the
- * observable API methods with new `opts` replacing the old ones. 
+ * observable API methods with new `opts` replacing the old ones.
+ * 
+ * The method added takes two arguments, the first being an `object`
+ * representing the new options to set on the target. 
+ * 
+ * The second is an optional `boolean` value that determines if the
+ * existing `opts` should be used as defaults for any options not
+ * specified in the first argument.
+ * 
+ * @param {boolean} [opts.reinherit=false] Used as the default value of
+ * the second argument of the method added by `opts.addre`.
+ * 
+ * @param {boolean} [redefine=false] If `true` allow targets already
+ * implementing the `on()` and `trigger()` methods to be re-initialized.
+ * 
+ * Generally only needed if you need to change the `opts` for some reason.
+ * This is forced to `true` by the method added by `opts.addre`.
  *
  * @returns {object} el
  * 
  * @exports module:@lumjs/core/observable
  */
-function observable (el={}, opts={}) 
+function observable (el={}, opts={}, redefine=false) 
 {
   //console.debug("observable", el, opts);
 
@@ -93,7 +109,7 @@ function observable (el={}, opts={})
     throw new Error("non-object sent to observable()");
   }
 
-  if (observable.is(el))
+  if (isObservable(el) && !redefine)
   { // It's already observable.
     return el;
   }
@@ -338,9 +354,15 @@ function observable (el={}, opts={})
 
   if (addre)
   { // Add a method to change the observable options.
-    add(addre, function(opts={})
+    const reinherit = opts.reinherit ?? false;
+
+    add(addre, function(replacementOpts={}, inherit=reinherit)
     {
-      return observable(el, opts);
+      const newOpts 
+        = inherit 
+        ? Object.assign({}, opts, replacementOpts)
+        : replacementOpts;
+      return observable(el, replacementOpts, true);
     });
   }
 
@@ -362,7 +384,7 @@ module.exports = observable;
  */
 function isObservable(obj)
 {
-  return (isObj(obj)
+  return (isComplex(obj)
     && typeof obj.trigger === F
     && typeof obj.on === F);
 }

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.21.0",
   "main": "lib/index.js",
   "exports":
   {