@lumjs/core 1.33.0 → 1.35.0

package/lib/observable.js

@@ -1,15 +1,36 @@
-// Defining these after observable.
-const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');
-const {duplicateAll: clone} = require('./obj/copyall');
-const lock = Object.freeze;
+/**
+ * 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 lock = Object.freeze;
  * 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, clone(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;