@lumjs/core 1.18.0 → 1.20.0

package/lib/{types/console.js → console.js}

@@ -1,5 +1,5 @@
-const def = require('./def');
-const {F} = require('./js');
+const def = require('./types/def');
+const {F} = require('./types/js');
 
 /**
  * A super simple singleton wrapper around the Javascript console.
@@ -7,7 +7,7 @@ const {F} = require('./js');
  * By default includes `info`, `log`, `warn`, and `error` methods.
  * It may be expanded further using the `addMethod` method.
  * 
- * @exports module:@lumjs/core/types/console
+ * @exports module:@lumjs/core/console
  */
 const LC = 
 {
@@ -80,7 +80,7 @@ const LC =
 
 /** 
  * A reference to the real console object.
- * @alias module:@lumjs/core/types/console.real
+ * @alias module:@lumjs/core/console.real
  */ 
 const RC = globalThis.console;
 def(LC, 'real', RC);
@@ -97,14 +97,14 @@ const HANDLER_OPTIONS =
 /**
  * Add a wrapper method to the console wrapper object.
  * @param {string} method - The console method to wrap.
- * @alias module:@lumjs/core/types/console.addMethod
+ * @alias module:@lumjs/core/console.addMethod
  */
 function addMethod(method)
 {
   def(LC, method, function(...args)
   {
     if (typeof LC.trigger === F)
-    { // Support for core.observable(core.types.console);
+    { // Support for core.observable(core.console);
       LC.trigger(method, ...args);
     }
 

package/lib/index.js

@@ -79,6 +79,13 @@ lazy(exports, 'flags', () => require('./flags'));
  */
 lazy(exports, 'obj', () => require('./obj'));
 
+/**
+ * A wrapper around the Javascript console.
+ * @name module:@lumjs/core.console
+ * @type {module:@lumjs/core/console}
+ */
+lazy(exports, 'console', () => require('./console'));
+
 /**
  * Functions for getting values and properties with fallback defaults «Lazy»
  * @name module:@lumjs/core.opt

package/lib/types/basics.js

@@ -6,92 +6,92 @@ const {O, F, S, SY} = require('./js');
  * @returns {boolean}
  * @alias module:@lumjs/core/types.isObj
  */
- function isObj(v) { return (typeof v === O && v !== null); }
-
- /**
-  * See if a value is *complex* (i.e. either `object` or `function`).
-  * Like `isObj()`, `null` does not count as an `object`.
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isComplex
-  */
- function isComplex(v) { return (typeof v === F || isObj(v)); }
- 
- /**
-  * See if a value is *nil* (i.e. either `null` or `undefined`).
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isNil
-  */
- function isNil(v) { return (v === undefined || v === null); }
- 
- /**
-  * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.notNil
-  */
- function notNil(v) { return (v !== undefined && v !== null); }
- 
- /**
-  * See if a value is a scalar.
-  * For the purposes of this, a scalar is any value which
-  * is neither *nil* nor *complex*.
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isScalar
-  */
- function isScalar(v) { return (notNil(v) && !isComplex(v)); }
- 
- /**
-  * See if a value is an `Array` object.
-  * This is literally just a copy of `Array.isArray`.
-  * @function
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isArray
-  */
- const isArray = Array.isArray;
- 
- /**
-  * See if a value is a `TypedArray` object.
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isTypedArray
-  */
- function isTypedArray(v)
- {
-   return (ArrayBuffer.isView(v) && !(v instanceof DataView));
- }
- 
- /**
-  * See if a value is a non-empty Array.
-  * @param {*} v - The value we're testing.
-  * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
-  *   If `false` (default) we want a regular `Array`.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.nonEmptyArray
-  */
- function nonEmptyArray(v, typed=false)
- {
-   if (typed)
-     return (isTypedArray(v) && v.length > 0);
-   else
-     return (isArray(v) && v.length > 0);
- }
- 
- /**
-  * See if a value is an `arguments` object.
-  * @param {*} v - The value we're testing.
-  * @returns {boolean}
-  * @alias module:@lumjs/core/types.isArguments
-  */
- function isArguments(v) 
- {
-   return Object.prototype.toString.call(v) === '[object Arguments]';
- }
-
- /**
+function isObj(v) { return (typeof v === O && v !== null); }
+
+/**
+ * See if a value is *complex* (i.e. either `object` or `function`).
+ * Like `isObj()`, `null` does not count as an `object`.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isComplex
+ */
+function isComplex(v) { return (typeof v === F || isObj(v)); }
+
+/**
+ * See if a value is *nil* (i.e. either `null` or `undefined`).
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isNil
+ */
+function isNil(v) { return (v === undefined || v === null); }
+
+/**
+ * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.notNil
+ */
+function notNil(v) { return (v !== undefined && v !== null); }
+
+/**
+ * See if a value is a scalar.
+ * For the purposes of this, a scalar is any value which
+ * is neither *nil* nor *complex*.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isScalar
+ */
+function isScalar(v) { return (notNil(v) && !isComplex(v)); }
+
+/**
+ * See if a value is an `Array` object.
+ * This is literally just a copy of `Array.isArray`.
+ * @function
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isArray
+ */
+const isArray = Array.isArray;
+
+/**
+ * See if a value is a `TypedArray` object.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isTypedArray
+ */
+function isTypedArray(v)
+{
+  return (ArrayBuffer.isView(v) && !(v instanceof DataView));
+}
+
+/**
+ * See if a value is a non-empty Array.
+ * @param {*} v - The value we're testing.
+ * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
+ *   If `false` (default) we want a regular `Array`.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.nonEmptyArray
+ */
+function nonEmptyArray(v, typed=false)
+{
+  if (typed)
+    return (isTypedArray(v) && v.length > 0);
+  else
+    return (isArray(v) && v.length > 0);
+}
+
+/**
+ * See if a value is an `arguments` object.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isArguments
+ */
+function isArguments(v) 
+{
+  return Object.prototype.toString.call(v) === '[object Arguments]';
+}
+
+/**
  * See if a value is a Property name.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
@@ -122,28 +122,28 @@ function isProperty(v)
  * @returns {boolean} - Is the object a valid descriptor?
  * @alias module:@lumjs/core/types.doesDescriptor
  */
- function doesDescriptor(obj)
- {
-   if (isObj(obj))
-   {
-     const hasValue    = (obj.value !== undefined);
-     const hasGetter   = (typeof obj.get === F);
-     const hasSetter   = (typeof obj.set === F);
-     const hasWritable = (obj.writable !== undefined);
- 
-     if (hasValue && !hasGetter && !hasSetter)
-     { // We have a value, and no getter or setter.
-       return true;
-     }
-     else if ((hasGetter || hasSetter) && !hasValue && !hasWritable)
-     { // We have a getter or setter, and no value or writable properties.
-       return true;
-     }
-   }
- 
-   // Nothing matched, not a valid descriptor rule.
-   return false;
- }
+function doesDescriptor(obj)
+{
+  if (isObj(obj))
+  {
+    const hasValue    = (obj.value !== undefined);
+    const hasGetter   = (typeof obj.get === F);
+    const hasSetter   = (typeof obj.set === F);
+    const hasWritable = (obj.writable !== undefined);
+
+    if (hasValue && !hasGetter && !hasSetter)
+    { // We have a value, and no getter or setter.
+      return true;
+    }
+    else if ((hasGetter || hasSetter) && !hasValue && !hasWritable)
+    { // We have a getter or setter, and no value or writable properties.
+      return true;
+    }
+  }
+
+  // Nothing matched, not a valid descriptor rule.
+  return false;
+}
 
 /**
  * See if an object can be used as a valid *descriptor template*.
@@ -195,6 +195,6 @@ function doesDescriptorTemplate(obj, accessor=false, strict=true)
 // Now export those.
 module.exports =
 {
-isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-nonEmptyArray, isArguments, isProperty, doesDescriptor, doesDescriptorTemplate,
+  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+  nonEmptyArray, isArguments, isProperty, doesDescriptor, doesDescriptorTemplate,
 }

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');
@@ -42,8 +42,10 @@ const def   = require('./def');
 const lazy  = require('./lazy');
 const TYPES = require('./typelist');
 const stringify = require('./stringify');
+const ownCount = require('./owncount');
 
-const console = require('./console');
+// An alias for legacy reasons.
+const console = require('../console');
 
 // Okay, add all those to our exports.
 // Further tests can be added by `TYPES.add()` later.
@@ -53,7 +55,8 @@ module.exports =
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
   isInstance, isType, isa, needObj, needType, needs, stringify,
-  doesDescriptorTemplate, console,
+  doesDescriptorTemplate, ownCount, isArrayOf,
+  console,
 }
 
 // Last but not least, this will be the module for TYPES.add()

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/lib/types/needs.js

@@ -1,7 +1,7 @@
 const {F, S, B} = require('./js');
 const {isType, isa} = require('./isa');
 const {isObj, isComplex} = require('./basics');
-const console = require('./console');
+const console = require('../console');
 
 /**
  * If a value is not an object, throw an error.

package/lib/types/owncount.js

@@ -0,0 +1,50 @@
+/**
+ * Return the number of _local_ properties in an object.
+ * 
+ * @param {(object|function)} v - The value we want the property count of.
+ * 
+ * This can be any kind of `object`, or it can be a `function` that has
+ * a `prototype` property which is a `object`. Anything else is invalid.
+ * 
+ * @param {number} [level=0] Determine which properties to count.
+ * 
+ * - `== 0` : Counts only enumerable properties.
+ * - `> 0`  : Includes all properties with string names.
+ * - `> 1`  : Also includes symbol properties.
+ * 
+ * @returns {number} The number of matching properties.
+ * 
+ * If `v` was an invalid value, this will return `-1`.
+ * 
+ * @alias module:@lumjs/core/types.ownCount
+ */
+function ownCount(v, level=0)
+{
+  if (typeof v === F && isObj(v.prototype))
+  { // If a class constructor is passed, we use the prototype.
+    v = v.prototype;
+  }
+  
+  if (!isObj(v))
+  { // Nothing more to do here.
+    return -1;
+  }
+
+  if (level == 0)
+  { // Enumerable properties only.
+    return Object.keys(v).length;
+  }
+
+  // Include all properties with string names.
+
+  let count = Object.getOwnPropertyNames(v).length;
+
+  if (level > 1)
+  { // Also include symbol properties.
+    count += Object.getOwnPropertySymbols(v).length;
+  }
+
+  return count;
+}
+
+module.exports = ownCount;

package/package.json

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