@lumjs/core 1.16.0 → 1.19.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/{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

@@ -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
@@ -72,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/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;