@lumjs/core 1.34.0 → 1.35.1

package/lib/events/index.js

@@ -10,6 +10,9 @@
  * 
  * @module @lumjs/core/events
  */
+
+const lazy = require('../types/lazy');
+
 exports = module.exports =
 {
   Registry: require('./registry'),
@@ -50,7 +53,41 @@ exports = module.exports =
    */
   observable(target, opts)
   {
-    const {makeObservable} = require('./observable');
+    const {makeObservable} = exports.Observable;
     return makeObservable(target, opts);
   },
+
+  /**
+   * See if an object has a known trigger method.
+   * 
+   * Currently will look for one of:
+   * 
+   * - `emit`
+   * - `trigger`
+   * 
+   * @param {object} obj - Object we want to find a trigger method on
+   * 
+   * @returns {?string} The name of the method found,
+   * or null if none found.
+   */
+  hasTrigger(obj)
+  {
+    for (const trigger of exports.KNOWN_TRIGGERS)
+    {
+      if (typeof obj[trigger] === F)
+      {
+        return trigger;
+      }
+    }
+    
+    return null;
+  },
+
+  /**
+   * The list of known trigger method names for `hasTrigger()`
+   */
+  KNOWN_TRIGGERS: ['emit','trigger'],
+
 }
+
+lazy(exports, 'Observable', () => require('./observable'));

package/lib/events/observable.js

@@ -4,7 +4,7 @@
  */
 "use strict";
 
-const {B,F,S,def} = require('../types');
+const {B,F,S,def,isComplex,TYPES} = require('../types');
 const lock = Object.freeze;
 const copy = Object.assign;
 const Registry = require('./registry');
@@ -41,12 +41,10 @@ const OBS_OPTIONS =
  * A few obscure features that I don't think are particularly
  * important and won't affect *most* exising uses will be dropped.
  * 
- * @param {(object|function)} el - The target we're making observable
- * @param {object} [oo] 
- * {@link module:@lumjs/core/observable Observable} options;
+ * @param {(object|function)} el - The target to add observable API to.
  * 
- * The `addre` and `reinherit` options are not supported.
- * All the other ones should try to work mostly the same.
+ * @param {object} [oo] 
+ * {@link module:@lumjs/core/observable Observable} options
  * 
  * @param {boolean} [oo.addwrap] If this is `true`, 
  * and `oo.wrapargs` is `false`, then the `event` object 
@@ -69,10 +67,16 @@ const OBS_OPTIONS =
  * 
  * @param {boolean} [wantReg=false] Return the Registry?
  * @returns {object} normally `el`, unless `wantReg` was `true`
+ * @see module:@lumjs/core/observable~API
  * @alias module:@lumjs/core/events/observable.makeObservable
  */
 function makeObservable(el, oo, ro, wantReg=false)
 {
+  if (!isComplex(el))
+  {
+    throw new TypeError("el was not an object or function");
+  }
+
   ro = copy({}, ro);
   ro.extend = copy({}, OBS_EXTENDS, ro.extend);
   ro.setupEvent = setupEvent;
@@ -126,6 +130,7 @@ function makeObservable(el, oo, ro, wantReg=false)
 /**
  * Event setup for observable compatibility
  * @type {module:@lumjs/core/events~SetupEvent}
+ * @alias module:@lumjs/core/events/observable.setupEvent
  */
 function setupEvent(ev)
 {
@@ -150,6 +155,7 @@ function setupEvent(ev)
 /**
  * Listener setup for observable compatibility
  * @type {module:@lumjs/core/events~SetupListener}
+ * @alias module:@lumjs/core/events/observable.setupListener
  */
 function setupListener(ln)
 {
@@ -195,7 +201,43 @@ function setupListener(ln)
   }
 }
 
+/**
+ * See if a value appears to implement the observable API.
+ * 
+ * This is a simple function that relies on duck-typing,
+ * and only looks for `trigger` and `on` methods.
+ * 
+ * @param {(object|function)} obj - Value to check for observable API
+ * @returns {boolean}
+ * @alias module:@lumjs/core/events/observable.isObservable
+ */
+function isObservable(obj)
+{
+  return (isComplex(obj)
+    && typeof obj.trigger === F
+    && typeof obj.on === F);
+}
+
+// Undocumented alias for the sake of compatibility.
+def(makeObservable, 'is', isObservable);
+
+/**
+ * Does a value implement the Observable interface?
+ * @name module:@lumjs/core/types.doesObservable
+ * @function
+ * @param {*} v - The expected object/function to test.
+ * @returns {boolean}
+ * @see module:@lumjs/core/events/observable.isObservable
+ */
+
+/**
+ * Extension type for the {@link module:@lumjs/core/observable~API} interface.
+ * @memberof module:@lumjs/core/types.TYPES
+ * @member {string} OBSERV - Implements the *Observable* interface.
+ */
+TYPES.add('OBSERV', 'observable', isObservable, 'doesObservable');
+
 module.exports =
 {
-  makeObservable, setupEvent, setupListener,
+  makeObservable, setupEvent, setupListener, isObservable,
 }

package/lib/events/registry.js

@@ -225,19 +225,16 @@ class LumEventRegistry
             const value = iname === 'registry' 
               ? this // The registry instance itself
               : (...args) => this[iname](...args) // A proxy method
-            for (const target of targets)
+            if (opts.overwrite || target[ename] === undefined)
             {
-              if (opts.overwrite || target[ename] === undefined)
-              {
-                def(target, ename, {value});
-                tps[ename] = iname;
-                tpm.p[ename] = this;
-              }
-              else
-              {
-                console.error("Won't overwrite existing property",
-                  {target,iname,ename,registry: this});
-              }
+              def(target, ename, {value});
+              tps[ename] = iname;
+              tpm.p[ename] = this;
+            }
+            else
+            {
+              console.error("Won't overwrite existing property",
+                {target,iname,ename,registry: this});
             }
           }
         }

package/lib/observable.js

@@ -1,15 +1,36 @@
-// Defining these after observable.
-const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');
-const lock = Object.freeze;
-const copy = Object.assign;
+/**
+ * Observable API module
+ * @module @lumjs/core/observable
+ */
+"use strict";
+
+const {B,S,def} = require('./types');
+const orig = require('./old/observable');
+const evob = require('./events/observable');
 
 /**
- * Make a target object (or function) support the *Observable* API.
- *
- * Adds `on()`, `off()`, `one()`, and `trigger()` methods.
+ * Make a target object (or function) support the observable API.
+ * 
+ * There are currently two implementations of the observable API,
+ * and this function will determine which one to call based on the
+ * arguments passed (if old options or positional arguments are
+ * detected, the original implementation will be called, otherwise
+ * the new events-based implementation will be called.)
  * 
- * @param {(object|function)} el - The target we are making observable.
+ * When the older implementation is removed, this function will be
+ * replaced by a simple alias to `makeObservable`.
+ * 
+ * NOTE: this function is the *actual* exported value of the `observable`
+ * module, but it's also available as `observable.auto` and that is how
+ * it's being documented (as jsdoc doesn't like functions being treated
+ * like objects with methods defined on them, but I do that a lot.)
+ * 
+ * @param {(object|function)} el - The target to add observable API to.
  * @param {object} [opts] Options that define behaviours.
+ * 
+ * If the `addre` and `reinherit` options are detected, then the original
+ * implementation will be used.
+ * 
  * @param {string} [opts.wildcard='*'] The event name used as a wildcard. 
  * 
  * @param {boolean} [opts.wrapargs=false] If `true`, the event handlers will 
@@ -76,335 +97,57 @@ const copy = Object.assign;
  * to the `el` object, which is a version of `observable()` with the
  * default options being the same as the current `opts`.
  * 
- * @param {string} [opts.addre] If set, add a method with this name
- * to the `el` object, which is a function that can re-build the
- * observable API methods with new `opts` replacing the old ones.
- * 
- * The method added takes two arguments, the first being an `object`
- * representing the new options to set on the target. 
+ * @param {(boolean|object)} [arg3] Version dependent argument.
  * 
- * The second is an optional `boolean` value that determines if the
- * existing `opts` should be used as defaults for any options not
- * specified in the first argument.
+ * If this is a `boolean` then the original observable implementation
+ * will be called and this will be the `redefine` argument.
  * 
- * @param {boolean} [opts.reinherit=false] Used as the default value of
- * the second argument of the method added by `opts.addre`.
+ * Otherwise it's assumed to be the `ro` argument of the `makeObservable`
+ * compatibility implementation.
  * 
- * @param {boolean} [redefine=false] If `true` allow targets already
- * implementing the `on()` and `trigger()` methods to be re-initialized.
- * 
- * Generally only needed if you need to change the `opts` for some reason.
- * This is forced to `true` by the method added by `opts.addre`.
- *
  * @returns {object} el
  * 
- * @exports module:@lumjs/core/observable
+ * @see module:@lumjs/core/observable.orig
+ * @see module:@lumjs/core/events/observable.makeObservable
+ * @alias module:@lumjs/core/observable.auto
  */
-function observable (el={}, opts={}, redefine=false) 
+function observable (el={}, opts={}, arg3) 
 {
-  //console.debug("observable", el, opts);
-
-  if (!isComplex(el))
-  { // Don't know how to handle this, sorry.
-    throw new Error("non-object sent to observable()");
-  }
-
-  if (isObservable(el) && !redefine)
-  { // It's already observable.
-    return el;
-  }
-
-  if (typeof opts === B)
-  { // Assume it's the wrapthis option.
-    opts = {wrapthis: opts};
-  }
-  else if (!isObj(opts))
-  {
-    opts = {};
-  }
-
-  const noSpace = /^\S+$/;
-
-  const wildcard = (typeof opts.wildcard === S 
-    && noSpace.test(opts.wildcard))
-    ? opts.wildcard
-    : '*';
-
-  const wrapsetup = (typeof opts.wrapsetup === F)
-    ? opts.wrapsetup 
-    : null;
-
-  const wrapthis = (typeof opts.wrapthis === B) 
-    ? opts.wrapthis 
-    : false;
-
-  const wrapargs = (typeof opts.wrapargs === B)
-    ? opts.wrapargs
-    : (wrapsetup ? !wrapthis : false);
-
-  const wrapped = (wrapthis || wrapargs);
-
-  const wraplock = (typeof opts.wraplock === B)
-    ? opts.wraplock
-    : true;
-
-  const addname = (typeof opts.addname === B) 
-    ? opts.addname 
-    : !wrapped;
-
-  const addis = (typeof opts.addis === B)
-    ? opts.addis
-    : wrapped;
-
-  const validIdent = /^[a-zA-Z_$][0-9a-zA-Z_$]*$/;
-
-  const addme = (typeof opts.addme === S
-    && validIdent.test(opts.addme))
-    ? opts.addme
-    : null;
-
-  const addre = (typeof opts.addre === S
-    && validIdent.test(opts.addre))
-    ? opts.addre
-    : null;
-
-  const slice = Array.prototype.slice;
-
-  function onEachEvent (e, fn) 
+  if (typeof arg3 === B 
+    || typeof opts.addre === S 
+    || typeof opts.reinherit === B)
   { 
-    const es = e.split(/\s+/);
-    const me = es.length > 1;
-    for (e of es)
-    {
-      fn(e, me);
-    }
-  }
-
-  const add = def(el);
-
-  function runCallback (name, fn, args)
-  {
-    if (fn.busy) return;
-    fn.busy = 1;
-
-    let fobj;
-
-    if (wrapped)
-    { // Something is going to use our wrapper object.
-      const isWild = (name === wildcard);
-      const fname = isWild ? (addname ? args[0] : args.shift()) : name;
-
-      fobj = 
-      {
-        isObservable: lock({event: true, target: false}),
-        self: el,
-        target: el,
-        name: fname, 
-        type: fname,
-        func: fn,
-        wildcard: isWild,
-        args,
-      };
-
-      if (wrapsetup)
-      {
-        wrapsetup.call(el, fobj);
-      }
-
-      if (wraplock)
-      {
-        lock(fobj);
-      }
-    }
-
-    const fthis = wrapthis ? fobj : el;
-    const fargs = wrapargs ? [fobj] 
-      : ((fn.typed && addname) ? [name].concat(args) : args);
-    
-    fn.apply(fthis, fargs);
-    fn.busy = 0;
+    return orig(el, opts, arg3);
   }
-
-  let callbacks = {};
-
-  /**
-  * Assign an event handler
-  * 
-  * Listen to the given space separated list of `events` and execute
-  * the `callback` each time an event is triggered.
-  * @param  {string} events - events ids
-  * @param  {function} fn - callback function
-  * @returns {object} el
-  */
-  add('on', function(events, fn) 
-  {
-    if (typeof fn !== F)
-    {
-      console.error("non-function passed to on()");
-      return el;
-    }
-
-    onEachEvent(events, function(name, typed) 
-    {
-      (callbacks[name] = callbacks[name] || []).push(fn);
-      fn.typed = typed;
-    });
-
-    return el;
-  });
-
-  /**
-  * Removes the given space separated list of `events` listeners
-  * 
-  * @param   {string} events - events ids
-  * @param   {function} fn - callback function
-  * @returns {object} el
-  */
-  add('off', function(events, fn) 
-  {
-    if (events === wildcard && !fn) 
-    { // Clear all callbacks.
-      callbacks = {};
-    }
-    else 
-    {
-      onEachEvent(events, function(name) 
-      {
-        if (fn) 
-        { // Find a specific callback to remove.
-          var arr = callbacks[name]
-          for (var i = 0, cb; cb = arr && arr[i]; ++i) 
-          {
-            if (cb == fn) arr.splice(i--, 1);
-          }
-        } 
-        else 
-        { // Remove all callbacks for this event.
-          delete callbacks[name];
-        }
-      });
-    }
-    return el
-  });
-
-  /**
-  * Add a one-shot event handler.
-  * 
-  * Listen to the given space separated list of `events` and execute 
-  * the `callback` at most once.
-  * 
-  * @param   {string} events - events ids
-  * @param   {function} fn - callback function
-  * @returns {object} el
-  */
-  add('one', function(events, fn) 
-  {
-    function on() 
-    {
-      el.off(events, on)
-      fn.apply(el, arguments)
-    }
-    return el.on(events, on);
-  });
-
-  /**
-  * Execute all callback functions that listen to the given space 
-  * separated list of `events`
-  * @param   {string} events - events ids
-  * @returns {object} el
-  */
-  add('trigger', function(events) 
-  {
-    // getting the arguments
-    // skipping the first one
-    const args = slice.call(arguments, 1);
-
-    onEachEvent(events, function(name) 
-    {
-      const fns = slice.call(callbacks[name] || [], 0);
-
-      for (var i = 0, fn; fn = fns[i]; ++i) 
-      {
-        runCallback(name, fn, args);
-        if (fns[i] !== fn) { i-- }
-      }
-
-      if (callbacks[wildcard] && name != wildcard)
-      { // Trigger the wildcard.
-        el.trigger.apply(el, ['*', name].concat(args));
-      }
-
-    });
-
-    return el
-  });
-
-  if (addis)
+  else
   {
-    add('isObservable', lock({event: false, target: true}));
-  }
-
-  if (addme)
-  { // Add a wrapper for observable() that sets new default options.
-    add(addme, function (obj=null, mopts)
-    {
-      return observable(obj, copy({}, opts, mopts));
-    });
-  }
-
-  if (addre)
-  { // Add a method to change the observable options.
-    const reinherit = opts.reinherit ?? false;
-
-    add(addre, function(replacementOpts={}, inherit=reinherit)
-    {
-      const newOpts 
-        = inherit 
-        ? Object.assign({}, opts, replacementOpts)
-        : replacementOpts;
-      return observable(el, replacementOpts, true);
-    });
+    return evob.makeObservable(el, opts, arg3);
   }
-
-  // Metadata
-  add('$$observable$$', lock({opts, observable}));
-
-  return el
-
-} // observable()
+}
 
 module.exports = observable;
 
-/**
- * See if a value implements the *Observable* interface.
- * 
- * @function module:@lumjs/core/observable.is
- * @param {*} obj - The expected object/function to test.
- * @returns {boolean}
- */
-function isObservable(obj)
-{
-  return (isComplex(obj)
-    && typeof obj.trigger === F
-    && typeof obj.on === F);
-}
-
-// Add an 'is()' method to `observable` itself.
-def(observable, 'is', isObservable);
+def(observable)
+  ('is', evob.isObservable)
+  ('auto', observable)
+  ('orig', orig)
+  ('wrap', evob.makeObservable)
 
 /**
- * Does a value implement the Observable interface?
- * @name module:@lumjs/core/types.doesObservable
- * @function
- * @param {*} v - The expected object/function to test.
+ * Does a value implement the observable interface?
+ * @function module:@lumjs/core/observable.is
+ * @param {*} v - Value to test
  * @returns {boolean}
- * @see module:@lumjs/core/observable.is
+ * @see module:@lumjs/core/events/observable.isObservable
  */
 
 /**
- * Extension type for the {@link module:@lumjs/core/observable} interface.
- * @memberof module:@lumjs/core/types.TYPES
- * @member {string} OBSERV - Implements the *Observable* interface.
+ * An alias to
+ * {@link module:@lumjs/core/events/observable.makeObservable makeObservable()}
+ * 
+ * @function module:@lumjs/core/observable.wrap
+ * @param {(object|function)} el
+ * @param {object} oo
+ * @param {object} ro
+ * @returns {object}
  */
-
-TYPES.add('OBSERV', 'observable', isObservable, 'doesObservable');

package/lib/old/observable.js

@@ -0,0 +1,291 @@
+// Defining these after observable.
+const {B,F,S,def,isObj,isComplex} = require('../types');
+const {isObservable} = require('../events/observable');
+const lock = Object.freeze;
+const copy = Object.assign;
+
+/**
+ * The original implementation of the observable API.
+ * 
+ * This older implementation will be removed entirely when `v2.0` is
+ * released, and possibly sooner if I don't find anything broken with
+ * the compatibility wrapper. For now it's able to be loaded on demand.
+ * 
+ * @param {(object|function)} el - The target to add observable API to.
+ * 
+ * @param {object} [opts] 
+ * {@link module:@lumjs/core/observable.observable Observable} options.
+ * 
+ * Includes a few additional options no longer supported by the
+ * new events-based implementation. Only the options exclusive to this
+ * version will be documented here.
+ *
+ * @param {string} [opts.addre] If set, add a method with this name
+ * to the `el` object, which is a function that can re-build the
+ * observable API methods with new `opts` replacing the old ones.
+ * 
+ * The method added takes two arguments, the first being an `object`
+ * representing the new options to set on the target. 
+ * 
+ * The second is an optional `boolean` value that determines if the
+ * existing `opts` should be used as defaults for any options not
+ * specified in the first argument.
+ * 
+ * @param {boolean} [opts.reinherit=false] Used as the default value of
+ * the second argument of the method added by `opts.addre`.
+ * 
+ * @param {boolean} [redefine=false] If `true` allow targets already
+ * implementing the `on()` and `trigger()` methods to be re-initialized.
+ * 
+ * Generally only needed if you need to change the `opts` for some reason.
+ * This is forced to `true` by the method added by `opts.addre`.
+ *
+ * @returns {object} el
+ * @see module:@lumjs/core/observable~API
+ * @alias module:@lumjs/core/observable.orig
+ */
+function observable (el={}, opts={}, redefine=false) 
+{
+  //console.debug("observable", el, opts);
+
+  if (!isComplex(el))
+  { // Don't know how to handle this, sorry.
+    throw new Error("non-object sent to observable()");
+  }
+
+  if (isObservable(el) && !redefine)
+  { // It's already observable.
+    return el;
+  }
+
+  if (typeof opts === B)
+  { // Assume it's the wrapthis option.
+    opts = {wrapthis: opts};
+  }
+  else if (!isObj(opts))
+  {
+    opts = {};
+  }
+
+  const noSpace = /^\S+$/;
+
+  const wildcard = (typeof opts.wildcard === S 
+    && noSpace.test(opts.wildcard))
+    ? opts.wildcard
+    : '*';
+
+  const wrapsetup = (typeof opts.wrapsetup === F)
+    ? opts.wrapsetup 
+    : null;
+
+  const wrapthis = (typeof opts.wrapthis === B) 
+    ? opts.wrapthis 
+    : false;
+
+  const wrapargs = (typeof opts.wrapargs === B)
+    ? opts.wrapargs
+    : (wrapsetup ? !wrapthis : false);
+
+  const wrapped = (wrapthis || wrapargs);
+
+  const wraplock = (typeof opts.wraplock === B)
+    ? opts.wraplock
+    : true;
+
+  const addname = (typeof opts.addname === B) 
+    ? opts.addname 
+    : !wrapped;
+
+  const addis = (typeof opts.addis === B)
+    ? opts.addis
+    : wrapped;
+
+  const validIdent = /^[a-zA-Z_$][0-9a-zA-Z_$]*$/;
+
+  const addme = (typeof opts.addme === S
+    && validIdent.test(opts.addme))
+    ? opts.addme
+    : null;
+
+  const addre = (typeof opts.addre === S
+    && validIdent.test(opts.addre))
+    ? opts.addre
+    : null;
+
+  const slice = Array.prototype.slice;
+
+  function onEachEvent (e, fn) 
+  { 
+    const es = e.split(/\s+/);
+    const me = es.length > 1;
+    for (e of es)
+    {
+      fn(e, me);
+    }
+  }
+
+  const add = def(el);
+
+  function runCallback (name, fn, args)
+  {
+    if (fn.busy) return;
+    fn.busy = 1;
+
+    let fobj;
+
+    if (wrapped)
+    { // Something is going to use our wrapper object.
+      const isWild = (name === wildcard);
+      const fname = isWild ? (addname ? args[0] : args.shift()) : name;
+
+      fobj = 
+      {
+        isObservable: lock({event: true, target: false}),
+        self: el,
+        target: el,
+        name: fname, 
+        type: fname,
+        func: fn,
+        wildcard: isWild,
+        args,
+      };
+
+      if (wrapsetup)
+      {
+        wrapsetup.call(el, fobj);
+      }
+
+      if (wraplock)
+      {
+        lock(fobj);
+      }
+    }
+
+    const fthis = wrapthis ? fobj : el;
+    const fargs = wrapargs ? [fobj] 
+      : ((fn.typed && addname) ? [name].concat(args) : args);
+    
+    fn.apply(fthis, fargs);
+    fn.busy = 0;
+  }
+
+  let callbacks = {};
+
+  add('on', function(events, fn) 
+  {
+    if (typeof fn !== F)
+    {
+      console.error("non-function passed to on()");
+      return el;
+    }
+
+    onEachEvent(events, function(name, typed) 
+    {
+      (callbacks[name] = callbacks[name] || []).push(fn);
+      fn.typed = typed;
+    });
+
+    return el;
+  });
+
+  add('off', function(events, fn) 
+  {
+    if (events === wildcard && !fn) 
+    { // Clear all callbacks.
+      callbacks = {};
+    }
+    else 
+    {
+      onEachEvent(events, function(name) 
+      {
+        if (fn) 
+        { // Find a specific callback to remove.
+          var arr = callbacks[name]
+          for (var i = 0, cb; cb = arr && arr[i]; ++i) 
+          {
+            if (cb == fn) arr.splice(i--, 1);
+          }
+        } 
+        else 
+        { // Remove all callbacks for this event.
+          delete callbacks[name];
+        }
+      });
+    }
+    return el
+  });
+
+  add('one', function(events, fn) 
+  {
+    function on() 
+    {
+      el.off(events, on)
+      fn.apply(el, arguments)
+    }
+    return el.on(events, on);
+  });
+
+  add('trigger', function(events) 
+  {
+    // getting the arguments
+    // skipping the first one
+    const args = slice.call(arguments, 1);
+
+    onEachEvent(events, function(name) 
+    {
+      const fns = slice.call(callbacks[name] || [], 0);
+
+      for (var i = 0, fn; fn = fns[i]; ++i) 
+      {
+        runCallback(name, fn, args);
+        if (fns[i] !== fn) { i-- }
+      }
+
+      if (callbacks[wildcard] && name != wildcard)
+      { // Trigger the wildcard.
+        el.trigger.apply(el, ['*', name].concat(args));
+      }
+
+    });
+
+    return el
+  });
+
+  if (addis)
+  {
+    add('isObservable', lock({event: false, target: true}));
+  }
+
+  if (addme)
+  { // Add a wrapper for observable() that sets new default options.
+    add(addme, function (obj=null, mopts)
+    {
+      return observable(obj, copy({}, opts, mopts));
+    });
+  }
+
+  if (addre)
+  { // Add a method to change the observable options.
+    const reinherit = opts.reinherit ?? false;
+
+    add(addre, function(replacementOpts={}, inherit=reinherit)
+    {
+      const newOpts 
+        = inherit 
+        ? Object.assign({}, opts, replacementOpts)
+        : replacementOpts;
+      return observable(el, replacementOpts, true);
+    });
+  }
+
+  // Metadata
+  add('$$observable$$', lock({opts, observable}));
+
+  return el
+
+} // observable()
+
+// Add an 'is()' method to `observable` itself.
+def(observable, 'is', isObservable);
+
+module.exports = observable;

package/lib/traits.js

@@ -10,13 +10,18 @@ const getProp = require('./obj/getproperty');
 const 
 {
   def,F,B,S,
-  isObj,isArray,isConstructor,isProperty,
+  isObj,isArray,isConstructor,isProperty,isClassObject,
   needObj,needType,
 } = require('./types');
 
 // Symbol for private storage of composed traits.
 const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
 
+const FLAG_ET = 1; // Flag for ensure target
+const FLAG_ES = 2; // Flag for ensure source
+const FLAGS_S = 0; // Default flags for static mode
+const FLAGS_O = 3; // Default flags for object mode
+
 /**
  * For when we need a prototype object exclusively.
  * 
@@ -30,7 +35,7 @@ const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
  * 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
+ * including if it is a function but does not have a valid
  * prototype object to return.
  * 
  * @alias module:@lumjs/core/traits.ensureProto
@@ -47,7 +52,42 @@ function ensureProto(from)
   }
   else
   {
-    throw new TypeError("Invalid class constructor or object instance");
+    throw new TypeError("Invalid class constructor or instance object");
+  }
+}
+
+/**
+ * For when we need a constructor function exclusively.
+ * 
+ * @param {(function|object)} from - Target
+ * 
+ * May either be a class constructor `function`, or an `object` instance.
+ * 
+ * @returns {function}
+ * 
+ * If `from` is a constructor function it will be returned as-is.
+ * If `from` is an object instance (with a constructor other than `Object`),
+ * then the `from.constructor` value will be returned.
+ * 
+ * @throws {TypeError} If `from` was not a valid value;
+ * including if it was a function without a prototype,
+ * or an object with a constructor of `Object`.
+ * 
+ * @alias module:@lumjs/core/traits.ensureConstructor
+ */
+function ensureConstructor(from)
+{
+  if (isConstructor(from))
+  { // Good to go
+    return from;
+  }
+  else if (isClassObject(from))
+  { // An instance of a class (other than `Object` itself)
+    return from.constructor;
+  }
+  else
+  {
+    throw new TypeError("Invalid class constructor or instance object");
   }
 }
 
@@ -125,13 +165,16 @@ function getComposed(target, source, tryClass=true)
     composed = target[COMPOSED_TRAITS];
   }
 
-  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 (composed)
+  {
+    if (!source)
+    {
+      return composed;
+    }
+    if (composed.has(source))
+    { // Let's get definitions for a specific trait.
+      return composed.get(source);
+    }
   }
 
   if (tryClass && isObj(target))
@@ -224,9 +267,27 @@ function mapComposed(target, source)
  * or use the {@link module:@lumjs/core/traits.composeFully} function.
  * 
  * Only useful if `source` is a class constructor (always recommended).
+ * The exact behaviour may be customized further with the `.flags` option.
  * 
  * Default is `false`.
  * 
+ * @param {number} [opts.flags] Binary flags for advanced behaviours
+ * 
+ * The default `.flags` value, and the _ensure function_ used depends
+ * on the value of the `.static` option:
+ * 
+ * | .static | Default | Ensure function                                     |
+ * | ------- | ------- | --------------------------------------------------- |
+ * | `false` | `3`     | {@link module:@lumjs/core/traits.ensureProto}       |
+ * | `true`  | `0`     | {@link module:@lumjs/core/traits.ensureConstructor} |
+ * 
+ * The actual flags are fairly straightforward:
+ * 
+ * | Flag | Description                                                      |
+ * | ---- | ---------------------------------------------------------------- |
+ * | `1`  | Pass `target` through _ensure function_                          |
+ * | `2`  | Pass `source` through _ensure function_                          |
+ * 
  * @param {boolean} [opts.symbols=false] Auto-compose `Symbol` properties?
  * 
  * Calls `Object.getOwnPropertySymbols()` when generating a list of 
@@ -260,8 +321,7 @@ function compose(specTarget, specSource, opts={})
     =  getComposed(specTarget, specSource) 
     ?? mapComposed(specTarget, specSource);
 
-  const isStatic = opts.static ?? false;
-  
+  const isStatic = opts.static ?? false; 
   const mapId = isStatic ? 'static' : 'proto';
 
   if (composedMaps[mapId])
@@ -270,8 +330,11 @@ function compose(specTarget, specSource, opts={})
     return composedMaps;
   }
 
-  const target = isStatic ? specTarget : ensureProto(specTarget);
-  const source = isStatic ? specSource : ensureProto(specSource);
+  const flags = parseInt(opts.flags) ?? (isStatic ? FLAGS_S : FLAGS_O);
+  const ensure = isStatic ? ensureConstructor : ensureProto;
+
+  const target = (flags & FLAG_ET) ? specTarget : ensure(specTarget);
+  const source = (flags & FLAG_ES) ? specSource : ensure(specSource);
 
   let props  = opts.props;
 
@@ -382,7 +445,6 @@ function compose(specTarget, specSource, opts={})
     composed.set(tprop, cdef);
   }
 
-  composedMaps[mapId] = composed;
   return composedMaps;
 }
 
@@ -642,9 +704,10 @@ class CoreTrait
    * @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.
+   * then the decomposeFrom() operation will skip the step of
+   * actually decomposing the trait.
    * 
+   * @returns {*} Return value is not used. 
    */
   static removeTrait(info)
   {
@@ -714,7 +777,7 @@ class CoreTrait
  * @returns {function} The `registerTrait()` function created above.
  * @alias module:@lumjs/core/traits.makeRegistry
  */
-function makeTraitRegistry(registry)
+function makeTraitRegistry(registry={})
 {
   needObj(registry, false, 'invalid trait registry object');
 
@@ -749,56 +812,10 @@ function makeTraitRegistry(registry)
 module.exports = 
 {
   compose, composeFully, getComposed, decompose,
-  Trait: CoreTrait, IGNORE_STATIC, ensureProto,
+  Trait: CoreTrait, IGNORE_STATIC, 
+  ensureProto, ensureConstructor,
   makeRegistry: makeTraitRegistry,
 
   // Undocumented:
   hasOwn,
 }
-
-/**
- * Composed property maps.
- * 
- * @typedef {object} module:@lumjs/core/traits~Composed
- * 
- * @prop {?Map} proto  - Map of composed *prototype* properties.
- * 
- * Keys are the `string` or `symbol` for each composed property.
- * Values are {@link module:@lumjs/core/traits~ComposedProperty} objects.
- * 
- * If no applicable trait properties are currently composed,
- * this will be `null`.
- * 
- * @prop {?Map} static - Map of composed *static* properties.
- * 
- * 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.
- * 
- */
-
-/**
- * Composed property definitions.
- * 
- * @typedef {object} module:@lumjs/core/traits~ComposedProperty
- * 
- * @prop {(string|Symbol)} id - The property key on the `target`
- * @prop {(string|Symbol)} [srcKey] The property key from the `source`;
- * only included if different from `propKey`.
- * 
- * @prop {?object} newDescriptor - The property descriptor to be added;
- * will be `null` if the property did not exist.
- * 
- * @prop {object} [oldDescriptor] The replaced property descriptor;
- * only included if there was an existing property in the `target` 
- * and the `opts.overwrite` option was `true`.
- * 
- * @prop {boolean} found - Was the property found in the `source` ?
- * @prop {boolean} added - Was the property added to the `target` ?
- * 
- */

package/lib/types/basics.js

@@ -144,6 +144,9 @@ function isIterable(v)
 /**
  * Does a value appear to be a class constructor?
  * 
+ * For the purposes of this test, a class constructor is
+ * any Function that has a `prototype` Object property.
+ * 
  * @param {*} v - Value to test
  * @returns {boolean}
  * @alias module:@lumjs/core/types/basics.isConstructor
@@ -153,6 +156,35 @@ function isConstructor(v)
   return (typeof v === F && isObj(v.prototype));
 }
 
+/**
+ * Is a value a _plain_ object?
+ * 
+ * A plain object is one which has a `constructor` property
+ * that **IS** the `globalThis.Object` function.
+ * 
+ * @param {*} v - Value to test
+ * @returns {boolean}
+ */
+function isPlainObject(v)
+{
+  return (isObj(v) && v.constructor === Object);
+}
+
+/**
+ * Is a value a class instance object?
+ * 
+ * This is a counterpart to isPlainObject() that only returns
+ * true if the `constructor` property exists, but is **NOT**
+ * the `globalThis.Object` function.
+ * 
+ * @param {*} v - Value to test
+ * @returns {boolean}
+ */
+function isClassObject(v)
+{
+  return (isObj(v) && typeof v.constructor === F && v.constructor !== Object);
+}
+
 /**
  * See if an object can be used as a valid *descriptor*.
  * 
@@ -246,7 +278,8 @@ module.exports =
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   isIterable, nonEmptyArray, isArguments, isProperty, isConstructor,
-  doesDescriptor, doesDescriptorTemplate, JS,
+  isPlainObject, isClassObject, doesDescriptor, doesDescriptorTemplate,
+  JS,
 }
 
 JS.addTo(module.exports);

package/package.json

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