@lumjs/core 1.25.0 → 1.25.2

package/lib/traits.js

@@ -9,15 +9,32 @@ const getProp = require('./obj/getproperty');
 
 const 
 {
-  def,F,B,
+  def,F,B,S,
   isObj,isArray,isConstructor,isProperty,
-  needObj,
+  needObj,needType,
 } = require('./types');
 
 // Symbol for private storage of composed traits.
 const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
 
-// Protected function to get a class prototype.
+/**
+ * For when we need a prototype object exclusively.
+ * 
+ * @param {(function|object)} from - Target
+ * 
+ * May either be a class constructor `function`, or a prototype `object`.
+ * 
+ * @returns {object}
+ * 
+ * If `from` is an `object` it will be returned as-is.
+ * If `from` is a `function` then `from.prototype` will be returned.
+ * 
+ * @throws {TypeError} If `from` was not a valid value;
+ * including if it is a `function` but does not have a valid
+ * prototype object to return.
+ * 
+ * @alias module:@lumjs/core/traits.ensureProto
+ */
 function ensureProto(from)
 {
   if (isObj(from))
@@ -54,7 +71,8 @@ const IGNORE_STATIC =
   // Possible properties from `function` values.
   'length', 'name', 'arguments', 'caller', 'prototype',
   // Defined static methods from the Trait abstract class.
-  'composeInto', 'setupTrait', 'getComposed', 'decomposeFrom', 'removeTrait',
+  'composeInto', 'setupTrait', 'getComposed', 'decomposeFrom', 
+  'removeTrait', 'removedTrait',
   // Optional static getter properties for the Trait abstract class.
   'composeOptions', 'staticOptions',
 ];
@@ -65,9 +83,21 @@ const IGNORE_STATIC =
  * @param {(function|object)} target - Target to look in.
  * @param {(function|object)} [source] Source trait to get defs for.
  * 
+ * @param {boolean} [tryClass=true] Try the class constructor as well?
+ * 
+ * If this is `true` (the default value), then we will also look in 
+ * the `target.constructor` IF the `target` is an `object` and EITHER 
+ * one of these is true:
+ * 
+ * - The specified `source` was NOT composed into the `target` directly.
+ * - No `source` was specified, and the `target` has NO traits composed
+ *   directly into itself.
+ * 
+ * Set this to `false` to only ever consider the `target` itself.
+ * 
  * @returns {mixed} Return value depends on a few factors.
  * 
- * If NO traits have been composed into the `target`, returns `null`.
+ * If NO traits have been composed into the `target`, always returns `null`.
  * 
  * If NO `source` argument was passed, then this will return a `Map` where
  * the keys will be a full set of `source` traits that have been composed, 
@@ -78,14 +108,13 @@ const IGNORE_STATIC =
  * the return value will be the {@link module:@lumjs/core/traits~Composed}
  * object for the trait.
  * 
- * If the specified `source` trait has *never* been composed, but at least
- * one other trait has been, this will return `undefined`.
+ * If the specified `source` trait has *never* been composed, returns `null`.
  * 
  * @throws {TypeError} If `target` is not valid.
  * 
  * @alias module:@lumjs/core/traits.getComposed
  */
-function getComposed(target, source)
+function getComposed(target, source, tryClass=true)
 {
   needObj(target, true,  'invalid target');
 
@@ -95,15 +124,20 @@ function getComposed(target, source)
   {
     composed = target[COMPOSED_TRAITS];
   }
-  else if (isObj(target))
-  {
-    return getComposed(target.constructor, source);
-  }
 
-  if (composed && source)
+  if (composed && source && composed.has(source))
   { // Let's get definitions for a specific trait.
     return composed.get(source);
   }
+  else if (composed && !source)
+  { // No trait specified, but compose rules found.
+    return composed;
+  }
+
+  if (tryClass && isObj(target))
+  { // Try the class constructor.
+    return getComposed(target.constructor, source);
+  }
 
   return composed;
 }
@@ -116,7 +150,8 @@ function mapComposed(target, source)
     def(target, COMPOSED_TRAITS, {value: new Map()});
   }
 
-  const composed = {proto: null, static: null};
+  const forClass = isConstructor(target);
+  const composed = {proto: null, static: null, forClass};
   target[COMPOSED_TRAITS].set(source, composed);
   return composed;
 }
@@ -580,41 +615,69 @@ class CoreTrait
    * 
    * @param {(function|object)} target 
    * @param {object} [opts] 
-   * @returns {object} Return value from the `removeTrait()` static method.
+   * @returns {object} Return value from the `removedTrait()` static method.
    */
   static decomposeFrom(target, opts)
   {
-    const info = {target};
+    const info = {target, ok:true};
     info.composed = this.getComposed(target);
-    info.count = decompose(target, this, opts);
-    return this.removeTrait(info);
+    this.removeTrait(info);
+
+    if (info.ok)
+    {
+      info.count = decompose(target, this, opts);
+    }
+
+    return this.removedTrait(info);
   }
 
   /**
    * A static method called by `decomposeFrom()`
-   * _after_ decomposing the trait properties from the target.
+   * _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 {number} info.count - The number of properties decomposed.
+   * @param {boolean} info.ok - Will always be `true` initially.
+   * 
+   * If an overridden `removeTrait()` method sets this to `false`,
+   * then the `decomposeFrom()` operation will be cancelled before
+   * decomposing the trait.
+   * 
+   */
+  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 an overridden `removeTrait()` method in the sub-class.
+   * 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 removeTrait(info)
+  static removedTrait(info)
   {
     if (this.debug)
     {
-      console.debug(this.name, "removeTrait()", info, this);
+      console.debug(this.name, "removedTrait()", info, this);
     }
     return info;
-  }  
+  }
 
   /**
    * A method wrapping {@link module:@lumjs/core/traits.getComposed}
@@ -630,14 +693,67 @@ class CoreTrait
 
 } // 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 = 
 {
-  // The main public exports.
   compose, composeFully, getComposed, decompose,
-  Trait: CoreTrait, IGNORE_STATIC,
+  Trait: CoreTrait, IGNORE_STATIC, ensureProto,
+  makeRegistry: makeTraitRegistry,
 
-  // Undocumented protected functions.
-  ensureProto, hasOwn,
+  // Undocumented:
+  hasOwn,
 }
 
 /**
@@ -657,6 +773,13 @@ module.exports =
  * 
  * Exactly the same description as `proto`, but for static properties.
  * 
+ * @prop {boolean} forClass - Are these property maps from a class?
+ * 
+ * Will be `true` if the original target was a `function`, or `false`
+ * otherwise. Only really useful when trait functions need to be called
+ * differently depending on if the trait was applied to an individual
+ * instance or a class constructor.
+ * 
  */
 
 /**

package/package.json

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