@lumjs/core 1.13.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/context.js

@@ -6,18 +6,42 @@
  * describing the current JS environment and execution context.
  * 
  * @module @lumjs/core/context
- * @property {boolean} AMD - AMD (*RequireJS*) module loading detected.
- * @property {boolean} CJS - CommonJS environment detected.
+ * @property {boolean} hasDefine - A global `define()` function was found.
  * @property {boolean} hasRequire - A global `require()` function was found.
- * @property {boolean} hasExports - A global `exports` object was found.
+ * @property {boolean} hasExports - A global `exports` variable was found.
  * @property {boolean} hasModule - A global `module` object was found.
- * @property {boolean} isNode - Is likely *Node.js*, *Electron*, etc.
+ * @property {boolean} hasModuleExports - A `module.exports` exists.
+ * @property {boolean} hasSyncedExports - `exports === module.exports`
+ * @property {boolean} isNode - An alias to `Node.ok`.
  * @property {boolean} isBrowser - A web-browser environment detected.
  * @property {boolean} isWindow - Is a browser `Window` context.
  * @property {boolean} isWorker - Is a browser `Worker` (sub-types below.)
  * @property {boolean} isServiceWorker - Is a `ServiceWorker` context.
  * @property {boolean} isDedicatedWorker - Is a `DedicatedWorker` context.
  * @property {boolean} isSharedWorker - Is a `SharedWorker` context.
+ * @property {object} AMD - Asynchronous Module Definition detection.
+ * @property {boolean} AMD.isSupported - The `define.amd` property is set.
+ * @property {boolean} AMD.isRequireJS - A global `requirejs` was found.
+ * @property {object} CJS - CommonJS detection.
+ * @property {boolean} CJS.standard - `hasDefine && hasRequire`
+ * @property {boolean} CJS.nodeLike - `CJS.standard && hasExports`
+ * @property {boolean} CJS.isLumV5 - Lum.js browser bundler detected.
+ * @property {boolean} CJS.isWebpack - Webpack bundler detected.
+ * @property {boolean} CJS.inBrowser - `CJS.isLumV5 || CJS.isWebpack`
+ * @property {object} Node - Node.js detection.
+ * @property {boolean} Node.isSane - `CJS.nodeLike && !CJS.inBrowser`
+ * @property {boolean} Node.hasProcess - A global `process` object exists.
+ * @property {boolean} Node.ok - `Node.isSane && Node.hasProcess`
+ * @property {?string} Node.ver - `process.versions.node ?? null`
+ * @property {?object} Node.versions - `process.versions ?? null`
+ * @property {Array} Node.args - Command line arguments.
+ * @property {string} Node.script - Command line script name.
+ * @property {object} Electron - Electron detection.
+ * @property {boolean} ok - Electron environment detected.
+ * @property {boolean} isDefault - Is this the default app?
+ * @property {boolean} isBundled - Is this a bundled app?
+ * @property {boolean} isMain - Is this the main renderer frame?
+ * @property {?string} type - `process.type`
  * @property {object} root - See {@link module:@lumjs/core/types.root}
  */
 
@@ -28,37 +52,72 @@ const rootHas = what => typeof root[what] !== U;
 const cd = def(ctx, true);
 const CJS = {};
 const AMD = {};
+const Node = {};
+const Elec = {};
 const cjs = def(CJS, true);
 const amd = def(AMD, true);
+const node = def(Node, true);
+const elec = def(Elec, true);
 const isLumV5 = typeof module.$lib === O && module.$lib.$cached === module;
 
 cd('hasDefine', typeof define === F)
   ('hasRequire', typeof require === F)
-  ('hasExports', typeof exports !== U)
+  ('hasExports', typeof exports !== U && isComplex(exports))
   ('hasModule', typeof module === O && module !== null)
-  ('hasModuleExports', isComplex(module.exports))
-  ;
+  ('hasModuleExports', ctx.hasModule && isComplex(module.exports))
+  ('hasSyncedExports', ctx.hasExports && ctx.hasModuleExports 
+    && exports === module.exports)
 
 cjs('standard', ctx.hasModule && ctx.hasRequire)
    ('nodeLike', CJS.standard && ctx.hasExports)
    ('isLumV5', CJS.nodeLike && isLumV5)
    ('isWebpack', CJS.nodeLike && require.resolve === require)
    ('inBrowser', CJS.isLumV5 || CJS.isWebpack)
-   ;
+
+node('isSane', CJS.nodeLike && !CJS.inBrowser)
+    ('hasProcess', typeof process === O && process !== null)
+    ('ok', Node.isSane && Node.hasProcess)
+    ('versions', Node.hasProcess ? process.versions : null)
+    ('ver', Node.hasProcess ? process.versions.node : null)
+    ('args', {get: function()
+    { // Inspired by yargs hideBin() function.
+      if (Node.ok)
+      {
+        const o = (Elec.isBundled) ? 1 : 2;
+        return process.argv.slice(o);
+      }
+      return [];
+    }})
+    ('script', {get: function()
+    { // Inspired by yargs getProcessArgvBin() function.
+      if (Node.ok)
+      {
+        const i = (Elec.isBundled) ? 0 : 1;
+        return process.argv[i];
+      }
+      return '';
+    }})
+
+elec('ok', Node.ok && !!Node.versions.electron)
+    ('isDefault', Elec.ok && !!process.defaultApp)
+    ('isBundled', Elec.ok && !process.defaultApp)
+    ('isMain', Elec.ok && !!process.isMainFrame)
+    ('type', Elec.ok && process.type)
 
 amd('isSupported', ctx.hasDefine && isObj(define.amd))
    ('isRequireJS', AMD.isSupported && typeof requirejs === F)
 
 cd('CJS', CJS)
   ('AMD', AMD)
-  ('isNode', CJS.nodeLike && !CJS.inBrowser)
-  ('isWindow', rootHas('window'))
+  ('Node', Node)
+  ('Electron', Elec)
+  ('isNode', Node.ok)
+  ('isWindow', typeof Window === F && rootHas(window))
   ('isWorker', rootHas('WorkerGlobalScope'))
   ('isServiceWorker', rootHas('ServiceWorkerGlobalScope'))
   ('isDedicatedWorker', rootHas('DedicatedWorkerGlobalScope'))
   ('isSharedWorker', rootHas('SharedWorkerGlobalScope'))
   ('isBrowser', !ctx.isNode && (ctx.isWindow || ctx.isWorker))
-  ;
 
 /**
  * See if a root-level name is defined.

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.13.0",
+  "version": "1.15.0",
   "main": "lib/index.js",
   "exports":
   {