@lumjs/core 1.15.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/obj/apply.js

@@ -0,0 +1,52 @@
+const {F,isObj} = require('../types');
+const copyProps = require('./copyprops');
+
+/**
+ * Apply functions to an object
+ *  
+ * In addition to the parameters passed, we'll also define:
+ * 
+ * - `cp` will be a `CopyProps` instance via `copyProps.cache.into(obj)`;
+ * - `args` will be an array of `[obj, opts]`;
+ * - `opts` will be an object of `{obj, cp, args}`;
+ * 
+ * @param {(object|function)} obj - The target we're applying to.
+ * 
+ * @param  {...(function|object)} fns - Values we are applying.
+ * 
+ * For each value of `fns` as `fn`:
+ * 
+ * - If a `function` we'll call `fn.apply(obj, args)`; 
+ * - If an `object` we'll call `cp.from(fn)`.
+ * 
+ * @returns {object} `obj`
+ * @throws {TypeError} If a `fns` value is not valid.
+ * @alias module:@lumjs/core/obj.apply
+ */
+function apply(obj, ...fns)
+{
+  const cp = copyProps.cache.into(obj);
+  const opts = {obj, cp};
+  const args = [obj, opts];
+  opts.args = args;
+
+  for (const fn of fns)
+  {
+    if (typeof fn === F)
+    { 
+      fn.apply(obj, args);
+    }
+    else if (isObj(fn))
+    {
+      cp.from(fn);
+    }
+    else
+    {
+      throw new TypeError("invalid parameter value");
+    }
+  }
+
+  return obj;
+}
+
+module.exports = apply;

package/lib/obj/copyall.js

@@ -39,7 +39,7 @@ exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
  * 
  * Use `copyProps.into({}).from(...sources)` for a more robust version.
  * 
- * Alias: `copyAll.clone`
+ * Alias: `copyAll.duplicate`
  * 
  * @alias module:@lumjs/core/obj.duplicateOne
  * @param {object} obj - The object to duplicate.

package/lib/obj/copyprops.js

@@ -1,7 +1,7 @@
 
 // Get some constants
-const {B,N,F,isObj,isArray,needObj,def,console} = require('../types');
-const {duplicateOne: clone} = require('./copyall');
+const {S,B,N,F,isObj,isArray,needObj,def,console} = require('../types');
+const {copyAll, duplicateOne: clone} = require('./copyall');
 
 const RECURSE_NONE =  0;
 const RECURSE_ALL  = -1;
@@ -233,22 +233,35 @@ def(copyProps, 'RECURSE_LIST', RECURSE_LIST);
  * // Get a copy of the `copyProps` function.
  * const cp = require('@lumjs/core').obj.copyProps;
  * 
- * // Starting with the target:
+ * // Starting with the target(s):
  * cp.into(targetObj).given({all: true}).from(source1, source2);
  * 
- * // Starting with the sources:
+ * // Starting with the source(s):
  * cp.from(sourceObj).given({exclude: ['dontCopy']}).into(target1, target2);
  * 
  * // Starting with the options:
  * cp.given({recursive: cp.RECURSE_ALL}).from(source1, source2).into(target1, target2);
  * 
+ * // Call `cp.into()` and cache the instance in a `Map`.
+ * // Future calls with the same `targetObj` will return the cached instance.
+ * // Unlike `cp.into()`, only supports a single `targetObj`.
+ * cp.cache.into(targetObj);
+ *
+ * // Call `cp.from()` and cache the instance in a `Map`.
+ * // Future calls with the same `sourceObj` will return the cached instance.
+ * // Unlike `cp.from()`, only supports a single `sourceObj`.
+ * cp.cache.from(sourceObj);
  * 
+ * // Clear the `Map` instances for `cp.cache.into` and `cp.cache.from`
+ * cp.cache.clear();
+ *
  * ```
  * 
  * @alias module:@lumjs/core/obj~CopyProps
  */
 class $CopyProps
 {
+  // Constructor is private so we won't document it.
   constructor(opts={})
   {
     this.opts = opts;
@@ -257,21 +270,42 @@ class $CopyProps
   }
 
   /**
-   * Set a single option.
-   * @param {string} name - The option name
-   * @param {*} value - The option value
+   * Set options.
+   * 
+   * @param {(string|object)} opt - Option(s) to set.
+   * 
+   * If this is a `string` it's the name of an option to set.
+   * If this is an `object`, it's map of options to set with `copyAll`.
+   * 
+   * @param {*} value - The option value.
+   * 
+   * Only used if `option` is a `string`.
+   * 
    * @returns {object} `this`
    */
-  set(name, value)
+  set(opt, value)
   {
-    this.opts[name] = value;
+    //console.debug("CopyProps.set(", opt, value, ')');
+    if (typeof opt === S)
+    { // Set a single option.
+      this.opts[opt] = value;
+    }
+    else if (isObj(opt))
+    { // Set a bunch of options.
+      copyAll(this.opts, opt);
+    }
+    else
+    { // That's not supported
+      console.error("invalid opt", {opt, value, cp: this});
+    }
+    //console.debug("CopyProps.set:after", this);
     return this;
   }
 
   /**
-   * Set all of the options.
+   * Set all options.
    * 
-   * This replaces the currently set options entirely.
+   * This replaces any existing options entirely.
    * 
    * @param {object} opts - The options to set.
    * @returns {object} `this`
@@ -372,4 +406,48 @@ copyProps.from = function(...sources)
   return ((new $CopyProps()).from(...sources));
 }
 
+const CPC = copyProps.cache =
+{
+  into(target)
+  {
+    if (this.intoCache === undefined)
+      this.intoCache = new Map();
+    const cache = this.intoCache;
+    if (cache.has(target))
+    {
+      return cache.get(target);
+    }
+    else
+    {
+      const cp = copyProps.into(target);
+      cache.set(target, cp);
+      return cp;
+    }
+  },
+  from(source)
+  {
+    if (this.fromCache === undefined)
+      this.fromCache = new Map();
+    const cache = this.fromCache;
+    if (cache.has(source))
+    {
+      return cache.get(source);
+    }
+    else
+    {
+      const cp = copyProps.from(source);
+      cache.set(source, cp);
+      return cp;
+    }
+  },
+  clear()
+  {
+    if (this.intoCache)
+      this.intoCache.clear();
+    if (this.fromCache)
+      this.fromCache.clear();
+    return this;
+  },
+};
+
 module.exports = copyProps;

package/lib/obj/index.js

@@ -3,6 +3,7 @@
  * @module @lumjs/core/obj
  */
 
+const apply = require('./apply');
 const {copyAll,duplicateOne,duplicateAll} = require('./copyall');
 const copyProps = require('./copyprops');
 const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
@@ -23,5 +24,5 @@ module.exports =
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
-  MethodFilter,
+  MethodFilter, apply,
 }