@lumjs/core 1.25.2 → 1.26.0

package/TODO.md

@@ -17,6 +17,8 @@ for the future would be a good idea. A few of the things I want to do:
   - Cut anything that seems superfluous or rarely used
   - Add ability to copy `Symbol` properties
 - Replace `obj.syncNested` with `obj.sync` using the new `obj.copy` API
+- Move `opt.Opts` into its own separate package
+- Give `observable` some TLC
 
 I will likely update this list a bit before I get around to starting the
 new branch that will eventually become the `2.0.0` release.

package/lib/obj/ns.js

@@ -83,6 +83,11 @@ exports.nsArray = nsArray;
  * @param {(object|boolean)} [opts] Options changing the behaviours.
  *   If this is a `boolean` it's assumed to be the `opts.log` option.
  * @param {boolean} [opts.log=false] Log errors for missing namespaces?
+ * @param {boolean} [opts.allowFun=true] Allow `obj` to be a `function` ?
+ * 
+ * By default both `object` and `function` are valid `obj` argument values;
+ * if this is set to `false`, only `object` values will be allowed.
+ * 
  * @param {*} [opts.default] A default value if the namespace is not found.
  * 
  * @return {*} The property if found, or `opts.default` if not.
@@ -90,13 +95,13 @@ exports.nsArray = nsArray;
  */
 function getObjectPath(obj, proppath, opts={})
 {
-  needObj(obj, true);
-
   if (typeof opts === B)
     opts = {log: opts};
   else if (!isObj(opts))
     opts = {};
 
+  needObj(obj, (opts.allowFun ?? true));
+
   proppath = nsArray(proppath);
 
   for (let p = 0; p < proppath.length; p++)

package/lib/opt.js

@@ -3,25 +3,109 @@
  * @module @lumjs/core/opt
  */
 
-const {U,F,S,N,B,isObj,isComplex,needObj,needType} = require('./types');
+const 
+{
+  U,F,S,N,B,
+  isObj,isComplex,isArray,isNil,needObj,needType
+} = require('./types');
 const {insert} = require('./arrays/add');
+const {getObjectPath} = require('./obj/ns');
+
+// Aliases for Opts#get() and Opts#find()
+const OPTS_ALIASES =
+{
+  'null': 'allowNull',
+  'lazy': 'isLazy',
+}
+
+/**
+ * A helper to support both positional arguments and named
+ * options in the same method signature.
+ *
+ * @param {object} opts - Options built from positional arguments
+ * 
+ * Keep in mind that this object **WILL** be modified!
+ * 
+ * @param {string} optArg - The option that may contain named options
+ * 
+ * Generally the name of the first positional argument that may be
+ * an `object` full of options or a different positional argument value.
+ * 
+ * The biggest limitation is that it cannot be an `object` value when used
+ * as a positional argument, as that will always be seen as the _options_.
+ * 
+ * @param {*} optDef - A default value for `opts[optArg]`
+ * 
+ * If `opts[optArg]` was an `object`, we'll compose its properties
+ * into `opts` directly. If after that `opts[optArg]` is still the
+ * options `object` then this value will be used instead.
+ * 
+ * @param {boolean} [validate=true] Ensure `opts` is an object?
+ * 
+ * Should only be disabled if you know for certain it is.
+ * 
+ * @example <caption>Example usage</caption>
+ * 
+ *   function example(first=true, second=null, third="test")
+ *   {
+ *     const opts = argOpts({first, second, third}, 'first', true);
+ *   }
+ * 
+ * @alias module:@lumjs/core/opt.argOpts
+ */
+function argOpts(opts, optArg, optDef, validate=true)
+{
+  if (validate) needObj(opts, false, 'invalid opts object');
+
+  if (isObj(opts[optArg]))
+  { // Merge the named options.
+    const specOpts = opts[optArg];
+    Object.assign(opts, specOpts);
+    if (opts[optArg] === specOpts)
+    { // specOpts didn't override the real option.
+      opts[optArg] = optDef;
+    }
+  }
+
+} // argOpts()
+
+exports.argOpts = argOpts;
+
+// Private helper for `val()` and `get()` to support new-style options.
+function _opts(opts, defNull)
+{
+  return argOpts(opts, 'allowNull', defNull, false);
+}
 
 /**
  * See if a value is *set*, and if not, return a default value.
+ * 
+ * This function used to use all positional arguments, but it now
+ * supports named options if an `object` is passed as the third argument.
+ * If both named options and the corresponding positional arguments are
+ * specified, the named options will take precedence.
  *
  * @param {*} optvalue - The value we are testing.
  * @param {*} defvalue - The default value if opt was null or undefined.
+ * 
+ * @param {(object|boolean)} opts - Options
+ * 
+ * If this is a `boolean` it is used as the `allowNull` option.
  *
- * @param {boolean} [allowNull=false] If true, allow null to count as *set*.
- * @param {boolean} [isLazy=false]    If true, and `defvalue` is a function,
- *                                    use the value from the function as 
- *                                    the default.
- * @param {object} [lazyThis=null]    If `isLazy` is true, this object will
- *                                    be used as `this` for the function.
- * @param {Array}  [lazyArgs]         If `isLazy` is true, this may be used
- *                                    as a list of arguments to pass.
+ * @param {boolean} [opts.allowNull=false] If true, allow null to count as *set*.
+ * @param {boolean} [opts.isLazy=false] If true, and `defvalue` is a function,
+ *                                      use the value from the function as 
+ *                                      the default.
+ * @param {object} [opts.lazyThis=null] If `isLazy` is true, this object will
+ *                                      be used as `this` for the function.
+ * @param {Array}  [opts.lazyArgs] If `isLazy` is true, this may be used
+ *                                 as a list of arguments to pass.
+ * 
+ * @param {boolean} [isLazy=false]  Same as `opts.isLazy`
+ * @param {object}  [lazyThis=null] Same as `opts.lazyThis`
+ * @param {Array}   [lazyArgs]      Same as `opts.lazyArgs`
  *
- * @return {*} Either the specified `opt` value or the default value.
+ * @return {*} Either `optvalue` or `defvalue` depending on the test.
  * @alias module:@lumjs/core/opt.val
  */
 function val(optvalue, defvalue, 
@@ -30,11 +114,13 @@ function val(optvalue, defvalue,
   lazyThis=null,
   lazyArgs=[])
 {
-  if (typeof optvalue === U || (!allowNull && optvalue === null))
+  const opts = _opts({allowNull,isLazy,lazyThis,lazyArgs}, false);
+
+  if (typeof optvalue === U || (!opts.allowNull && optvalue === null))
   { // The defined value was not "set" as per our rules.
-    if (isLazy && typeof defvalue === F)
+    if (opts.isLazy && typeof defvalue === F)
     { // Get the default value from a passed in function.
-      return defvalue.apply(lazyThis, lazyArgs);
+      return defvalue.apply(opts.lazyThis, opts.lazyArgs);
     }
     return defvalue;
   }
@@ -48,34 +134,105 @@ exports.val = val;
  * See if a property in an object is set.
  *
  * If it is, return the property, otherwise return a default value.
- * This uses the `val()` method, and as such supports the same options.
- * However read the parameters carefully, as the defaults may be different!
+ * This uses the `val()` method, and as such supports the same arguments.
+ * However read the descriptions, as defaults may be quite different!
  *
- * @param {object} obj     - An object to test for a property in.
- * @param {string} optname - The property name we're checking for.
- * @param {*} defvalue     - The default value.
+ * @param {object} obj      - An object to test for a property in.
+ * @param {string} optname  - The property name we're checking for.
+ * @param {*}      defvalue - The default value.
  *
- * @param {bool}   [allowNull=true] Same as `val()`, but default is `true`.
- * @param {bool}   [isLazy=false]   Same as `val()`.
- * @param {object} [lazyThis=opts]  Same as `val()`, but default is `obj`.
- * @param {Array}  [lazyArgs]       Same as `val()`.
+ * @param {(object|boolean)} [opts] Options
+ * 
+ * If this is a `boolean` it is used as the `allowNull` option.
+ * 
+ * @param {boolean} [opts.allowNull=true] Passed to `val()`;
+ * default is `true`, which differs from `val()`.
+ * @param {boolean} [opts.isLazy=false] Passed to `val()`;
+ * default is `false`, the same as `val()`.
+ * @param {object}  [opts.lazyThis=obj] Passed to `val()`;
+ * default is `obj`, which differs from `val()`.
+ * @param {Array}   [opts.lazyArgs] Passed to `val()`
+ * @param {boolean} [opts.allowFun=false] Allow `obj` to be a `function` ?
+ * 
+ * By default only `object` values are valid for `obj`; this can be set to
+ * `true` to allow `function` values to be used.
+ * 
+ * @param {boolean} [isLazy=false]   Same as `opts.isLazy`
+ * @param {object}  [lazyThis=opts]  Same as `opts.lazyThis`
+ * @param {Array}   [lazyArgs]       Same as `opts.lazyArgs`
+ * @param {boolean} [allowFun]       Same as `opts.allowFun`
  *
- * @return {*} Either the property value, or the default value.
+ * @returns {*} Either the property value, or the default value.
+ * @see module:@lumjs/core/opt.val
  * @alias module:@lumjs/core/opt.get
  */
 function get(obj, optname, defvalue, 
   allowNull=true, 
   isLazy=false, 
   lazyThis=obj,
-  lazyArgs)
+  lazyArgs=[],
+  allowFun=false)
 {
-  needObj(obj);
+  const opts = _opts({allowNull,isLazy,lazyThis,lazyArgs,allowFun}, true);
+
+  needObj(obj, opts.allowFun);
   needType(S, optname);
-  return val(obj[optname], defvalue, allowNull, isLazy, lazyThis, lazyArgs);
+
+  return val(obj[optname], defvalue, 
+    opts.allowNull, 
+    opts.isLazy, 
+    opts.lazyThis, 
+    opts.lazyArgs);
 }
 
 exports.get = get;
 
+/**
+ * An alternative to `get()` that uses `getObjectPath()`
+ * to look for a specific nested property value.
+ * 
+ * While `get()` supports positional arguments like `val()`, 
+ * this function _only_ supports named options.
+ * 
+ * @param {object} obj - Object we're looking for properties in
+ * @param {(string|Array)} path - Path for `getObjectPath()`
+ * @param {object} [opts] Options
+ * 
+ * This supports all of the same options as `get()`, plus all of the
+ * options supported by `getObjectPath()`. See the docs for both those
+ * functions to see what all is supported. If the same option is supported
+ * by *both* functions (e.g. `allowFun`) then the default value 
+ * will be the one from `getObjectPath()` rather than `get()`.
+ * 
+ * @param {boolean} [opts.ro=false] Should `opts` be read-only?
+ * 
+ * If `true`, a copy of the `opts` will be made before any changes
+ * are performed, ensuring the original options aren't modified.
+ * 
+ * @returns {*} The property if found, or `opts.default` if not.
+ * 
+ * @see module:@lumjs/core/opt.get
+ * @see module:@lumjs/core/obj.getObjectPath
+ * @alias module:@lumjs/core/opt.getPath
+ */
+function getPath(obj, path, opts={})
+{
+  const defvalue = opts.default;
+  if (opts.ro)
+  {
+    opts = Object.assign({}, opts);
+  }
+  delete opts.default;
+  
+  return val(getObjectPath(obj, path, opts), defvalue,
+    (opts.allowNull ?? true),
+    opts.isLazy,
+    (opts.lazyThis ?? obj),
+    opts.lazyArgs);
+}
+
+exports.getPath = getPath;
+
 /**
  * A class for handling options with multiple sources.
  * @alias module:@lumjs/core/opt.Opts
@@ -100,7 +257,12 @@ class Opts
     this.$strictProps = false;
 
     this.add(...sources);
-    this._compile();
+  }
+
+  static isPath(value)
+  {
+    return (Array.isArray(value) 
+    || (typeof value === S && value.includes('.')));
   }
 
   /**
@@ -125,6 +287,7 @@ class Opts
    * 
    * @returns {object} `this`
    * @throws {Error} An error of `errClass` class, if fatal mode is enabled.
+   * @private
    */
   _err(msg, info={}, errClass=TypeError)
   {
@@ -139,6 +302,49 @@ class Opts
     }
   }
 
+  /**
+   * Normalize options.
+   * 
+   * Auto-sets `isLazy` if it wasn't specified.
+   * Applies any known aliases.
+   * 
+   * @param {object} opts - Options to normalize
+   * @returns {object} Usually `opts`, but might be a copy.
+   * @private
+   */
+  _opts(opts)
+  {
+    if (opts._opts_compiled)
+    { // Already done.
+      return opts;
+    }
+
+    if (opts.ro)
+    {
+      opts = Object.assign({}, opts);
+    }
+
+    if (isNil(opts.isLazy)
+      && (isComplex(opts.lazyThis) 
+      || isArray(opts.lazyArgs)))
+    {
+      opts.isLazy = true;
+    }
+
+    for (const akey in OPTS_ALIASES)
+    {
+      const okey = OPTS_ALIASES[akey];
+      if (opts[okey] === undefined && opts[akey] !== undefined)
+      { // An alias was found.
+        opts[okey] = opts[akey];
+      }
+    }
+
+    // Now remember that we've processed these options.
+    opts._opts_compiled = true;
+    return opts;
+  }
+
   /**
    * Set the fatal error handling setting.
    * 
@@ -291,8 +497,6 @@ class Opts
    */
   add(...sources)
   {
-    let pos=-1;
-
     for (let source of sources)
     {
       if (source === undefined || source === null)
@@ -324,7 +528,7 @@ class Opts
       
       if (isObj(source))
       { // It's a source to add.
-        insert(this.$sources, source, pos);
+        insert(this.$sources, source, this.$curPos);
       }
       else
       { // That's not valid.
@@ -370,35 +574,91 @@ class Opts
   /**
    * Get an option value from our compiled data sources.
    * 
-   * This uses the `get()` function, but instead of using positional
-   * arguments, it supports an object of named options instead.
+   * This uses either `get()` or `getPath()` depending on
+   * the specified arguments.
+   * 
+   * @param {(string|Array)} opt - The name or path of the option to get.
+   * 
+   * @param {object} [opts] Options
+   * 
+   * I will only list the options that are specific to this method,
+   * as the rest are already documented in `getPath()` and related functions.
    * 
-   * @param {string} opt - The name of the option to get.
-   * @param {object} [args] Optional arguments for `get()`.
-   * @param {*} [args.default] `defvalue` argument.
-   * @param {boolean} [args.null=true] `allowNull` argument.
-   * @param {boolean} [args.lazy=false] `isLazy` argument.
-   * @param {(object|function)} [args.lazyThis] `lazyThis` argument.
-   * If this is defined, `args.lazy` will be set to `true`.
-   * @param {Array} [args.lazyArgs] `lazyArgs` argument.
-   * If this is defined, `args.lazy` will be set to `true`.
+   * Note that some options like `opts.ro` and `opts.default` which are
+   * supported by `getPath()` but not `get()` are usable here regardless
+   * of which of those functions will end up being called. The method
+   * will do the right thing to make those options work in every context.
+   * 
+   * @param {boolean} [opts.path] Use `getPath()` instead of `get()` ?
+   * 
+   * If not specified, this will be auto-determined based on the `opt`;
+   * if `opt` is an `Array` or contains the `'.'` character the default
+   * will be `true`, otherwise it will be `false`.
    * 
    * @returns {*} The output of the `get()` function.
+   * @see module:@lumjs/core/opt.getPath
    */
-  get(opt, args={})
+  get(opt, opts={})
   {
-    if (isComplex(args.lazyThis) || Array.isArray(args.lazyArgs))
+    opts = this._opts(opts);
+
+    const isPath = this.constructor.isPath;
+    const usePath = opts.path ?? isPath(opt);
+
+    if (usePath)
     {
-      args.lazy = true;
+      return getPath(this.$data, opt, opts);
     }
+    else
+    {
+      return get(this.$data, opt, opts.default, opts);
+    }
+  }
 
-    return get(this.$data, opt, 
-      args.default, 
-      args.null, 
-      args.lazy, 
-      args.lazyThis, 
-      args.lazyArgs);
+  /**
+   * A wrapper around the `get()` method that can check for
+   * multiple possible properties or namespaces, and will
+   * return the first one that has a defined value.
+   * 
+   * @param {object} opts - Options
+   * 
+   * The same options as the `get()` instance method, which includes all
+   * of the options of the `getPath()`, `get()`, and `getObjectPath()`
+   * utility functions. So there's a lot of options supported here.
+   * 
+   * Unlike every other method and function that uses options,
+   * this is a mandatory argument. You cannot skip it. If you want
+   * to use all default options, just pass `{}` and presto, defaults.
+   * 
+   * @param  {...(string|Array)} paths - All the properties/paths to try.
+   * 
+   * At least one path must be specified (although if you were only
+   * going to specify one, you may as well use the `get()` method
+   * directly rather than this...)
+   * 
+   * @returns {*} Could be anything!
+   */
+  find(opts, ...paths)
+  { 
+    opts = this._opts(opts);
+
+    const defvalue = opts.default;
+    delete opts.default;
+    delete opts.ro;
+
+    for (const path of paths)
+    {
+      const value = this.get(path, opts);
+      if (value !== undefined)
+      { // Found a value.
+        return value;
+      }
+    }
+
+    // No matches found, use the default.
+    return val(undefined, defvalue, opts);
   }
-}
+
+} // Opts
 
 exports.Opts = Opts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.25.2",
+  "version": "1.26.0",
   "main": "lib/index.js",
   "exports":
   {