@lumjs/core 1.36.0 → 1.37.0

package/lib/events/listener.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const {F,isObj} = require('../types');
+const {F,isObj,def} = require('../types');
 const Event = require('./event');
 
 const REMOVE_OPTS = ['listener','handler','eventNames'];
@@ -127,6 +127,10 @@ class LumEventListener
     return event;
   }
 
+  static get classProps()
+  {
+    return Object.getOwnPropertyNames(this.prototype);
+  }
 }
 
 LumEventListener.isListener = isListener;

package/lib/events/registry.js

@@ -3,6 +3,7 @@
 const {S,F,isObj,def,isIterable} = require('../types');
 const Listener = require('./listener');
 const RegSym = Symbol('@lumjs/core/events:registry');
+const cp = Object.assign;
 
 const DEF_EXTENDS =
 {
@@ -13,6 +14,13 @@ const DEF_EXTENDS =
   once:     null,
 }
 
+const INT_EXTENDS =
+{
+  listeners: true,
+  results:   true,
+  onDemand:  false,
+}
+
 const DEF_OPTIONS =
 {
   delimiter: /\s+/,
@@ -20,6 +28,12 @@ const DEF_OPTIONS =
   wildcard: '*',
 }
 
+const RES_PROPS =
+[
+  'eventNames', 'targets', 'multiMatch', 'onceRemoved', 'stopEmitting',
+  'emitted', 'targetListeners', 'registry',
+]
+
 /**
  * Has a target object been registered with an event registry?
  * @param {object} target 
@@ -98,29 +112,53 @@ class LumEventRegistry
    * If you want to use a `function` as an actual target, you'll need to
    * wrap it in an array or other iterable object.
    * 
-   * @param {object} [opts] Options (saved to `options` property).
+   * @param {object} [opts] Options
+   * 
+   * A _compiled_ version is saved to the `options` property.
+   * The compiled version includes a bunch of defaults, and various
+   * compose rules (mostly for the `.extend` nested options).
    * 
    * @param {(RegExp|string)} [opts.delimiter=/\s+/] Used to split event names
    * 
-   * @param {(object|boolean)} [opts.extend]
-   * This option determines the rules for adding wrapper methods and
-   * other extension properties to the target objects.
+   * @param {object} [opts.extend] Options for wrapper methods/properties
+   * 
+   * The `boolean` options determine if extension methods will be added to
+   * certain types of objects (and in some cases, when to do so).
    * 
-   * If this is `true` (default when `targets` is an `object`), then
-   * the target objects will be extended using the default property names.
+   * The `?string` options are each the names of properties/methods in the
+   * Registry class. If they are set to a `string` then that will be the
+   * name used for the wrapper property/method added to objects. If it
+   * is explicitly set to `null` it means skip adding a wrapper for that
+   * method/property. If it is omitted entirely the default will be used.
    * 
-   * If this is set to `false` (default when `targets` is a `function`), 
-   * it disables adding extension properties entirely.
+   * @param {boolean} [opts.extend.targets] Extend target objects?
    * 
-   * If it is an `object` then each nested property may be set to a string
-   * to override the default, or `null` to skip adding that property.
+   * The default will be `true` when `targets` is an `object`, or `false`
+   * when `targets` is a `function`.
+   * 
+   * @param {boolean} [opts.extend.listeners=true] Extend Listener instances?
+   * As returned by `makeListener()`, `listen()`, and `once()`
+   * @param {boolean} [opts.extend.results=true] Extend `emit()` results?
+   * @param {boolean} [opts.extend.onDemand=false] On-demand target setup
+   * 
+   * If `targets` was a `function` and this is set to `true`, then
+   * we'll perform the target setup on every emit() call. The setup process
+   * is skipped on any targets that have already been set up, so this
+   * is meant for dynamic targets that may change on every call.
+   * 
+   * @param {?string} [opts.extend.registry="events"] Registry property;
+   * only added to `targets`, never to listeners or results which have
+   * their own inherent `registry` property already.
    * 
-   * @param {?string} [opts.extend.registry="events"] Registry property
    * @param {?string} [opts.extend.emit="emit"] `emit()` proxy method
    * @param {?string} [opts.extend.listen="on"] `listen()` proxy method
    * @param {?string} [opts.extend.once=null]   `once()` proxy method
    * @param {?string} [opts.extend.remove=null] `remove()` proxy method
    * 
+   * The `remove` wrapper method added to Listener instances is slightly
+   * different than the one added to other objects, as if you call it
+   * with no arguments, it will pass the Listener itself as the argument.
+   * 
    * @param {boolean} [opts.multiMatch=false]
    * If a registered listener has multiple event names, and a call
    * to `emit()` also has multiple event names, the value of this
@@ -159,7 +197,7 @@ class LumEventRegistry
    */
   constructor(targets, opts={})
   {
-    let defExt; // Default opts.extend value
+    let defExt; // Default opts.extend.targets value
     if (typeof targets === F)
     { // A dynamic getter method
       this.funTargets = true;
@@ -181,47 +219,53 @@ class LumEventRegistry
       defExt = true;
     }
 
-    this.options = Object.assign({extend: defExt}, DEF_OPTIONS, opts);
+    // Build composite extend rules
+    const extend = cp(
+      {targets: defExt}, 
+      INT_EXTENDS, 
+      DEF_EXTENDS, 
+      opts.extend);
+
+    // Now compile the final options
+    this.options = cp({}, DEF_OPTIONS, opts, {extend});
 
     this.allListeners = new Set();
     this.listenersFor = new Map();
 
-    this.extend(targets);
+    this.setupTargets(targets);
   } // constructor()
 
   /**
-   * Add extension methods to target objects;
-   * used by `constructor` and `register()`,
-   * not meant to be called from outside code.
+   * Set up target objects
+   * 
+   * Always sets the necessary metadata on each target.
+   * May also extend the targets with wrapper properties and methods
+   * depending on the `options.extend` values set.
+   * 
+   * Not meant to be called from outside code.
    * @private
    * @param  {Iterable} targets - Targets to extend
    * @returns {module:@lumjs/core/events.Registry} `this`
    */
-  extend(targets)
+  setupTargets(targets)
   {
     const opts = this.options;
     const extOpts = opts.extend;
-
-    let intNames = null, extNames = null;
-
-    if (extOpts)
-    {
-      intNames = Object.keys(DEF_EXTENDS);
-      extNames = Object.assign({}, DEF_EXTENDS, extOpts);
-    }
+    const intNames = extOpts.targets ? Object.keys(DEF_EXTENDS) : null;
 
     for (const target of targets)
     {
       const tps = {}, tpm = getMetadata(target, true);
+      if (tpm.r.has(this)) continue; // Already set up with this registry.
       tpm.r.set(this, tps);
 
-      if (extOpts)
+      if (extOpts.targets)
       {
         for (const iname of intNames)
         {
-          if (typeof extNames[iname] === S && extNames[iname].trim() !== '')
+          if (typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
           {
-            const ename = extNames[iname];
+            const ename = extOpts[iname];
             const value = iname === 'registry' 
               ? this // The registry instance itself
               : (...args) => this[iname](...args) // A proxy method
@@ -240,6 +284,48 @@ class LumEventRegistry
         }
       }
     }
+
+    return this;
+  }
+
+  /**
+   * Add extension methods to internal objects;
+   * currently supports Listener instances and result/status objects.
+   * Not meant to be called from outside code.
+   * @private
+   * @param {object} obj - Internal object to extend
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  extendInternal(obj)
+  {
+    const opts = this.options;
+    const extOpts = opts.extend;
+    const intNames = Object.keys(DEF_EXTENDS);
+    const isLs = (obj instanceof Listener);
+    const reserved = isLs ? Listener.classProps : RES_PROPS;
+
+    for (const iname of intNames)
+    {
+      if (iname === 'registry') continue; // skip the registry property
+      if (typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
+      {
+        const ename = extOpts[iname];
+        if (reserved.includes(ename))
+        { // Skip reserved names
+          console.warn("reserved property", {ename, obj, registry: this});
+          continue;
+        }
+
+        const value = (isLs && iname === 'remove') 
+          ? (what=obj) => this.remove(what)   // special remove wrapper
+          : (...args) => this[iname](...args) // regular wrapper method
+        if (opts.overwrite || obj[ename] === undefined)
+        {
+          def(obj, ename, {value});
+        }
+      }  
+    }
+
     return this;
   }
 
@@ -305,16 +391,21 @@ class LumEventRegistry
     }
     else if (args.length === 1 && isObj(args[0]))
     { // listen(spec)
-      spec = Object.assign({}, args[0]);
+      spec = cp({}, args[0]);
     }
     else
     { // listen(eventNames, listener, [spec])
-      spec = Object.assign({}, args[2]);
+      spec = cp({}, args[2]);
       spec.eventNames = args[0];
       spec.handler    = args[1];
     }
 
-    return new Listener(this, spec);
+    const lsnr = new Listener(this, spec);
+    if (this.options.extend.listeners)
+    {
+      this.extendInternal(lsnr);
+    }
+    return lsnr;
   }
 
   /**
@@ -524,6 +615,7 @@ class LumEventRegistry
    */
   emit(eventNames, ...args)
   {
+    const extOpts = this.options.extend;
     const sti =
     {
       eventNames: this.getEventNames(eventNames),
@@ -531,11 +623,21 @@ class LumEventRegistry
       onceRemoved: new Set(),
       stopEmitting: false,
       emitted: [],
+      registry: this,
+    }
+
+    if (extOpts.results)
+    {
+      this.extendInternal(sti);
     }
 
     { // Get the targets.
       const tgs = this.getTargets(sti);
       sti.targets = (tgs instanceof Set) ? tgs : new Set(tgs);
+      if (this.funTargets && extOpts.onDemand)
+      {
+        this.setupTargets(sti.targets);
+      }
     }
 
     const wilds = this.listenersFor.get(this.options.wildcard);
@@ -579,8 +681,6 @@ class LumEventRegistry
     return sti;
   }
 
-
-
   /**
    * Register additional target objects
    * @param  {...object} addTargets - Target objects to register
@@ -617,7 +717,7 @@ class LumEventRegistry
       }
     }
 
-    this.extend(addTargets);
+    this.setupTargets(addTargets);
     return this;
   }
 
@@ -735,7 +835,7 @@ class LumEventRegistry
 
 }
 
-Object.assign(LumEventRegistry, 
+cp(LumEventRegistry, 
 { 
   isRegistered, getMetadata, targetsAre,
 });

package/lib/obj/clone.js

@@ -296,6 +296,9 @@ exports.addClone = addClone;
   *
   * If not, if the object has a `clone()` method it will be used.
   * Otherwise use our `clone()` function.
+  * 
+  * **NOTE**: A newer replacement for this function exists, see
+  * {@link module:@lumjs/core/obj.unlocked} for details.
   *
   * @param {object} obj - The object to clone if needed.
   * @param {object} [opts] - Options to pass to `clone()` method.

package/lib/obj/index.js

@@ -14,6 +14,7 @@ const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
 const cp = require('./cp');
+const unlocked = require('./unlocked');
 
 const 
 {
@@ -27,5 +28,5 @@ module.exports =
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
-  MethodFilter, apply, flip, flipKeyVal, flipMap,
+  MethodFilter, apply, flip, flipKeyVal, flipMap, unlocked,
 }

package/lib/obj/unlocked.js

@@ -0,0 +1,87 @@
+"use strict";
+
+const {F,S,isObj,needObj} = require('../types');
+
+const CLONE = 'clone';
+const clone = obj => Object.assign({}, obj);
+
+/**
+ * Get an unlocked object
+ * 
+ * @param {object} obj - The target object;
+ * 
+ * If the object is extensible it will be returned _as is_.
+ * 
+ * If the object is frozen, sealed, or otherwise non-extensible,
+ * a cloning function will be used to make an unlocked copy.
+ * 
+ * @param {(object|function|string)} [opts] Options to customize the behaviour
+ * 
+ * - If this is a `function` it will be used as the `opts.fn` value.
+ * - If this is a `string` it will be used as the `opts.method` value.
+ *
+ * @param {string} [opts.method='clone'] Object method to use
+ * 
+ * Set to an empty string `""` to skip checking for an object method.
+ * 
+ * If the method exists on the target object, it will be called to
+ * perform the cloning procedure, otherwise `opts.fn` will be used.
+ * 
+ * @param {Array} [opts.args] Arguments for `opts.method` method
+ * 
+ * If not specified, the default value is: `[opts]`
+ * 
+ * @param {function} [opts.fn] A function to perform the clone operation
+ *
+ * Must take only a single parameter, which is the object to clone.
+ * Must return an extensible clone of the object.
+ * 
+ * If for whatever reason you need the `opts` in the function,
+ * then use a unbound function, and `opts` will be available
+ * as `this` in the function body. Arrow functions (closures) are 
+ * always considered bound and cannot have a `this` value assigned.
+ * 
+ * The default value is a closure: `obj => Object.assign({}, obj)`;
+ * 
+ * @return {object}
+ *
+ * @alias module:@lumjs/core/obj.unlocked
+ */
+function unlocked(obj, opts={})
+{
+  needObj(obj, true, "invalid obj value");
+  
+  if (Object.isExtensible(obj))
+  { // We're done here.
+    return obj;
+  }
+
+  if (typeof opts === F)
+  {
+    opts = {fn: opts}
+  }
+  else if (typeof opts === S)
+  {
+    opts = {method: opts}
+  }
+  else if (!isObj(opts))
+  {
+    console.error({obj, opts});
+    throw new TypeError("invalid opts value");
+  }
+
+  const fn   = (typeof opts.fn     === F) ? opts.fn            : clone;
+  const meth = (typeof opts.method === S) ? opts.method.trim() : CLONE;
+  const args = (Array.isArray(opts.args)) ? opts.args          : [opts];
+
+  if (meth && typeof obj[meth] === F)
+  { // Use a clone method
+    return obj[meth](...args);
+  }
+  else
+  { // Use a clone function
+    return fn.call(opts, obj);
+  }
+}
+
+module.exports = unlocked;

package/package.json

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