@lumjs/core 1.31.0 → 1.31.1

package/lib/events/index.js

@@ -23,8 +23,20 @@ exports = module.exports =
    * @param {object} [opts]
    * @returns {module:@lumjs/core/events.Registry}
    */
-  register()
+  register(targets, opts)
   {
-    return new exports.Registry(...arguments);
+    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/registry.js

@@ -2,6 +2,7 @@
 
 const {S,F,isObj,def,isIterable} = require('../types');
 const Listener = require('./listener');
+const RegSym = Symbol('@lumjs/core/events:registry');
 
 const DEF_EXTENDS =
 {
@@ -19,6 +20,53 @@ const DEF_OPTIONS =
   wildcard: '*',
 }
 
+/**
+ * Has a target object been registered with an event registry?
+ * @param {object} target 
+ * @returns {boolean}
+ * @alias module:@lumjs/core/events.Registry.isRegistered
+ */
+const isRegistered = target => isObj(target[RegSym]);
+
+/**
+ * Get event registry metadata from a target
+ * @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)
+ * @alias module:@lumjs/core/events.Registry.getMetadata
+ */
+function getMetadata(target, create=false)
+{
+  if (isRegistered(target))
+  { // Existing registry metadata found
+    return target[RegSym];
+  }
+  else if (create)
+  { // Create new metadata
+    const tpm = 
+    {
+      r: new Map(),
+      p: {},
+    }
+    def(target, RegSym, tpm);
+    return tpm;
+  }
+}
+
+function targetsAre(targets)
+{
+  const isaSet = (targets instanceof Set);
+  const isaArr = (!isaSet && Array.isArray(targets));
+  const tis =
+  {
+    set: isaSet,
+    array: isaArr,
+    handled: (isaSet || isaArr),
+  }
+  return tis;
+}
+
 /**
  * A class that handles events for target objects
  * 
@@ -40,29 +88,17 @@ class LumEventRegistry
    * 
    * @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.
+   * be considered as single target. 
+   * 
+   * If this is a `function`, it will be called to dynamically get a
+   * list of target objects whenever an event is triggered.
    * 
    * @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.
@@ -81,6 +117,18 @@ class LumEventRegistry
    * @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.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 {boolean} [opts.overwrite=false] Overwrite existing properties?
    * 
@@ -106,55 +154,89 @@ class LumEventRegistry
     let defExt; // Default opts.extend value
     if (typeof targets === F)
     { // A dynamic getter method
+      this.funTargets = true;
       this.getTargets = targets;
+      targets = this.getTargets();
       defExt = false;
     }
     else
     { // Simple getter for a static value
-      if (!isIterable(targets))
+      if (!(targets instanceof Set))
       {
-        targets = [targets];
+        if (!isIterable(targets))
+          targets = [targets];
+        targets = new Set(targets);
       }
+
+      this.funTargets = false;
       this.getTargets = () => targets;
       defExt = true;
     }
 
-    this.options = Object.assign({}, DEF_OPTIONS, opts);
+    this.options = Object.assign({extend: defExt}, DEF_OPTIONS, opts);
 
     this.allListeners = new Set();
     this.listenersFor = new Map();
 
-    const extOpts = opts.extend ?? defExt;
-    if (extOpts !== false)
+    this.extend(targets);
+  } // constructor()
+
+  /**
+   * Add extension methods to target objects;
+   * used by `constructor` and `register()`,
+   * not meant to be called from outside code.
+   * @private
+   * @param  {Iterable} targets - Targets to extend
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  extend(targets)
+  {
+    const opts = this.options;
+    const extOpts = opts.extend;
+
+    let intNames = null, extNames = null;
+
+    if (extOpts)
     {
-      const intNames = Object.keys(DEF_EXTENDS);
-      const extNames = Object.assign({}, DEF_EXTENDS, extOpts);
-      const targets = this.getTargets();
+      intNames = Object.keys(DEF_EXTENDS);
+      extNames = Object.assign({}, DEF_EXTENDS, extOpts);
+    }
+
+    for (const target of targets)
+    {
+      const tps = {}, tpm = getMetadata(target, true);
+      tpm.r.set(this, tps);
 
-      for (const iname of intNames)
+      if (extOpts)
       {
-        if (typeof extNames[iname] === S && extNames[iname].trim() !== '')
+        for (const iname of intNames)
         {
-          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 (typeof extNames[iname] === S && extNames[iname].trim() !== '')
           {
-            if (opts.overwrite || target[ename] === undefined)
+            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)
             {
-              def(target, ename, {value});
-            }
-            else
-            {
-              console.error("Won't overwrite existing property",
-                {target,iname,ename,registry: this});
+              if (opts.overwrite || target[ename] === undefined)
+              {
+                def(target, ename, {value});
+                tps[ename] = iname;
+                tpm.p[ename] = this;
+              }
+              else
+              {
+                console.error("Won't overwrite existing property",
+                  {target,iname,ename,registry: this});
+              }
             }
           }
         }
       }
     }
-  } // constructor()
+    return this;
+  }
 
   /**
    * Build a new Listener instance; used by `listen()` method.
@@ -491,6 +573,119 @@ class LumEventRegistry
     return sti;
   }
 
+
+
+  /**
+   * Register additional target objects
+   * @param  {...object} addTargets - Target objects to register
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  register(...addTargets)
+  {
+    const allTargets = this.getTargets();
+    const tis = targetsAre(allTargets);
+
+    if (tis.handled)
+    {
+      for (const target of addTargets)
+      {
+        if (tis.set)
+        {
+          allTargets.add(target);
+        }
+        else if (tis.array)
+        {
+          if (allTargets.indexOf(target) === -1)
+          {
+            allTargets.push(target);
+          }
+        }
+      }
+    }
+    else
+    {
+      if (!tis.handled)
+      {
+        console.warn("cannot add targets to collection", 
+          {addTargets, allTargets, registry: this});
+      }
+    }
+
+    this.extend(addTargets);
+    return this;
+  }
+
+  /**
+   * Remove a target object from the registry.
+   * 
+   * This will also remove any extension properties added to the
+   * target object by this registry instance.
+   * 
+   * @param  {...object} [delTargets] Targets to unregister
+   * 
+   * If no targets are specified, this will unregister **ALL** targets
+   * from this registry!
+   * 
+   * @returns {module:@lumjs/core/events.Registry} `this`
+   */
+  unregister(...delTargets)
+  {
+    const allTargets = this.getTargets();
+    const tis = targetsAre(allTargets);
+
+    if (delTargets.length === 0)
+    { // Unregister ALL targets.
+      delTargets = allTargets;
+    }
+
+    if (!tis.handled)
+    {
+      console.warn("cannot remove targets from collection", 
+        {delTargets, allTargets, registry: this});
+    }
+
+    for (const target of delTargets)
+    {
+      if (!isRegistered(target)) continue;
+
+      const tpm = target[RegSym];
+      const tp  = tpm.r.get(this);
+
+      if (tis.set)
+      {
+        allTargets.delete(target);
+      }
+      else if (tis.array)
+      {
+        const tin = allTargets.indexOf(target);
+        if (tin !== -1)
+        {
+          allTargets.splice(tin, 1);
+        }
+      }
+      
+      if (isObj(tp))
+      { // Remove any added extension properties
+        for (const ep in tp)
+        {
+          if (tpm.p[ep] === this)
+          { // Remove it from the target.
+            delete target[ep];
+            delete tpm.p[ep];
+          }
+        }
+        tpm.r.delete(this);
+      }
+
+      if (tpm.r.size === 0)
+      { // No registries left, remove the metadata too
+        delete target[RegSym];
+      }
+    }
+
+    return this;
+  }
+
   /**
    * Get a Set of event names from various kinds of values
    * @param {(string|Iterable)} names - Event names source
@@ -534,4 +729,9 @@ class LumEventRegistry
 
 }
 
+Object.assign(LumEventRegistry, 
+{ 
+  isRegistered, getMetadata, targetsAre,
+});
+
 module.exports = LumEventRegistry;

package/lib/index.js

@@ -39,6 +39,9 @@ def(exports, 'types', types);
 def(exports, 'def',   def);
 def(exports, 'lazy',  lazy);
 
+// TODO: document
+def(exports, 'state', require('./state'));
+
 /**
  * Array utility functions «Lazy»
  * @name module:@lumjs/core.arrays

package/lib/state.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const {S,isObj} = require('./types')
+const ctx = require('./context')
+const stateSym  = Symbol('@lumjs/core/state')
+const stateData = {[stateSym]: false}
+const stateKey  = 'LUM_JS_STATE'
+const stateOpts = {}
+
+module.exports =
+{
+  get(opts={})
+  {
+    if (opts.refresh || !stateData[stateSym])
+    {
+      let json;
+      if (ctx.isNode)
+      {
+        json = process.env[stateKey];
+      }
+      else if (ctx.isBrowser)
+      {
+        json = localStorage.getItem(stateKey);
+      }
+  
+      if (typeof json === S)
+      {
+        const revive = opts.jsonRevive ?? stateOpts.jsonRevive;
+        const storedData = JSON.parse(json, revive);
+        if (isObj(storedData))
+        {
+          Object.assign(stateData, storedData);
+          stateData[stateSym] = true;
+        }
+      }
+    }
+    return stateData;
+  },
+
+  save(opts={})
+  {
+    if (!stateData[stateSym]) return false;
+  
+    const replace = opts.jsonReplace ?? stateOpts.jsonReplace;
+    const json = JSON.stringify(stateData, replace);
+  
+    if (ctx.isBrowser)
+    {
+      localStorage.setItem(stateKey, json);
+    }
+    else if (ctx.isNode)
+    {
+      console.log("export ", stateKey, "=", json);
+    }
+  },
+
+  opts: stateOpts,
+  
+  [stateSym]: stateData,
+  $$: stateSym,
+}

package/lum.build.js

@@ -1,40 +1,11 @@
-"use strict";
-
-const D =
+module.exports = function(rb)
 {
-  build: 'docs/build',
-  api: 'docs/api/',
-  changelogs: 'docs/changelogs',
-  ad(from)
-  {
-    const to = D.api+from.replace(/\.md/, '.html');
-    return {from,to}
-  },
-}
-
-const dirs = 
-[
-  D.build,
-  D.api+D.changelogs,
-]
-
-const header = "<html><body>";
-const footer = "</body></html>";
-
-const files = 
-[
-  {
-    from: 'README.md', 
-    to: D.build+'/README.md',
-  },
-  D.ad('docs/TODO.md'),
-  D.ad(D.changelogs+'/index.md'),
-  D.ad(D.changelogs+'/1.0-beta.md'),
-  D.ad(D.changelogs+'/1.x.md'),
-  D.ad(D.changelogs+'/2.x.md'),
-]
-
-module.exports =
-{
-  dirs, files, header, footer,
+  rb.readme
+    .add('docs/TODO.md')
+    .chdir('docs/changelogs')
+    .add('index.md')
+    .add('1.0-beta.md')
+    .add('1.x.md')
+    .add('2.x.md')
+    //.set('debug', true)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.31.0",
+  "version": "1.31.1",
   "main": "lib/index.js",
   "exports": 
   {
@@ -32,7 +32,7 @@
   },
   "devDependencies": 
   {
-    "@lumjs/build": "^1.0.0",
+    "@lumjs/build": "^1.1.0",
     "@lumjs/tests": "^2.0.0"
   },
   "scripts":