@lumjs/core 1.16.0 → 1.19.0

package/lib/opt.js

@@ -3,12 +3,13 @@
  * @module @lumjs/core/opt
  */
 
-const {U,F,S,needObj,needType} = require('./types');
+const {U,F,S,N,B,isObj,isComplex,needObj,needType} = require('./types');
+const {insert} = require('./arrays/add');
 
 /**
  * See if a value is *set*, and if not, return a default value.
  *
- * @param {*} opt - The value we are testing.
+ * @param {*} optvalue - The value we are testing.
  * @param {*} defvalue - The default value if opt was null or undefined.
  *
  * @param {boolean} [allowNull=false] If true, allow null to count as *set*.
@@ -17,22 +18,28 @@ const {U,F,S,needObj,needType} = require('./types');
  *                                    the default.
  * @param {object} [lazyThis=null]    If `isLazy` is true, this object will
  *                                    be used as `this` for the function.
+ * @param {Array}  [lazyArgs]         If `isLazy` is true, this may be used
+ *                                    as a list of arguments to pass.
  *
  * @return {*} Either the specified `opt` value or the default value.
  * @alias module:@lumjs/core/opt.val
  */
-function val(opt, defvalue, allowNull=false, isLazy=false, lazyThis=null)
+function val(optvalue, defvalue, 
+  allowNull=false, 
+  isLazy=false, 
+  lazyThis=null,
+  lazyArgs=[])
 {
-  if (typeof opt === U || (!allowNull && opt === null))
+  if (typeof optvalue === U || (!allowNull && optvalue === null))
   { // The defined value was not "set" as per our rules.
     if (isLazy && typeof defvalue === F)
     { // Get the default value from a passed in function.
-      return defvalue.call(lazyThis);
+      return defvalue.apply(lazyThis, lazyArgs);
     }
     return defvalue;
   }
 
-  return opt;
+  return optvalue;
 }
 
 exports.val = val;
@@ -48,18 +55,350 @@ exports.val = val;
  * @param {string} optname - The property name we're checking for.
  * @param {*} defvalue     - The default value.
  *
- * @param {bool}   [allowNull=true] Same as `val()`, but the default is `true`.
+ * @param {bool}   [allowNull=true] Same as `val()`, but default is `true`.
  * @param {bool}   [isLazy=false]   Same as `val()`.
- * @param {object} [lazyThis=opts]  Same as `val()`.
+ * @param {object} [lazyThis=opts]  Same as `val()`, but default is `obj`.
+ * @param {Array}  [lazyArgs]       Same as `val()`.
  *
  * @return {*} Either the property value, or the default value.
- * module:@lumjs/core/opt.get
+ * @alias module:@lumjs/core/opt.get
  */
-function get(obj, optname, defvalue, allowNull=true, isLazy=false, lazyThis=obj)
+function get(obj, optname, defvalue, 
+  allowNull=true, 
+  isLazy=false, 
+  lazyThis=obj,
+  lazyArgs)
 {
   needObj(obj);
   needType(S, optname);
-  return val(obj[optname], defvalue, allowNull, isLazy, lazyThis);
+  return val(obj[optname], defvalue, allowNull, isLazy, lazyThis, lazyArgs);
 }
 
 exports.get = get;
+
+/**
+ * A class for handling options with multiple sources.
+ * @alias module:@lumjs/core/opt.Opts
+ */
+class Opts
+{
+  /**
+   * Build an Opts instance.
+   * 
+   * @param  {...object} sources - Initial sources of options.
+   * 
+   * The order of sources matters, as the ones added later will override
+   * the ones added earlier. Keep that in mind when adding sources.
+   */
+  constructor(...sources)
+  {
+    this.$sources = [];
+    this.$curPos = -1;
+    this.$curSrc = null;
+
+    this.$fatalErrors = false;
+    this.$strictProps = false;
+
+    this.add(...sources);
+    this._compile();
+  }
+
+  /**
+   * Compile current sources into a data object.
+   * 
+   * @returns {object} `this`
+   * @private
+   */
+  _compile()
+  {
+    this.$data = Object.assign({}, ...this.$sources);
+    return this;
+  }
+
+  /**
+   * Handle an error
+   * 
+   * @param {string} msg - A summary of the error.
+   * @param {object} info - Debugging information for the logs.
+   * @param {function} [errClass=TypeError] Constructor for an `Error` class.
+   * Used if fatal errors are enabled.
+   * 
+   * @returns {object} `this`
+   * @throws {Error} An error of `errClass` class, if fatal mode is enabled.
+   */
+  _err(msg, info={}, errClass=TypeError)
+  {
+    const args = this.$fatalErrors ? [info] : [msg, info];
+
+    info.instance = this;
+    console.error(...args);
+
+    if (this.$fatalErrors)
+    {
+      throw new errClass(msg);
+    }
+  }
+
+  /**
+   * Set the fatal error handling setting.
+   * 
+   * Default is `false`, so errors will be logged, but not thrown.
+   * 
+   * @param {boolean} val - Should errors be fatal?
+   * @returns {object} `this`
+   */
+  fatal(val)
+  {
+    if (typeof val === B)
+    {
+      this.$fatalErrors = val;
+    }
+    else
+    {
+      this._err('invalid fatal value', {val});
+    }
+
+    return this;
+  }
+
+  /**
+   * Set the strict property check setting.
+   * 
+   * Default is `false`, we don't care about non-existent properties. 
+   *
+   * @param {boolean} val - Should non-existant properties be an error?
+   * @returns {object} `this`
+   */
+  strict(val)
+  {
+    if (typeof val === B)
+    {
+      this.$strictProps = val;
+    }
+    else
+    {
+      this._err('invalid strict value', {val});
+    }
+
+    return this;
+  }
+
+  /**
+   * Set the position/offset to add new sources at.
+   * 
+   * This will affect subsequent calls to the `add()` method.
+   * 
+   * @param {number} pos - The position/offset value.
+   * 
+   * - A value of `-1` uses `Array#push(src))`; end of array.
+   * - A value of `0` uses `Array#unshift(src)`; start of array.
+   * - Any value `> 0` uses `Array#splice(pos, 0, src)`; offset from start.
+   * - Any value `< -1` uses `Array#splice(pos+1, 0, src)`; offset from end.
+   * 
+   * The default value if none is specified is `-1`.
+   * 
+   * @returns {object} `this`
+   * @throws {TypeError} An invalid value was passed while `fatal` was true.
+   */
+  at(pos)
+  {
+    if (typeof pos === N)
+    {
+      this.$curPos = pos;
+    }
+    else
+    {
+      this._err("Invalid pos value", {pos});
+    }
+    
+    return this;
+  }
+
+  /**
+   * Set the object to look for nested properties in.
+   * 
+   * This will affect subsequent calls to the `add()` method.
+   * 
+   * @param  {(object|number|boolean)} source - Source definition
+   *
+   * - If this is an `object` it will be used as the object directly.
+   * - If this is a `number` it is the position of one of our data sources.
+   *   Negative numbers count from the end of the list of sources.
+   * - If this is `true` then the compiled options data at the time of the
+   *   call to this method will be used.
+   * - If this is `false` then the next time a `string` value is passed to
+   *   `add()` the options will be compiled on demand, and that object will
+   *   be used until the next call to `from()`.
+   * 
+   * If this is not specified, then it defaults to `false`.
+   *
+   * @returns {object} `this`
+   * @throws {TypeError} An invalid value was passed while `fatal` was true.
+   */
+  from(source)
+  {
+    if (source === true)
+    { // Use existing data as the source.
+      this.$curSrc = this.$data;
+    }
+    else if (source === false)
+    { // Auto-generate the source the next time.
+      this.$curSrc = null;
+    }
+    else if (typeof source === N)
+    { // A number will be the position of an existing source.
+      const offset 
+        = (source < 0)
+        ? this.$sources.length + source
+        : source;
+
+      if (isObj(this.$sources[offset]))
+      {
+        this.$curSrc = this.$sources[offset];
+      }
+      else
+      {
+        this._err("Invalid source offset", {offset, source});
+      }
+    }
+    else if (isObj(source))
+    { // An object or function will be used as the source.
+      this.$curSrc = source;
+    }
+    else
+    {
+      this._err("Invalid source", {source});
+    }
+
+    return this;
+  } 
+
+  /**
+   * Add new sources of options.
+   * 
+   * @param  {...(object|string)} sources - Sources and positions.
+   * 
+   * If this is an `object` then it's a source of options to add.
+   * This is the most common way of using this.
+   * 
+   * If this is a `string` then it's assumed to be nested property
+   * of the current `from()` source, and if that property exists and
+   * is an object, it will be used as the source to add. If it does
+   * not exist, then the behaviour will depend on the values of the
+   * `strict()` and `fatal()` modifiers.
+   * 
+   * @returns {object} `this`
+   */
+  add(...sources)
+  {
+    let pos=-1;
+
+    for (let source of sources)
+    {
+      if (source === undefined || source === null)
+      { // Skip undefined or null values.
+        continue;
+      }
+
+      if (typeof source === S)
+      { // Try to find a nested property to include.
+        if (this.$curSrc === null)
+        { // Has not been initialized, let's do that now.
+          this._compile();
+          this.$curSrc = this.$data;
+        }
+
+        if (isObj(this.$curSrc[source]))
+        { // Found a property, use it.
+          source = this.$curSrc[source];
+        }
+        else
+        { // No such property.
+          if (this.$strictProps)
+          {
+            this._err('Property not found', {source});
+          }
+          continue;
+        }
+      }
+      
+      if (isObj(source))
+      { // It's a source to add.
+        insert(this.$sources, source, pos);
+      }
+      else
+      { // That's not valid.
+        this._err('invalid source value', {source, sources});
+      }
+    }
+
+    return this._compile();
+  }
+
+  /**
+   * Remove existing sources of options.
+   * 
+   * @param  {...object} sources - Sources to remove.
+   * 
+   * @returns {object} `this`
+   */
+  remove(...sources)
+  {
+    for (const source of sources)
+    {
+      const index = this.$sources.indexOf(source);
+      if (index !== -1)
+      {
+        this.$sources.splice(index, 1);
+      }
+    }
+
+    return this._compile();
+  }
+
+  /**
+   * Remove all current sources. Resets compiled options data.
+   * 
+   * @returns {object} `this`
+   */
+  clear()
+  {
+    this.$sources = [];
+    return this._compile();
+  }
+
+  /**
+   * Get an option value from our compiled data sources.
+   * 
+   * This uses the `get()` function, but instead of using positional
+   * arguments, it supports an object of named options instead.
+   * 
+   * @param {string} opt - The name of the option to get.
+   * @param {object} [args] Optional arguments for `get()`.
+   * @param {*} [args.default] `defvalue` argument.
+   * @param {boolean} [args.null=true] `allowNull` argument.
+   * @param {boolean} [args.lazy=false] `isLazy` argument.
+   * @param {(object|function)} [args.lazyThis] `lazyThis` argument.
+   * If this is defined, `args.lazy` will be set to `true`.
+   * @param {Array} [args.lazyArgs] `lazyArgs` argument.
+   * If this is defined, `args.lazy` will be set to `true`.
+   * 
+   * @returns {*} The output of the `get()` function.
+   */
+  get(opt, args={})
+  {
+    if (isComplex(args.lazyThis) || Array.isArray(args.lazyArgs))
+    {
+      args.lazy = true;
+    }
+
+    return get(this.$data, opt, 
+      args.default, 
+      args.null, 
+      args.lazy, 
+      args.lazyThis, 
+      args.lazyArgs);
+  }
+}
+
+exports.Opts = Opts;

package/lib/strings.js

@@ -189,3 +189,31 @@ function replaceItems(string, replacements, useAll)
 }
 
 exports.replaceItems = replaceItems;
+
+/**
+ * Replace values in a string via an async function.
+ * 
+ * @param {string} string - The input string.
+ * 
+ * @param {(RegExp|string)} regexp - The pattern to find.
+ * 
+ * If this is a `RegExp`, it *must* have the `g` flag set.
+ * If this is a `string` it will be converted into a `RegExp`,
+ * see the `String#matchAll` method for details.
+ * 
+ * @param {function} replacerFunction - An `async` function.
+ * 
+ * See `String#replace` for details on replacer functions.
+ * 
+ * @returns {string}
+ */
+async function replaceAsync(string, regexp, replacerFunction) 
+{
+  const replacements = await Promise.all(
+      Array.from(string.matchAll(regexp),
+          match => replacerFunction(...match)));
+  let i = 0;
+  return string.replace(regexp, () => replacements[i++]);
+}
+
+exports.replaceAsync = replaceAsync;

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

@@ -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,
+  console,
 }
 
 // Last but not least, this will be the module for TYPES.add()