@lumjs/core 1.26.0 → 1.31.0

package/README.md

@@ -6,6 +6,16 @@ and work in CommonJS/Node.js and modern browsers without any modifications.
 
 Used by all the rest of my *Lum.js* libraries.
 
+## Notes
+
+As of version `1.30.0` the `opt.Opts` class has been split into its the new
+[@lumjs/opts] package, which itself depends on a new [@lumjs/errors] package.
+
+Until the next major release (`2.0`), this package will have
+a dependency on the split-away pacakages, so that it can have a deprecated
+alias to the old class name available. As of `2.0` that alias will be
+removed, and the dependencies will also be removed.
+
 ## Documentation
 
 ### [API Docs](https://supernovus.github.io/docs/js/@lumjs/core/)
@@ -16,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
@@ -34,3 +44,7 @@ Timothy Totten <2010@totten.ca>
 
 [MIT](https://spdx.org/licenses/MIT.html)
 
+---
+
+[@lumjs/opts]: https://github.com/supernovus/lum.opts.js
+[@lumjs/errors]: https://github.com/supernovus/lum.errors.js

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/console.js

@@ -177,4 +177,58 @@ for (const method of DEFAULT_METHODS)
   addMethod(method);
 }
 
+/**
+ * Export our wrapper to replace the real console
+ * in the global namespace.
+ * 
+ * @param {*} [handler] Set a handler while we're exported.
+ * 
+ * See the description of `handler` for possible values.
+ * Any existing handler value will be saved to the `preHandler`
+ * static property.
+ * 
+ * @function module:@lumjs/core/console.export
+ */
+def(LC, 'export', function(handler)
+{
+  if (handler !== undefined)
+  { // Save the existing handler as 'preHandler'
+    LC.preHandler = LC.handler ?? null; // Prevent `undefined`
+    LC.handler = handler;
+  }
+
+  globalThis.console = LC;
+  return LC;
+});
+
+/**
+ * Restore the real console.
+ * 
+ * If a `handler` was passed to `export()`, then
+ * it will be removed, and the previous handler value
+ * will be restored.
+ * 
+ * @function module:@lumjs/core/console.restore
+ */
+def(LC, 'restore', function()
+{
+  if (LC.preHandler !== undefined)
+  {
+    LC.handler = LC.preHandler;
+    delete LC.preHandler;
+  }
+
+  globalThis.console = LC.real;
+  return LC;
+});
+
+/**
+ * A shortcut for `LC.export(false)`
+ * @function module:@lumjs/core/console.mute
+ */
+def(LC, 'mute', function()
+{
+  return LC.export(false);
+});
+
 module.exports = LC;

package/lib/enum.js

@@ -1,14 +1,24 @@
-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 ENUM_ID = new InternalObjectId({name: '$Enum'});
+const EID = '@lumjs/core/enum';
+const ENUM_ID = new InternalObjectId({name: EID});
+const isEnum = ENUM_ID.isFunction();
+const EOPT = Symbol(EID+':opts');
 
 /**
  * A function to build magic Enum objects.
  * 
  * 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 
@@ -24,7 +34,13 @@ const ENUM_ID = new InternalObjectId({name: '$Enum'});
  * 
  * @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.
  * 
@@ -45,18 +61,24 @@ const ENUM_ID = new InternalObjectId({name: '$Enum'});
  * 
  * 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`.
@@ -65,29 +87,44 @@ const ENUM_ID = new InternalObjectId({name: '$Enum'});
  * 
  * @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={})
 {
   needObj(spec, "Enum spec must be an object")
   needObj(opts, "Enum options must be an object")
 
-  const anEnum = ENUM_ID.tag({});
+  const isExisting = isEnum(opts);
+  const anEnum = isExisting ? opts : ENUM_ID.tag({});
+  if (isExisting)
+  {
+    opts = anEnum[EOPT];
+    if (!isObj(opts))
+    {
+      throw new Error("existing Enum was not open for changes");
+    }
+  }
 
   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
@@ -130,6 +167,10 @@ function Enum (spec, opts={})
         counter++;
       }
     }
+    if (opts.open)
+    { // Save the last counter value into the opts
+      opts.counter = counter;
+    }
   }
   else
   { // An object mapping of property name to value.
@@ -141,7 +182,18 @@ function Enum (spec, opts={})
     }
   }
 
-  if (!opts.open)
+  if (opts.open)
+  {
+    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
   {
     if (notNil(opts.lock))
     { // Use lock() function.
@@ -180,13 +232,11 @@ function Enum (spec, opts={})
  * @param {*} obj - The expected object/function to test.
  * @returns {boolean}
  */
-const isEnum = ENUM_ID.isFunction()
 def(Enum, 'is', isEnum);
 
 /**
  * Is a value an *Enum* magic object?
- * @name module:@lumjs/core/types.isEnum
- * @function
+ * @function module:@lumjs/core/types.isEnum
  * @param {*} v - The value to test.
  * @returns {boolean}
  * @see module:@lumjs/core/enum.is
@@ -202,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,30 @@
+/**
+ * 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()
+  {
+    return new exports.Registry(...arguments);
+  },
+}

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;