@lumjs/core 1.32.0 → 1.34.0

package/lib/console.js

@@ -1,5 +1,5 @@
 const def = require('./types/def');
-const {F} = require('./types/js');
+const {F,isObj} = require('./types/basics');
 
 /**
  * A super simple singleton wrapper around the Javascript console.

package/lib/events/index.js

@@ -36,7 +36,21 @@ exports = module.exports =
    */
   extend(target, opts)
   {
-    exports.register(target, opts);
+    exports.register([target], opts);
     return target;
   },
+
+  /**
+   * Apply the compatibility version of the observable API;
+   * will load the events/observable sub-module on demand.
+   * @param {object} target
+   * @param {object} [opts]
+   * @returns {object} `target`
+   * @see module:@lumjs/core/events/observable.makeObservable
+   */
+  observable(target, opts)
+  {
+    const {makeObservable} = require('./observable');
+    return makeObservable(target, opts);
+  },
 }

package/lib/events/listener.js

@@ -77,6 +77,12 @@ class LumEventListener
     this.registry = registry;
     this.options = makeOpts(spec);
     this.eventNames = registry.getEventNames(spec.eventNames);
+
+    const setup = this.options.setupListener ?? registry.options.setupListener;
+    if (typeof setup === F)
+    {
+      setup.call(registry, this);
+    }
   }
 
   /**

package/lib/events/observable.js

@@ -0,0 +1,201 @@
+/**
+ * Observable Compatibility API
+ * @module @lumjs/core/events/observable
+ */
+"use strict";
+
+const {B,F,S,def} = require('../types');
+const lock = Object.freeze;
+const copy = Object.assign;
+const Registry = require('./registry');
+
+const ISOB = 'isObservable';
+
+const OBS_EXTENDS =
+{
+  registry: '$events',
+  listen:   'on',
+  emit:     'trigger',
+  remove:   'off',
+  once:     'one',
+}
+
+const OBS_OPTIONS =
+{
+  wrapargs: false,
+  wrapthis: false,
+  wraplock: true,
+  wrapsetup: null,
+  addme: null,
+  // addname: !(wrapargs || wrapthis)
+  // addis:    (wrapargs || wrapthis)
+}
+
+/**
+ * A version of the observable API using the events module.
+ * 
+ * It's obviously not going to be 100% identical due to
+ * the very different nature of the backend engine, but it'll
+ * try its best to make existing code work.
+ * 
+ * A few obscure features that I don't think are particularly
+ * important and won't affect *most* exising uses will be dropped.
+ * 
+ * @param {(object|function)} el - The target we're making observable
+ * @param {object} [oo] 
+ * {@link module:@lumjs/core/observable Observable} options;
+ * 
+ * The `addre` and `reinherit` options are not supported.
+ * All the other ones should try to work mostly the same.
+ * 
+ * @param {boolean} [oo.addwrap] If this is `true`, 
+ * and `oo.wrapargs` is `false`, then the `event` object 
+ * will be appended to the arguments sent to the handler.
+ * 
+ * The default value is: `!oo.wrapthis`
+ * 
+ * @param {object} [ro]
+ * {@link module:@lumjs/core/events.Registry Registry} options;
+ * 
+ * The `setupEvent` and `setupListener` options cannot be specified,
+ * as the versions from this module will always be used.
+ * 
+ * The `extend` defaults are changed to match those used
+ * by the observable API (`on`,`trigger`,`off`,`one`),
+ * and `extend.registry` is set to `$events` by default.
+ * 
+ * Setting the `extend` option to `false` will have no effect
+ * in this implementation.
+ * 
+ * @param {boolean} [wantReg=false] Return the Registry?
+ * @returns {object} normally `el`, unless `wantReg` was `true`
+ * @alias module:@lumjs/core/events/observable.makeObservable
+ */
+function makeObservable(el, oo, ro, wantReg=false)
+{
+  ro = copy({}, ro);
+  ro.extend = copy({}, OBS_EXTENDS, ro.extend);
+  ro.setupEvent = setupEvent;
+  ro.setupListener = setupListener;
+  oo = ro.observable = copy({}, OBS_OPTIONS, oo);
+
+  let wrapped = (oo.wrapargs || oo.wrapthis);
+  if (!wrapped && typeof oo.wrapsetup === F)
+  {
+    wrapped = oo.wrapargs = true;
+  }
+
+  if (typeof oo.wildcard === S)
+  { // oo.wildcard takes precedence
+    ro.wildcard = oo.wildcard;
+  }
+
+  const setIf = (opt, get) => 
+  {
+    if (typeof oo[opt] !== B)
+    {
+      oo[opt] = get();
+    }
+  }
+
+  setIf('addname', () => !wrapped);
+  setIf('addis',   () =>  wrapped);
+  setIf('addwrap', () => !oo.wrapthis);
+
+  const reg = new Registry([el], ro);
+
+  if (oo.addis)
+  {
+    def(el, ISOB, lock({event: false, target: true}));
+  }
+
+  if (typeof oo.addme === S)
+  {
+    def(el, oo.addme, function(el2, oo2, ro2)
+    {
+      return makeObservable(el2, 
+        copy({}, oo, oo2),
+        copy({}, ro, ro2)
+      );
+    });
+  }
+
+  return wantReg ? reg : el;
+}
+
+/**
+ * Event setup for observable compatibility
+ * @type {module:@lumjs/core/events~SetupEvent}
+ */
+function setupEvent(ev)
+{
+  const ro = this.registry.options;
+  const oo = ro.observable;
+  ev.wildcard = this.eventNames.has(ro.wildcard);
+  ev.self = ev.target;
+  ev.type = ev.name;
+  def(ev, ISOB, lock({event: true, target: false}));
+
+  if (typeof oo.wrapsetup === F)
+  {
+    oo.wrapsetup.call(ev.target, ev);
+  }
+
+  if (oo.wraplock)
+  {
+    lock(ev);
+  }
+}
+
+/**
+ * Listener setup for observable compatibility
+ * @type {module:@lumjs/core/events~SetupListener}
+ */
+function setupListener(ln)
+{
+  const oo = this.options.observable;
+  const oh = ln.observableHandler = ln.handler;
+  const go = (ev, args) => 
+  {
+    if (typeof oh === F)
+    {
+      const thisTarget = oo.wrapthis ? ev : ev.target;
+      oh.apply(thisTarget, args);
+    }
+    else
+    {
+      oh.handleEvent(...args);
+    }
+  }
+
+  if (!oo.wrapargs)
+  { // Not wrapping args, we need to wrap the handler.
+    const ec = ln.eventNames.size;
+    ln.handler = function(ev)
+    {
+      const args = ev.args;
+      if (ec > 1 && oo.addname)
+      {
+        args.unshift(ev.name);
+      }
+      if (oo.addwrap)
+      {
+        args.push(ev);
+      }
+
+      go(ev, args);
+    }
+  }
+  else if (oo.wrapthis)
+  { // Both wrapargs and wrapthis are in use, woah!
+    ln.handler = function(ev)
+    {
+      go(ev, [ev]);
+    }
+  }
+}
+
+module.exports =
+{
+  makeObservable, setupEvent, setupListener,
+}

package/lib/events/registry.js

@@ -95,6 +95,9 @@ class LumEventRegistry
    * If this is a `function`, it will be called to dynamically get a
    * list of target objects whenever an event is triggered.
    * 
+   * If you want to use a `function` as an actual target, you'll need to
+   * wrap it in an array or other iterable object.
+   * 
    * @param {object} [opts] Options (saved to `options` property).
    * 
    * @param {(RegExp|string)} [opts.delimiter=/\s+/] Used to split event names
@@ -135,12 +138,17 @@ class LumEventRegistry
    * 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?
+   * @param {module:@lumjs/core/events~SetupEvent} [opts.setupEvent]
    * 
    * 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 {module:@lumjs/core/events~SetupListener} [opts.setupListener]
+   * 
+   * If this is specified, it will be called and passed the Listener
+   * 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
@@ -248,7 +256,7 @@ class LumEventRegistry
    * 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 
+   * 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] 
@@ -277,7 +285,8 @@ class LumEventRegistry
    * names `listener`, `handler` or `eventNames` as option properties,
    * and if found, they will be removed.
    * 
-   * You may also override the `setupEvent` registry option here.
+   * You may also override the `setupEvent` and `setupListener` registry
+   * options here if needed.
    * 
    * @param {boolean} [spec.options.once=false] Only use the listener once?
    * 

package/lib/index.js

@@ -10,100 +10,7 @@
  * @module @lumjs/core
  */
 
-/**
- * Constants and functions for type checks
- * and other fundamental functions
- * 
- * @alias module:@lumjs/core.types
- * @see module:@lumjs/core/types
- */
-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;
-
-/**
- * Define *lazy* properties on an object or function
- * @alias module:@lumjs/core.lazy
- * @function
- * @see module:@lumjs/core/types.lazy
- */
-const lazy = types.lazy;
-
-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
- * @type {module:@lumjs/core/arrays}
- */
-lazy(exports, 'arrays', () => require('./arrays'));
-
-/**
- * Map utility functions «Lazy»
- * @name module:@lumjs/core.maps
- * @type {module:@lumjs/core/maps}
- */
-lazy(exports, 'maps', () => require('./maps'));
-
-/**
- * Information about the JS context we're running in
- * @name module:@lumjs/core.context
- * @type {module:@lumjs/core/context}
- */
-def(exports, 'context', require('./context'));
-
-/**
- * Functions for working with strings and locales «Lazy»
- * @name module:@lumjs/core.strings
- * @type {module:@lumjs/core/strings}
- */
-lazy(exports, 'strings', () => require('./strings'));
-
-/**
- * Functions for working with binary flags «Lazy»
- * @name module:@lumjs/core.flags
- * @type {module:@lumjs/core/flags}
- */
-lazy(exports, 'flags', () => require('./flags'));
-
-/**
- * Functions for manipulating objects «Lazy»
- * @name module:@lumjs/core.obj
- * @type {module:@lumjs/core/obj}
- */
-lazy(exports, 'obj', () => require('./obj'));
-
-/**
- * A wrapper around the Javascript console «Lazy»
- * @name module:@lumjs/core.console
- * @type {module:@lumjs/core/console}
- */
-lazy(exports, 'console', () => require('./console'));
-
-/**
- * A simplistic implementation of class/object traits «Lazy»
- * @name module:@lumjs/core.traits
- * @type {module:@lumjs/core/traits}
- */
-lazy(exports, 'traits', () => require('./traits'));
-
-/**
- * Functions for getting values and properties with fallback defaults «Lazy»
- * @name module:@lumjs/core.opt
- * @type {module:@lumjs/core/opt}
- */
-lazy(exports, 'opt', () => require('./opt'), {def:{autoDesc: false}});
+/// see also: `docs/src/index.js`
 
 // Get a bunch of properties from a submodule.
 function from(submod)
@@ -114,49 +21,18 @@ function from(submod)
   }
 }
 
-// ObjectID stuff is imported directly without registering a sub-module.
-from(require('./objectid'));
-
-/**
- * Get a simplistic debugging stacktrace
- * @name module:@lumjs/core.stacktrace
- * @function
- * @see module:@lumjs/core/meta.stacktrace
- */
-
-/**
- * A simple base class for making *abstract* classes
- * @name module:@lumjs/core.AbstractClass
- * @see module:@lumjs/core/meta.AbstractClass
- */
-
-/**
- * A *factory* for special types of JS `function` constructors
- * @name module:@lumjs/core.Functions
- * @see module:@lumjs/core/meta.Functions
- */
+const types = require('./types');
+const {def,lazy} = types;
 
-/**
- * Throw an `Error` saying that a feature is not yet implemented
- * @name module:@lumjs/core.NYI
- * @function
- * @see module:@lumjs/core/meta.NYI
- */
+def(exports, 'types', types);
+def(exports, 'def',   def);
+def(exports, 'lazy',  lazy);
 
-/**
- * A function indicating that something is deprecated
- * @name module:@lumjs/core.deprecated
- * @function
- * @see module:@lumjs/core/meta.deprecated
- */
+def(exports, 'context', require('./context'));
+def(exports, 'state', {value: require('./state')});
 
-/**
- * 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
- */
+// ObjectID stuff is imported directly without registering a sub-module.
+from(require('./objectid'));
 
 // These are exported directly, but a meta sub-module also exists.
 // Unlike most sub-modules there is no `meta` property in the main library.
@@ -167,25 +43,14 @@ def(exports, 'AbstractClass',
   get() { return meta.AbstractClass; }
 });
 
-/**
- * Create a magic *Enum* object «Lazy»
- * @name module:@lumjs/core.Enum
- * @function
- * @see module:@lumjs/core/enum
- */
+lazy(exports, 'arrays', () => require('./arrays'));
+lazy(exports, 'maps', () => require('./maps'));
+lazy(exports, 'strings', () => require('./strings'));
+lazy(exports, 'flags', () => require('./flags'));
+lazy(exports, 'obj', () => require('./obj'));
+lazy(exports, 'console', () => require('./console'));
+lazy(exports, 'traits', () => require('./traits'));
+lazy(exports, 'opt', () => require('./opt'), {def:{autoDesc: false}});
 lazy(exports, 'Enum', () => require('./enum'));
-
-/**
- * Make an object support the *Observable* API «Lazy»
- * @name module:@lumjs/core.observable
- * @function
- * @see module:@lumjs/core/observable
- */
 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

@@ -135,7 +135,11 @@ function NYI(fatal=true, prefix='')
 exports.NYI = NYI;
 
 /**
- * Send a deprecation message with a stack trace.
+ * Send a deprecation message to the console.
+ * 
+ * Will default to using `console.warn()` to send the message,
+ * unless `core.state.get('core.traceDeprecated')` evaluates to true,
+ * in which case it will use `console.trace()` instead. 
  * 
  * @param {string} dep - Name of what is deprecated
  * @param {(string|string[])} [rep] Replacement suggestion(s).
@@ -145,12 +149,15 @@ exports.NYI = NYI;
  */
 function deprecated(dep, rep, ret)
 {
+  const fn = require('./state').get('core.traceDeprecated')
+    ? 'trace' 
+    : 'warn';
   const msgs = [dep,'is deprecated'];
   if (rep)
   {
     msgs.push('replace with', rep);
   }
-  console.trace(...msgs);
+  console[fn](...msgs);
   return ret;
 }
 

package/lib/obj/cp.js

@@ -440,7 +440,7 @@ function cpArgs(subject, ...sources)
 } // cpArgs()
 
 /**
- * Copy enumerable properties into a subject. 
+ * Copy enumerable properties into a subject.
  * 
  * This version overwrites any existing properties, with latter sources
  * taking precedence over earlier ones.
@@ -448,6 +448,18 @@ function cpArgs(subject, ...sources)
  * See {@link module:@lumjs/core/obj/cp.safe cp.safe()} for a version that
  * only copies non-existent properties.
  * 
+ * **Note**: this is the actual `obj.cp` default export value! 
+ * 
+ * To keep JSDoc happy it is listed as a _named export_ inside 
+ * the `cp` module, but in reality, it *is* the module.
+ * 
+ * So when you do: `const cp = require('@lumjs/core/obj/cp');`
+ * or `const core = require('@lumjs/core), {cp} = core.obj;`
+ * the `cp` variable will be this function. All the other named 
+ * exports are properties attached to the function object itself.
+ * 
+ * The named export *does* exist as an alias to itself (`cp.cp = cp`).
+ * 
  * @param {object} subject - Subject of the copy operation
  * 
  * If this is a {@link module:@lumjs/core/obj/cp.HandlerSet HandlerSet},
@@ -475,20 +487,7 @@ function cpArgs(subject, ...sources)
  * 
  * @returns {object} Either `subject` or a clone of `subject`.
  * 
- * @alias module:@lumjs/core/obj/cp.cp
- * 
- * **Note**: this is the actual `obj.cp` default export value! 
- * 
- * To keep JSDoc happy it is listed as a _named export_ inside 
- * the `cp` module, but in reality, it *is* the module.
- * 
- * So when you do: `const cp = require('@lumjs/core/obj/cp');`
- * or `const core = require('@lumjs/core), {cp} = core.obj;`
- * the `cp` variable will be this function. All the other named 
- * exports are properties attached to the function object itself.
- * 
- * The named export *does* exist as an alias to itself (`cp.cp = cp`).
- * 
+ * @alias module:@lumjs/core/obj/cp.cp 
  */
 function cp()
 {
@@ -1236,7 +1235,7 @@ cp.from = function()
  * @param {?object} [opts] Options
  * 
  * If this is an `object`, the clone call will be:
- * `cp.with(opts).into(obj).ow.clone();`
+ * `cp.with(opts).from(obj).ow.clone();`
  * 
  * If this is `null` or `undefined`, the call will be: 
  * `cp(obj);`
@@ -1252,7 +1251,7 @@ cp.clone = function(obj, opts)
   }
   else
   {
-    return cp.with(opts).into(obj).ow.clone();
+    return cp.with(opts).from(obj).ow.clone();
   }
 }
 

package/lib/obj/ns.js

@@ -2,7 +2,7 @@
 const 
 {
   B, S,
-  root, isObj, needObj, def, nonEmptyArray, notNil,
+  root, isObj, needObj, def, nonEmptyArray, isNil, notNil,
   doesDescriptorTemplate,
 } = require('../types');
 
@@ -152,20 +152,20 @@ function setObjectPath(obj, proppath, opts={})
   proppath = nsArray(proppath);
 
   let assign;
-  if (doesDescriptorTemplate(opts.desc))
+  if (opts.assign)
+  { // Use direct property assignment.
+    assign = (o,p,v={}) => o[p] = v;
+  }
+  else if (doesDescriptorTemplate(opts.desc))
   { // An explicit descriptor.
     assign = (o,p,v={}) => 
     {
-      const desc = clone(opts.desc);
+      const desc = Object.assign({}, opts.desc);
       desc.value = v;
       def(o,p,desc);
     }
   }
-  else if (opts.assign)
-  { // Use direct property assignment.
-    assign = (o,p,v={}) => o[p] = v;
-  }
-  else 
+  else
   { // Use def with default descriptor.
     assign = (o,p,v={}) => def(o,p,v);
   }
@@ -216,6 +216,41 @@ function setObjectPath(obj, proppath, opts={})
 
 exports.setObjectPath = setObjectPath;
 
+/**
+ * Delete a nested property from an object.
+ * 
+ * @param {(object|function)} obj - Object we're operating on.
+ * @param {(string|Array)} proppath - Property path we want to remove.
+ * 
+ * Generally a string of dot (`.`) separated nested property names.
+ * 
+ * The last property name in the path will be the one that is deleted 
+ * from its parent object.
+ * 
+ * @param {object} [opts] Options for `getObjectPath()`
+ * @returns {*} The value that was removed; or `undefined` if the
+ * proppath didn't resolve to a defined value.
+ */
+function delObjectPath(obj, proppath, opts={})
+{
+  proppath = nsArray(proppath);
+  const rmProp = proppath.pop();
+  const rmFrom = proppath.length
+    ? getObjectPath(obj, proppath, opts)
+    : obj;
+
+  if (isNil(rmFrom))
+  { // Nothing to remove from
+    return undefined;
+  }
+
+  const removed = rmFrom[rmProp];
+  delete rmFrom[rmProp];
+  return removed;
+}
+
+exports.delObjectPath = delObjectPath;
+
 /**
  * Get a global namespace path if it exists.
  *

package/lib/observable.js

@@ -1,7 +1,7 @@
 // Defining these after observable.
 const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');
-const {duplicateAll: clone} = require('./obj/copyall');
 const lock = Object.freeze;
+const copy = Object.assign;
 
 /**
  * Make a target object (or function) support the *Observable* API.
@@ -346,9 +346,9 @@ function observable (el={}, opts={}, redefine=false)
 
   if (addme)
   { // Add a wrapper for observable() that sets new default options.
-    add(addme, function (obj=null, mopts={})
+    add(addme, function (obj=null, mopts)
     {
-      return observable(obj, clone(opts, mopts));
+      return observable(obj, copy({}, opts, mopts));
     });
   }
 

package/lib/state.js

@@ -2,15 +2,47 @@
 
 const {S,isObj} = require('./types')
 const ctx = require('./context')
+const ns = require('./obj/ns');
+const cp = require('./obj/cp');
 const stateSym  = Symbol('@lumjs/core/state')
 const stateData = {[stateSym]: false}
 const stateKey  = 'LUM_JS_STATE'
 const stateOpts = {}
 
-module.exports =
+function getOpts(localOpts)
 {
-  get(opts={})
+  return Object.assign({}, stateOpts, localOpts);
+}
+
+/**
+ * A simple persistent state helper object.
+ * 
+ * Will use `localStorage` in a browser environment,
+ * and `process.env` if running in Node.js.
+ * 
+ * In both cases the key `LUM_JS_STATE` is used,
+ * and the value must be valid JSON data.
+ * 
+ * @exports module:@lumjs/core/state
+ */
+exports = module.exports =
+{
+  /**
+   * Load (retrieve) state data
+   * @param {object} [opts] Options
+   * @param {boolean} [opts.refresh=false] Refresh data from storage?
+   * 
+   * If `true` this will force the data to be reloaded from storage.
+   * If `false` previously loaded data will be returned as is.
+   * 
+   * @param {function} [opts.jsonRevive] JSON.parse() reviver
+   * 
+   * @returns {object}
+   */
+  load(opts)
   {
+    opts = getOpts(opts);
+
     if (opts.refresh || !stateData[stateSym])
     {
       let json;
@@ -25,24 +57,44 @@ module.exports =
   
       if (typeof json === S)
       {
-        const revive = opts.jsonRevive ?? stateOpts.jsonRevive;
+        const revive = opts.jsonRevive;
         const storedData = JSON.parse(json, revive);
         if (isObj(storedData))
         {
           Object.assign(stateData, storedData);
-          stateData[stateSym] = true;
         }
       }
+
+      stateData[stateSym] = true;
     }
+
     return stateData;
   },
 
-  save(opts={})
+  /**
+   * Save current state data into persistent storage.
+   * 
+   * In a web browser environment, this will save the data
+   * into the `localStorage` global object directly.
+   * 
+   * In Node.js while this updates the `process.env` object,
+   * there's no way to export to the environment in a truly 
+   * persistent way. So this also will output a shell statement
+   * via `console.log()` that can be exported into the environment 
+   * (or added to a `.env` file, etc.)
+   * 
+   * @param {object} [opts] Options
+   * @param {function} [opts.jsonReplace] JSON.stringify() replacer
+   * @returns {string} The JSON data
+   */
+  save(opts)
   {
     if (!stateData[stateSym]) return false;
+
+    opts = getOpts(opts);
   
-    const replace = opts.jsonReplace ?? stateOpts.jsonReplace;
-    const json = JSON.stringify(stateData, replace);
+    const replace = opts.jsonReplace;
+    let json = JSON.stringify(stateData, replace);
   
     if (ctx.isBrowser)
     {
@@ -50,10 +102,71 @@ module.exports =
     }
     else if (ctx.isNode)
     {
-      console.log("export ", stateKey, "=", json);
+      process.env[stateKey] = json;
+      console.log(`${stateKey}='${json.replaceAll("'", "'\"'\"'")}'`);
     }
+
+    return json;
+  },
+
+  /**
+   * Get a property value from the state data via a namespace path
+   * @param {(string|string[])} path - Namespace path to get
+   * @param {object} [opts] Options for `load()` and `getObjectPath()`
+   * @returns {*} The property value (or `undefined` if not found)
+   * @see module:@lumjs/core/obj.getObjectPath
+   */
+  get(path, opts)
+  {
+    const data = exports.load(opts);
+    return ns.getObjectPath(data, path, opts);
+  },
+
+  /**
+   * Set a (nested) property value in the state data
+   * @param {(string|string[])} path - Namespace path to set
+   * @param {*} value - Value to set the property to
+   * @param {object} [opts] Options for `load()` and `setObjectPath()`
+   * 
+   * The call to `setObjectPath()` has a few different defaults here:
+   * - `opts.assign` defaults to `true`
+   * - `opts.overwrite` defaults to `true`
+   * - `opts.value` is **forced** to the `value` argument
+   * 
+   * @returns {*}
+   * @see module:@lumjs/core/obj.setObjectPath
+   */
+  set(path, value, opts)
+  {
+    const loadOpts = cp({refresh: false}, opts);
+    const setOpts = cp({assign: true, overwrite: true}, opts, {value});
+    const data = exports.load(loadOpts);
+    return ns.setObjectPath(data, path, setOpts);
+  },
+
+  /**
+   * Get a property value from the state data via a namespace path
+   * @param {(string|string[])} path - Namespace path to delete
+   * @param {object} [opts] Options for `load()` and `delObjectPath()`
+   * @returns {*} The property value (or `undefined` if not found)
+   * @see module:@lumjs/core/obj.delObjectPath
+   */
+  del(path, opts)
+  {
+    const data = exports.load(cp({refresh: false}, opts));
+    return ns.delObjectPath(data, path, opts);
   },
 
+  /**
+   * Default options for `load()` and `save()` methods.
+   * 
+   * Any of the options supported by those methods can be set here.
+   * 
+   * The `refresh` option will be ignored by the `set()` and `del()` 
+   * methods if it's specified here.
+   * 
+   * @type {object}
+   */
   opts: stateOpts,
   
   [stateSym]: stateData,

package/lib/types/index.js

@@ -16,11 +16,11 @@ Object.assign(exports,
   require('./basics'), 
   require('./root'),
   require('./isa'),
+  require('./stringify'),
   require('./needs'),
   { // A few standalone exports.
     def, lazy,
     TYPES: require('./typelist'),
-    stringify: require('./stringify'),
     ownCount: require('./owncount'),
   },
 );

package/lib/types/stringify.js

@@ -1,142 +1,301 @@
 // Get the extended type list.
 const TYPES = require('./typelist');
-const {isObj, isArray, isTypedArray} = require('./basics');
+const {F, S, N, B, isObj, isArray, isTypedArray} = require('./basics');
 const def = require('./def');
 
-const TOSTRING_TYPES = [TYPES.F, TYPES.SY];
+const TOSTRING_TYPES     = [TYPES.SY];
 const TOSTRING_INSTANCES = [RegExp];
 const CUSTOM = [];
+const DEF = 
+{
+  MAXD: 1,
+  NEWD: 0,
+}
 
 /**
  * Stringify a Javascript value.
  * 
- * We typically just use `JSON.stringify()` but that doesn't work on
- * some types. So this function adds string formats for:
+ * Creates a new `Stringify` instance, then passes the
+ * first argument to it's `stringify()` method.
+ * 
+ * This is the primary way to use the Stringify class
+ * rather than manually creating an instance of it.
+ * 
+ * @param {*} what - Passed to `instance.stringify()`
+ * @param {(object|number)} [opts] Options for Stringify constructor;
+ * 
+ * If this is a `number` it's the `opts.maxDepth` option value.
+ * 
+ * @param {(number|boolean)} [addNew] The `opts.newDepth` option value;
+ * 
+ * For compatibility with old API. Boolean values are shortcuts:
+ * - `false` = `0`
+ * - `true`  = `1`
+ * 
+ * @returns {string} The stringified value
+ * 
+ * @alias module:@lumjs/core/types.stringify
+ * @see module:@lumjs/core/types.Stringify
+ * @see module:@lumjs/core/types.Stringify#stringify
+ */
+function stringify (what, opts={}, addNew=null)
+{
+  if (typeof opts === N)
+  {
+    opts = {maxDepth: opts}
+  }
+
+  if (typeof addNew === N)
+  {
+    opts.newDepth = addNew;
+  }
+  else if (typeof addNew === B)
+  {
+    opts.newDepth = addNew ? 1 : 0;
+  }
+
+  const si = new Stringify(opts);
+  return si.stringify(what);
+}
+
+/**
+ * A class to stringify Javascript values for testing and debugging.
+ * 
+ * This is NOT meant for serializing data, the output is in a format
+ * that's meant to be read by a developer, not parsed by a machine.
+ * 
+ * Currently directly supports:
+ * 
  *  - `function`
  *  - `symbol`
  *  - `TypedArray`
  *  - `Map`
  *  - `Set`
  *  - `Error`
- * I may add even more extended types in the future, but that's enough
- * for now.
+ *  - `RegExp`
+ *  - `Object`
  * 
- * This is NOT meant for serializing data, and does not use a JSON-friendly
- * output format. I'm writing a different library for that.
+ * Any other JS value types (`number`,`boolean`, `string`, etc.) will
+ * be serialized using JSON.
  * 
- * @param {*} what - The value to stringify.
- * @param {integer} [recurse=1] Recurse objects to this depth.
- * @param {boolean} [addNew=false] Use 'new Class()' instead of 'Class()'. 
- * @returns {string} The stringified value.
- * @alias module:@lumjs/core/types.stringify
+ * @alias module:@lumjs/core/types.Stringify
  */
-function stringify (what, recurse=1, addNew=false)
+class Stringify 
 {
-  const whatType = typeof what;
-
-  for (const test of CUSTOM)
-  { // If there are custom extensions, we check them first.
-    const ret = test.call({stringify}, what, recurse, addNew);
-    if (typeof ret === TYPES.S)
-    { // The extension processed the item.
-      return ret;
-    }
-  }
+  /**
+   * Create a new Stringify instance
+   * @param {object} [opts] Options; saved to `this.options`
+   * @param {number} [opts.maxDepth=1] Max depth to recurse?
+   * @param {number} [opts.newDepth=0] Depth to prepend 'new' to strings?
+   * @param {boolean} [opts.fnString=false] Fully stringify functions?
+   * @param {(Array|function)} [opts.setCustom] Set custom stringifiers;
+   * used *INSTEAD* of the globally registered ones.
+   * @param {(Array|function)} [opts.addCustom] Add custom stringifiers;
+   * used *in addition* to the globally registered ones.
+   */
+  constructor(opts={})
+  {
+    this.options = opts;
+    this.maxDepth = opts.maxDepth ?? DEF.MAXD;
+    this.newDepth = opts.newDepth ?? DEF.NEWD;
+    this.seenObjects = new Map(); // object => description
+    this.seenDescrip = new Map(); // description => count
+    this.strClass = TOSTRING_INSTANCES.slice();
+    this.strTypes = TOSTRING_TYPES.slice();
 
-  // A few types we simply stringify right now.
-  if (TOSTRING_TYPES.includes(whatType)) return what.toString();
+    if (opts.fnString)
+    {
+      this.strTypes.push(F);
+    }
 
-  if (isObj(what))
-  { // We support a few kinds of objects.
+    if (opts.errString)
+    {
+      this.strClass.push(Error);
+    }
 
-    // Any class instance that we can simply call `toString()` on, let's do that.
-    for (const aClass of TOSTRING_INSTANCES)
+    if (Array.isArray(opts.setCustom))
+    {
+      this.customFn = opts.setCustom.slice();
+    }
+    else if (typeof opts.setCustom === F)
     {
-      if (what instanceof aClass)
+      this.customFn = [];
+      opts.setCustom.call(this, this.customFn);
+    }
+    else
+    { // Start out with the global custom tests.
+      this.customFn = CUSTOM.slice();
+      if (Array.isArray(opts.addCustom))
+      {
+        this.customFn.push(...opts.addCustom);
+      }
+      else if (typeof opts.addCustom === F)
       {
-        return what.toString();
+        opts.addCustom.call(this, this.customFn);
       }
     }
 
-    // A few formatting helpers used below.
-    const classname = () => (addNew ? 'new ' : '') + what.constructor.name;
-    const construct = val => `${classname()}(${val})`;
-    const reconstruct = val => construct(stringify(val,recurse,addNew));
-    const arrayish = vals => reconstruct(Array.from(vals));
+  }
 
-    if (isTypedArray(what))
-    { // This one is pretty simple.
-      return construct(what.toString());
+  /**
+   * Stringify a JS value
+   * @param {*} what - Value to stringify
+   * @returns {string} A friendly representation of `what`
+   */
+  stringify(what, curd=0)
+  {
+    if (this.seenObjects.has(what))
+    { // Cached string for this subject already found.
+      return this.seenObjects.get(what);
     }
+
+    const recurse = curd < this.maxDepth;
+    const addNew  = curd < this.newDepth;
+    const whatType = typeof what;
+    const strFor = (str) => this._stringFor(what, str);
     
-    if (what instanceof Map)
-    {
-      return arrayish(what.entries());
+    for (const test of this.customFn)
+    { // If there are custom extensions, we check them first.
+      const ret = test.call(this, what, curd);
+      if (typeof ret === S)
+      { // The extension processed the item.
+        return strFor(ret);
+      }
     }
-    
-    if (what instanceof Set)
+
+    // A few types we simply stringify right now.
+    if (this.strTypes.includes(whatType)) 
     {
-      return arrayish(what.values());
+      return strFor(what.toString());
     }
 
-    if (what instanceof Error)
-    {
-      return `${what.name}(${JSON.stringify(what.message)})`;
+    if (!this.options.fnString && typeof what === F)
+    { // Simple format for functions
+      return strFor(what.name+'()');
     }
     
-    if (recurse)
-    { // Recursion mode enabled.
-      let out = '';
-      if (isArray(what))
-      { // Stringify an array.
-        out = '[';
-        out += what.map(item => stringify(item, recurse-1, addNew)).join(',');
-        out += ']';
-      }
-      else
-      { // Stringify a plain object.
-        out = '{';
-        function add(key, pre='')
+    if (isObj(what))
+    { // We support a few kinds of objects.
+
+      // Any class instance that we can simply call `toString()` on, let's do that.
+      for (const aClass of this.strClass)
+      {
+        if (what instanceof aClass)
         {
-          out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+          return strFor(what.toString());
         }
-        const keys = Object.keys(what);
-        //console.debug("keys!", keys);
-        if (keys.length > 0)
-        { // Let's add the first key, then all subsequent keys.
-          add(keys.shift());    
-          for (const key of keys)
+      }
+
+      // A few formatting helpers used below.
+      const nameFor = (name=what.constructor.name) => 
+        (addNew ? 'new ' : '') + strFor(name);
+      
+      const container = (content, ps='[', pe=']') =>
+      {
+        let cstr = nameFor();
+        if (recurse)
+        {
+          cstr += ps;
+          if (!Array.isArray(content))
           {
-            add(key, ',');
+            content = Array.from(content);
           }
+          cstr += (content
+            .map(item => this.stringify(item, curd+1))
+            .join(','));
+          cstr += pe;
+        }
+        return cstr;
+      }
+      
+      if (isTypedArray(what))
+      { // This one is pretty simple.
+        if (this.options.typedContent)
+        {
+          return container(what.toString());
         }
-        out += '}';
+        return nameFor();
+      }
+
+      if (what instanceof Map)
+      {
+        return container(what.entries());
+      }
+      
+      if (what instanceof Set)
+      {
+        return container(what.values());
+      }
+
+      if (isArray(what))
+      {
+        return container(what);
+      }
+
+      if (!this.options.errString && what instanceof Error)
+      {
+        return nameFor(what.name)+'('+JSON.stringify(what.message)+')';
       }
-      return out;
+
+      // If we reached here, it's another kind of object entirely.
+      return container(Object.keys(what), '{', '}');
+
+    } // if isObj
+    
+    // If we reached here, there's no special methods, use JSON.
+    return JSON.stringify(what);
+  }
+
+  _stringFor(obj, str)
+  {
+    let count = 0;
+    if (this.seenDescrip.has(str))
+    {
+      count = this.seenDescrip.get(str);
     }
+    this.seenDescrip.set(str, ++count);
+    str += '#' + count.toString(16).padStart(3, '0');
+    this.seenObjects.set(obj, str);
+    return str;
+  }
 
-  } // if isObj
-  
-  // If we reached here, there's no special methods, use JSON.
-  return JSON.stringify(what);
-}
+  static addCustoms(...testFns)
+  {
+    for (let fn of testFns)
+    {
+      if (typeof fn === F)
+      {
+        CUSTOM.push(fn);
+      }
+      else
+      {
+        console.debug({fn, testFns});
+        throw new TypeError("Invalid custom stringify function");
+      }
+    }
+  }
 
-// Add a custom extension.
-def(stringify, '$extend',
-function(func, registration=false)
-{
-  if (typeof func === TYPES.F)
+  static registerCustoms(registerFn)
   {
-    if (registration)
-    { // Using the function to register custom behaviour.
-      func.call({stringify, TOSTRING_INSTANCES, TOSTRING_TYPES}, CUSTOM);
+    if (typeof registerFn === F)
+    {
+      registerFn.call(this, this);
     }
-    else 
-    { // The function is a custom test.
-      CUSTOM.push(func);
+    else
+    {
+      console.debug({registerFn});
+      throw new TypeError("Invalid custom registration function");
     }
   }
-});
+
+} // Stringify
+
+// Add some static properties for registerCustoms to use
+def(Stringify) 
+  ('strClass', {value: TOSTRING_INSTANCES})
+  ('strTypes', {value: TOSTRING_TYPES})
+  ('customFn', {value: CUSTOM})
+  ('DEFAULTS', {value: DEF})
 
 // Export it.
-module.exports = stringify;
+module.exports = {stringify, Stringify};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "main": "lib/index.js",
   "exports": 
   {
@@ -10,6 +10,7 @@
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
     "./events": "./lib/events/index.js",
+    "./events/observable": "./lib/events/observable.js",
     "./flags": "./lib/flags.js",
     "./maps": "./lib/maps.js",
     "./meta": "./lib/meta.js",
@@ -19,6 +20,7 @@
     "./observable": "./lib/observable.js",
     "./opt": "./lib/opt/index.js",
     "./opt/args": "./lib/opt/args.js",
+    "./state": "./lib/state.js",
     "./strings": "./lib/strings.js",
     "./traits": "./lib/traits.js",
     "./types": "./lib/types/index.js",
@@ -40,7 +42,8 @@
     "test": "lumtest.js",
     "build-meta": "lum-build",
     "build-jsdoc": "jsdoc -c ./jsdoc.js",
-    "build-docs": "npm run build-meta && npm run build-jsdoc"
+    "build-docs": "npm run build-meta && npm run build-jsdoc",
+    "build": "npm run build-docs"
   },
   "repository": 
   {