@lumjs/core 1.30.0 → 1.31.1

package/README.md

@@ -26,7 +26,7 @@ You can compile the documentation using `npm run build-docs`
 which will put the generated docs into the `./docs/api` folder.
 
 ### [Changelog](./docs/changelogs/1.x.md)
-### [TODO](TODO.md)
+### [TODO](./docs/TODO.md)
 ### [Homepage](https://supernovus.github.io/)
 
 ## Official URLs

package/jsdoc.js

@@ -0,0 +1,13 @@
+"use strict";
+
+const docRules = require('@lumjs/build/jsdoc-rules');
+const ourRules = docRules.docsReadme.srcDocs.clone();
+module.exports = ourRules;
+
+/*console.debug(
+{
+  docRules,
+  ourRules,
+  incPath: ourRules?.source?.include,
+});*/
+

package/lib/enum.js

@@ -1,6 +1,11 @@
-const {S,def,notNil,isObj,needObj,TYPES} = require('./types');
+const {S,F,def,notNil,isObj,needObj,TYPES} = require('./types');
 const {InternalObjectId} = require('./objectid');
 
+/**
+ * A pseudo-module describing everything associated with `core.Enum`
+ * @module @lumjs/core/enum
+ */
+
 // Internal id instances should never be exported.
 const EID = '@lumjs/core/enum';
 const ENUM_ID = new InternalObjectId({name: EID});
@@ -12,6 +17,8 @@ const EOPT = Symbol(EID+':opts');
  * 
  * Like the built-in `Symbol`, this is called as a function, not a constructor.
  * 
+ * This is the *actual* exported value from the `enum` pseudo-module.
+ * 
  * @param {(string[]|object)} spec - May be in one of two formats:
  * 
  * - An `Array` of strings. Each string represents the name of an Enum 
@@ -27,7 +34,13 @@ const EOPT = Symbol(EID+':opts');
  * 
  * @param {object} [opts] Options for creating the Enum
  * 
- * @param {bool} [opts.symbols=false] Use `Symbol` property values.
+ * If the `opts` is an _open_ `Enum` object, then 
+ * 
+ * @param {(bool|function)} [opts.symbols=false] Use `Symbol` property values.
+ * 
+ * If this is a `function`, it will be passed the name that would be used as
+ * the symbol key, and must return the actual key string to use, or any
+ * non-string value to disable the use of symbols for that name.
  * 
  * @param {bool} [opts.globals=false] Use `Symbol.for()` property values.
  * 
@@ -48,18 +61,24 @@ const EOPT = Symbol(EID+':opts');
  * 
  * The default value is `1` if `opts.flags` is `true` or `0` otherwise.
  * 
- * @param {bool} [opts.open=false] If `true` the Enum object won't be locked.
- * If `false`, by default we use `Object.freeze()` to lock the object.
+ * @param {bool} [opts.open=false] Should the Enum be open to be extended?
+ * 
+ * - If `true` the Enum object won't be locked, and the `opts` will be saved.
+ * - If `false` (default value) we use `Object.freeze()` to lock the object.
  * 
  * @param {(bool|object|Array)} [opts.lock=null] If this is *not* `null`, 
  * use {@see module:@lumjs/core/obj.lock lock()} instead of `Object.freeze()`.
  * 
- * Only used if `opts.open` is `false`. The supported values are:
+ * If `opts.open` is `false`, the supported values are:
  * 
  * - `Array`: The `[cloneable, cloneOpts, useSeal]` parameters for `clone()`.
  * - `object`: The `cloneOpts` parameter for `clone()`.
  * - `bool`: The `cloneable` parameter for `clone()`.
  * 
+ * If `opts.open` is `true`, this only supports an `object` which will be
+ * used as the `opts` for {@see module:@lumjs/core/obj.addLock addLock()},
+ * which will be called on the open Enum object.
+ * 
  * @param {bool} [opts.configurable=false] Enum properties are configurable?
  * 
  * This option is ignored if `opts.open` is `false`.
@@ -68,7 +87,7 @@ const EOPT = Symbol(EID+':opts');
  * 
  * @returns {object} A magic Enum object.
  * @throws {TypeError} If an invalid value was passed.
- * @exports module:@lumjs/core/enum
+ * @alias module:@lumjs/core/enum.Enum
  */
 function Enum (spec, opts={})
 {
@@ -89,17 +108,23 @@ function Enum (spec, opts={})
   const configurable = opts.configurable ?? false;
   const enumerable   = opts.enumerable   ?? true;
 
+  const symKey
+    = (typeof opts.symbols === F) 
+    ? opts.symbols 
+    : v => v;
+
   function getVal (name, def)
   {
     if (opts.symbols)
     { // We want to use symbols.
+      const key = symKey(name);
       if (opts.globals)
       {
-        return Symbol.for(name);
+        return Symbol.for(key);
       }
       else
       {
-        return Symbol(name);
+        return Symbol(key);
       }
     }
     else
@@ -162,6 +187,10 @@ function Enum (spec, opts={})
     if (!isExisting)
     { // Save the options into a special Symbol property.
       def(anEnum, EOPT, {value: opts});
+      if (isObj(opts.lock))
+      { // Add lock() method.
+        addLock(anEnum, opts.lock);
+      }
     }
   }
   else
@@ -223,4 +252,4 @@ TYPES.add('ENUM', 'enum', isEnum, 'isEnum');
 module.exports = Enum;
 
 // Loading this at the end.
-const {lock} = require('./obj/lock');
+const {lock,addLock} = require('./obj/lock');

package/lib/events/event.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const {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 {object} target - Target object for this event.
+ * @prop {Array} args - Arguments passed to `emit()`
+ * @prop {object} options - Composes options from the
+ * Registry and the Listener. Listener options take priority.
+ * @prop {?object} data 
+ * If `args[0]` is any kind of `object` other than another Event 
+ * instance, it will be used as the `data` property. 
+ * If `args[0]` is not an `object`, this property will be `null`.
+ * @prop {module:@lumjs/core/events.Event} origEvent
+ * Unless `this.prevEvent` is set, this should always be
+ * a reference to `this` instance itself.
+ * @prop {?module:@lumjs/core/events.Event} prevEvent
+ * If `args[0]` is another Event instance this property
+ * will be set with its value, as well as the following
+ * changes to the default behavior:
+ * 
+ * - `this.data` will be set to `prevEvent.data`.
+ * - `this.origEvent` will be set to `prevEvent.origEvent`
+ * 
+ * @prop {module:@lumjs/core/events~Status} emitStatus
+ * 
+ * @alias module:@lumjs/core/events.Event
+ */
+class LumEvent 
+{
+  /**
+   * Create a new Event instance; should not be called directly.
+   * @protected
+   * @param {module:@lumjs/core/events.Listener} listener 
+   * @param {object} target 
+   * @param {string} name 
+   * @param {Array}  args 
+   * @param {object} status
+   */
+  constructor(listener, target, name, args, status)
+  {
+    const reg = listener.registry;
+    this.eventListener = listener;
+    this.args = args;
+    this.target = target;
+    this.name = name;
+    this.emitStatus = status;
+    this.options = Object.assign({},
+      reg.options,
+      listener.options,
+      status.options);
+
+    this.data = null;
+    this.prevEvent = null;
+    this.origEvent = this;
+
+    if (isObj(args[0]))
+    { // The first argument is an object.
+      const ao = args[0];
+      if (ao instanceof LumEvent)
+      { // A previous event.
+        this.prevEvent = ao;
+        this.origEvent = ao.origEvent;
+        this.data      = ao.data;
+      }
+      else
+      { // Use it as a data object.
+        this.data = ao;
+      }
+    }
+
+    if (typeof this.options.setupEvent === F)
+    {
+      this.options.setupEvent.call(listener, this);
+    }
+
+  }
+}
+
+module.exports = LumEvent;

package/lib/events/index.js

@@ -0,0 +1,42 @@
+/**
+ * A simplistic event registration and dispatch module.
+ * 
+ * Designed to be a replacement for the `observable` API which started
+ * out simple enough (when I forked it from `riot.js`), but has since 
+ * grown into a big mess with many unusual and unexpected behaviours.
+ * 
+ * So this has been designed to work with a cleaner, more consistent,
+ * yet extremely flexible event model.
+ * 
+ * @module @lumjs/core/events
+ */
+exports = module.exports =
+{
+  Registry: require('./registry'),
+  Listener: require('./listener'),
+  Event: require('./event'),
+
+  /**
+   * A shortcut function to create a new Registry instance.
+   * All arguments are passed to the Registry constructor.
+   * @param {(object|module:@lumjs/core/events~GetTargets)} targets
+   * @param {object} [opts]
+   * @returns {module:@lumjs/core/events.Registry}
+   */
+  register(targets, opts)
+  {
+    return new exports.Registry(targets, opts);
+  },
+
+  /**
+   * Create a registry for a single target object, then return the target.
+   * @param {object} target 
+   * @param {object} [opts] 
+   * @returns {object} `target`
+   */
+  extend(target, opts)
+  {
+    exports.register(target, opts);
+    return target;
+  },
+}

package/lib/events/listener.js

@@ -0,0 +1,127 @@
+"use strict";
+
+const {F,isObj} = require('../types');
+const Event = require('./event');
+
+const REMOVE_OPTS = ['listener','handler','eventNames'];
+
+function makeOpts(spec)
+{
+  const opts = Object.assign({}, spec, spec.options);
+  for (const rm of REMOVE_OPTS)
+  {
+    delete opts[rm];
+  }
+  return opts;
+}
+
+/**
+ * Is something a valid value for an event listener?
+ * 
+ * Valid listener values are inspired by the `DOM.EventTarget` interface:
+ * 
+ * - A `function`
+ * - An `object` with a `handleEvent()` method
+ * 
+ * @param {*} v - Value we are testing
+ * @returns {boolean}
+ * @alias module:@lumjs/core/events.Listener.isListener
+ */
+function isListener(v)
+{
+  return (typeof v === F || (isObj(v) && typeof v.handleEvent === F));
+}
+
+/**
+ * An Event Listener instance used by a Registry
+ * 
+ * Used internally by the Registry class, there's likely very few 
+ * reasons you'd want to call any methods on this manually.
+ * 
+ * @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 {object} options - Options specific to this listener.
+ * 
+ * See {@link module:@lumjs/core/events.Registry#makeListener makeListener()}
+ * for details on what this may contain and how it is populated.
+ * 
+ * @alias module:@lumjs/core/events.Listener
+ */
+class LumEventListener
+{
+  /**
+   * Build a listener; called by Registry instance
+   * @private
+   * @param {module:@lumjs/core/events.Registry} registry 
+   * @param {object} spec 
+   */
+  constructor(registry, spec)
+  {
+    if (isListener(spec.listener))
+    {
+      this.handler = spec.listener;
+    }
+    else if (isListener(spec.handler))
+    {
+      this.handler = spec.handler;
+    }
+    else
+    {
+      console.error({spec,registry});
+      throw new TypeError("Invalid listener/handler in spec");
+    }
+    
+    // Assign the rest here.
+    this.registry = registry;
+    this.options = makeOpts(spec);
+    this.eventNames = registry.getEventNames(spec.eventNames);
+  }
+
+  /**
+   * See if there is at least one item in `this.eventNames`
+   * @type {boolean}
+   */
+  get hasEvents()
+  {
+    return this.eventNames.size > 0;
+  }
+
+  /**
+   * Used by {@link module:@lumjs/core/events.Registry#emit emit()} to create
+   * and emit a new Event instance for a specified event name and target.
+   * 
+   * This is a *protected method* and should not be called directly.
+   * @protected
+   * @param {string} eventName - A single event 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)
+  {
+    const event = new Event(this, target, eventName, args, status);
+
+    if (typeof this.handler === F)
+    { // The simplest is the good old function
+      this.handler.call(event.target, event);
+    }
+    else
+    { // An object with a `handleEvent()` method
+      this.handler.handleEvent(event);
+    }
+
+    if (event.options.once)
+    { // This listener is to be removed
+      status.onceRemoved.add(this);
+    }
+
+    return event;
+  }
+
+}
+
+LumEventListener.isListener = isListener;
+module.exports = LumEventListener;