@lumjs/core 1.35.1 → 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/lib/{traits.js → traits/funcs.js}

@@ -1,18 +1,11 @@
-/**
- * A very simplistic Trait system.
- * @module @lumjs/core/traits
- */
-
 "use strict";
 
-const getProp = require('./obj/getproperty');
-
+const getProp = require('../obj/getproperty');
 const 
 {
-  def,F,B,S,
+  def,F,B,needObj,
   isObj,isArray,isConstructor,isProperty,isClassObject,
-  needObj,needType,
-} = require('./types');
+} = require('../types');
 
 // Symbol for private storage of composed traits.
 const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
@@ -568,254 +561,10 @@ function decompose(specTarget, specSource, opts={})
   return c;
 }
 
-/**
- * An abstract class for Traits.
- * 
- * Simply offers a couple static methods and APIs that
- * wrap the `compose()` and `composeFully()` functions,
- * and makes it fairly simple to create Trait classes.
- * 
- * @alias module:@lumjs/core/traits.Trait
- */
-class CoreTrait
-{
-  /**
-   * Extend another class or object instance with the methods and
-   * getter/setter properties from a Trait.
-   * 
-   * The sub-class of Trait this static method is called on will always 
-   * be the `source` argument.
-   * 
-   * @param {(function|object)} target - Target class or instance.
-   * 
-   * @param {object} [protoOpts] Options for `compose()` function.
-   * 
-   * If this is not specified, or is any value other than an `object`,
-   * we will look for defaults in a `composeOptions` static property:
-   * 
-   * ```js
-   * static get composeOptions() { return {your: default, options: here}; }
-   * ```
-   * 
-   * @param {(object|true)} [staticOpts] Static options.
-   * 
-   * If this is set we'll use `composeFully()` instead of using `compose()`.
-   * 
-   * If this value is an `object` it will be used as the `staticOpts`.
-   * 
-   * If this is the special value `true`, then we will look for the options
-   * in a `staticOptions` static property:
-   * 
-   * ```js
-   * static get staticOptions() { return {your: static, options: here}; }
-   * ```
-   * 
-   * If this any value other than an `object` or `true`, it will be ignored
-   * entirely, and the regular `compose()` call will be used.
-   * 
-   * @returns {object} Return value from the `setupTrait()` static method.
-   * 
-   */
-  static composeInto(target, protoOpts, staticOpts)
-  {
-    if (!isObj(protoOpts))
-    {
-      protoOpts = this.composeOptions ?? {};
-    }
-
-    if (staticOpts === true)
-    {
-      staticOpts = this.staticOptions ?? {};
-    }
-
-    let composed;
-
-    if (isObj(staticOpts))
-    {
-      composed = composeFully(target, this, protoOpts, staticOpts);
-    }
-    else
-    {
-      composed = compose(target, this, protoOpts);
-    }
-
-    return this.setupTrait({target, protoOpts, staticOpts, composed});
-  }
-
-  /**
-   * A static method called by `composeInto()`
-   * _after_ composing the trait properties into the target.
-   * 
-   * @param {object} info - Metadata from `composeInto()`
-   * @param {(function|object)} info.target - The `target` argument
-   * @param {object} info.protoOpts - The `protoOpts` used
-   * @param {object} [info.staticOpts] The `staticOpts` if used
-   * @param {module:@lumjs/core/traits~Composed} info.composed 
-   * The return value from `compose()` or `composeFully()`.
-   * 
-   * @returns {object} The `info` object, with any changes made
-   * by an overridden `setupTrait()` method in the sub-class.
-   * 
-   * The default implementation is a placeholder that returns the
-   * `info` object without making any changes.
-   * 
-   */
-  static setupTrait(info)
-  {
-    if (this.debug)
-    {
-      console.debug(this.name, "setupTrait()", info, this);
-    }
-    return info;
-  }
-
-  /**
-   * A method wrapping {@link module:@lumjs/core/traits.decompose}
-   * where the `source` is always the Trait sub-class constructor.
-   * 
-   * See the `decompose()` docs for descriptions of the other arguments.
-   * 
-   * @param {(function|object)} target 
-   * @param {object} [opts] 
-   * @returns {object} Return value from the `removedTrait()` static method.
-   */
-  static decomposeFrom(target, opts)
-  {
-    const info = {target, ok:true};
-    info.composed = this.getComposed(target);
-    this.removeTrait(info);
-
-    if (info.ok)
-    {
-      info.count = decompose(target, this, opts);
-    }
-
-    return this.removedTrait(info);
-  }
-
-  /**
-   * A static method called by `decomposeFrom()`
-   * _before_ decomposing the trait properties from the target.
-   * 
-   * @param {object} info - Metadata from `decomposeFrom()`
-   * @param {(function|object)} info.target - The `target` argument
-   * @param {module:@lumjs/core/traits~Composed} info.composed 
-   * The property map that was previously composed.
-   * @param {boolean} info.ok - Will always be `true` initially.
-   * 
-   * If an overridden `removeTrait()` method sets this to `false`,
-   * then the decomposeFrom() operation will skip the step of
-   * actually decomposing the trait.
-   * 
-   * @returns {*} Return value is not used. 
-   */
-  static removeTrait(info)
-  {
-    if (this.debug)
-    {
-      console.debug(this.name, "removeTrait()", info, this);
-    }
-    return info;
-  }
-
-  /**
-   * A static method called by `decomposeFrom()`
-   * _after_ decomposing the trait properties from the target.
-   * 
-   * @param {object} info - The same as `removeTrait()`, plus:
-   * @param {number} info.count - The number of properties decomposed;
-   * 
-   * @returns {object} The `info` object, with any changes made
-   * by `removeTrait()` and `removedTrait()` methods in the 
-   * sub-class.
-   * 
-   * The default implementation is a placeholder that returns the
-   * `info` object without making any changes.
-   * 
-   */
-  static removedTrait(info)
-  {
-    if (this.debug)
-    {
-      console.debug(this.name, "removedTrait()", info, this);
-    }
-    return info;
-  }
-
-  /**
-   * A method wrapping {@link module:@lumjs/core/traits.getComposed}
-   * where the `source` is always the Trait sub-class constructor.
-   * 
-   * @param {(function|object)} target
-   * @returns {mixed} Return value from `getComposed()`
-   */
-  static getComposed(target)
-  {
-    return getComposed(target, this);
-  }
-
-} // CoreTrait class
-
-/**
- * Build a Trait registry.
- * 
- * @param {object} registry - Object for the registry.
- * 
- * Generally the `exports` from a Node.js module would be good here.
- * 
- * It will have a `Trait` property added, which is an alias to
- * the `Trait` class constructor.
- * 
- * It will also have a `registerTrait(name, value)` function added.
- * This function will add new traits to the registry, using
- * the `name` as its property key. The `value` is either the
- * Trait sub-class constructor `function` itself, or a _lazy-loading_
- * closure `function` that must load and return the actual sub-class
- * constructor when executed. The registry DOES NOT support `object`
- * type traits, or any class that doesn't extend the `Trait` class.
- * 
- * @returns {function} The `registerTrait()` function created above.
- * @alias module:@lumjs/core/traits.makeRegistry
- */
-function makeTraitRegistry(registry={})
-{
-  needObj(registry, false, 'invalid trait registry object');
-
-  def(registry, 'Trait', CoreTrait);
-
-  function registerTrait(name, value)
-  {
-    needType(S, name,  'invalid trait name');
-    needType(F, value, 'invalid trait loader value');
-
-    if (registry[name] !== undefined)
-    {
-      console.error("trait already registered", {name,value,registry});
-      return;
-    }
-
-    if (CoreTrait.isPrototypeOf(value))
-    { // Make it available directly.
-      def(registry, name, value, def.e);
-    }
-    else
-    { // Lazy-loading engaged.
-      def.lazy(registry, name, value, def.e);
-    }
-  }
-
-  def(registry, 'registerTrait', registerTrait);
-
-  return registerTrait;
-}
-
 module.exports = 
 {
   compose, composeFully, getComposed, decompose,
-  Trait: CoreTrait, IGNORE_STATIC, 
-  ensureProto, ensureConstructor,
-  makeRegistry: makeTraitRegistry,
-
+  IGNORE_STATIC, ensureProto, ensureConstructor,  
   // Undocumented:
   hasOwn,
 }

package/lib/traits/index.js

@@ -0,0 +1,13 @@
+/**
+ * A very simplistic Trait system.
+ * @module @lumjs/core/traits
+ */
+
+"use strict";
+
+const funcs = require('./funcs');
+const Trait = require('./trait');
+const regfns = require('./registry');
+
+// Export all the things
+Object.assign(exports, funcs, regfns, {Trait});

package/lib/traits/registry.js

@@ -0,0 +1,166 @@
+"use strict";
+
+const {def,F,S,needObj,needType} = require('../types');
+const Trait = require('./trait');
+
+/**
+ * Get a trait from the specified registry
+ * 
+ * The exported function version of this is not generally called directly.
+ * Instead use the bound `getTrait()` method of a registry object.
+ * 
+ * @alias module:@lumjs/core/traits.getTrait
+ * 
+ * @param {module:@lumjs/core/traits~Registry} registry
+ * @param {(string|function)} trait - Trait to get
+ * 
+ * This should almost always be the name of the trait you want
+ * to get out of this registry.
+ * 
+ * If this happens to be a Trait class constructor already, 
+ * it will be returned as is.
+ * 
+ * @returns {?function} A trait class constructor, or `null` if the
+ * specified trait name does not exist in the registry.
+ */
+function getTrait(registry,trait)
+{
+  if (typeof trait === S)
+  { // Assume a string is the name of a trait in this registry
+    trait = registry[trait];
+  }
+
+  if (typeof trait === F && Trait.isPrototypeOf(trait))
+  {
+    return trait;
+  }
+  else
+  {
+    console.error("invalid trait", {trait});
+    return null;
+  }
+}
+
+/**
+ * Get a bunch of traits from the specified registry
+ * 
+ * The exported function version of this is not generally called directly.
+ * Instead use the bound `getTraits()` method from a registry object.
+ * 
+ * @alias module:@lumjs/core/traits.getTraits
+ * 
+ * @param {module:@lumjs/core/traits~Registry} registry 
+ * @param {Iterable<(string|function)>} inList - List of traits to get
+ * 
+ * Every item from this list will be passed to `getTrait()` to get
+ * the Trait class constructors for the returned set.
+ * 
+ * @param {Set} [outSet=new Set] Will be populated with requested traits
+ * 
+ * @returns {Set} The `outSet` with all traits added to it
+ */
+function getTraits(registry, inList, outSet)
+{
+  if (!outSet)
+  {
+    outSet=new Set();
+  }
+  else if (!(outSet instanceof Set))
+  {
+    console.error({inList, outSet});
+    throw new TypeError("Invalid Set object");
+  }
+
+  for (const ti of inList)
+  {
+    const tc = getTrait(registry, ti);
+    if (tc)
+    {
+      outSet.add(tc);
+    }
+  }
+
+  return outSet;
+}
+
+/**
+ * Register a trait class in a registry
+ * 
+ * The exported function version of this is not generally called directly.
+ * Instead use the bound `registerTrait()` method from a registry object.
+ * 
+ * @function module:@lumjs/core/traits.registerTrait
+ * 
+ * @param {module:@lumjs/core/traits~Registry} registry
+ * @param {string} name - Name to use for the trait in the registry
+ * @param {function} getTrait
+ * 
+ * If the function passed is a class constructor with the `Trait`
+ * class in its prototype chain, it will be used as the trait itself.
+ * 
+ * If it is just a regular function or closure, it will be used as
+ * a lazy-loader that must return the actual class constructor.
+ * 
+ * @param {boolean} [overwrite=false] 
+ * 
+ * @returns {module:@lumjs/core/traits~Registry} The registry object
+ * 
+ * As a special exception to the argument type checking, if you omit both
+ * arguments, then the registry object will be returned immediately.
+ * 
+ * @throws {TypeError} If `name` or `getTrait` were not valid values
+ */
+
+function registerTrait(registry, name, getTrait, overwrite=false)
+{
+  if (name === undefined && getTrait === undefined)
+  { // A special case, return the registry object
+    return registry;
+  }
+
+  needType(S, name,  'invalid trait name');
+  needType(F, getTrait, 'invalid trait loader value');
+
+  if (!overwrite && registry[name] !== undefined)
+  {
+    console.error("trait already registered", {name,getTrait,registry});
+    return registry;
+  }
+
+  if (Trait.isPrototypeOf(getTrait))
+  { // Make it available directly.
+    def(registry, name, getTrait, def.e);
+  }
+  else
+  { // Lazy-loading engaged.
+    def.lazy(registry, name, getTrait, def.e);
+  }
+
+  return registry;
+}
+
+/**
+ * Build a Trait registry.
+ * 
+ * @param {object} [registry={}] Object for the registry
+ * 
+ * Generally the `exports` from a Node.js module would be good here.
+ * The object will have several properties and methods assigned to it
+ * see {@link module:@lumjs/core/traits~Registry} for details. 
+ * 
+ * @returns {function} A 
+ * @alias module:@lumjs/core/traits.makeRegistry
+ */
+function makeTraitRegistry(registry={})
+{
+  needObj(registry, false, 'invalid trait registry object');
+
+  def(registry, 'Trait', Trait);
+  def(registry, 'getTrait', getTrait.bind(registry, registry));
+  def(registry, 'getTraits', getTraits.bind(registry, registry));
+  def(registry, 'registerTrait', registerTrait.bind(registry, registry));
+
+  return registerTrait;
+}
+
+module.exports = makeTraitRegistry;

package/lib/traits/trait.js

@@ -0,0 +1,194 @@
+"use strict";
+
+const {isObj} = require('../types');
+const {getComposed,decompose,compose,composeFully} = require('./funcs');
+
+/**
+ * An abstract class for Traits.
+ * 
+ * Simply offers a couple static methods and APIs that
+ * wrap the `compose()` and `composeFully()` functions,
+ * and makes it fairly simple to create Trait classes.
+ * 
+ * @alias module:@lumjs/core/traits.Trait
+ */
+class CoreTrait
+{
+  /**
+   * Extend another class or object instance with the methods and
+   * getter/setter properties from a Trait.
+   * 
+   * The sub-class of Trait this static method is called on will always 
+   * be the `source` argument.
+   * 
+   * @param {(function|object)} target - Target class or instance.
+   * 
+   * @param {object} [protoOpts] Options for `compose()` function.
+   * 
+   * If this is not specified, or is any value other than an `object`,
+   * we will look for defaults in a `composeOptions` static property:
+   * 
+   * ```js
+   * static get composeOptions() { return {your: default, options: here}; }
+   * ```
+   * 
+   * @param {(object|true)} [staticOpts] Static options.
+   * 
+   * If this is set we'll use `composeFully()` instead of using `compose()`.
+   * 
+   * If this value is an `object` it will be used as the `staticOpts`.
+   * 
+   * If this is the special value `true`, then we will look for the options
+   * in a `staticOptions` static property:
+   * 
+   * ```js
+   * static get staticOptions() { return {your: static, options: here}; }
+   * ```
+   * 
+   * If this any value other than an `object` or `true`, it will be ignored
+   * entirely, and the regular `compose()` call will be used.
+   * 
+   * @returns {object} Return value from the `setupTrait()` static method.
+   * 
+   */
+  static composeInto(target, protoOpts, staticOpts)
+  {
+    if (!isObj(protoOpts))
+    {
+      protoOpts = this.composeOptions ?? {};
+    }
+
+    if (staticOpts === true)
+    {
+      staticOpts = this.staticOptions ?? {};
+    }
+
+    let composed;
+
+    if (isObj(staticOpts))
+    {
+      composed = composeFully(target, this, protoOpts, staticOpts);
+    }
+    else
+    {
+      composed = compose(target, this, protoOpts);
+    }
+
+    return this.setupTrait({target, protoOpts, staticOpts, composed});
+  }
+
+  /**
+   * A static method called by `composeInto()`
+   * _after_ composing the trait properties into the target.
+   * 
+   * @param {object} info - Metadata from `composeInto()`
+   * @param {(function|object)} info.target - The `target` argument
+   * @param {object} info.protoOpts - The `protoOpts` used
+   * @param {object} [info.staticOpts] The `staticOpts` if used
+   * @param {module:@lumjs/core/traits~Composed} info.composed 
+   * The return value from `compose()` or `composeFully()`.
+   * 
+   * @returns {object} The `info` object, with any changes made
+   * by an overridden `setupTrait()` method in the sub-class.
+   * 
+   * The default implementation is a placeholder that returns the
+   * `info` object without making any changes.
+   * 
+   */
+  static setupTrait(info)
+  {
+    if (this.debug)
+    {
+      console.debug(this.name, "setupTrait()", info, this);
+    }
+    return info;
+  }
+
+  /**
+   * A method wrapping {@link module:@lumjs/core/traits.decompose}
+   * where the `source` is always the Trait sub-class constructor.
+   * 
+   * See the `decompose()` docs for descriptions of the other arguments.
+   * 
+   * @param {(function|object)} target 
+   * @param {object} [opts] 
+   * @returns {object} Return value from the `removedTrait()` static method.
+   */
+  static decomposeFrom(target, opts)
+  {
+    const info = {target, ok:true};
+    info.composed = this.getComposed(target);
+    this.removeTrait(info);
+
+    if (info.ok)
+    {
+      info.count = decompose(target, this, opts);
+    }
+
+    return this.removedTrait(info);
+  }
+
+  /**
+   * A static method called by `decomposeFrom()`
+   * _before_ decomposing the trait properties from the target.
+   * 
+   * @param {object} info - Metadata from `decomposeFrom()`
+   * @param {(function|object)} info.target - The `target` argument
+   * @param {module:@lumjs/core/traits~Composed} info.composed 
+   * The property map that was previously composed.
+   * @param {boolean} info.ok - Will always be `true` initially.
+   * 
+   * If an overridden `removeTrait()` method sets this to `false`,
+   * then the decomposeFrom() operation will skip the step of
+   * actually decomposing the trait.
+   * 
+   * @returns {*} Return value is not used. 
+   */
+  static removeTrait(info)
+  {
+    if (this.debug)
+    {
+      console.debug(this.name, "removeTrait()", info, this);
+    }
+    return info;
+  }
+
+  /**
+   * A static method called by `decomposeFrom()`
+   * _after_ decomposing the trait properties from the target.
+   * 
+   * @param {object} info - The same as `removeTrait()`, plus:
+   * @param {number} info.count - The number of properties decomposed;
+   * 
+   * @returns {object} The `info` object, with any changes made
+   * by `removeTrait()` and `removedTrait()` methods in the 
+   * sub-class.
+   * 
+   * The default implementation is a placeholder that returns the
+   * `info` object without making any changes.
+   * 
+   */
+  static removedTrait(info)
+  {
+    if (this.debug)
+    {
+      console.debug(this.name, "removedTrait()", info, this);
+    }
+    return info;
+  }
+
+  /**
+   * A method wrapping {@link module:@lumjs/core/traits.getComposed}
+   * where the `source` is always the Trait sub-class constructor.
+   * 
+   * @param {(function|object)} target
+   * @returns {mixed} Return value from `getComposed()`
+   */
+  static getComposed(target)
+  {
+    return getComposed(target, this);
+  }
+
+} // CoreTrait class
+
+module.exports = CoreTrait;

package/package.json

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