@lumjs/core 1.25.2 → 1.30.0

package/lib/opt/args.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const {isObj} = require('../types/basics');
+
+/**
+ * A helper function 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.
+ * 
+ * @example <caption>Example usage</caption>
+ * 
+ *   function example(first=true, second=null, third="test")
+ *   {
+ *     const opts = argOpts({first, second, third}, 'first', true);
+ *   }
+ * 
+ * @exports module:@lumjs/core/opt/args
+ */
+function argOpts(opts, optArg, optDef)
+{
+  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;
+    }
+  }
+  return opts;
+} // argOpts()
+
+module.exports = argOpts;

package/lib/opt/getpath.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const {isArrayOf,S} = require('../types/basics');
+const {getObjectPath} = require('../obj/ns');
+const {val} = require('./val');
+
+/**
+ * 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);
+}
+
+/**
+ * Does a value appear to be a path usable by the
+ * {@link module:@lumjs/core/opt.getPath} function?
+ * 
+ * @param {*} value - Value to test;
+ * will be considered a path if it is:
+ * 
+ * - An `Array` with only `string` values in it.
+ * - A string with a `.` character in it.
+ * 
+ * @returns {boolean}
+ * @alias module:@lumjs/core/opt.isPath
+ */
+function isPath(value)
+{
+  return (isArrayOf(value, S) 
+  || (typeof value === S && value.includes('.')));
+}
+
+module.exports = {getPath, isPath};

package/lib/opt/getval.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const {S,needObj,needType} = require('../types');
+const {_opts,val} = require('./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 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|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`
+ *
+ * @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=[],
+  allowFun=false)
+{
+  const opts = _opts({allowNull,isLazy,lazyThis,lazyArgs,allowFun}, true);
+
+  needObj(obj, opts.allowFun);
+  needType(S, optname);
+
+  return val(obj[optname], defvalue, 
+    opts.allowNull, 
+    opts.isLazy, 
+    opts.lazyThis, 
+    opts.lazyArgs);
+}
+
+module.exports = {val, get};

package/lib/opt/index.js

@@ -0,0 +1,21 @@
+/**
+ * Functions for working with options and default values.
+ * @module @lumjs/core/opt
+ */
+
+const argOpts = require('./args');
+const {getPath,isPath} = require('./getpath');
+const {val,get} = require('./getval');
+
+exports = module.exports =
+{
+  argOpts, get, getPath, isPath, val,
+}
+
+const {wrapDepr} = require('../meta');
+wrapDepr(exports, 'Opts',
+{
+  dep: '@lumjs/core.opt.Opts',
+  rep: '@lumjs/opts',
+  get: () => require('@lumjs/opts'),
+});

package/lib/opt/val.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const {U,F} = require('../types/js');
+const argOpts = require('./args');
+
+// Helper for `val()` and `get()` to support new-style options.
+function _opts(opts, defNull)
+{
+  return argOpts(opts, 'allowNull', defNull);
+}
+
+/**
+ * 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} [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 `optvalue` or `defvalue` depending on the test.
+ * @alias module:@lumjs/core/opt.val
+ */
+function val(optvalue, defvalue, 
+  allowNull=false, 
+  isLazy=false, 
+  lazyThis=null,
+  lazyArgs=[])
+{
+  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 (opts.isLazy && typeof defvalue === F)
+    { // Get the default value from a passed in function.
+      return defvalue.apply(opts.lazyThis, opts.lazyArgs);
+    }
+    return defvalue;
+  }
+
+  return optvalue;
+}
+
+module.exports = {_opts, val};

package/lib/strings.js

@@ -2,7 +2,7 @@
  * String and locale related functions.
  * @module @lumjs/core/strings
  */
-const {S,B,F,isObj,root,isArray,needType,needObj,console} = require('./types');
+const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types');
 
 /**
  * Get the locale/language string.

package/lib/types/basics.js

@@ -1,10 +1,35 @@
-const {O, F, S, SY} = require('./js');
+"use strict";
+
+/**
+ * Basic types sub-module.
+ * 
+ * Provides simple type tests, and a few one or two character constants
+ * One or two character identifiers for the core JS type names.
+ * 
+ * These are only the strings returned by the `typeof` operator.
+ * See {@link module:@lumjs/core/types.TYPES} for a list
+ * that includes special types and compound pseudo-types, etc.
+ * 
+ * @prop {string} O - object
+ * @prop {string} F - function
+ * @prop {string} S - string
+ * @prop {string} B - boolean
+ * @prop {string} N - number
+ * @prop {string} U - undefined
+ * @prop {string} SY - symbol
+ * @prop {string} BI - bigint
+ * 
+ * @module @lumjs/core/types/basics
+ */
+
+const JS = require('./js');
+const {O, F, S, SY} = JS;
 
 /**
  * See if a value is a non-null `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isObj
+ * @alias module:@lumjs/core/types/basics.isObj
  */
 function isObj(v) { return (typeof v === O && v !== null); }
 
@@ -13,7 +38,7 @@ function isObj(v) { return (typeof v === O && v !== null); }
  * Like `isObj()`, `null` does not count as an `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isComplex
+ * @alias module:@lumjs/core/types/basics.isComplex
  */
 function isComplex(v) { return (typeof v === F || isObj(v)); }
 
@@ -21,7 +46,7 @@ function isComplex(v) { return (typeof v === F || isObj(v)); }
  * See if a value is *nil* (i.e. either `null` or `undefined`).
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isNil
+ * @alias module:@lumjs/core/types/basics.isNil
  */
 function isNil(v) { return (v === undefined || v === null); }
 
@@ -29,7 +54,7 @@ function isNil(v) { return (v === undefined || v === null); }
  * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.notNil
+ * @alias module:@lumjs/core/types/basics.notNil
  */
 function notNil(v) { return (v !== undefined && v !== null); }
 
@@ -39,7 +64,7 @@ function notNil(v) { return (v !== undefined && v !== null); }
  * is neither *nil* nor *complex*.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isScalar
+ * @alias module:@lumjs/core/types/basics.isScalar
  */
 function isScalar(v) { return (notNil(v) && !isComplex(v)); }
 
@@ -49,7 +74,7 @@ function isScalar(v) { return (notNil(v) && !isComplex(v)); }
  * @function
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isArray
+ * @alias module:@lumjs/core/types/basics.isArray
  */
 const isArray = Array.isArray;
 
@@ -57,7 +82,7 @@ const isArray = Array.isArray;
  * See if a value is a `TypedArray` object.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isTypedArray
+ * @alias module:@lumjs/core/types/basics.isTypedArray
  */
 function isTypedArray(v)
 {
@@ -70,7 +95,7 @@ function isTypedArray(v)
  * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
  *   If `false` (default) we want a regular `Array`.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.nonEmptyArray
+ * @alias module:@lumjs/core/types/basics.nonEmptyArray
  */
 function nonEmptyArray(v, typed=false)
 {
@@ -84,7 +109,7 @@ function nonEmptyArray(v, typed=false)
  * See if a value is an `arguments` object.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isArguments
+ * @alias module:@lumjs/core/types/basics.isArguments
  */
 function isArguments(v) 
 {
@@ -95,7 +120,7 @@ function isArguments(v)
  * See if a value is a Property name.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isProperty
+ * @alias module:@lumjs/core/types/basics.isProperty
  */
 function isProperty(v)
 {
@@ -117,7 +142,7 @@ function isProperty(v)
  * function will pass the test.
  * 
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isIterable
+ * @alias module:@lumjs/core/types/basics.isIterable
  */
 function isIterable(v)
 {
@@ -129,7 +154,7 @@ function isIterable(v)
  * 
  * @param {*} v - Value to test
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isConstructor
+ * @alias module:@lumjs/core/types/basics.isConstructor
  */
 function isConstructor(v)
 {
@@ -153,7 +178,7 @@ function isConstructor(v)
  * 
  * @param {object} obj - The object we are testing. 
  * @returns {boolean} - Is the object a valid descriptor?
- * @alias module:@lumjs/core/types.doesDescriptor
+ * @alias module:@lumjs/core/types/basics.doesDescriptor
  */
 function doesDescriptor(obj)
 {
@@ -193,7 +218,7 @@ function doesDescriptor(obj)
  *   If this is `false` then any unknown properties will be ignored.
  * 
  * @returns {boolean} Is the object a valid descriptor template?
- * @alias module:@lumjs/core/types.doesDescriptorTemplate
+ * @alias module:@lumjs/core/types/basics.doesDescriptorTemplate
  */
 function doesDescriptorTemplate(obj, accessor=false, strict=true)
 {
@@ -229,5 +254,7 @@ module.exports =
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   isIterable, nonEmptyArray, isArguments, isProperty, isConstructor,
-  doesDescriptor, doesDescriptorTemplate,
+  doesDescriptor, doesDescriptorTemplate, JS,
 }
+
+JS.addTo(module.exports);

package/lib/types/def.js

@@ -2,29 +2,27 @@
 const unbound = require('./root').unbound;
 const {F, B} = require('./js');
 const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
-const {copy, duplicateOne: clone} = require('../obj/copyall');
+const clone = (...args) => Object.assign({}, ...args);
 
 /**
- * A wrapper around `Object.defineProperty()`.
- * 
- * This has a few features that makes adding properties a lot nicer.
- * It replaces the `prop()` method from the old Lum.js v4.
+ * A wrapper around `Object.defineProperty()` with added flair!
  * 
  * @param {(object|function)} obj - The object to add a property to.
+ * 
  * @param {?(string|symbol|boolean|object)} name 
  * If a `string` or `symbol`, it's the property name.
  * 
  * If this is `null` or `undefined` then the `value` is ignored entirely,
  * and instead a bound version of this function is created with the
- * `obj` already passed as the first parameter, and any of the options from
- * `opts` added to a new default set of options bound to the function.
- * Can be useful if you need to add a lot of properties to the same object.
+ * `obj` already passed as the first parameter. It will generate context
+ * options which will compose the enumerable properties of `opts` if
+ * that argument is passed.
  * 
  * If this is a `boolean`, then the same logic as if it was `null` or 
  * `undefined` will apply, except that an `enumerable` property with this 
  * value will also be added to the descriptors.
  * 
- * If this is an `object`, we also ignore `value` entirely, as each of 
+ * If this is an `object`, the `value` will be ignored, as each of 
  * the keys of this object will be used as the name of a property, 
  * and the value associated with the key will be the value to assign it.
  * 
@@ -101,6 +99,40 @@ function def(obj, name, value, opts)
     = !unbound(this, true, true) 
     && typeof this.bound === F;
 
+  if (isNil(name) || typeof name === B)
+  { // Binding of Isaac?
+    const bindOpts = (to) =>
+    {
+      Object.assign(to, opts);
+      if (typeof name === B) to.enumerable = name;
+      return to;
+    }
+
+    if (isBound)
+    { // Already bound, update options and return.
+      return bindOpts(this).bound;
+    }
+
+    const V = (value) => ({value, configurable: false});
+
+    // Create a fresh binding context for the bound function.
+    const bind = bindOpts({});
+    // Create a bound function.
+    const bound = def.bind(bind, obj);
+    // Add a reference to the function in the binding context.
+    def(bind, 'bound', V(bound));
+    // And a reference to the binding options from the function.
+    def(bound, '$this', V(bind));
+
+    if (value)
+    { // Add DescriptorTemplate magic properties.
+      const dopts = clone(value, {desc: bind});
+      DT.addInstance(bound, dopts);
+    }
+
+    return bound;
+  }
+
   // When we're finished, return this value.
   const done = () => 
   { 
@@ -114,9 +146,12 @@ function def(obj, name, value, opts)
     }
   }
 
-  if (isBound && isNil(opts))
-  { // We'll use `this` as the options.
-    opts = this;
+  if (isBound)
+  { // Assign `this` options.
+    if (isNil(opts)) 
+      opts = this;
+    else if (isObj(opts))
+      opts = clone(this, opts);
   }
 
   if (isObj(name))
@@ -128,29 +163,6 @@ function def(obj, name, value, opts)
     // Okay, we're done now.
     return done();
   }
-  else if (isNil(name) || typeof name === B)
-  { // Create a fresh binding context for the bound function.
-    const bind = {};
-
-    if (isObj(opts))
-    { // Copy our existing options as defaults.
-      copy(bind, opts);
-    }
-
-    if (typeof name === B)
-    { // A boolean `name` overrides the enumerable option.
-      bind.enumerable = name;
-    }
-
-    // Create a bound function.
-    const bound = def.bind(bind, obj);
-    // Add a reference to the function in the binding context.
-    bind.bound = bound;
-    // And a reference to the binding options from the function.
-    bound.$this = bind;
-
-    return bound;
-  }
   else if (!isProperty(name))
   { // That's not valid.
     throw new TypeError("Property name must be a string or a Symbol");
@@ -225,4 +237,5 @@ module.exports = def;
 
 // Now we'll setup the descriptor template accessors.
 const DT = require('./dt');
-DT.addTo(def);
+DT.addInit(def);
+def.DT = DT;