@lumjs/core 1.35.1 → 1.36.0

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.36.0",
   "main": "lib/index.js",
   "exports": 
   {