@lumjs/core 1.33.0 → 1.34.0

package/lib/console.js

@@ -1,5 +1,5 @@
 const def = require('./types/def');
-const {F} = require('./types/js');
+const {F,isObj} = require('./types/basics');
 
 /**
  * A super simple singleton wrapper around the Javascript console.

package/lib/events/index.js

@@ -36,7 +36,21 @@ exports = module.exports =
    */
   extend(target, opts)
   {
-    exports.register(target, opts);
+    exports.register([target], opts);
     return target;
   },
+
+  /**
+   * Apply the compatibility version of the observable API;
+   * will load the events/observable sub-module on demand.
+   * @param {object} target
+   * @param {object} [opts]
+   * @returns {object} `target`
+   * @see module:@lumjs/core/events/observable.makeObservable
+   */
+  observable(target, opts)
+  {
+    const {makeObservable} = require('./observable');
+    return makeObservable(target, opts);
+  },
 }

package/lib/events/listener.js

@@ -77,6 +77,12 @@ class LumEventListener
     this.registry = registry;
     this.options = makeOpts(spec);
     this.eventNames = registry.getEventNames(spec.eventNames);
+
+    const setup = this.options.setupListener ?? registry.options.setupListener;
+    if (typeof setup === F)
+    {
+      setup.call(registry, this);
+    }
   }
 
   /**

package/lib/events/observable.js

@@ -0,0 +1,201 @@
+/**
+ * Observable Compatibility API
+ * @module @lumjs/core/events/observable
+ */
+"use strict";
+
+const {B,F,S,def} = require('../types');
+const lock = Object.freeze;
+const copy = Object.assign;
+const Registry = require('./registry');
+
+const ISOB = 'isObservable';
+
+const OBS_EXTENDS =
+{
+  registry: '$events',
+  listen:   'on',
+  emit:     'trigger',
+  remove:   'off',
+  once:     'one',
+}
+
+const OBS_OPTIONS =
+{
+  wrapargs: false,
+  wrapthis: false,
+  wraplock: true,
+  wrapsetup: null,
+  addme: null,
+  // addname: !(wrapargs || wrapthis)
+  // addis:    (wrapargs || wrapthis)
+}
+
+/**
+ * A version of the observable API using the events module.
+ * 
+ * It's obviously not going to be 100% identical due to
+ * the very different nature of the backend engine, but it'll
+ * try its best to make existing code work.
+ * 
+ * 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;
+ * 
+ * The `addre` and `reinherit` options are not supported.
+ * All the other ones should try to work mostly the same.
+ * 
+ * @param {boolean} [oo.addwrap] If this is `true`, 
+ * and `oo.wrapargs` is `false`, then the `event` object 
+ * will be appended to the arguments sent to the handler.
+ * 
+ * The default value is: `!oo.wrapthis`
+ * 
+ * @param {object} [ro]
+ * {@link module:@lumjs/core/events.Registry Registry} options;
+ * 
+ * The `setupEvent` and `setupListener` options cannot be specified,
+ * as the versions from this module will always be used.
+ * 
+ * The `extend` defaults are changed to match those used
+ * by the observable API (`on`,`trigger`,`off`,`one`),
+ * and `extend.registry` is set to `$events` by default.
+ * 
+ * Setting the `extend` option to `false` will have no effect
+ * in this implementation.
+ * 
+ * @param {boolean} [wantReg=false] Return the Registry?
+ * @returns {object} normally `el`, unless `wantReg` was `true`
+ * @alias module:@lumjs/core/events/observable.makeObservable
+ */
+function makeObservable(el, oo, ro, wantReg=false)
+{
+  ro = copy({}, ro);
+  ro.extend = copy({}, OBS_EXTENDS, ro.extend);
+  ro.setupEvent = setupEvent;
+  ro.setupListener = setupListener;
+  oo = ro.observable = copy({}, OBS_OPTIONS, oo);
+
+  let wrapped = (oo.wrapargs || oo.wrapthis);
+  if (!wrapped && typeof oo.wrapsetup === F)
+  {
+    wrapped = oo.wrapargs = true;
+  }
+
+  if (typeof oo.wildcard === S)
+  { // oo.wildcard takes precedence
+    ro.wildcard = oo.wildcard;
+  }
+
+  const setIf = (opt, get) => 
+  {
+    if (typeof oo[opt] !== B)
+    {
+      oo[opt] = get();
+    }
+  }
+
+  setIf('addname', () => !wrapped);
+  setIf('addis',   () =>  wrapped);
+  setIf('addwrap', () => !oo.wrapthis);
+
+  const reg = new Registry([el], ro);
+
+  if (oo.addis)
+  {
+    def(el, ISOB, lock({event: false, target: true}));
+  }
+
+  if (typeof oo.addme === S)
+  {
+    def(el, oo.addme, function(el2, oo2, ro2)
+    {
+      return makeObservable(el2, 
+        copy({}, oo, oo2),
+        copy({}, ro, ro2)
+      );
+    });
+  }
+
+  return wantReg ? reg : el;
+}
+
+/**
+ * Event setup for observable compatibility
+ * @type {module:@lumjs/core/events~SetupEvent}
+ */
+function setupEvent(ev)
+{
+  const ro = this.registry.options;
+  const oo = ro.observable;
+  ev.wildcard = this.eventNames.has(ro.wildcard);
+  ev.self = ev.target;
+  ev.type = ev.name;
+  def(ev, ISOB, lock({event: true, target: false}));
+
+  if (typeof oo.wrapsetup === F)
+  {
+    oo.wrapsetup.call(ev.target, ev);
+  }
+
+  if (oo.wraplock)
+  {
+    lock(ev);
+  }
+}
+
+/**
+ * Listener setup for observable compatibility
+ * @type {module:@lumjs/core/events~SetupListener}
+ */
+function setupListener(ln)
+{
+  const oo = this.options.observable;
+  const oh = ln.observableHandler = ln.handler;
+  const go = (ev, args) => 
+  {
+    if (typeof oh === F)
+    {
+      const thisTarget = oo.wrapthis ? ev : ev.target;
+      oh.apply(thisTarget, args);
+    }
+    else
+    {
+      oh.handleEvent(...args);
+    }
+  }
+
+  if (!oo.wrapargs)
+  { // Not wrapping args, we need to wrap the handler.
+    const ec = ln.eventNames.size;
+    ln.handler = function(ev)
+    {
+      const args = ev.args;
+      if (ec > 1 && oo.addname)
+      {
+        args.unshift(ev.name);
+      }
+      if (oo.addwrap)
+      {
+        args.push(ev);
+      }
+
+      go(ev, args);
+    }
+  }
+  else if (oo.wrapthis)
+  { // Both wrapargs and wrapthis are in use, woah!
+    ln.handler = function(ev)
+    {
+      go(ev, [ev]);
+    }
+  }
+}
+
+module.exports =
+{
+  makeObservable, setupEvent, setupListener,
+}

package/lib/events/registry.js

@@ -95,6 +95,9 @@ class LumEventRegistry
    * If this is a `function`, it will be called to dynamically get a
    * list of target objects whenever an event is triggered.
    * 
+   * 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 {(RegExp|string)} [opts.delimiter=/\s+/] Used to split event names
@@ -135,12 +138,17 @@ class LumEventRegistry
    * If `true` then when adding wrapper methods, the properties from
    * `opts.extend` will replace any existing ones in each target.
    * 
-   * @param {function} [opts.setupEvent] Initialize each Event object?
+   * @param {module:@lumjs/core/events~SetupEvent} [opts.setupEvent]
    * 
    * If this is specified (either here or in individual listeners),
    * it will be called and passed the Event object at the very end of
    * its constructor.
    * 
+   * @param {module:@lumjs/core/events~SetupListener} [opts.setupListener]
+   * 
+   * If this is specified, it will be called and passed the Listener
+   * object at the very end of its constructor.
+   * 
    * @param {string} [opts.wildcard='*'] Wildcard event name.
    * 
    * - If you use this in `listen()` the handler will be used regardless
@@ -248,7 +256,7 @@ class LumEventRegistry
    * it will be used as the `spec`, and the `spec.eventNames`
    * and `spec.listener` properties will become mandatory.
    * 
-   * If it's a string or there is more than one argument, this 
+   * If it's a string *OR* there is more than one argument, this 
    * will be used as the `spec.eventNames` property.
    * 
    * @param {module:@lumjs/core/events~Handler} [handler] 
@@ -277,7 +285,8 @@ class LumEventRegistry
    * names `listener`, `handler` or `eventNames` as option properties,
    * and if found, they will be removed.
    * 
-   * You may also override the `setupEvent` registry option here.
+   * You may also override the `setupEvent` and `setupListener` registry
+   * options here if needed.
    * 
    * @param {boolean} [spec.options.once=false] Only use the listener once?
    * 

package/lib/obj/cp.js

@@ -1235,7 +1235,7 @@ cp.from = function()
  * @param {?object} [opts] Options
  * 
  * If this is an `object`, the clone call will be:
- * `cp.with(opts).into(obj).ow.clone();`
+ * `cp.with(opts).from(obj).ow.clone();`
  * 
  * If this is `null` or `undefined`, the call will be: 
  * `cp(obj);`
@@ -1251,7 +1251,7 @@ cp.clone = function(obj, opts)
   }
   else
   {
-    return cp.with(opts).into(obj).ow.clone();
+    return cp.with(opts).from(obj).ow.clone();
   }
 }
 

package/lib/observable.js

@@ -1,7 +1,7 @@
 // Defining these after observable.
 const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');
-const {duplicateAll: clone} = require('./obj/copyall');
 const lock = Object.freeze;
+const copy = Object.assign;
 
 /**
  * Make a target object (or function) support the *Observable* API.
@@ -346,9 +346,9 @@ function observable (el={}, opts={}, redefine=false)
 
   if (addme)
   { // Add a wrapper for observable() that sets new default options.
-    add(addme, function (obj=null, mopts={})
+    add(addme, function (obj=null, mopts)
     {
-      return observable(obj, clone(opts, mopts));
+      return observable(obj, copy({}, opts, mopts));
     });
   }
 

package/lib/types/index.js

@@ -16,11 +16,11 @@ Object.assign(exports,
   require('./basics'), 
   require('./root'),
   require('./isa'),
+  require('./stringify'),
   require('./needs'),
   { // A few standalone exports.
     def, lazy,
     TYPES: require('./typelist'),
-    stringify: require('./stringify'),
     ownCount: require('./owncount'),
   },
 );

package/lib/types/stringify.js

@@ -1,142 +1,301 @@
 // Get the extended type list.
 const TYPES = require('./typelist');
-const {isObj, isArray, isTypedArray} = require('./basics');
+const {F, S, N, B, isObj, isArray, isTypedArray} = require('./basics');
 const def = require('./def');
 
-const TOSTRING_TYPES = [TYPES.F, TYPES.SY];
+const TOSTRING_TYPES     = [TYPES.SY];
 const TOSTRING_INSTANCES = [RegExp];
 const CUSTOM = [];
+const DEF = 
+{
+  MAXD: 1,
+  NEWD: 0,
+}
 
 /**
  * Stringify a Javascript value.
  * 
- * We typically just use `JSON.stringify()` but that doesn't work on
- * some types. So this function adds string formats for:
+ * Creates a new `Stringify` instance, then passes the
+ * first argument to it's `stringify()` method.
+ * 
+ * This is the primary way to use the Stringify class
+ * rather than manually creating an instance of it.
+ * 
+ * @param {*} what - Passed to `instance.stringify()`
+ * @param {(object|number)} [opts] Options for Stringify constructor;
+ * 
+ * If this is a `number` it's the `opts.maxDepth` option value.
+ * 
+ * @param {(number|boolean)} [addNew] The `opts.newDepth` option value;
+ * 
+ * For compatibility with old API. Boolean values are shortcuts:
+ * - `false` = `0`
+ * - `true`  = `1`
+ * 
+ * @returns {string} The stringified value
+ * 
+ * @alias module:@lumjs/core/types.stringify
+ * @see module:@lumjs/core/types.Stringify
+ * @see module:@lumjs/core/types.Stringify#stringify
+ */
+function stringify (what, opts={}, addNew=null)
+{
+  if (typeof opts === N)
+  {
+    opts = {maxDepth: opts}
+  }
+
+  if (typeof addNew === N)
+  {
+    opts.newDepth = addNew;
+  }
+  else if (typeof addNew === B)
+  {
+    opts.newDepth = addNew ? 1 : 0;
+  }
+
+  const si = new Stringify(opts);
+  return si.stringify(what);
+}
+
+/**
+ * A class to stringify Javascript values for testing and debugging.
+ * 
+ * This is NOT meant for serializing data, the output is in a format
+ * that's meant to be read by a developer, not parsed by a machine.
+ * 
+ * Currently directly supports:
+ * 
  *  - `function`
  *  - `symbol`
  *  - `TypedArray`
  *  - `Map`
  *  - `Set`
  *  - `Error`
- * I may add even more extended types in the future, but that's enough
- * for now.
+ *  - `RegExp`
+ *  - `Object`
  * 
- * This is NOT meant for serializing data, and does not use a JSON-friendly
- * output format. I'm writing a different library for that.
+ * Any other JS value types (`number`,`boolean`, `string`, etc.) will
+ * be serialized using JSON.
  * 
- * @param {*} what - The value to stringify.
- * @param {integer} [recurse=1] Recurse objects to this depth.
- * @param {boolean} [addNew=false] Use 'new Class()' instead of 'Class()'. 
- * @returns {string} The stringified value.
- * @alias module:@lumjs/core/types.stringify
+ * @alias module:@lumjs/core/types.Stringify
  */
-function stringify (what, recurse=1, addNew=false)
+class Stringify 
 {
-  const whatType = typeof what;
-
-  for (const test of CUSTOM)
-  { // If there are custom extensions, we check them first.
-    const ret = test.call({stringify}, what, recurse, addNew);
-    if (typeof ret === TYPES.S)
-    { // The extension processed the item.
-      return ret;
-    }
-  }
+  /**
+   * Create a new Stringify instance
+   * @param {object} [opts] Options; saved to `this.options`
+   * @param {number} [opts.maxDepth=1] Max depth to recurse?
+   * @param {number} [opts.newDepth=0] Depth to prepend 'new' to strings?
+   * @param {boolean} [opts.fnString=false] Fully stringify functions?
+   * @param {(Array|function)} [opts.setCustom] Set custom stringifiers;
+   * used *INSTEAD* of the globally registered ones.
+   * @param {(Array|function)} [opts.addCustom] Add custom stringifiers;
+   * used *in addition* to the globally registered ones.
+   */
+  constructor(opts={})
+  {
+    this.options = opts;
+    this.maxDepth = opts.maxDepth ?? DEF.MAXD;
+    this.newDepth = opts.newDepth ?? DEF.NEWD;
+    this.seenObjects = new Map(); // object => description
+    this.seenDescrip = new Map(); // description => count
+    this.strClass = TOSTRING_INSTANCES.slice();
+    this.strTypes = TOSTRING_TYPES.slice();
 
-  // A few types we simply stringify right now.
-  if (TOSTRING_TYPES.includes(whatType)) return what.toString();
+    if (opts.fnString)
+    {
+      this.strTypes.push(F);
+    }
 
-  if (isObj(what))
-  { // We support a few kinds of objects.
+    if (opts.errString)
+    {
+      this.strClass.push(Error);
+    }
 
-    // Any class instance that we can simply call `toString()` on, let's do that.
-    for (const aClass of TOSTRING_INSTANCES)
+    if (Array.isArray(opts.setCustom))
+    {
+      this.customFn = opts.setCustom.slice();
+    }
+    else if (typeof opts.setCustom === F)
     {
-      if (what instanceof aClass)
+      this.customFn = [];
+      opts.setCustom.call(this, this.customFn);
+    }
+    else
+    { // Start out with the global custom tests.
+      this.customFn = CUSTOM.slice();
+      if (Array.isArray(opts.addCustom))
+      {
+        this.customFn.push(...opts.addCustom);
+      }
+      else if (typeof opts.addCustom === F)
       {
-        return what.toString();
+        opts.addCustom.call(this, this.customFn);
       }
     }
 
-    // A few formatting helpers used below.
-    const classname = () => (addNew ? 'new ' : '') + what.constructor.name;
-    const construct = val => `${classname()}(${val})`;
-    const reconstruct = val => construct(stringify(val,recurse,addNew));
-    const arrayish = vals => reconstruct(Array.from(vals));
+  }
 
-    if (isTypedArray(what))
-    { // This one is pretty simple.
-      return construct(what.toString());
+  /**
+   * Stringify a JS value
+   * @param {*} what - Value to stringify
+   * @returns {string} A friendly representation of `what`
+   */
+  stringify(what, curd=0)
+  {
+    if (this.seenObjects.has(what))
+    { // Cached string for this subject already found.
+      return this.seenObjects.get(what);
     }
+
+    const recurse = curd < this.maxDepth;
+    const addNew  = curd < this.newDepth;
+    const whatType = typeof what;
+    const strFor = (str) => this._stringFor(what, str);
     
-    if (what instanceof Map)
-    {
-      return arrayish(what.entries());
+    for (const test of this.customFn)
+    { // If there are custom extensions, we check them first.
+      const ret = test.call(this, what, curd);
+      if (typeof ret === S)
+      { // The extension processed the item.
+        return strFor(ret);
+      }
     }
-    
-    if (what instanceof Set)
+
+    // A few types we simply stringify right now.
+    if (this.strTypes.includes(whatType)) 
     {
-      return arrayish(what.values());
+      return strFor(what.toString());
     }
 
-    if (what instanceof Error)
-    {
-      return `${what.name}(${JSON.stringify(what.message)})`;
+    if (!this.options.fnString && typeof what === F)
+    { // Simple format for functions
+      return strFor(what.name+'()');
     }
     
-    if (recurse)
-    { // Recursion mode enabled.
-      let out = '';
-      if (isArray(what))
-      { // Stringify an array.
-        out = '[';
-        out += what.map(item => stringify(item, recurse-1, addNew)).join(',');
-        out += ']';
-      }
-      else
-      { // Stringify a plain object.
-        out = '{';
-        function add(key, pre='')
+    if (isObj(what))
+    { // We support a few kinds of objects.
+
+      // Any class instance that we can simply call `toString()` on, let's do that.
+      for (const aClass of this.strClass)
+      {
+        if (what instanceof aClass)
         {
-          out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+          return strFor(what.toString());
         }
-        const keys = Object.keys(what);
-        //console.debug("keys!", keys);
-        if (keys.length > 0)
-        { // Let's add the first key, then all subsequent keys.
-          add(keys.shift());    
-          for (const key of keys)
+      }
+
+      // A few formatting helpers used below.
+      const nameFor = (name=what.constructor.name) => 
+        (addNew ? 'new ' : '') + strFor(name);
+      
+      const container = (content, ps='[', pe=']') =>
+      {
+        let cstr = nameFor();
+        if (recurse)
+        {
+          cstr += ps;
+          if (!Array.isArray(content))
           {
-            add(key, ',');
+            content = Array.from(content);
           }
+          cstr += (content
+            .map(item => this.stringify(item, curd+1))
+            .join(','));
+          cstr += pe;
+        }
+        return cstr;
+      }
+      
+      if (isTypedArray(what))
+      { // This one is pretty simple.
+        if (this.options.typedContent)
+        {
+          return container(what.toString());
         }
-        out += '}';
+        return nameFor();
+      }
+
+      if (what instanceof Map)
+      {
+        return container(what.entries());
+      }
+      
+      if (what instanceof Set)
+      {
+        return container(what.values());
+      }
+
+      if (isArray(what))
+      {
+        return container(what);
+      }
+
+      if (!this.options.errString && what instanceof Error)
+      {
+        return nameFor(what.name)+'('+JSON.stringify(what.message)+')';
       }
-      return out;
+
+      // If we reached here, it's another kind of object entirely.
+      return container(Object.keys(what), '{', '}');
+
+    } // if isObj
+    
+    // If we reached here, there's no special methods, use JSON.
+    return JSON.stringify(what);
+  }
+
+  _stringFor(obj, str)
+  {
+    let count = 0;
+    if (this.seenDescrip.has(str))
+    {
+      count = this.seenDescrip.get(str);
     }
+    this.seenDescrip.set(str, ++count);
+    str += '#' + count.toString(16).padStart(3, '0');
+    this.seenObjects.set(obj, str);
+    return str;
+  }
 
-  } // if isObj
-  
-  // If we reached here, there's no special methods, use JSON.
-  return JSON.stringify(what);
-}
+  static addCustoms(...testFns)
+  {
+    for (let fn of testFns)
+    {
+      if (typeof fn === F)
+      {
+        CUSTOM.push(fn);
+      }
+      else
+      {
+        console.debug({fn, testFns});
+        throw new TypeError("Invalid custom stringify function");
+      }
+    }
+  }
 
-// Add a custom extension.
-def(stringify, '$extend',
-function(func, registration=false)
-{
-  if (typeof func === TYPES.F)
+  static registerCustoms(registerFn)
   {
-    if (registration)
-    { // Using the function to register custom behaviour.
-      func.call({stringify, TOSTRING_INSTANCES, TOSTRING_TYPES}, CUSTOM);
+    if (typeof registerFn === F)
+    {
+      registerFn.call(this, this);
     }
-    else 
-    { // The function is a custom test.
-      CUSTOM.push(func);
+    else
+    {
+      console.debug({registerFn});
+      throw new TypeError("Invalid custom registration function");
     }
   }
-});
+
+} // Stringify
+
+// Add some static properties for registerCustoms to use
+def(Stringify) 
+  ('strClass', {value: TOSTRING_INSTANCES})
+  ('strTypes', {value: TOSTRING_TYPES})
+  ('customFn', {value: CUSTOM})
+  ('DEFAULTS', {value: DEF})
 
 // Export it.
-module.exports = stringify;
+module.exports = {stringify, Stringify};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "main": "lib/index.js",
   "exports": 
   {
@@ -10,6 +10,7 @@
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
     "./events": "./lib/events/index.js",
+    "./events/observable": "./lib/events/observable.js",
     "./flags": "./lib/flags.js",
     "./maps": "./lib/maps.js",
     "./meta": "./lib/meta.js",