@lumjs/core 1.14.0 → 1.15.0

package/lib/arrays.js

@@ -1,82 +1,314 @@
 /**
- * Array helper functions.
+ * Array (and other list objects) helper functions.
  * @module @lumjs/core/arrays
  */
+const {F,S} = require('./types/js');
+
+/**
+ * A wrapper class to abstract functionality of various kinds of lists.
+ *
+ * Supports `Array`, `Set`, and `Map` explicitly.
+ * Other classes may be supported. YMMV.
+ *
+ * @alias module:@lumjs/core/arrays.List
+ */
+class List
+{
+  /**
+   * A list of known closure properties.
+   *
+   * Corresponding `wrap_${closure}` methods will be used to generate
+   * the closure properties.
+   */
+  static get KNOWN_CLOSURES()
+  {
+    return (Object.getOwnPropertyNames(this.prototype)
+      .filter(name => name.startsWith('wrap_')));
+  }
+
+  /**
+   * Build a new List wrapper.
+   *
+   * @param {object} obj - The list object.
+   *
+   * Typically an `Array`, `Set`, `Map`, or something similar.
+   * Not all of types will support all features. YMMV.
+   *
+   * @param {object} [opts] Options for advanced use.
+   *
+   * @param {bool} [opts.allowRaw=false] Attempt to support raw objects?
+   *
+   * Treat regular Javascript objects as lists, as they are a kind of
+   * map after all. This may lead to unusual results. YMMV.
+   *
+   * @param {mixed} [opts.closures=true] Create closure methods?
+   *
+   * If `true` or `"*"` we will create all known closure properties.
+   *
+   * If an `Array` it's the list of closure names we want to create.
+   * Possible values can be found in `List.KNOWN_CLOSURES`.
+   *
+   * If it's a `string` it's treated as a whitespace separated list
+   * of closure names and split into an `Array`.
+   *
+   * If `false` we won't create any closure properties.
+   *
+   */
+  constructor(obj, opts={})
+  {
+    this.obj = obj;
+    this.opts = opts;
+    this.allowRaw = opts.allowRaw ?? false;
+    this.setupClosures(opts.closures ?? true);  
+  }
+
+  setupClosures(closures)
+  {
+    if (!closures)
+    { // Nothing to do.
+      return;
+    }
+
+    if (closures === true || closures === '*')
+    { // Setup all closures.
+      closures = this.constructor.KNOWN_CLOSURES;
+    }
+    else if (typeof closures === S)
+    {
+      closures = closures.trim().split(/\s+/);
+    }
+    
+    if (Array.isArray(closures))
+    {
+      for (const closure of closures)
+      {
+        const meth = 'wrap_'+closure;
+        if (typeof this[meth] === F)
+        { // Create the detail property.
+          this[closure] = this[meth]();
+        }
+        else
+        {
+          console.error({closure, closures, list: this});
+          throw new Error("Unsupported closure");
+        }
+      }
+    }
+    else
+    {
+      console.error({closures, list: this});
+      throw new TypeError("Invalid closures value");
+    }
+  }
+
+  unsupported(obj, forClosure, info, retVal=false)
+  {
+    console.error("Unsupported object", {obj, forClosure, info, list: this});
+    return () => retVal;
+  }
+
+  /**
+   * Return a closure that returns if an item is in a list object.
+   *
+   * @param {object} obj - The list object the closure will be for.
+   *
+   * May be an `Array`, `Set`, `Map`, or `TypedArray` or any object
+   * that has either an `includes()` or `has()` method.
+   *
+   * @returns {function}
+   * @throws {TypeError}
+   */
+  wrap_contains(obj=this.obj, allowRaw=this.allowRaw)
+  {
+    if (typeof obj.includes === F)
+    { // Array and TypedArray have includes()
+      return item => obj.includes(item);
+    }
+    else if (typeof obj.has === F)
+    { // Set and Map have has()
+      return item => obj.has(item);
+    }
+    else if (allowRaw)
+    { // A fallback to raw object search.
+      return item => (typeof obj[item] !== undefined);
+    }
+    else
+    { // Nope.
+      return this.unsupported(obj, 'contains', {allowRaw});
+    }
+  }
+
+  /**
+   * Return a closure that removes an item from a list.
+   *
+   * @param {object} obj - The list object the closure will be for.
+   *
+   * May be an `Array`, `Set`, `Map`, or anything with a `delete()` method.
+   *
+   * @returns {function}
+   * @throws {TypeError}
+   */
+  wrap_remove(obj=this.obj, allowRaw=this.allowRaw)
+  {
+    let closure;
+    if (Array.isArray(obj))
+    { // Arrays have no easy method to do this.
+      closure = function(item) 
+      {
+        let removed = 0;
+        let index = obj.indexOf(item);
+        while (index !== -1)
+        {
+          obj.splice(index, 1);
+          removed++;
+          index = obj.indexOf(item, index);
+        }
+        return removed;
+      }
+    }
+    else if (typeof obj.delete === F)
+    { // Use the delete() method.
+      closure = item => (obj.delete(item) ?  1 : 0);
+    }
+    else if (allowRaw)
+    { // Fallback to removing the property.
+      closure = function(item)
+      {
+        if (obj[item] === undefined)
+        {
+          return 0;
+        }
+        else
+        {
+          return (delete obj[item] ? 1 : 0);
+        }
+      }
+    }
+    else
+    { // Nada.
+      closure = this.unsupported(obj, 'remove', {allowRaw}, 0);
+    }
+    return closure;
+  }
+
+  /** 
+   * See if our list object contains *any* of the specified items.
+   *
+   * @param  {...any} items 
+   * @returns {boolean}
+   */
+  containsAny(...items)
+  {
+    for (const item of items)
+    {
+      if (this.contains(item))
+      { // Item found.
+        return true;
+      }
+    }
+ 
+    // No items found.
+    return false;
+  }
+
+  /**
+    * See if our list contains *all* of the specified items.
+    *
+    * @param  {...any} items 
+    * @returns {boolean}
+    */
+  containsAll(...items)
+  {
+    for (const item of items)
+    {
+      if (!this.contains(item))
+      { // An item was missing.
+        return false;
+      }
+    }
+    // All items found.
+    return true;
+  }
+
+  /**
+   * Remove items from our list object.
+   * 
+   * Passed any number of items, it will see if any of those items are
+   * found in the array, and if they are, will remove them from the array.
+   * 
+   * @param  {...any} items 
+   * @returns {number} Number of items actually removed.
+   */
+  removeAll(...items)
+  {
+    let removed = 0;
+    for (const item of items)
+    {
+      removed += this.remove(item);
+    }
+    return removed;
+  }
+
+  /**
+   * Return a List instance for the passed object.
+   *
+   * If the object is already a `List` it is returned as is.
+   *
+   * @param {object} obj - The list object.
+   * @param {object} [opts] - Passed to constructor.
+   */
+  static for(obj, opts)
+  {
+    return (obj instanceof this) ? obj : new this(obj, opts);
+  }
+}
+
+const CONTAINS_OPTS = {closures: ['contains']};
 
 /** 
- * See if an array contains *any* of the specified items.
- * @param {Array} array 
+ * See if an list object contains *any* of the specified items.
+ *
+ * @param {object} list - A `List` or object for `new List(list)`;
  * @param  {...any} items 
  * @returns {boolean}
  * @alias module:@lumjs/core/arrays.containsAny
  */
- function containsAny(array, ...items)
- {
-   for (const item of items)
-   {
-     if (array.includes(item))
-     { // Item found.
-       return true;
-     }
-   }
- 
-   // No items found.
-   return false;
- }
- 
- exports.containsAny = containsAny;
+function containsAny(list, ...items)
+{
+  return List.for(list, CONTAINS_OPTS).containsAny(...items);
+}
 
  /**
-  * See if an array contains *all* of the specified items.
-  * @param {Array} array
+  * See if a list contains *all* of the specified items.
+  *
+  * @param {object} list - A `List` or object for `new List(list)`;
   * @param  {...any} items 
   * @returns {boolean}
   * @alias module:@lumjs/core/arrays.containsAll
   */
- function containsAll(array, ...items)
- {
-   for (const item of items)
-   {
-     if (!array.includes(item))
-     { // An item was missing.
-       return false;
-     }
-   }
-   
-   // All items found.
-   return true;
- }
-
- exports.containsAll = containsAll;
- 
+function containsAll(list, ...items)
+{
+  return List.for(list, CONTAINS_OPTS).containsAll(...items);
+}
+
+const REMOVE_OPTS = {closures: ['remove']};
+
 /**
- * Remove items from an array.
+ * Remove items from a list object.
  * 
  * Passed any number of items, it will see if any of those items are
  * found in the array, and if they are, will remove them from the array.
  * 
- * @param {Array} array 
+ * @param {object} list - A `List` or object for `new List(list)`; 
  * @param  {...any} items 
  * @returns {number} Number of items actually removed.
  * @alias module:@lumjs/core/arrays.removeItems
  */
-function removeItems(array, ...items)
+function removeItems(list, ...items)
 {
-  let removed = 0;
-  for (const item of items)
-  {
-    const index = array.indexOf(item);
-    if (index !== -1)
-    {
-      array.splice(index, 1);
-      removed++;
-    }
-  }
-  return removed;
+  return List.for(list, REMOVE_OPTS).removeAll(...items);
 }
 
-exports.removeItems = removeItems;
-
 /**
  * Return a Powerset of values in the array.
  * @param {Array} array  The array to make the powerset from.
@@ -99,8 +331,6 @@ function powerset(array)
   return ps;
 }
 
-exports.powerset = powerset;
-
 /**
  * Get a random element from an array.
  * @param {Array} array  The array to get an item from.
@@ -112,4 +342,9 @@ function random(array)
   return array[Math.floor(Math.random()*array.length)];
 }
 
-exports.random = random;
+module.exports = exports =
+{
+  List, containsAny, containsAll,
+  removeItems, powerset, random,
+}
+

package/lib/index.js

@@ -33,47 +33,44 @@ const def = types.def;
  */
 const lazy = types.lazy;
 
-// A descriptor template for def/lazy.
-const E = def.e;
-
-def(exports, 'types', types, E);
-def(exports, 'def',   def,   E);
-def(exports, 'lazy',  lazy,  E);
+def(exports, 'types', types);
+def(exports, 'def',   def);
+def(exports, 'lazy',  lazy);
 
 /**
  * Array utility functions «Lazy»
  * @name module:@lumjs/core.arrays
  * @type {module:@lumjs/core/arrays}
  */
-lazy(exports, 'arrays', () => require('./arrays'), E);
+lazy(exports, 'arrays', () => require('./arrays'));
 
 /**
  * Information about the JS context we're running in
  * @name module:@lumjs/core.context
  * @type {module:@lumjs/core/context}
  */
-def(exports, 'context', require('./context'), E);
+def(exports, 'context', require('./context'));
 
 /**
  * Functions for working with strings and locales «Lazy»
  * @name module:@lumjs/core.strings
  * @type {module:@lumjs/core/strings}
  */
-lazy(exports, 'strings', () => require('./strings'), E);
+lazy(exports, 'strings', () => require('./strings'));
 
 /**
  * Functions for working with binary flags «Lazy»
  * @name module:@lumjs/core.flags
  * @type {module:@lumjs/core/flags}
  */
-lazy(exports, 'flags', () => require('./flags'), E);
+lazy(exports, 'flags', () => require('./flags'));
 
 /**
  * Functions for manipulating objects «Lazy»
  * @name module:@lumjs/core.obj
  * @type {module:@lumjs/core/obj}
  */
-lazy(exports, 'obj', () => require('./obj'), E);
+lazy(exports, 'obj', () => require('./obj'));
 
 /**
  * Functions for getting values and properties with fallback defaults «Lazy»
@@ -88,7 +85,7 @@ function from(submod, ...libs)
 {
   for (const lib of libs)
   {
-    def(exports, lib, submod[lib], E);
+    def(exports, lib, submod[lib]);
   }
 }
 
@@ -133,7 +130,7 @@ from(meta, 'stacktrace', 'AbstractClass', 'Functions', 'NYI');
  * @function
  * @see module:@lumjs/core/enum
  */
-lazy(exports, 'Enum', () => require('./enum'), E);
+lazy(exports, 'Enum', () => require('./enum'));
 
 /**
  * Make an object support the *Observable* API «Lazy»
@@ -141,4 +138,5 @@ lazy(exports, 'Enum', () => require('./enum'), E);
  * @function
  * @see module:@lumjs/core/observable
  */
-lazy(exports, 'observable', () => require('./observable'), E);
+lazy(exports, 'observable', () => require('./observable'));
+

package/package.json

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