@lumjs/core 1.16.0 → 1.18.0

package/lib/arrays/add.js

@@ -0,0 +1,233 @@
+
+const {N,def} = require('../types');
+
+/**
+ * Functions for adding values to arrays in different ways.
+ * @alias module:@lumjs/core/arrays.add
+ */
+const ArrayAdd = module.exports = exports =
+{
+  prepend, before, append, after, insert,
+}
+
+function _addWith(array, oldValue, newValue, ifMissing, fn)
+{
+  let pos = array.indexOf(oldValue);
+
+  if (pos === -1)
+  {
+    if (typeof ifMissing === N)
+    {
+      pos = ifMissing;
+    }
+    else
+    {
+      return false;
+    }
+  }
+
+  return fn(array, newValue, pos);
+}
+
+/**
+ * Prepend a value to an array.
+ * 
+ * @param {Array} array - Array to add the value to.
+ * @param {*}     value - Value to add to the array.
+ * @param {number} [pos=0] Position to prepend at.
+ * 
+ * If `pos` is `0` then `array.unshift(value)` is used.
+ * Otherwise `array.splice(pos, 0, value)` is used.
+ * 
+ * @returns {Array} `array`
+ * @alias module:@lumjs/core/arrays.add.prepend
+ */
+function prepend(array, value, pos=0)
+{
+  if (pos === 0)
+  {
+    array.unshift(value);
+  }
+  else
+  {
+    array.splice(pos, 0, value);
+  }
+
+  return array;
+}
+
+/**
+ * Append a value to an array.
+ * 
+ * @param {Array} array - Array to add the value to.
+ * @param {*}     value - Value to add to the array.
+ * @param {number} [pos=-1] Position to append at.
+ * 
+ * If `pos` is `-1` then `array.push(value)` is used.
+ * Otherwise `array.splice(pos+1, 0, value)` is used.
+ * 
+ * @returns {Array} `array`
+ * @alias module:@lumjs/core/arrays.add.append
+ */
+function append(array, value, pos=-1)
+{
+  if (pos === -1)
+  {
+    array.push(value);
+  }
+  else
+  {
+    array.splice(pos+1, 0, value);
+  }
+
+  return array;
+}
+
+/**
+ * Add a value to an array _before_ an existing value.
+ * 
+ * This uses `prepend()` to add the value.
+ * 
+ * @param {Array} array - Array to add the value to.
+ * @param {*} oldValue  - Existing value to find.
+ * @param {*} newValue  - Value to add to the array.
+ * @param {(number|false)} [ifMissing=0] If `oldValue` is not found.
+ * 
+ * If this is a `number` it will be used as the `pos` argument.
+ * 
+ * If this is `false` the function will not add the value at all,
+ * but will return `false` instead.
+ * 
+ * @returns {(Array|false)} Usually the input `array`; but will return
+ * `false` if `ifMissing` was `false` and the `oldValue` was not found.
+ * 
+ * @alias module:@lumjs/core/arrays.add.before
+ */
+function before(array, oldValue, newValue, ifMissing=0)
+{
+  return _addWith(array, oldValue, newValue, ifMissing, prepend);
+}
+
+/**
+ * Add a value to an array _after_ an existing value.
+ * 
+ * This uses `append()` to add the value.
+ * 
+ * @param {Array} array - Array to add the value to.
+ * @param {*} oldValue  - Existing value to find.
+ * @param {*} newValue  - Value to add to the array.
+ * @param {(number|false)} [ifMissing=-1] If `oldValue` is not found.
+ * 
+ * If this is a `number` it will be used as the `pos` argument.
+ * 
+ * If this is `false` the function will not add the value at all,
+ * but will return `false` instead.
+ * 
+ * @returns {(Array|false)} Usually the input `array`; but will return
+ * `false` if `ifMissing` was `false` and the `oldValue` was not found.
+ * 
+ * @alias module:@lumjs/core/arrays.add.after
+ */
+function after(array, oldValue, newValue, ifMissing=-1)
+{
+  return _addWith(array, oldValue, newValue, ifMissing, append);
+}
+
+/**
+ * Insert a value to an array using special logic.
+ * 
+ * See the `pos` argument for the positioning logic used.
+ * 
+ * @param {Array} array - Array to add the value to.
+ * @param {*}     value - Value to add to the array.
+ * @param {number} [pos=-1] Position to insert at.
+ * 
+ * If `pos` is less than `0` this uses `append()`;
+ * Otherwise it uses `prepend()`.
+ *
+ * @returns {Array} `array`
+ * @alias module:@lumjs/core/arrays.add.insert
+ */
+function insert(array, value, pos=-1)
+{
+  if (pos < 0)
+  {
+    return append(array, value, pos);
+  }
+  else
+  {
+    return prepend(array, value, pos);
+  }
+}
+
+/**
+ * A wrapper class to provide helper methods to Arrays.
+ * 
+ * Provides wrapped versions of `prepend()`, `append()`, 
+ * `before()`, `after()`, and `insert()`.
+ * 
+ * The methods obviously pass the array argument, so remove it from
+ * the argument signature when using the wrapper method. Other than that,
+ * the rest of the arguments are the same as the wrapped functions.
+ * 
+ * @alias module:@lumjs/core/arrays.add.At
+ */
+class ArrayAt
+{
+  /**
+   * Build a wrapper around an array.
+   * 
+   * @param {Array} array - Array to wrap.
+   */
+  constructor(array)
+  {
+    this.array = array;
+  }
+
+  /**
+   * Add wrappers for the helper functions to the Array directly.
+   * 
+   * WARNING: This is monkey patching the array object instance.
+   * If you're okay with that, cool. 
+   * 
+   * Otherwise, use a new `ArrayAt` object instance instead.
+   * 
+   * @param {Array} array - Array to add methods to.
+   * 
+   * @returns {Array} The input `array`
+   */
+  static extend(array)
+  {
+    for (const methName in ArrayAdd)
+    {
+      const methFunc = ArrayAdd[methName];
+      def(array, methName, methFunc.bind(array, array));
+    }
+    return array;
+  }
+
+  /**
+   * A static method that calls `new ArrayAt(array)`;
+   * 
+   * @param {Array} array - Array to wrap
+   * @returns {module:@lumjs/core/arrays.ArrayAt} A new instance.
+   */
+  static new(array)
+  {
+    return new this(array);
+  }
+
+} // ArrayAt class
+
+// Set up ArrayAt methods, and export the functions.
+for (const methName in ArrayAdd)
+{
+  const methFunc = ArrayAdd[methName];
+
+  def(ArrayAt.prototype, methName, function()
+  {
+    methFunc(this.array, ...arguments);
+  });
+}
+
+def(ArrayAdd, 'At', ArrayAt);

package/lib/arrays/index.js

@@ -0,0 +1,21 @@
+/**
+ * Array helper libraries
+ * 
+ * @module @lumjs/core/arrays
+ */
+
+const {lazy} = require('../types');
+const {powerset, random} = require('./util');
+
+// Utils.
+exports.powerset = powerset;
+exports.random   = random;
+
+// List stuff.
+lazy(exports, 'List', () => require('./list'));
+lazy(exports, 'containsAny', () => exports.List.containsAny);
+lazy(exports, 'containsAll', () => exports.List.containsAll);
+lazy(exports, 'removeItems', () => exports.List.removeItems);
+
+// Add functions and At class.
+lazy(exports, 'add', () => require('./add'));

package/lib/{arrays.js → arrays/list.js}

@@ -1,8 +1,5 @@
-/**
- * Array (and other list objects) helper functions.
- * @module @lumjs/core/arrays
- */
-const {F,S} = require('./types/js');
+
+const {F,S} = require('../types');
 
 /**
  * A wrapper class to abstract functionality of various kinds of lists.
@@ -278,6 +275,8 @@ function containsAny(list, ...items)
   return List.for(list, CONTAINS_OPTS).containsAny(...items);
 }
 
+List.containsAny = containsAny;
+
  /**
   * See if a list contains *all* of the specified items.
   *
@@ -291,6 +290,8 @@ function containsAll(list, ...items)
   return List.for(list, CONTAINS_OPTS).containsAll(...items);
 }
 
+List.containsAll = containsAll;
+
 const REMOVE_OPTS = {closures: ['remove']};
 
 /**
@@ -309,42 +310,6 @@ function removeItems(list, ...items)
   return List.for(list, REMOVE_OPTS).removeAll(...items);
 }
 
-/**
- * Return a Powerset of values in the array.
- * @param {Array} array  The array to make the powerset from.
- * @returns {Array}  The powerset.
- * @alias module:@lumjs/core/arrays.powerset
- */
-function powerset(array) 
-{
-  var ps = [[]];
-  for (var i=0; i < array.length; i++) 
-  {
-    // we modify the ps array in the next loop,
-    // so can't use the ps.length property directly in the loop condition.
-    var current_length = ps.length;
-    for (var j = 0; j < current_length; j++) 
-    {
-      ps.push(ps[j].concat(array[i]));
-    }
-  }
-  return ps;
-}
-
-/**
- * Get a random element from an array.
- * @param {Array} array  The array to get an item from.
- * @returns {mixed}  The randomly selected item.
- * @alias module:@lumjs/core/arrays.random
- */
-function random(array)
-{
-  return array[Math.floor(Math.random()*array.length)];
-}
-
-module.exports = exports =
-{
-  List, containsAny, containsAll,
-  removeItems, powerset, random,
-}
+List.removeItems = removeItems;
 
+module.exports = exports = List;

package/lib/arrays/util.js

@@ -0,0 +1,38 @@
+
+/**
+ * Return a Powerset of values in the array.
+ * @param {Array} array  The array to make the powerset from.
+ * @returns {Array}  The powerset.
+ * @alias module:@lumjs/core/arrays.powerset
+ */
+function powerset(array) 
+{
+  var ps = [[]];
+  for (var i=0; i < array.length; i++) 
+  {
+    // we modify the ps array in the next loop,
+    // so can't use the ps.length property directly in the loop condition.
+    var current_length = ps.length;
+    for (var j = 0; j < current_length; j++) 
+    {
+      ps.push(ps[j].concat(array[i]));
+    }
+  }
+  return ps;
+}
+
+/**
+ * Get a random element from an array.
+ * @param {Array} array  The array to get an item from.
+ * @returns {mixed}  The randomly selected item.
+ * @alias module:@lumjs/core/arrays.random
+ */
+function random(array)
+{
+  return array[Math.floor(Math.random()*array.length)];
+}
+
+module.exports = exports =
+{
+  powerset, random,
+}

package/lib/index.js

@@ -44,6 +44,13 @@ def(exports, 'lazy',  lazy);
  */
 lazy(exports, 'arrays', () => require('./arrays'));
 
+/**
+ * Map utility functions «Lazy»
+ * @name module:@lumjs/core.maps
+ * @type {module:@lumjs/core/maps}
+ */
+lazy(exports, 'maps', () => require('./maps'));
+
 /**
  * Information about the JS context we're running in
  * @name module:@lumjs/core.context

package/lib/maps.js

@@ -0,0 +1,67 @@
+/**
+ * Map object helper functions.
+ * @module @lumjs/core/maps
+ */
+const {F,isObj} = require('./types/js');
+
+/**
+ * Build a `Map` instance out of various types of objects.
+ * 
+ * @param {object} input - An object to be converted into a `Map`.
+ * 
+ * Supported object types:
+ * 
+ * - `Array`, `Map`, or any other object with an `entries()` method.
+ * - Implements `Iterable` interface (`[Symbol.iterator]`).
+ * - Implements `Iterator` interface (`next()`).
+ * - Anything other object we'll use all enumerable properties.
+ * 
+ * @returns {Map}
+ * @alias module:@lumjs/core/maps.mapOf
+ */
+function mapOf(input)
+{
+  if (!isObj(input))
+  {
+    throw new TypeError('Non-object passed to mapOf');
+  }
+
+  if (typeof input.entries === F)
+  { // Short-cut for Arrays, other Maps, etc.
+    return new Map(input.entries());
+  }
+
+  const map = new Map();
+
+  if (typeof input[Symbol.iterator] === F)
+  { // Using the Iterable interface.
+    let i = 0;
+    for (const value of input)
+    {
+      map.set(i++, value);
+    }
+  }
+  else if (typeof thing.next === F)
+  { // Using the Iterator interface.
+    let i = 0, next;
+
+    while ((next = input.next()) && !next.done)
+    {
+      map.set(i++, next.value);
+    }
+  }
+  else
+  { // A plain old object. Use enumerable properties.
+    for (const key in input)
+    {
+      map.set(key, input[key]);
+    }
+  }
+
+  return map;
+}
+
+module.exports =
+{
+  mapOf,
+}

package/lib/observable.js

@@ -11,31 +11,46 @@ const lock = Object.freeze;
  * @param {object} el - The object we are making observable.
  * @param {object} [opts] Options that define behaviours.
  * @param {string} [opts.wildcard='*'] The event name used as a wildcard. 
- * @param {boolean} [opts.wrapthis=false] If `true`, `this` will be a wrapper.
  * 
- * If `wrapthis` is `true`, the function will be called with a wrapper object 
- * as the `this` variable instead of the target object. The wrapper will be:
- *
+ * @param {boolean} [opts.wrapargs=false] If `true`, the event handlers will 
+ * be passed a wrapper object as the sole argument:
+ * 
  * ```js
- * {
+ * { 
  *   isObservable:
- *   {
+ *   { // Immutable;
  *     event: true,   // This is an event data object.
  *     target: false, // This is not the target object.
  *   },
- *   self: el,        // The target object.
- *   name: event,     // The event name that was triggered.
  *   wildcard: bool,  // Will be true if this was a wildcard event handler.
  *   func: function,  // The function being called.
  *   args: array,     // The arguments passed to trigger.
+ *   self: el,        // The target object.
+ *   name: event,     // The event name that was triggered.
+ *   target: el,      // An alias to `self`.
+ *   type: event,     // An alias to `name`.
+ *   // ...
  * }
  * ```
  * 
- * The object will be frozen so its values cannot be modified.
+ * @param {boolean} [opts.wrapthis=false] If `true`, `this` in event 
+ * handlers will be the same object as `opts.wrapargs`.
+ * 
+ * @param {?function} [opts.wrapsetup=null] Setup function for wrapper data.
+ * 
+ * This function will be called with the target `el` as `this`,
+ * and will be passed the wrapper object (before it is locked),
+ * so it can examine the event name and arguments passed to
+ * `trigger()` and adjust the object accordingly.
  * 
- * @param {boolean} [opts.wrapargs=false] If `true`, the functions will be
- * passed a single object as the sole argument. The object will be the same
- * as the one from `opts.wrapthis`.
+ * This allows the wrapper objects to have a lot more custom properties,
+ * and feel more like the standard Event objects used by the `DOM`.
+ * 
+ * If this is specified, but neither `opts.wrapargs` or `opts.wrapthis` 
+ * is `true`, then `opts.wrapargs` will be changed to `true` implicitly.
+ * 
+ * @param {boolean} [opts.wraplock=true] If `true`, the wrapper object
+ * will be made immutable using the `Object.freeze()` method.
  * 
  * @param {boolean} [opts.addname] If `true` callbacks with 
  * multiple events will have the name of the triggered event added as
@@ -99,16 +114,24 @@ function observable (el={}, opts={})
     ? opts.wildcard
     : '*';
 
+  const wrapsetup = (typeof opts.wrapsetup === F)
+    ? opts.wrapsetup 
+    : null;
+
   const wrapthis = (typeof opts.wrapthis === B) 
     ? opts.wrapthis 
     : false;
 
   const wrapargs = (typeof opts.wrapargs === B)
     ? opts.wrapargs
-    : false;
+    : (wrapsetup ? !wrapthis : false);
 
   const wrapped = (wrapthis || wrapargs);
 
+  const wraplock = (typeof opts.wraplock === B)
+    ? opts.wraplock
+    : true;
+
   const addname = (typeof opts.addname === B) 
     ? opts.addname 
     : !wrapped;
@@ -154,15 +177,28 @@ function observable (el={}, opts={})
     { // Something is going to use our wrapper object.
       const isWild = (name === wildcard);
       const fname = isWild ? (addname ? args[0] : args.shift()) : name;
+
       fobj = 
-      lock({
+      {
         isObservable: lock({event: true, target: false}),
         self: el,
-        name: fname,
+        target: el,
+        name: fname, 
+        type: fname,
         func: fn,
         wildcard: isWild,
         args,
-      });
+      };
+
+      if (wrapsetup)
+      {
+        wrapsetup.call(el, fobj);
+      }
+
+      if (wraplock)
+      {
+        lock(fobj);
+      }
     }
 
     const fthis = wrapthis ? fobj : el;

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/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@lumjs/core",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "main": "lib/index.js",
   "exports":
   {
     ".": "./lib/index.js",
 
-    "./arrays": "./lib/arrays.js",
+    "./arrays": "./lib/arrays/index.js",
+    "./maps": "./lib/maps.js",
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
     "./flags": "./lib/flags.js",

package/debug/2023-06-08T19_55_05_247Z-debug-0.log

@@ -1,107 +0,0 @@
-0 verbose cli /usr/bin/node /usr/bin/npm
-1 info using npm@9.7.1
-2 info using node@v18.16.0
-3 timing npm:load:whichnode Completed in 1ms
-4 timing config:load:defaults Completed in 1ms
-5 timing config:load:file:/usr/lib/node_modules/npm/npmrc Completed in 1ms
-6 timing config:load:builtin Completed in 1ms
-7 timing config:load:cli Completed in 1ms
-8 timing config:load:env Completed in 0ms
-9 timing config:load:file:/system/docs/dev/js/lumjs/core/.npmrc Completed in 0ms
-10 timing config:load:project Completed in 1ms
-11 timing config:load:file:/home/novus/.npmrc Completed in 1ms
-12 timing config:load:user Completed in 1ms
-13 timing config:load:file:/usr/etc/npmrc Completed in 0ms
-14 timing config:load:global Completed in 0ms
-15 timing config:load:setEnvs Completed in 1ms
-16 timing config:load Completed in 6ms
-17 timing npm:load:configload Completed in 6ms
-18 timing config:load:flatten Completed in 1ms
-19 timing npm:load:mkdirpcache Completed in 0ms
-20 timing npm:load:mkdirplogs Completed in 0ms
-21 verbose title npm publish
-22 verbose argv "publish"
-23 timing npm:load:setTitle Completed in 0ms
-24 timing npm:load:display Completed in 1ms
-25 verbose logfile logs-max:10 dir:/home/novus/.npm/_logs/2023-06-08T19_55_05_247Z-
-26 verbose logfile /home/novus/.npm/_logs/2023-06-08T19_55_05_247Z-debug-0.log
-27 timing npm:load:logFile Completed in 5ms
-28 timing npm:load:timers Completed in 0ms
-29 timing npm:load:configScope Completed in 0ms
-30 timing npm:load Completed in 22ms
-31 verbose publish [ '.' ]
-32 silly logfile start cleaning logs, removing 1 files
-33 silly logfile done cleaning log files
-34 timing arborist:ctor Completed in 0ms
-35 notice
-36 notice 📦  @lumjs/core@1.16.0
-37 notice === Tarball Contents ===
-38 notice 928B   README.md             
-38 notice 627B   TODO.md               
-38 notice 501B   jsdoc.json            
-38 notice 8.6kB  lib/arrays.js         
-38 notice 6.4kB  lib/context.js        
-38 notice 5.8kB  lib/enum.js           
-38 notice 1.3kB  lib/flags.js          
-38 notice 3.6kB  lib/index.js          
-38 notice 3.8kB  lib/meta.js           
-38 notice 3.6kB  lib/modules.js        
-38 notice 1.2kB  lib/obj/apply.js      
-38 notice 12.1kB lib/obj/clone.js      
-38 notice 1.2kB  lib/obj/copyall.js    
-38 notice 12.5kB lib/obj/copyprops.js  
-38 notice 3.2kB  lib/obj/getmethods.js 
-38 notice 1.2kB  lib/obj/getproperty.js
-38 notice 870B   lib/obj/index.js      
-38 notice 2.2kB  lib/obj/lock.js       
-38 notice 2.8kB  lib/obj/merge.js      
-38 notice 6.8kB  lib/obj/ns.js         
-38 notice 2.5kB  lib/objectid.js       
-38 notice 8.7kB  lib/observable.js     
-38 notice 2.2kB  lib/opt.js            
-38 notice 5.3kB  lib/strings.js        
-38 notice 6.0kB  lib/types/basics.js   
-38 notice 4.7kB  lib/types/console.js  
-38 notice 7.2kB  lib/types/def.js      
-38 notice 1.1kB  lib/types/dt.js       
-38 notice 1.8kB  lib/types/index.js    
-38 notice 4.9kB  lib/types/isa.js      
-38 notice 457B   lib/types/js.js       
-38 notice 7.2kB  lib/types/lazy.js     
-38 notice 3.4kB  lib/types/needs.js    
-38 notice 2.7kB  lib/types/root.js     
-38 notice 3.8kB  lib/types/stringify.js
-38 notice 5.5kB  lib/types/typelist.js 
-38 notice 826B   package.json          
-39 notice === Tarball Details ===
-40 notice name:          @lumjs/core                             
-40 notice version:       1.16.0                                  
-40 notice filename:      lumjs-core-1.16.0.tgz                   
-40 notice package size:  42.7 kB                                 
-40 notice unpacked size: 147.6 kB                                
-40 notice shasum:        424727206c94f94fbf8e18c5f62eab4aa64e52af
-40 notice integrity:     sha512-iPLVQTAe/Bf8P[...]TV8PNxn6/ji5A==
-40 notice total files:   37                                      
-41 notice
-42 notice Publishing to https://registry.npmjs.org/ with tag latest and default access
-43 http fetch PUT 401 https://registry.npmjs.org/@lumjs%2fcore 277ms
-44 timing command:publish Completed in 367ms
-45 verbose stack HttpErrorGeneral: 401 Unauthorized - PUT https://registry.npmjs.org/@lumjs%2fcore - unexpected status code from "get-packument" = 401
-45 verbose stack     at /usr/lib/node_modules/npm/node_modules/npm-registry-fetch/lib/check-response.js:95:15
-45 verbose stack     at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
-45 verbose stack     at async publish (/usr/lib/node_modules/npm/node_modules/libnpmpublish/lib/publish.js:54:17)
-45 verbose stack     at async otplease (/usr/lib/node_modules/npm/lib/utils/otplease.js:4:12)
-45 verbose stack     at async Publish.exec (/usr/lib/node_modules/npm/lib/commands/publish.js:123:7)
-45 verbose stack     at async module.exports (/usr/lib/node_modules/npm/lib/cli-entry.js:61:5)
-46 verbose statusCode 401
-47 verbose pkgid @lumjs/core@1.16.0
-48 verbose cwd /system/docs/dev/js/lumjs/core
-49 verbose Linux 5.10.0-22-amd64
-50 verbose node v18.16.0
-51 verbose npm  v9.7.1
-52 error code E401
-53 error 401 Unauthorized - PUT https://registry.npmjs.org/@lumjs%2fcore - unexpected status code from "get-packument" = 401
-54 verbose exit 1
-55 timing npm Completed in 495ms
-56 verbose code 1
-57 error A complete log of this run can be found in: /home/novus/.npm/_logs/2023-06-08T19_55_05_247Z-debug-0.log