@lumjs/core 1.30.0 → 1.31.0

package/lib/events/registry.js

@@ -0,0 +1,537 @@
+"use strict";
+
+const {S,F,isObj,def,isIterable} = require('../types');
+const Listener = require('./listener');
+
+const DEF_EXTENDS =
+{
+  registry: 'events',
+  listen:   'on',
+  emit:     'emit',
+  remove:   null,
+  once:     null,
+}
+
+const DEF_OPTIONS =
+{
+  delimiter: /\s+/,
+  multiMatch: false,
+  wildcard: '*',
+}
+
+/**
+ * A class that handles events for target objects
+ * 
+ * @prop {module:@lumjs/core/events~GetTargets} getTargets 
+ * A constructor-assigned callback method that returns a set of targets.
+ * @prop {object} options - Registry-level options
+ * @prop {Set.<module:@lumjs/core/events.Listener>} allListeners
+ * All registered event listeners
+ * @prop {Map.<string,Set.<module:@lumjs/core/events.Listener>>} listenersFor
+ * Each key is a single event name, and the value is a Set of
+ * listener objects that handle that event.
+ * 
+ * @alias module:@lumjs/core/events.Registry
+ */
+class LumEventRegistry
+{
+  /**
+   * Create a new registry instance for one or more target objects
+   * 
+   * @param {(object|module:@lumjs/core/events~GetTargets)} targets
+   * 
+   * If this is a `function`, it will be called to dynamically get a
+   * list of target objects whenever an event is triggered.
+   * 
+   * If this is an `object`, then any kind of `Iterable` may be used
+   * to represent multiple targets, while any non-Iterable object will
+   * be considered as single target.
+   * 
+   * @param {object} [opts] Options (saved to `options` property).
+   * 
+   * @param {(RegExp|string)} [opts.delimiter=/\s+/] Used to split event names
+   * 
+   * @param {boolean} [opts.multiMatch=false]
+   * If a registered listener has multiple event names, and a call
+   * to `emit()` also has multiple event names, the value of this
+   * option will determine if the same listener will have its
+   * handler function called more than once.
+   * 
+   * If this is `true`, the handler will be called once for every
+   * combination of target and event name.
+   * 
+   * If this is `false` (default), then only the first matching event 
+   * name will be called for each target.
+   * 
+   * @param {(object|boolean)} [opts.extend]
+   * This option determines the rules for adding wrapper methods and
+   * other extension properties to the target objects.
+   * 
+   * If this is `true` (default when `targets` is an `object`), then
+   * the target objects will be extended using the default property names.
+   * 
+   * If this is set to `false` (default when `targets` is a `function`), 
+   * it disables adding extension properties entirely.
+   * 
+   * If it is an `object` then each nested property may be set to a string
+   * to override the default, or `null` to skip adding that property.
+   * 
+   * @param {?string} [opts.extend.registry="events"] Registry property
+   * @param {?string} [opts.extend.emit="emit"] `emit()` proxy method
+   * @param {?string} [opts.extend.listen="on"] `listen()` proxy method
+   * @param {?string} [opts.extend.once=null]   `once()` proxy method
+   * @param {?string} [opts.extend.remove=null] `remove()` proxy method
+   *
+   * @param {boolean} [opts.overwrite=false] Overwrite existing properties?
+   * 
+   * 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?
+   * 
+   * 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 {string} [opts.wildcard='*'] Wildcard event name.
+   * 
+   * - If you use this in `listen()` the handler will be used regardless
+   *   as to what event name was triggered. You can always see which
+   *   event name was actually triggered by using `event.name`.
+   * - If you use this in `remove()` it calls `removeAll()` to remove all
+   *   registered listeners.
+   */
+  constructor(targets, opts={})
+  {
+    let defExt; // Default opts.extend value
+    if (typeof targets === F)
+    { // A dynamic getter method
+      this.getTargets = targets;
+      defExt = false;
+    }
+    else
+    { // Simple getter for a static value
+      if (!isIterable(targets))
+      {
+        targets = [targets];
+      }
+      this.getTargets = () => targets;
+      defExt = true;
+    }
+
+    this.options = Object.assign({}, DEF_OPTIONS, opts);
+
+    this.allListeners = new Set();
+    this.listenersFor = new Map();
+
+    const extOpts = opts.extend ?? defExt;
+    if (extOpts !== false)
+    {
+      const intNames = Object.keys(DEF_EXTENDS);
+      const extNames = Object.assign({}, DEF_EXTENDS, extOpts);
+      const targets = this.getTargets();
+
+      for (const iname of intNames)
+      {
+        if (typeof extNames[iname] === S && extNames[iname].trim() !== '')
+        {
+          const ename = extNames[iname];
+          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)
+            {
+              def(target, ename, {value});
+            }
+            else
+            {
+              console.error("Won't overwrite existing property",
+                {target,iname,ename,registry: this});
+            }
+          }
+        }
+      }
+    }
+  } // constructor()
+
+  /**
+   * Build a new Listener instance; used by `listen()` method.
+   * 
+   * @param  {(string|object)} eventNames 
+   * What this does depends on the type, and the number of arguments passed.
+   * 
+   * If this is an `object` **AND** is *the only argument* passed,
+   * 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 
+   * will be used as the `spec.eventNames` property.
+   * 
+   * @param {module:@lumjs/core/events~Handler} [handler] 
+   * Used as the `spec.handler` property if specified.
+   * 
+   * This is mandatory if `eventNames` argument is a `string`!
+   * 
+   * @param {object} [spec] The listener specification rules
+   * 
+   * @param {(string|Iterable)} [spec.eventNames] Event names to listen for
+   * 
+   * See {@link module:@lumjs/core/events.Registry#getEventNames} for details.
+   * 
+   * @param {module:@lumjs/core/events~Handler} [spec.handler] Event handler.
+   * 
+   * @param {(function|object)} [spec.listener] An alias for `handler`
+   * 
+   * @param {object} [spec.options] Options for the listener
+   * 
+   * The option properties can be included directly in the `spec` itself
+   * for brevity, but a nested `options` object is supported to be more
+   * like the `DOM.addEventListener()` method. Either way works fine.
+   * 
+   * If `spec.options` is used, the properties in it take precedence over
+   * those directly in the `spec` object. Note that you cannot use the
+   * names `listener`, `handler` or `eventNames` as option properties,
+   * and if found, they will be removed.
+   * 
+   * You may also override the `setupEvent` registry option here.
+   * 
+   * @param {boolean} [spec.options.once=false] Only use the listener once?
+   * 
+   * If this is set to `true`, then the first time this listener is used in
+   * an {@link module:@lumjs/core/events.Registry#emit emit()} call, it will
+   * be removed from the registry at the end of the emit process (after all
+   * events for all targets have been triggered).
+   * 
+   * @returns {module:@lumjs/core/events.Listener} A new `Listener` instance
+   */
+  makeListener(...args)
+  {
+    let spec;
+
+    if (args.length === 0 || args.length > 3)
+    { 
+      console.error({args, registry: this});
+      throw new RangeError("Invalid number of arguments");
+    }
+    else if (args.length === 1 && isObj(args[0]))
+    { // listen(spec)
+      spec = Object.assign({}, args[0]);
+    }
+    else
+    { // listen(eventNames, listener, [spec])
+      spec = Object.assign({}, args[2]);
+      spec.eventNames = args[0];
+      spec.handler    = args[1];
+    }
+
+    return new Listener(this, spec);
+  }
+
+  /**
+   * Assign a new event listener.
+   * 
+   * Calls `this.makeListener()` passing all arguments to it.
+   * Then calls `this.add(listener)` passing the newly make `Listener`.
+   * 
+   * @param {...mixed} args
+   * @returns {module:@lumjs/core/events.Listener}
+   */
+  listen()
+  {
+    const listener = this.makeListener(...arguments)
+    this.add(listener);
+    return listener;
+  }
+
+  /**
+   * Assign a new event listener that will only run once.
+   * 
+   * Calls `this.listen()` passing all arguments to it,
+   * then sets the `listener.options.once` to `true`.
+   * 
+   * @param {...mixed} args
+   * @returns {module:@lumjs/core/events.Listener}
+   */
+  once()
+  {
+    const listener = this.listen(...arguments);
+    listener.options.once = true;
+    return listener;
+  }
+
+  /**
+   * Add a Listener instance.
+   * 
+   * You'd generally use `listen()` or `once()` rather than this, but if
+   * you need to (re-)add an existing instance, this is the way to do it.
+   * 
+   * @param {module:@lumjs/core/events.Listener} listener - Listener instance
+   * 
+   * If the same instance is passed more than once it will have no affect,
+   * as we store the instances in a `Set` internally, so it'll only ever
+   * be stored once.
+   * 
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  add(listener)
+  {
+    if (!(listener instanceof Listener))
+    {
+      console.error({listener, registry: this});
+      throw new TypeError("Invalid listener instance");
+    }
+
+    this.allListeners.add(listener);
+
+    for (const ename of listener.eventNames)
+    {
+      let lset;
+      if (this.listenersFor.has(ename))
+      {
+        lset = this.listenersFor.get(ename);
+      }
+      else
+      {
+        lset = new Set();
+        this.listenersFor.set(ename, lset);
+      }
+
+      lset.add(listener);
+    }
+    
+    return this;
+  }
+
+  /**
+   * Remove **ALL** registered event listeners!
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  removeAll()
+  {
+    this.allListeners.clear();
+    this.listenersFor.clear();
+    return this;
+  }
+
+  /**
+   * Remove specific event names.
+   * 
+   * It will remove any of the the specified event names
+   * from applicable listener instances, and clear the
+   * associated `listenersFor` set.
+   * 
+   * If a listener has no more event names left, that listener
+   * will be removed from the `allListeners` set as well.
+   * 
+   * @param  {...string} names - Event names to remove
+   * 
+   * If the `wildcard` string is specified here, this will simply
+   * remove any wildcard listeners currently registered.
+   * See `remove(wildcard)` or `removeAll()` if you really want
+   * to remove **ALL** listeners.
+   * 
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  removeEvents(...names)
+  {
+    for (const name of names)
+    {
+      if (this.listenersFor.has(name))
+      {
+        const eventListeners = this.listenersFor.get(name);
+        for (const lsnr of eventListeners)
+        {
+          lsnr.eventNames.delete(name);
+          if (!lsnr.hasEvents)
+          { // The last event name was removed.
+            this.removeListeners(lsnr);
+          }
+        }
+        eventListeners.clear();
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Remove specific Listener instances
+   * @param {...module:@lumjs/core/events.Listener} listeners 
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  removeListeners(...listeners)
+  {
+    for (const listener of listeners)
+    {
+      if (this.allListeners.has(listener))
+      { // First remove it from allListeners
+        this.allListeners.delete(listener);
+  
+        for (const ename of listener.eventNames)
+        {
+          if (this.listenersFor.has(ename))
+          {
+            const lset = this.listenersFor.get(ename);
+            lset.delete(listener);
+          }
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Remove listeners based on the value type used.
+   * 
+   * @param {(string|module:@lumjs/core/events.Listener)} what
+   * 
+   * - If this is the `wildcard` string, then this will call `removeAll()`.
+   * - If this is any other `string` it will be split using `splitNames()`,
+   *   and the resulting strings passed as arguments to `removeEvents()`.
+   * - If this is a `Listener` instance, its passed to `removeListeners()`.
+   * 
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   * @throws {TypeError} If `what` is none of the above values.
+   */
+  remove(what)
+  {
+    if (what === this.options.wildcard)
+    {
+      return this.removeAll();
+    }
+    else if (typeof what === S)
+    { 
+      const events = this.splitNames(what);
+      return this.removeEvents(...events);
+    }
+    else if (what instanceof Listener)
+    {
+      return this.removeListeners(what);
+    }
+    else
+    {
+      console.error({what, registry: this});
+      throw new TypeError("Invalid event name or listener instance");
+    }
+  }
+
+  /**
+   * Emit (trigger) one or more events.
+   * 
+   * @param {(string|string[])} eventNames - Events to emit.
+   * 
+   * If this is a single `string` it will be split via `splitNames()`.
+   * 
+   * @param  {object} [data] A data object (highly recommended);
+   * will be assigned to `event.data` if specified.
+   * 
+   * @param  {...any} [args] Any other arguments;
+   * will be assigned to `event.args`.
+   * 
+   * Note: if a `data` object argument was passed, it will always 
+   * be the first item in `event.args`.
+   * 
+   * @returns {module:@lumjs/core/events~Status}
+   */
+  emit(eventNames, ...args)
+  {
+    const sti =
+    {
+      eventNames: this.getEventNames(eventNames),
+      multiMatch: this.options.multiMatch,
+      onceRemoved: new Set(),
+      stopEmitting: false,
+      emitted: [],
+    }
+
+    { // Get the targets.
+      const tgs = this.getTargets(sti);
+      sti.targets = (tgs instanceof Set) ? tgs : new Set(tgs);
+    }
+
+    const wilds = this.listenersFor.get(this.options.wildcard);
+
+    emitting: for (const tg of sti.targets)
+    {
+      const called = sti.targetListeners = new Set();
+      for (const ename of sti.eventNames)
+      {
+        if (!this.listenersFor.has(ename)) continue;
+
+        let listeners = this.listenersFor.get(ename);
+        if (wilds) listeners = listeners.union(wilds);
+
+        for (const lsnr of listeners)
+        {
+          if (sti.multiMatch || !called.has(lsnr))
+          { // Let's emit an event!
+            called.add(lsnr);
+            const event = lsnr.emitEvent(ename, tg, args, sti);
+            sti.emitted.push(event);
+            if (sti.stopEmitting)
+            {
+              break emitting;
+            }
+          }
+        }
+      }
+    }
+
+    // Nix the targetListeners property.
+    delete sti.targetListeners;
+
+    // Handle any `onceRemoved` listeners.
+    for (const lsnr of sti.onceRemoved)
+    {
+      this.removeListeners(lsnr);
+    }
+
+    // Return the final status.
+    return sti;
+  }
+
+  /**
+   * Get a Set of event names from various kinds of values
+   * @param {(string|Iterable)} names - Event names source
+   * 
+   * If this is a string, it'll be passed to `splitNames()`.
+   * If it's any kind of `Iterable`, it'll be converted to a `Set`.
+   * 
+   * @returns {Set}
+   * @throws {TypeError} If `names` is not a valid value
+   */
+  getEventNames(names)
+  {
+    if (typeof names === S)
+    {
+      return this.splitNames(names);
+    }
+    else if (names instanceof Set)
+    {
+      return names;
+    }
+    else if (isIterable(names))
+    {
+      return new Set(names);
+    }
+    else
+    {
+      console.error({names, registry: this});
+      throw new TypeError("Invalid event names");
+    }
+  }
+
+  /**
+   * Split a (trimmed) string using `this.options.delimiter`
+   * @param {string} names - String to split
+   * @returns {Set}
+   */
+  splitNames(names)
+  {
+    return new Set(names.trim().split(this.options.delimiter));
+  }
+
+}
+
+module.exports = LumEventRegistry;

package/lib/index.js

@@ -22,6 +22,7 @@ const types = require('./types');
 /**
  * Define properties on an object or function
  * @name module:@lumjs/core.def
+ * @function
  * @see module:@lumjs/core/types.def
  */
 const def = types.def;
@@ -29,6 +30,7 @@ const def = types.def;
 /**
  * Define *lazy* properties on an object or function
  * @alias module:@lumjs/core.lazy
+ * @function
  * @see module:@lumjs/core/types.lazy
  */
 const lazy = types.lazy;
@@ -80,7 +82,7 @@ lazy(exports, 'flags', () => require('./flags'));
 lazy(exports, 'obj', () => require('./obj'));
 
 /**
- * A wrapper around the Javascript console.
+ * A wrapper around the Javascript console «Lazy»
  * @name module:@lumjs/core.console
  * @type {module:@lumjs/core/console}
  */
@@ -138,7 +140,20 @@ from(require('./objectid'));
  * @see module:@lumjs/core/meta.NYI
  */
 
-// TODO: documentation for 'deprecated' and 'wrapDepr'
+/**
+ * A function indicating that something is deprecated
+ * @name module:@lumjs/core.deprecated
+ * @function
+ * @see module:@lumjs/core/meta.deprecated
+ */
+
+/**
+ * Assign a getter property to an object that calls the `deprecated`
+ * function with a specific message before returning the proxied value.
+ * @name module:@lumjs/core.wrapDepr
+ * @function
+ * @see module:@lumjs/core/meta.wrapDepre
+ */
 
 // These are exported directly, but a meta sub-module also exists.
 // Unlike most sub-modules there is no `meta` property in the main library.
@@ -165,3 +180,9 @@ lazy(exports, 'Enum', () => require('./enum'));
  */
 lazy(exports, 'observable', () => require('./observable'));
 
+/**
+ * The Events module «Lazy»
+ * @name module:@lumjs/core.events
+ * @see module:@lumjs/core/events
+ */
+lazy(exports, 'events', () => require('./events'));

package/lib/meta.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Meta-programming helpers
+ * 
+ * All of the function exported by this module are also available
+ * in the main {@link module:@lumjs/core core object} itself.
+ * 
+ * @module @lumjs/core/meta
+ */
 
 const {F} = require('./types/js');
 
@@ -13,7 +21,7 @@ const {F} = require('./types/js');
  * @param {string} [msg] - A message for the Error object.
  *
  * @returns {string[]} An array of stack strings.
- * @alias module:@lumjs/core.stacktrace
+ * @alias module:@lumjs/core/meta.stacktrace
  */
 function stacktrace(msg)
 {
@@ -50,7 +58,7 @@ exports.stacktrace = stacktrace;
  * }
  * ```
  * 
- * @alias module:@lumjs/core.AbstractError
+ * @alias module:@lumjs/core/meta.AbstractError
  */
 class AbstractError extends Error
 {
@@ -82,8 +90,7 @@ exports.AbstractError = AbstractError;
 
 /**
  * Function prototypes for async, generator, and async generator functions.
- * @namespace
- * @alias module:@lumjs/core.Functions
+ * @alias module:@lumjs/core/meta.Functions
  */
 const Functions =
 {
@@ -114,7 +121,7 @@ exports.Functions = Functions;
  * @param {string} [prefix=''] A prefix for the error message.
  * 
  * @returns {void}
- * @alias module:@lumjs/core.NYI
+ * @alias module:@lumjs/core/meta.NYI
  */
 function NYI(fatal=true, prefix='') 
 { 
@@ -134,7 +141,7 @@ exports.NYI = NYI;
  * @param {(string|string[])} [rep] Replacement suggestion(s).
  * @param {*} [ret] Value to return
  * @returns {mixed} `ret`
- * @alias module:@lumjs/core.deprecated
+ * @alias module:@lumjs/core/meta.deprecated
  */
 function deprecated(dep, rep, ret)
 {
@@ -167,6 +174,8 @@ exports.deprecated = deprecated;
  * @param {object} [spec.opts] Options for `def()` to add getter with.
  * 
  * @returns {object} `obj`
+ * 
+ * @alias module:@lumjs/core/meta.wrapDepr
  */
 function wrapDepr(obj,prop,spec)
 {

package/lib/obj/copyprops.js

@@ -406,7 +406,7 @@ copyProps.from = function(...sources)
   return ((new $CopyProps()).from(...sources));
 }
 
-const CPC = copyProps.cache =
+copyProps.cache =
 {
   into(target)
   {