@lumjs/core 1.31.1 → 1.33.0

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()
 {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.31.1",
+  "version": "1.33.0",
   "main": "lib/index.js",
   "exports": 
   {
@@ -19,6 +19,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 +41,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": 
   {