@lumjs/core 1.6.1 → 1.7.1

package/lib/index.js

@@ -51,8 +51,36 @@ has('lazy',  {value: types.lazy});
 
 // The module builder itself.
 has('ModuleBuilder', {value: Builder});
-// And a shortcut function.
-has('buildModule', {value: function(m,o) { return Builder.build(m,o); }});
+
+/**
+ * Return a set of functions for building a module.
+ * 
+ * @name module:@lumjs/core.buildModule
+ * @function
+ * @see module:@lumjs/core/modulebuilder.build 
+ */
+has('buildModule', 
+{
+  value: function(m,o) 
+  { 
+    return Builder.build(m,o); 
+  },
+});
+
+/**
+ * Create a new `ModuleBuilder` instance.
+ * 
+ * @name module:@lumjs/core.newBuilder
+ * @function
+ * @see module:@lumjs/core/modulebuilder.new
+ */
+has('newBuilder',
+{
+  value: function(m, o)
+  {
+    return Builder.new(m,o);
+  }
+});
 
 /**
  * Array utility functions «Lazy»
@@ -83,7 +111,7 @@ can('strings');
 can('flags');
 
 /**
- * Functions for manipulating objects
+ * Functions for manipulating objects «Lazy»
  * @name module:@lumjs/core.obj
  * @type {module:@lumjs/core/obj}
  */
@@ -137,12 +165,12 @@ from('objectid', 'randomNumber', 'InternalObjectId');
 from('meta', 'stacktrace', 'AbstractClass', 'Functions', 'NYI');
 
 /**
- * Create a magic *Enum* object
+ * Create a magic *Enum* object «Lazy»
  * @name module:@lumjs/core.Enum
  * @function
  * @see module:@lumjs/core/enum
  */
-can('Enum', {module: 'enum'});
+can('Enum', true);
 
 /**
  * Make an object support the *Observable* API «Lazy»

package/lib/modulebuilder.js

@@ -1,18 +1,18 @@
 
-const {S,F,B,isObj,needObj,needType,def,lazy} = require('./types');
-
-function clone(obj)
+const 
 {
-  const copy = {};
-  for (const name in obj)
-  {
-    copy[name] = obj[name];
-  }
-  return copy;
-}
+  S,F,B,
+  isObj,needObj,needType,
+  def,lazy
+} = require('./types');
+
+const clone = require('./obj/copyall').duplicateOne;
 
 // Methods we want to export in the functional API.
-const BUILD_METHODS = ['has', 'can', 'from'];
+const BUILD_METHODS = ['has', 'can', 'from', 'set'];
+
+// Fallback locale
+const DLOC = 'en-US';
 
 /**
  * A class to make building modules easier.
@@ -53,6 +53,16 @@ class ModuleBuilder
    * It's always possible to set the `conf.module` parameter manually as well,
    * which avoids the need to generate a separate parameter name.
    * 
+   * @param {(string|boolean)} [opts.withLocale=false] Use locales?
+   * 
+   * If this is a `string` it's the name of the locale (e.g. `en-US`).
+   * 
+   * If this is `true` we'll use the default locale as determined by
+   * [getLocale()]{@link module:@lumjs/core/strings.getLocale}.
+   * 
+   * If this is `false` we won't use locales (unless the `NESTED_CAMEL`
+   * mode is in use, in which case we'll use the default locale.)
+   * 
    */
   constructor(targetModule, opts={})
   {
@@ -69,13 +79,28 @@ class ModuleBuilder
 
     this.nested = opts.nested ?? ModuleBuilder.NESTED_ERROR;
 
-    this.strings = opts.strings;
-    this.locale = opts.locale;
+    if (opts.withLocale)
+    { // Initialize the strings here.
+      this.withLocale(opts.locale);
+    }
   }
 
   // Get a descriptor for a module export.
   requireDescriptor(name, conf={})
   {
+    if (typeof conf === S)
+    { // A quick shortcut for setting module name.
+      conf = {module: conf};
+    }
+    else if (conf === true)
+    { // Use the lowercase name as the module.
+      conf = {module: this.$lc(name)};
+    }
+    else if (typeof conf.getter === F || typeof conf.setter === F)
+    { // It's an accessor-style descriptor already.
+      return conf;
+    }
+
     let value = conf.value;
     
     if (value === undefined)
@@ -100,6 +125,11 @@ class ModuleBuilder
     return {configurable, enumerable, writable, value};
   }
 
+  $lc(name)
+  {
+    return name.toLocaleLowerCase(this.locale ?? DLOC);
+  }
+ 
   // Normalize a property name.
   $normalizeProperty(name)
   {
@@ -132,16 +162,29 @@ class ModuleBuilder
     return name;
   }
 
-  $normalizeWithCamelCase(names)
+  withLocale(loc)
   {
     if (this.strings === undefined)
-    {
+    { // Load the strings library.
       this.strings = require('./strings');
     }
+
     if (this.locale === undefined)
-    {
-      this.locale = this.strings.getLocale();
+    { // Set the locale.
+      if (typeof loc === S)
+      { // Use an explicitly passed value.
+        this.locale = loc;
+      }
+      else 
+      { // Use the default locale.
+        this.locale = this.strings.getLocale();
+      }
     }
+  }
+
+  $normalizeWithCamelCase(names)
+  {
+    this.withLocale();
     let name = names.shift().toLocaleLowerCase(this.locale);
     for (const path in names)
     {
@@ -155,7 +198,14 @@ class ModuleBuilder
    * 
    * @param {string} name - The property name to export.
    *
-   * @param {object} [conf] Additional export configuration options.
+   * @param {(object|string|true)} [conf] Additional export configuration options.
+   * 
+   * If this is a `string` instead of an `object`, it's assumed to be the
+   * `conf.module` value.
+   * 
+   * If this is `true` then the `conf` will be set with `module` being the
+   * lowercase version of `name`.
+   * 
    * @param {string} [conf.module=`./${name}`] The module to `require()`.
    * @param {string} [conf.prop] If set, we want an exported property
    * of this name from the loaded module.
@@ -191,7 +241,7 @@ class ModuleBuilder
    * @param {object} [conf] Additional export configuration options.
    * 
    * In addition to all the options supported by 
-   * [has()]{@link module:@lumjs/core/modules.has}
+   * [has()]{@link module:@lumjs/core/modules#has}
    * this also supports one further option.
    * 
    * @param {object} [conf.lazy] Advanced options for the `lazy()` call.
@@ -268,6 +318,33 @@ class ModuleBuilder
     return this;
   }
 
+  /**
+   * Define an exported property in our module.
+   * 
+   * This is literally just a wrapper around the
+   * [def()]{@link module:@lumjs/core/types.def} method,
+   * that passes `this.module.exports` as the `obj` parameter.
+   * 
+   * @param {*} name - See `def()` for details.
+   * @param {*} value - See `def()` for details.
+   * @param {*} opts - See `def()` for details.
+   * @returns {(object|function)} What is returned may vary:
+   * 
+   * If the `def()` returns a *bound* copy of itself, we'll return that
+   * bound function directly.
+   * 
+   * In any other case, we return `this` ModuleBuilder instance.
+   */
+  set(name, value, opts)
+  {
+    const retval = def(this.module.exports, name, value, opts);
+    if (typeof retval === F && isObj(retval.$this) && retval.$this.bound === retval)
+    { // A bound copy was returned, we're going to return it directly.
+      return retval;
+    }
+    return this;
+  }
+
   /**
    * Create a functional API for the ModuleBuilder class.
    * 
@@ -278,12 +355,14 @@ class ModuleBuilder
    * They each have a special `builder` property which is a reference
    * to the underlying `ModuleBuilder` instance.
    * 
-   * There's also a `builder` property in the exported function list.
+   * There's also a `builder` property in the exported function list,
+   * as well as a copy of the `def()` method for quick exporting.
    * 
    * Example usage:
    * 
    * ```js
-   * const {has,can,from} = require('@lumjs/core').ModuleBuilder.build(module);
+   * const {has,can,from,set} 
+   *  = require('@lumjs/core').ModuleBuilder.build(module);
    * // or the shortcut: require('@lumjs/core).buildModule(module);
    * 
    * // exports.foo = require('./foo');
@@ -301,7 +380,7 @@ class ModuleBuilder
   static build(targetModule, opts)
   {
     const builder = new this(targetModule, opts);
-    const funcs = {builder};
+    const funcs = {builder, def};
     for (const name of BUILD_METHODS)
     {
       const func = function()

package/lib/obj/copyall.js

@@ -1,8 +1,10 @@
 /**
  * This is a 'dumb' copy method.
  *
- * It does no type checking, and has no qualms about overwriting properties.
- * You probably want something like `copyProps` instead.
+ * It only copies enumerable properties, does no type checking, 
+ * and has no qualms about overwriting properties.
+ * 
+ * Use `copyProps`, or `mergeNested` for more robust versions.
  * 
  * @alias module:@lumjs/core/obj.copyAll
  */
@@ -17,5 +19,30 @@ function copyAll(target, ...sources)
   }
   return target;
 }
+exports.copyAll = copyAll;
+
+/**
+ * Make a copy of a single object using `copyAll`.
+ * 
+ * Use `clone` for a more robust version.
+ * 
+ * Alias: `copyAll.clone`
+ * 
+ * @alias module:@lumjs/core/obj.duplicateOne
+ * @param {object} obj - The object to duplicate.
+ * @returns {object} A clone of the object.
+ */
+exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
 
-module.exports = copyAll;
+/**
+ * Make a new object containing properties from other objects using `copyAll`.
+ * 
+ * Use `copyProps.into({}).from(...sources)` for a more robust version.
+ * 
+ * Alias: `copyAll.clone`
+ * 
+ * @alias module:@lumjs/core/obj.duplicateOne
+ * @param {object} obj - The object to duplicate.
+ * @returns {object} A clone of the object.
+ */
+exports.duplicateAll = copyAll.duplicate = () => copyAll({}, ...arguments);

package/lib/obj/copyprops.js

@@ -1,6 +1,11 @@
 
 // Get some constants
-const {B,isObj,isComplex,isArray,def: defProp} = require('../types');
+const {B,N,F,isObj,isArray,needObj,def} = require('../types');
+const {duplicateOne: clone} = require('./copyall');
+
+const RECURSE_NONE =  0;
+const RECURSE_ALL  = -1;
+const RECURSE_LIST = -2;
 
 /**
  * Copy properties from one object to another.
@@ -8,61 +13,143 @@ const {B,isObj,isComplex,isArray,def: defProp} = require('../types');
  * @param {(object|function)} source - The object to copy properties from.
  * @param {(object|function)} target - The target to copy properties to.
  *
- * @param {object} [propOpts] Options for how to copy properties.
- * @param {boolean} [propOpts.default=true] Copy only enumerable properties.
- * @param {boolean} [propOpts.all=false] Copy ALL object properties.
- * @param {Array} [propOpts.props] A list of specific properties to copy.
- * @param {object} [propOpts.overrides] Descriptor overrides for properties.
- * @param {Array} [propOpts.exclude] A list of properties NOT to copy.
- * @param {*} [propOpts.overwrite=false] Overwrite existing properties.
- *   If this is a `boolean` value, it will allow or disallow overwriting
- *   of any and all properties in the target object.
+ * @param {object} [opts] Options for how to copy properties.
+ * @param {boolean} [opts.default=true] Copy only enumerable properties.
+ * @param {boolean} [opts.all=false] Copy ALL object properties.
+ * @param {Array} [opts.props] A list of specific properties to copy.
+ * @param {Array} [opts.exclude] A list of properties NOT to copy.
+ * @param {object} [opts.overrides] Descriptor overrides for properties.
+ * 
+ * The object is considered a map, where each *key* is the name of the
+ * property, and the value should be an `object` containing any valid
+ * descriptor properties.
+ * 
+ * If `opts.default` is explicitly set to `false` and `opts.overrides` 
+ * is set, then not only will it be used as a list of overrides, 
+ * but only the properties specified in it will be copied.
+ * 
+ * @param {*} [opts.overwrite=false] Overwrite existing properties.
+ * 
+ * If this is a `boolean` value, it will allow or disallow overwriting
+ * of any and all properties in the target object.
  *
- *   If this is an object, it can be an Array of property names to allow
- *   to be overwritten, or a map of property name to a boolean indicating
- *   if that property can be overwritten or not.
+ * If this is an `object`, it can be an `Array` of property names to allow
+ * to be overwritten, or a *map* of property name to a `boolean` indicating
+ * if that property can be overwritten or not.
+ * 
+ * Finally, if this is a `function` it'll be passed the property name and
+ * must return a boolean indicating if overwriting is allowed.
+ * 
+ * @param {number} [opts.recursive=0] Enable recursive copying of objects.
+ * 
+ * If it is `0` (also `copyProps.RECURSE_NONE`) then no recursion is done.
+ * In this case, the regular assignment rules (including `opts.overwrite`)
+ * will be used regardless of the property type. 
+ * This is the default value.
+ * 
+ * If this is *above zero*, it's the recursion depth for `object` properties.
+ * 
+ * If this is *below zero*, then it should be one of the constant values:
+ * 
+ * | Contant                  | Value | Description                          |
+ * | ------------------------ | ----- | ------------------------------------ |
+ * | `copyProps.RECURSE_ALL`  | `-1`  | Recurse to an *unlimited* depth.     |
+ * | `copyProps.RECURSE_LIST` | `-2`  | Recurse `opts.recurseOpts` props.    |
+ * 
+ * @param {object} [opts.recurseOpts] Options for recursive properties.
+ * 
+ * If `opts.recursive` is not `0` then `opts.recurseOpts` can be a map of
+ * property names to further objects, which will be used as the `opts` for
+ * that property when calling `copyProps()` recursively.
+ * 
+ * So you could have nested `opts.recurseOpts` values if required.
+ * 
+ * The `recursive` property will automatically be added to the individual
+ * `recurseOpts`, automatically applying the correct value.
+ * 
+ * The `opts.recurseOpts` option has an extra-special meaning if `opts.recurse`
+ * is set to `RECURSE_LIST`, as then *only* the properties with options defined
+ * in `opts.recurseOpts` will be recursed. The rest will simply be copied.
  *
  * @returns {object} The `target` object.
  * @alias module:@lumjs/core/obj.copyProps
  */
-function copyProps(source, target, propOpts)
+function copyProps(source, target, opts={})
 {
   //console.debug("copyProps", source, target, propOpts);
-  if (!isComplex(source) || !isComplex(target))
+  needObj(source, true, 'source must be an object or function');
+  needObj(target, true, 'target must be an object or function');
+  needObj(opts, false, 'opts must be an object');
+
+  const useDefaults = opts.default   ?? true;
+  const overrides   = opts.overrides ?? {};
+  
+  let recursive;
+  if (typeof opts.recursive === N)
+  {
+    recursive = opts.recursive;
+  }
+  else if (typeof opts.recursive === B)
   {
-    throw new TypeError("source and target both need to be objects");
+    recursive = opts.recursive ? RECURSE_ALL : RECURSE_NONE;
+  }
+  else 
+  {
+    recursive = RECURSE_NONE;
   }
 
-  if (!isObj(propOpts))
-    propOpts = {default: true};
+  let recurseCache, recurseOpts;
+  if (recursive !== RECURSE_NONE)
+  {
+    recurseCache = opts.recurseCache ?? [];
+    recurseOpts  = opts.recurseOpts  ?? {};
+  }
 
-  const defOverrides = propOpts.overrides ?? {};
-  const defOverwrite = propOpts.overwrite ?? false;
+  let overwrites;
+  if (typeof opts.overwrite === F)
+  { // A custom function.
+    overwrites = opts.overwrite;
+  }
+  else if (isObj(opts.overwrite))
+  { // An object may be an array or a map.
+    if (isArray(opts.overwrite))
+    { // A flat array of properties to overwrite.
+      overwrites = prop => opts.overwrite.includes(prop);
+    }
+    else 
+    { // A map of properties to overwrite.
+      overwrites = prop => opts.overwrite[prop] ?? false;
+    }
+  }
+  else 
+  { // The only other values should be boolean.
+    overwrites = () => opts.overwrite ?? false;
+  }
 
-  const exclude = isArray(propOpts.exclude) ? propOpts.exclude : null;
+  const exclude = isArray(opts.exclude) ? opts.exclude : null;
 
   let propDefs;
 
-  if (propOpts.props && isArray(propOpts.props))
+  if (isArray(opts.props))
   {
-    propDefs = propOpts.props;
+    propDefs = opts.props;
   }
-  else if (propOpts.all)
+  else if (opts.all)
   {
     propDefs = Object.getOwnPropertyNames(source); 
   }
-  else if (propOpts.default)
+  else if (useDefaults)
   {
     propDefs = Object.keys(source);
   }
-  else if (propOpts.overrides)
+  else
   {
-    propDefs = Object.keys(propOpts.overrides);
+    propDefs = Object.keys(overrides);
   }
 
   if (!propDefs)
   {
-    console.error("Could not determine properties to copy", propOpts);
+    console.error("Could not determine properties to copy", opts);
     return;
   }
 
@@ -71,34 +158,57 @@ function copyProps(source, target, propOpts)
   {
     //console.debug(" @prop:", prop);
     if (exclude && exclude.indexOf(prop) !== -1)
-      continue; // Excluded property.
-
-    let overwrite = false;  
-    if (typeof defOverwrite === B)
-    {
-      overwrite = defOverwrite;
-    }
-    else if (isObj(defOverwrite) && typeof defOverwrite[prop] === B)
-    {
-      overwrite = defOverwrite[prop];
+    { // Excluded property.
+      continue;
     }
 
-    const def = Object.getOwnPropertyDescriptor(source, prop);
+    let desc = Object.getOwnPropertyDescriptor(source, prop);
     //console.debug(" @desc:", def);
-    if (def === undefined) continue; // Invalid property.
+    if (desc === undefined) 
+    { // A non-existent property.
+      continue; // Invalid property.
+    }
 
-    if (isObj(defOverrides[prop]))
-    {
-      for (const key in defOverrides[prop])
+    if (isObj(overrides[prop]))
+    { // Overriding descriptor properties.
+      desc = clone(desc);
+      for (const key in overrides[prop])
       {
-        const val = defOverrides[prop][key];
-        def[key] = val;
+        const val = overrides[prop][key];
+        desc[key] = val;
       }
     }
 
-    if (overwrite || target[prop] === undefined)
+    let overwrite = overwrites(prop);
+
+    if (recursive !== 0 
+      && (recursive !== RECURSE_LIST || isObj(recurseOpts[prop]))
+      && isObj(desc.value) 
+      && isObj(target[prop])
+      && !recurseCache.includes(desc.value) 
+      && !recurseCache.includes(target[prop]))
+    { // Recursive mode is enabled, so we're going to go deeper.
+      recurseCache.push(decs.value);
+      if (desc.value !== target[prop])
+      { // They're not the same literal object already.
+        recurseCache.push(target[prop]);
+        const ropts 
+          = isObj(recurseOpts[prop]) 
+          ? clone(recurseOpts[prop]) 
+          : {overwrite};
+        // Always set the cache.
+        ropts.recurseCache = recurseCache;
+        if (typeof ropts.recursive !== N)
+        { // Set the recursive option.
+          ropts.recursive = (recursive > 0) ? recursive - 1 : recursive;
+        }
+        // Okay, we're ready, let's recurse now!
+        copyProps(desc.value, target[prop], ropts);
+      }
+    }
+    else if (overwrite || target[prop] === undefined)
     { // Property doesn't already exist, let's add it.
-      defProp(target, prop, def);
+      def(target, prop, desc);
     }
   }
 
@@ -107,4 +217,159 @@ function copyProps(source, target, propOpts)
   return target;
 } // copyProps()
 
+def(copyProps, 'RECURSE_NONE', RECURSE_NONE);
+def(copyProps, 'RECURSE_ALL',  RECURSE_ALL);
+def(copyProps, 'RECURSE_LIST', RECURSE_LIST);
+
+/**
+ * A class providing a declarative `copyProps()` API,
+ * which makes it easy to copy one or more sources,
+ * into one or more targets.
+ * 
+ * This class is not directly accessible, and instead is available
+ * via some special sub-methods of `copyProps`; examples:
+ * 
+ * ```js
+ * // Get a copy of the `copyProps` function.
+ * const cp = require('@lumjs/core').obj.copyProps;
+ * 
+ * // Starting with the target:
+ * cp.into(targetObj).given({all: true}).from(source1, source2);
+ * 
+ * // Starting with the sources:
+ * cp.from(sourceObj).given({exclude: ['dontCopy']}).into(target1, target2);
+ * 
+ * // Starting with the options:
+ * cp.given({recursive: cp.RECURSE_ALL}).from(source1, source2).into(target1, target2);
+ * 
+ * 
+ * ```
+ * 
+ * @alias module:@lumjs/core/obj~CopyProps
+ */
+class $CopyProps
+{
+  constructor(opts={})
+  {
+    this.opts = opts;
+    this.sources = [];
+    this.targets = [];
+  }
+
+  /**
+   * Set a single option.
+   * @param {string} name - The option name
+   * @param {*} value - The option value
+   * @returns {object} `this`
+   */
+  set(name, value)
+  {
+    this.opts[name] = value;
+    return this;
+  }
+
+  /**
+   * Set all of the options.
+   * 
+   * This replaces the currently set options entirely.
+   * 
+   * @param {object} opts - The options to set.
+   * @returns {object} `this`
+   */
+  given(opts)
+  {
+    needObj(opts);
+    this.opts = opts;
+    return this;
+  }
+
+  /**
+   * Specify the `targets` to copy properties into.
+   * 
+   * @param {...object} [targets] The target objects
+   * 
+   * If `this.sources` has objects in it already,
+   * then we'll run `copyProps()` for each of the 
+   * sources into each of the `targets`.
+   * 
+   * If `this.sources` is empty, then this will set
+   * `this.target` to the specified value.
+   * 
+   * You can specify no sources at all to clear the 
+   * currently set `this.targets` value.
+   * 
+   * @returns {object} `this`
+   */
+  into(...targets)
+  {
+    if (this.sources.length > 0 && targets.length > 0)
+    {
+      this.$run(this.sources, targets);
+    }
+    else 
+    {
+      this.targets = targets;
+    }
+    return this;
+  }
+
+  /**
+   * Specify the `sources` to copy properties from.
+   * 
+   * @param  {...object} [sources] The source objects.
+   * 
+   * If `this.targets` has objects in it already, 
+   * then we'll run `copyProps()` for each of the 
+   * `sources` into each of the targets.
+   * 
+   * If `this.targets` is empty, then this will set
+   * `this.sources` to the specified value.
+   * 
+   * You can specify no sources at all to clear the 
+   * currently set `this.sources` value.
+   * 
+   * @returns {object} `this`
+   */
+  from(...sources)
+  {
+    if (this.targets.length > 0 && sources.length > 0)
+    {
+      this.$run(sources, this.targets);
+    }
+    else 
+    {
+      this.sources = sources;
+    }
+    return this;
+  }
+
+  // Protected method doesn't need to be documented.
+  $run(sources, targets)
+  {
+    for (const source of sources)
+    {
+      for (const target of targets)
+      {
+        copyProps(source, target, this.opts);
+      }
+    }
+  }
+
+}
+
+copyProps.given = function(opts)
+{
+  return new $CopyProps(opts);
+}
+
+copyProps.into = function(...targets)
+{
+  return ((new $CopyProps()).into(...targets));
+}
+
+copyProps.from = function(...sources)
+{
+  return ((new $CopyProps()).from(...sources));
+}
+
 module.exports = copyProps;

package/lib/obj/index.js

@@ -3,7 +3,7 @@
  * @module @lumjs/core/obj
  */
 
-const copyAll = require('./copyall');
+const {copyAll,duplicateOne,duplicateAll} = require('./copyall');
 const copyProps = require('./copyprops');
 const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
 const {lock,addLock} = require('./lock');
@@ -21,5 +21,5 @@ module.exports =
   CLONE, clone, addClone, cloneIfLocked, lock, addLock,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
-  getProperty,
+  getProperty, duplicateAll, duplicateOne,
 }

package/lib/obj/merge.js

@@ -1,48 +1,56 @@
 // Import required bits here.
-const {B, isObj} = require('../types');
+const {B, N, isObj} = require('../types');
+const copyProps = require('./copyprops');
+
+// A shortcut for the recursive option.
+const recursive = copyProps.RECURSE_ALL;
 
 /**
  * Merge two objects recursively.
  *
- * This is currently suseptible to circular reference infinite loops,
- * but given what it's designed for, I'm not too worried about that.
+ * This used to be a standalone function, but was poorly designed. 
+ * It's now a wrapper around the
+ * [copyProps()]{@link module:@lumjs/core/obj.copyProps} method.
  *
  * @param {object} source - The source object we're copying from.
  * @param {object} target - The target object we're copying into.
  *
- * @param {object} [opts] Options that change the behaviour.
- * @param {boolean} [opts.overwrite=true] Allow overwriting.
- *   Unlike `copy` which does not allow overwriting by default,
- *   this method does. It's not designed for the same kind of objects
- *   as `copy`, but more for JSON structured configuration files.
- *
- *   As this is currently the only option, passing the boolean
- *   as the `opts` argument directly will set this option.
+ * @param {(object|boolean)} [opts] Options for `copyProps()`
+ * 
+ * If `opts.recursive` is not a `number`, it'll be set to
+ * `copyProps.RECURSE_ALL` to enable recursion with no
+ * depth limits.
+ * 
+ * Also, if `opts.overwrite` is not explicitly set, it will
+ * be set as `true`, a different default value than `copyProps()`.
+ * 
+ * For backwards compatibility, if this specified as a `boolean`
+ * value instead of an object, it'll be assumed to be value 
+ * for the `opts.overwrite` option.
  *
  * @returns {object} The `target` object.
  * @alias module:@lumjs/core/obj.mergeNested
  */
- function mergeNested(source, target, opts={})
- {
-   if (typeof opts === B) 
-     opts = {overwrite: opts};
- 
-   const overwrite = opts.overwrite ?? true;
- 
-   for (const prop in source)
-   {
-     if (isObj(source[prop]) && isObj(to[prop]))
-     { // Nested objects, recurse deeper.
-       mergeNested(source[prop], target[prop], opts);
-     }
-     else if (overwrite || target[prop] === undefined)
-     { // Not tested objects, do a simple assignment.
-       target[prop] = source[prop];
-     }
-   }
- 
-   return target;
- }
+function mergeNested(source, target, opts={})
+{
+  if (typeof opts === B) 
+  { // Boolean overwrite option was specified.
+    opts = {overwrite: opts, recursive};
+  }
+  else if (!isObj(opts))
+  { // Wasn't an object, use default values.
+    opts = {overwrite: true, recursive};
+  }
+  else
+  { // If recursive or overwrite aren't set, set them.
+    if (opts.recursive === undefined)
+      opts.recursive = recursive;
+    if (opts.overwrite === undefined)
+      opts.overwrite = true;
+  }
+  
+  return copyProps(source, target, opts);
+}
 
  exports.mergeNested = mergeNested;
  

package/lib/types/def.js

@@ -2,10 +2,7 @@
 const unbound = require('./root').unbound;
 const {F, B} = require('./js');
 const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
-const copy = require('../obj/copyall');
-
-// A really really cheap version of clone().
-const clone = obj => copy({}, obj);
+const {copy, duplicateOne: clone} = require('../obj/copyall');
 
 /**
  * A wrapper around `Object.defineProperty()`.

package/lib/types/isa.js

@@ -10,177 +10,174 @@ const TYPES = require('./typelist');
  * @returns {boolean}
  * @alias module:@lumjs/core/types.isInstance
  */
- function isInstance(v, f, needProto=false) 
- {
-   if (!isObj(v)) return false; // Not an object.
-   if (needProto && (typeof v.prototype !== O || v.prototype === null))
-   { // Has no prototype.
-     return false;
-   }
- 
-   if (typeof f !== F || !(v instanceof f)) return false;
- 
-   // Everything passed.
-   return true;
- }
- 
- exports.isInstance = isInstance;
-
- /**
-  * A smarter `typeof` function.
-  * 
-  * @param {string} type - The type we're checking for.
-  * 
-  * This supports all the same type names as `typeof` plus any of
-  * the properties defined in the `TYPES` object.
-  * 
-  * One other thing, while `typeof` reports `null` as being an `object`,
-  * this function does not count `null` as a valid `object`. 
-  * 
-  * @param {*} v - The value we're testing. 
-  * @returns {boolean} If the value was of the desired type.
-  * @alias module:@lumjs/core/types.isType
-  */
- function isType(type, v)
- {
-   if (typeof type !== S || !TYPES.list.includes(type))
-   {
-     throw new TypeError(`Invalid type ${JSON.stringify(type)} specified`);
-   }
- 
-   if (typeof TYPES.tests[type] === F)
-   { // A type-specific test.
-     return TYPES.tests[type](v);
-   }
-   else 
-   { // No type-specific tests.
-     return (typeof v === type);
-   }
- }
- 
- exports.isType = isType;
-
- // Default options parser.
- const DEFAULT_ISA_PARSER = function(type, v)
- { // `this` is the options object itself.
-   if (typeof type.is === F)
-   { // We assume `is()` methods are the type check.
-     if (type.is(v)) return true;
-   }
- 
-   if (typeof type.isa === O)
-   { // Process our known options.
-     const opts = type.isa;
- 
-     if (typeof opts.process === F)
-     { // We'll pass the current `opts` as well as the `v` to this method.
-       // It doesn't return anything on its own, but can assign further tests,
-       // which by default only apply to `object` 
-       opts.process(this, v);
-     }
- 
-     if (typeof opts.parsers === F)
-     { // Assign another parser.
-       this.parsers.push(opts.parsers);
-     }
- 
-     if (typeof opts.test === F)
-     { // A custom test, will be passed `v` and the current `opts`.
-       if (opts.test(v, this))
-       { // Mark this as having passed.
-         return true;
-       }
-     }
- 
-     // Okay, now anything else gets set.
-     const RESERVED = ['parsers','process','test'];
-     for (const opt in opts)
-     {
-       if (RESERVED.includes(opt)) continue; // Skip it.
-       this[opt] = opts[opt];
-     }
- 
-   }
- 
-   // We should almost always return false.
-   return false;
- }
- 
- /**
-  * Is value a certain type, or an instance of a certain class.
-  * 
-  * @param {*} v - The value we're testing.
-  * @param {...any} types - The types the value should be one of.
-  * 
-  * For each of the `types`, if it is a `string` we test with `isType()`,
-  * if it is a `function` we test with `isInstance()`. 
-  * 
-  * If it is an `object` and has an `is()` method, use that as the test.
-  * 
-  * If it is an `object` it will be passed to the current options parsers.
-  * The default options parser looks for an `object` property called `isa`,
-  * which supports the following child properties:
-  * 
-  *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
-  *  - `parsers: function`, Add another options parser function.
-  *  - `process: function`, A one-time set-up function.
-  *  - `test: function`, Pass the `v` to this test and return `true` if it passes.
-  *  - Anything else will be set as an option.
-  * 
-  * Any other type value will only match if `v === type`
-  * 
-  * @returns {boolean} Was the value one of the desired types?
-  * @alias module:@lumjs/core/types.isa
-  */
- function isa(v, ...types)
- {
-   // A special options object.
-   const opts =
-   {
-     needProto: false,
-     parsers:
-     [
-       DEFAULT_ISA_PARSER,
-     ],
-     process(type, v)
-     {
-       for (const parser of this.parsers)
-       {
-         if (typeof parser === F)
-         {
-           if (parser.call(this, type, v) === true)
-           { // Returning true means a custom test passed.
-             return true;
-           }
-         }
-       }
-       return false;
-     },
-   }
- 
-   for (const type of types)
-   {
-     // First a quick test for absolute equality.
-     if (v === type) return true;
- 
-     // With that out of the way, let's go!
-     if (typeof type === S)
-     { // A string is passed to isType()
-       if (isType(type, v)) return true;
-     }
-     else if (typeof type === F)
-     { // A function is passed to isInstance()
-       if (isInstance(v, type, opts.needProto)) return true;     
-     }
-     else if (isObj(type))
-     { // Objects can be additional tests, or options.
-       if (opts.process(type, v)) return true;
-     }
- 
-   }
+function isInstance(v, f, needProto=false) 
+{
+  if (!isObj(v)) return false; // Not an object.
+  if (needProto && (typeof v.prototype !== O || v.prototype === null))
+  { // Has no prototype.
+    return false;
+  }
+
+  if (typeof f !== F || !(v instanceof f)) return false;
+
+  // Everything passed.
+  return true;
+}
  
-   // None of the tests passed. We have failed.
-   return false;
- }
+exports.isInstance = isInstance;
+
+/**
+ * A smarter `typeof` function.
+ * 
+ * @param {string} type - The type we're checking for.
+ * 
+ * This supports all the same type names as `typeof` plus any of
+ * the properties defined in the `TYPES` object.
+ * 
+ * One other thing, while `typeof` reports `null` as being an `object`,
+ * this function does not count `null` as a valid `object`. 
+ * 
+ * @param {*} v - The value we're testing. 
+ * @returns {boolean} If the value was of the desired type.
+ * @alias module:@lumjs/core/types.isType
+ */
+function isType(type, v)
+{
+  if (typeof type !== S || !TYPES.list.includes(type))
+  {
+    throw new TypeError(`Invalid type ${JSON.stringify(type)} specified`);
+  }
+
+  if (typeof TYPES.tests[type] === F)
+  { // A type-specific test.
+    return TYPES.tests[type](v);
+  }
+  else 
+  { // No type-specific tests.
+    return (typeof v === type);
+  }
+}
+ 
+exports.isType = isType;
+
+// Default options parser.
+const DEFAULT_ISA_PARSER = function(type, v)
+{ // `this` is the options object itself.
+  if (typeof type.is === F)
+  { // We assume `is()` methods are the type check.
+    if (type.is(v)) return true;
+  }
+
+  if (typeof type.isa === O)
+  { // Process our known options.
+    const opts = type.isa;
+
+    if (typeof opts.process === F)
+    { // Run a method to extend the options further.
+      opts.process(this, v, type);
+    }
+
+    if (typeof opts.parsers === F)
+    { // Assign another parser.
+      this.parsers.push(opts.parsers);
+    }
+
+    if (typeof opts.test === F)
+    { // A custom test, will be passed `v` and the current `opts`.
+      if (opts.test(v, this))
+      { // Mark this as having passed.
+        return true;
+      }
+    }
+
+    // Okay, now anything else gets set.
+    const RESERVED = ['parsers','process','test'];
+    for (const opt in opts)
+    {
+      if (RESERVED.includes(opt)) continue; // Skip it.
+      this[opt] = opts[opt];
+    }
+
+  }
+
+  // We should almost always return false.
+  return false;
+}
+
+// Process further options
+function processOptions(type, v)
+{
+  for (const parser of this.parsers)
+  {
+    if (typeof parser === F)
+    {
+      if (parser.call(this, type, v) === true)
+      { // Returning true means a custom test passed.
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Is value a certain type, or an instance of a certain class.
+ * 
+ * @param {*} v - The value we're testing.
+ * @param {...any} types - The types the value should be one of.
+ * 
+ * For each of the `types`, if it is a `string` we test with `isType()`,
+ * if it is a `function` we test with `isInstance()`. 
+ * 
+ * If it is an `object` and has an `is()` method, use that as the test.
+ * 
+ * If it is an `object` it will be passed to the current options parsers.
+ * The default options parser looks for an `object` property called `isa`,
+ * which supports the following child properties:
+ * 
+ *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
+ *  - `parsers: function`, Add another options parser function.
+ *  - `process: function`, A one-time set-up function.
+ *  - `test: function`, Pass the `v` to this test and return `true` if it passes.
+ *  - Anything else will be set as an option.
+ * 
+ * Any other type value will only match if `v === type`
+ * 
+ * @returns {boolean} Was the value one of the desired types?
+ * @alias module:@lumjs/core/types.isa
+ */
+function isa(v, ...types)
+{
+  // A special options object.
+  const opts =
+  {
+    needProto: false,
+    parsers: [DEFAULT_ISA_PARSER],
+    process: processOptions,
+  }
+
+  for (const type of types)
+  {
+    // First a quick test for absolute equality.
+    if (v === type) return true;
+
+    // With that out of the way, let's go!
+    if (typeof type === S)
+    { // A string is passed to isType()
+      if (isType(type, v)) return true;
+    }
+    else if (typeof type === F)
+    { // A function is passed to isInstance()
+      if (isInstance(v, type, opts.needProto)) return true;     
+    }
+    else if (isObj(type))
+    { // Objects can be additional tests, or options.
+      if (opts.process(type, v)) return true;
+    }
+  }
+
+  // None of the tests passed. We have failed.
+  return false;
+}
 
- exports.isa = isa;
+exports.isa = isa;

package/lib/types/needs.js

@@ -6,23 +6,42 @@ const {isObj, isComplex} = require('./basics');
  * If a value is not an object, throw an error.
  * 
  * @param {*} v - The value we're testing.
- * @param {boolean} [allowFunc=false] - Also accept functions?
+ * @param {(boolean|string)} [allowFunc=false] - Also accept `function`?
+ * 
+ * By default this function uses `isObj()` to perform the
+ * test. If `allowFunc` is `true` then it'll use `isComplex()` instead.
+ * 
+ * If this is a `string` then it'll be assigned to the `msg`
+ * parameter, and `allowFunc` will be `true` if the word
+ * `function` is found in the message, or `false` otherwise.
+ * 
  * @param {string} [msg] A custom error message.
+ * 
+ * If not specified, a generic one will be used.
+ * 
  * @throws {TypeError} If the type check failed.
  * @alias module:@lumjs/core/types.needObj
  */
 function needObj (v, allowFunc=false, msg=null)
 {
-  if (allowFunc && isComplex(v)) return;
-  if (isObj(v)) return;
+  if (typeof allowFunc === S)
+  { // A message was passed.
+    msg = allowFunc;
+    allowFunc = msg.toLowerCase().includes(F);
+  }
 
-  if (typeof msg !== S)
-  { // Use a default message.
-    msg = "Invalid object";
-    if (allowFunc)
-      msg += " or function";
+  const ok = allowFunc ? isComplex(v) : isObj(v);
+
+  if (!ok)
+  { // Did not pass the test.
+    if (typeof msg !== S)
+    { // Use a default message.
+      msg = "Invalid object";
+      if (allowFunc)
+        msg += " or function";
+    }
+    throw new TypeError(msg);
   }
-  throw new TypeError(msg);
 }
 
 exports.needObj = needObj;
@@ -101,6 +120,7 @@ function needs(v, ...types)
     {
       error = new TypeError("value did not pass needs check");
     }
+    console.error("needs()", v, types);
     throw error;
   }
 }

package/package.json

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