@lumjs/core 1.37.0 → 1.37.2

package/lib/events/event.js

@@ -1,13 +1,16 @@
 "use strict";
 
-const {F,isObj} = require('../types');
+const {SY,F,isObj} = require('../types');
 
 /**
  * An Event object to emit to handler callbacks.
  * 
  * @prop {module:@lumjs/core/events.Listener} eventListener
  * The event Listener instance this event was emitted from.
- * @prop {string} name - The event name that was triggered.
+ * @prop {(string|Symbol)} type - The event type that was triggered.
+ * @prop {string} name - The event name that was triggered;
+ * if `type` is a string this will be the same value,
+ * for a Symbol type this will be the `type.description` value.
  * @prop {object} target - Target object for this event.
  * @prop {Array} args - Arguments passed to `emit()`
  * @prop {object} options - Composes options from the
@@ -38,17 +41,18 @@ class LumEvent
    * @protected
    * @param {module:@lumjs/core/events.Listener} listener 
    * @param {object} target 
-   * @param {string} name 
-   * @param {Array}  args 
+   * @param {(string|Symbol)} type 
+   * @param {Array} args 
    * @param {object} status
    */
-  constructor(listener, target, name, args, status)
+  constructor(listener, target, type, args, status)
   {
     const reg = listener.registry;
     this.eventListener = listener;
     this.args = args;
     this.target = target;
-    this.name = name;
+    this.type = type;
+    this.name = (typeof type === SY) ? type.description : type;
     this.emitStatus = status;
     this.options = Object.assign({},
       reg.options,

package/lib/events/listener.js

@@ -1,9 +1,9 @@
 "use strict";
 
-const {F,isObj,def} = require('../types');
+const {F,isObj} = require('../types');
 const Event = require('./event');
 
-const REMOVE_OPTS = ['listener','handler','eventNames'];
+const REMOVE_OPTS = ['listener','handler','eventNames','eventTypes'];
 
 function makeOpts(spec)
 {
@@ -41,7 +41,8 @@ function isListener(v)
  * @prop {module:@lumjs/core/events.Registry} registry 
  * The Registry instance this Listener belongs to.
  * @prop {(function|object)} handler - Event handler callback
- * @prop {Set} eventNames - A set of all event names handled by this
+ * @prop {Set} eventTypes - A set of all event types handled by this
+ * @prop {Set} eventNames - Alias to `eventTypes`
  * @prop {object} options - Options specific to this listener.
  * 
  * See {@link module:@lumjs/core/events.Registry#makeListener makeListener()}
@@ -76,7 +77,8 @@ class LumEventListener
     // Assign the rest here.
     this.registry = registry;
     this.options = makeOpts(spec);
-    this.eventNames = registry.getEventNames(spec.eventNames);
+    const events = spec.eventTypes ?? spec.eventNames;
+    this.eventTypes = this.eventNames = registry.getEventNames(events);
 
     const setup = this.options.setupListener ?? registry.options.setupListener;
     if (typeof setup === F)
@@ -86,12 +88,12 @@ class LumEventListener
   }
 
   /**
-   * See if there is at least one item in `this.eventNames`
+   * See if there is at least one item in `this.eventTypes`
    * @type {boolean}
    */
   get hasEvents()
   {
-    return this.eventNames.size > 0;
+    return this.eventTypes.size > 0;
   }
 
   /**
@@ -100,15 +102,15 @@ class LumEventListener
    * 
    * This is a *protected method* and should not be called directly.
    * @protected
-   * @param {string} eventName - A single event name that was triggered
+   * @param {string} type      - A single event type/name that was triggered
    * @param {object} target    - A single target object
    * @param {Array}  args      - Arguments passed to `emit()`
    * @param {module:@lumjs/core/events~Status} status - Emit status info
    * @returns {module:@lumjs/core/events.Event} The new Event that was emitted
    */
-  emitEvent(eventName, target, args, status)
+  emitEvent(type, target, args, status)
   {
-    const event = new Event(this, target, eventName, args, status);
+    const event = new Event(this, target, type, args, status);
 
     if (typeof this.handler === F)
     { // The simplest is the good old function

package/lib/events/registry.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const {S,F,isObj,def,isIterable} = require('../types');
+const {S,F,SY,isObj,def,isIterable} = require('../types');
 const Listener = require('./listener');
 const RegSym = Symbol('@lumjs/core/events:registry');
 const cp = Object.assign;
@@ -30,8 +30,8 @@ const DEF_OPTIONS =
 
 const RES_PROPS =
 [
-  'eventNames', 'targets', 'multiMatch', 'onceRemoved', 'stopEmitting',
-  'emitted', 'targetListeners', 'registry',
+  'eventNames', 'eventTypes', 'targets', 'multiMatch', 'onceRemoved', 
+  'stopEmitting', 'emitted', 'targetListeners', 'registry',
 ]
 
 /**
@@ -47,7 +47,7 @@ const isRegistered = target => isObj(target[RegSym]);
  * @private
  * @param {object} target - Object to get metadata for
  * @param {boolean} [create=false] Create metadata if it's not found?
- * @returns {object} metadata (TODO: schema docs)
+ * @returns {(object|undefined)} metadata (TODO: schema docs)
  * @alias module:@lumjs/core/events.Registry.getMetadata
  */
 function getMetadata(target, create=false)
@@ -58,10 +58,16 @@ function getMetadata(target, create=false)
   }
   else if (create)
   { // Create new metadata
+    const exts = Object.keys(DEF_EXTENDS);
     const tpm = 
     {
       r: new Map(),
       p: {},
+      x: {},
+    }
+    for (const ext of exts)
+    {
+      tpm.x[ext] = [];
     }
     def(target, RegSym, tpm);
     return tpm;
@@ -263,7 +269,8 @@ class LumEventRegistry
       {
         for (const iname of intNames)
         {
-          if (typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
+          if ((typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
+            || typeof extOpts[iname] === SY)
           {
             const ename = extOpts[iname];
             const value = iname === 'registry' 
@@ -274,6 +281,7 @@ class LumEventRegistry
               def(target, ename, {value});
               tps[ename] = iname;
               tpm.p[ename] = this;
+              tpm.x[iname].push([this, ename]);
             }
             else
             {
@@ -307,7 +315,8 @@ class LumEventRegistry
     for (const iname of intNames)
     {
       if (iname === 'registry') continue; // skip the registry property
-      if (typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
+      if ((typeof extOpts[iname] === S && extOpts[iname].trim() !== '')
+        || typeof extOpts[iname] === SY)
       {
         const ename = extOpts[iname];
         if (reserved.includes(ename))
@@ -332,28 +341,30 @@ class LumEventRegistry
   /**
    * Build a new Listener instance; used by `listen()` method.
    * 
-   * @param  {(string|object)} eventNames 
+   * @param  {(string|symbol|object)} eventTypes 
    * 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`
+   * it will be used as the `spec`, and the `spec.eventTypes`
    * 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.
+   * If it's NOT an object *OR* there is more than one argument, this
+   * will be used as the `spec.eventTypes` 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`!
+   * This is mandatory if `eventTypes` argument is a string or Symbol!
    * 
    * @param {object} [spec] The listener specification rules
    * 
-   * @param {(string|Iterable)} [spec.eventNames] Event names to listen for
+   * @param {(string|symbol|Iterable)} [spec.eventTypes] Event type(s)
    * 
    * See {@link module:@lumjs/core/events.Registry#getEventNames} for details.
    * 
-   * @param {module:@lumjs/core/events~Handler} [spec.handler] Event handler.
+   * @param {(string|symbol|Iterable)} [spec.eventNames] Alias of `eventTypes`
+   * 
+   * @param {module:@lumjs/core/events~Handler} [spec.handler] Event handler
    * 
    * @param {(function|object)} [spec.listener] An alias for `handler`
    * 
@@ -365,8 +376,8 @@ class LumEventRegistry
    * 
    * 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.
+   * names `listener`, `handler`, `eventTypes`, or `eventNames` as option 
+   * properties, and if found, they will be removed.
    * 
    * You may also override the `setupEvent` and `setupListener` registry
    * options here if needed.
@@ -394,9 +405,9 @@ class LumEventRegistry
       spec = cp({}, args[0]);
     }
     else
-    { // listen(eventNames, listener, [spec])
+    { // listen(eventTypes, listener, [spec])
       spec = cp({}, args[2]);
-      spec.eventNames = args[0];
+      spec.eventTypes = args[0];
       spec.handler    = args[1];
     }
 
@@ -464,7 +475,7 @@ class LumEventRegistry
 
     this.allListeners.add(listener);
 
-    for (const ename of listener.eventNames)
+    for (const ename of listener.eventTypes)
     {
       let lset;
       if (this.listenersFor.has(ename))
@@ -522,7 +533,7 @@ class LumEventRegistry
         const eventListeners = this.listenersFor.get(name);
         for (const lsnr of eventListeners)
         {
-          lsnr.eventNames.delete(name);
+          lsnr.eventTypes.delete(name);
           if (!lsnr.hasEvents)
           { // The last event name was removed.
             this.removeListeners(lsnr);
@@ -547,7 +558,7 @@ class LumEventRegistry
       { // First remove it from allListeners
         this.allListeners.delete(listener);
   
-        for (const ename of listener.eventNames)
+        for (const ename of listener.eventTypes)
         {
           if (this.listenersFor.has(ename))
           {
@@ -568,6 +579,7 @@ class LumEventRegistry
    * - 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 `Symbol` it will be passed to `removeEvents()`.
    * - If this is a `Listener` instance, its passed to `removeListeners()`.
    * 
    * @returns {module:@lumjs/core/events.Registry} `this`
@@ -584,6 +596,10 @@ class LumEventRegistry
       const events = this.splitNames(what);
       return this.removeEvents(...events);
     }
+    else if (typeof what === SY)
+    {
+      return this.removeEvents(what);
+    }
     else if (what instanceof Listener)
     {
       return this.removeListeners(what);
@@ -598,9 +614,8 @@ class LumEventRegistry
   /**
    * 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 {(string|symbol|Array)} eventTypes - Events to emit;
+   * see {@link module:@lumjs/core/events#getEventTypes} for details.
    * 
    * @param  {object} [data] A data object (highly recommended);
    * will be assigned to `event.data` if specified.
@@ -613,18 +628,19 @@ class LumEventRegistry
    * 
    * @returns {module:@lumjs/core/events~Status}
    */
-  emit(eventNames, ...args)
+  emit(eventTypes, ...args)
   {
     const extOpts = this.options.extend;
     const sti =
     {
-      eventNames: this.getEventNames(eventNames),
+      eventTypes: this.getEventTypes(eventTypes),
       multiMatch: this.options.multiMatch,
       onceRemoved: new Set(),
       stopEmitting: false,
       emitted: [],
       registry: this,
     }
+    sti.eventNames = sti.eventTypes;
 
     if (extOpts.results)
     {
@@ -645,7 +661,7 @@ class LumEventRegistry
     emitting: for (const tg of sti.targets)
     {
       const called = sti.targetListeners = new Set();
-      for (const ename of sti.eventNames)
+      for (const ename of sti.eventTypes)
       {
         if (!this.listenersFor.has(ename)) continue;
 
@@ -793,32 +809,37 @@ class LumEventRegistry
   }
 
   /**
-   * Get a Set of event names from various kinds of values
-   * @param {(string|Iterable)} names - Event names source
+   * Get a Set of event types/names from various kinds of values
+   * @param {(string|symbol|Iterable)} types - Event types 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`.
+   * If it's a Symbol, it'll be wrapped in a Set.
+   * If it's any kind of Iterable value, it'll be converted to a Set.
    * 
    * @returns {Set}
    * @throws {TypeError} If `names` is not a valid value
    */
-  getEventNames(names)
+  getEventTypes(types)
   {
-    if (typeof names === S)
+    if (typeof types === S)
     {
-      return this.splitNames(names);
+      return this.splitNames(types);
     }
-    else if (names instanceof Set)
+    else if (typeof types === SY)
     {
-      return names;
+      return new Set([types]);
     }
-    else if (isIterable(names))
+    else if (types instanceof Set)
     {
-      return new Set(names);
+      return types;
+    }
+    else if (isIterable(types))
+    {
+      return new Set(types);
     }
     else
     {
-      console.error({names, registry: this});
+      console.error({names: types, registry: this});
       throw new TypeError("Invalid event names");
     }
   }
@@ -835,9 +856,20 @@ class LumEventRegistry
 
 }
 
+const LERP = LumEventRegistry.prototype;
+def(LERP, 'getEventNames', LERP.getEventTypes);
+
 cp(LumEventRegistry, 
 { 
   isRegistered, getMetadata, targetsAre,
 });
 
 module.exports = LumEventRegistry;
+
+/**
+ * An alias to `getEventTypes`
+ * @function module:@lumjs/core/events.Registry#getEventNames
+ * @param {(string|symbol|Iterable)} names - Event names source
+ * @returns {Set}
+ * @see module:@lumjs/core/events.Registry#getEventTypes
+ */

package/lib/types/def.js

@@ -1,7 +1,7 @@
-// Thanks to CJS `require()` rules, recursive dependencies are possible.
-const unbound = require('./root').unbound;
-const {F, B} = require('./js');
-const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
+"use strict";
+
+const {F,B} = require('./js');
+const {isObj,isNil,isProperty,doesDescriptor} = require('./basics');
 const clone = (...args) => Object.assign({}, ...args);
 
 /**
@@ -95,9 +95,10 @@ const clone = (...args) => Object.assign({}, ...args);
  */
 function def(obj, name, value, opts)
 {
-  const isBound // Is this a 'bound' def function?
-    = !unbound(this, true, true) 
-    && typeof this.bound === F;
+  const isBound
+    = isObj(this)
+    && typeof this.bound === F
+    && this.bound.$this === this;
 
   if (isNil(name) || typeof name === B)
   { // Binding of Isaac?

package/lib/types/isa.js

@@ -461,7 +461,7 @@ class OfTest
     }
     else if (isObj(rules))
     {
-      this.valid = valid(rules.valid);
+      this.valid = valid(rules.value);
     }
     else
     { // That's gonna be a no from me.

package/lib/types/root.js

@@ -1,5 +1,5 @@
 const {U} = require('./js');
-const {isNil,isArray} = require('./basics');
+const {isNil,isObj,isArray} = require('./basics');
 
 // «private»
 function no_root()
@@ -11,40 +11,81 @@ function no_root()
  * The global root object. Usually `globalThis` these days.
  * @alias module:@lumjs/core/types.root
  */
-const root = typeof globalThis !== U ? globalThis
-  : typeof global !== U ? global 
-  : typeof self !== U ? self 
-  : typeof window !== U ? window 
+const root 
+  = typeof globalThis !== U ? globalThis
+  : typeof global     !== U ? global 
+  : typeof self       !== U ? self 
+  : typeof window     !== U ? window 
   : no_root(); // Unlike the old way, we'll die if the environment is undetermined.
 
 exports.root = root;
 
-// A list of objects to be considered unbound globally.
+// A Set of objects to be considered unbound globally.
 const unboundObjects = require('./unbound/objects');
 
+// Default options for unbound()
+const UBDO =
+{
+  nil:   true,
+  root:  true,
+}
+
 /**
  * Pass `this` here to see if it is bound to an object.
  * 
- * Always considers `null` and `undefined` as unbound.
+ * @param {*} whatIsThis - The `this` from any context
+ * 
+ * @param {(boolean|object)} [opts] Options for advanced behaviours.
+ * 
+ * If this is boolean then it'll be used as `opts.root`;
+ * If it is an `Array` or `Set` it will be used as `opts.list`;
+ * Use just a plain object literal for specifying named options.
+ * 
+ * TODO: as of v2.0 this will no longer accept a boolean value
+ * as a shortcut to `opts.root`. That must be explicitly set.
+ * 
+ * @param {boolean} [opts.root=true] The global root is unbound?
+ * @param {boolean} [opts.nil=true] `null` and `undefined` are unbound?
+ * @param {(Array|Set)} [opts.list] A list of additional values that
+ * for the purposes of this test will be considered unbound.
+ * 
+ * @param {(Array|Set|boolean)} [list] A positional version of `opts.list`;
+ * ONLY used when the `opts` argument is boolean.
+ * 
+ * TODO: remove this argument as of v2.0
  * 
- * @param {*} whatIsThis - The `this` from any context.
- * @param {boolean} [rootIsUnbound=true] The global root is unbound. 
- * @param {(boolean|Array)} [areUnbound=false] A list of unbound objects.
- *   If the is `true` we use an global list that can register special
- *   internal objects. Otherwise an `Array` of unbound objects may be used.
  * @returns {boolean}
  * @alias module:@lumjs/core/types.unbound
  */
-function unbound(whatIsThis, rootIsUnbound=true, areUnbound=false)
+function unbound(whatIsThis, opts=true, list)
 {
-  if (areUnbound === true)
-  { // If areUnbound is true, we use the unboundObjects 
-    areUnbound = unboundObjects;
+  if (isObj(opts))
+  { // Merge in defaults
+    if (opts instanceof Set || isArray(opts))
+    { // A shortcut to the `list` property
+      list = opts;
+      opts = Object.assign({}, UBDO);
+    }
+    else
+    { // Regular options were specified.
+      opts = Object.assign({}, UBDO, {list}, opts);
+      list = opts.list;
+    }
+  }
+  else
+  { // Assume old positional arguments are being used
+    opts = Object.assign({}, UBDO, {root: opts});
+  }
+
+  if (list === true)
+  { // Internal special unbound values
+    list = unboundObjects;
   }
 
-  if (isNil(whatIsThis)) return true;
-  if (rootIsUnbound && whatIsThis === root) return true;
-  if (isArray(areUnbound) && areUnbound.includes(whatIsThis)) return true;
+  if (opts.nil && isNil(whatIsThis)) return true;
+  if (opts.root && whatIsThis === root) return true;
+  if (list instanceof Set && list.has(whatIsThis)) return true;
+  if (isArray(list) && list.includes(whatIsThis)) return true;
 
   // Nothing considered unbound.
   return false;

package/lib/types/unbound/extend.js

@@ -2,45 +2,41 @@
 
 const def = require('../def');
 const {needObj} = require('../needs');
-const removeFromArray = require('../../arrays/list').removeItems;
 const unboundObjects = require('./objects');
 
-// Adds a couple magic methods to the `unbound` function.
+// Adds a couple proxy methods to the `unbound` function.
 module.exports = function(unbound)
 {
   /**
    * Add an item to the unbound global objects list.
    * 
-   * @function
-   * @param {(object|function)} obj - The object to be considered unbound.
-   * @returns {boolean} Will be `false` if `obj` is already unbound.
-   * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
-   * @name module:@lumjs/core/types.unbound.add
+   * @deprecated the global list is going away in 2.0
+   * @function module:@lumjs/core/types.unbound.add
+   * @param {(object|function)} obj - Value to be added
+   * @returns {boolean} always true as of v1.37.2
+   * @throws {TypeError} If `obj` was not a valid value
    */
   def(unbound, 'add', function (obj)
   {
     needObj(obj, true);
-    if (unbound(obj, true, true))
-    { // Item is already unbound.
-      return false;
-    }
-    // Add to list and we're done.
-    unboundObjects.push(obj);
+    if (unboundObjects.has(obj)) return false;
+    unboundObjects.add(obj);
     return true;
   });
 
   /**
    * Remove an item from the unbound global objects list.
    * 
-   * @function
-   * @param {(object|function)} obj - The object to be removed.
-   * @returns {boolean} Will be `false` if the item was not in the list.
-   * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
-   * @name module:@lumjs/core/types.unbound.remove
+   * @deprecated the global list is going away in 2.0
+   * @function module:@lumjs/core/types.unbound.remove
+   * @param {(object|function)} obj - value to be removed
+   * @returns {boolean} always true as of v1.37.2
+   * @throws {TypeError} If `obj` was not a valid value
    */
   def(unbound, 'remove', function(obj)
   {
     needObj(obj, true);
-    return (removeFromArray(unboundObjects, obj) > 0);
+    unboundObjects.delete(obj);
+    return true;
   });
 }

package/lib/types/unbound/objects.js

@@ -1,2 +1,3 @@
 // Private storage, not exported outside the package.
-module.exports = [];
+// TODO: remove this in 2.0
+module.exports = new Set();

package/package.json

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