@lumjs/core 1.2.1 → 1.3.0

package/docs/changelogs/1.x.md

@@ -6,6 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2022-09-11
+### Changed
+- Overhauled the `obj.clone()` method.
+- Added *named options* for all of the behaviours that the `CLONE` *modes* affect.
+  While this technically could make the *modes* obsolete, I'm leaving them in as
+  simple sets of default options that can be used instead of manually choosing all
+  of the individual options.
+- Added a new `CLONE.N` *mode* which has **no** options turned on.
+  It will always remain first in the *enum* list so it's value will always be `0`.
+- Added the ability to clone properties using their descriptors.
+  It is enabled by default on most of the *modes* now, as it simply makes sense.
+- Added the ability to set the `prototype` on the cloned object.
+- The `opts` parameter of `clone()` may be a `CLONE.*` enum value.
+  It's a shortcut for `{mode: CLONE.MODE}` for convenience.
+- A small tweak to `obj.copyProps()`, not important, just a cleanup.
+### Fixed
+- A reference in the DocBlock for `obj.getProperty()`.
+
 ## [1.2.1] - 2022-09-05
 ### Added
 - `core.InternalObjectId#untag()`
@@ -46,7 +64,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - See [1.0-beta.md](1.0-beta.md) for the beta versions of `1.0`
 - See [lum.js](https://github.com/supernovus/lum.js) for the original library this is replacing.
 
-[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/supernovus/lum.core.js/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/supernovus/lum.core.js/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/supernovus/lum.core.js/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/supernovus/lum.core.js/compare/v1.1.0...v1.1.1

package/lib/obj/clone.js

@@ -1,27 +1,38 @@
 // Import *most* required bits here.
-const {B,N,F, isObj, isComplex, def} = require('../types');
+const {B,N,F, isObj, isComplex, def, isArray} = require('../types');
 const Enum = require('../enum');
 const copyProps = require('./copyprops');
+const getProp = require('./getproperty');
 
 /**
- * An enum of supported modes for the `clone` method.
+ * An `enum` of supported *modes* for the `clone()` method.
  * 
- * - **P** = All properties. If unchecked, enumerable properties only.
- * - **A** = Uses `Array.slice()` shortcut for shallow Array cloning.
- * - **R** = Recursive (deep) cloning of nested objects.
+ * - **P** → All properties. If unchecked, *enumerable* properties only.
+ * - **A** → Uses `Array.slice()` shortcut for shallow `Array` cloning.
+ * - **R** → Recursive (deep) cloning of nested objects.
+ * - **D** → Uses *descriptor* cloning instead of direct assignment.
+ * - **T** → Sets the `prototype` of the clone as well. 
  * 
- * | Mode | P | A | R | Notes |
- * | ---- | - | - | - | ----- |
- * | `CLONE.DEF` | × | ✓ | × | Default mode for cloning functions. |
- * | `CLONE.DEEP` | × | × | ✓ | |
- * | `CLONE.FULL` | ✓ | ✓ | × | |
- * | `CLONE.ALL` | ✓ | × | × | |
- * | `CLONE.ENTIRE` | ✓ | × | ✓ | |
- * | `CLONE.JSON` | × | × | ✓ | Uses JSON, so no `function` or `symbol` support. |
+ * | Mode | P | A | R | D | T | Notes |
+ * | ---- | - | - | - | - | - | ----- |
+ * | `CLONE.N` | × | × | × | × | × | Can be used to manually specify options. |
+ * | `CLONE.DEF` | × | ✓ | × | × | × | Default mode for cloning functions. |
+ * | `CLONE.DEEP` | × | × | ✓ | ✓ | × | |
+ * | `CLONE.FULL` | ✓ | ✓ | × | ✓ | × | |
+ * | `CLONE.ALL` | ✓ | × | × | ✓ | × | |
+ * | `CLONE.ENTIRE` | ✓ | × | ✓ | ✓ | ✓ | |
+ * | `CLONE.JSON` | - | - | ✓ | - | × | Uses JSON, so no `function` or `symbol` support. |
+ * 
+ * The `✓` and `×` marks signify the *default settings* in the mode.
+ * In *most* cases there are options that can override the
+ * defaults.
+ * 
+ * Any feature in the `CLONE.JSON` row marked with `-` are
+ * incompatible with that mode and cannot be enabled at all.
  * 
  * @alias module:@lumjs/core/obj.CLONE
  */
- const CLONE = Enum(['DEF','FULL','ALL','DEEP','ENTIRE','JSON']);
+ const CLONE = Enum(['N','DEF','FULL','ALL','DEEP','ENTIRE','JSON']);
 
  exports.CLONE = CLONE;
 
@@ -29,7 +40,7 @@ const copyProps = require('./copyprops');
  const SLICE_ARRAYS = [CLONE.DEF, CLONE.FULL];
 
  // A list of modes that should get *all* properties.
- const ALL_PROPS = [CLONE.FULL, CLONE.ALL, CLONE.DEEP];
+ const ALL_PROPS = [CLONE.FULL, CLONE.ALL, CLONE.ENTIRE];
 
  // A list of modes that should do recursive cloning of objects.
  const RECURSIVE = [CLONE.DEEP, CLONE.ENTIRE];
@@ -37,28 +48,103 @@ const copyProps = require('./copyprops');
  /**
   * Clone an object or function.
   *
-  * @param {object|function} obj - The object we want to clone.
-  * @param {object} [opts={}] - Options for the cloning process.
+  * @param {object} obj - The object we want to clone.
+  * 
+  * @param {(object|number)} [opts={}] Options for the cloning process.
+  * 
+  *   If this is a `number` then it's assumed to be the `opts.mode` parameter.
+  * 
+  * @param {number} [opts.mode=CLONE.DEF] One of the `CLONE.*` enum values.
+  * 
+  *   When the `clone()` method was written to replace some similar methods
+  *   from earlier libraries, I for some reason decided to simply have a bunch
+  *   of different cloning modes. I have since added a full set of options that
+  *   allows overriding the options of any mode (except `CLONE.JSON`).
   * 
-  * @param {number} [opts.mode=CLONE.DEF] - One of the `CLONE.*` enum values.
+  *   The `CLONE` enum is also aliased as `clone.MODE` as an alternative.
   * 
-  *   Note: The `CLONE` enum is also aliased as `clone.MODE` as an alternative.
+  * @param {boolean} [opts.all] Clone **all** of the object's properties?
+  * 
+  *   If `false` only *enumerable* properties will be cloned.
+  * 
+  *   The default value depends on the `opts.mode` used.
+  * 
+  *   This is not used if `opts.mode` was `CLONE.JSON`.
   *
-  * @param {boolean} [opts.addClone=false] - Call `addClone()` on the cloned object.
+  * @param {boolean} [opts.slice] Use the `Array.slice()` shortcut?
+  * 
+  *   If `true` then when cloning `Array` objects, a shallow clone will be
+  *   created using the `Array.slice()` method.
+  * 
+  *   The default value depends on the `opts.mode` used.
+  * 
+  *   This is not used if `opts.mode` was `CLONE.JSON`.
+  * 
+  * @param {boolean} [opts.recursive] Clone nested objects recursively?
+  * 
+  *   The default value depends on the `opts.mode` used.
+  *   If `opts.slice` is also `true` then `Array` objects will
+  *   be *shallow clones* while any other kind of object will be recursive.
+  * 
+  *   This is not used if `opts.mode` was `CLONE.JSON`.
+  * 
+  * @param {boolean} [opts.descriptors] Clone using the property descriptors?
+  * 
+  *   If `true` we will get the property descriptors from the original object,
+  *   and assign them to the clone.
+  *   This is the only way to clone *accessor* type properties properly.
+  * 
+  *   If `false` we will directly assign the *property value* from the original
+  *   object into the clone. This means the *current value* returned from an
+  *   *accessor* type property will be assigned statically to the clone.
+  * 
+  *   The default value will be `true` if `opts.all` **OR** `opts.recursive`
+  *   are `true`. It will be `false` otherwise.
+  * 
+  *   This is not used if `opts.mode` was `CLONE.JSON`.
+  * 
+  * @param {boolean} [opts.prototype] Set the clone's `prototype`?
+  * 
+  *   If `true`, once the cloning is complete, we will call
+  *   `Object.getPrototypeOf()` on the original `obj`, and then call
+  *   `Object.setProrotypeOf()` on the clone.
+  *  
+  *   If `false` then the clone with have a prototype of `Object` or
+  *   `Array` depending on whether the original object was an `Array`
+  *   or not. No further prototype handling will be done.
+  * 
+  *   The default value will be `true` if `opts.all` **AND** `opts.recursive`
+  *   are *both* `true`. Otherwise the default value is `false`.
+  *   So for *modes*, only `CLONE.ENTIRE` uses this by default.
+  * 
+  * @param {(object|boolean)} [opts.addClone=false] 
+  *   Call `addClone()` on the cloned object.
   *
-  *   The options sent to this function will be used as the defaults in
-  *   the `clone()` method added to the object.
+  *   If `opts.addClone` is an `object` then it will be used as the options
+  *   passed to the `addClone()` method. If it is `true` then the `opts`
+  *   will be passed as is.
   *
-  * @param {boolean} [opts.addLock=false] - Call `addLock()` on the cloned object.
+  * @param {(object|boolean)} [opts.addLock=false] 
+  *   Call `addLock()` on the cloned object.
   *
-  *   No further options for this, just add a `lock()` method to the clone.
+  *   If `opts.addLock` is an `object` then it will be used as the options
+  *   passed to the `addLock()` method. If it is `true` then the `opts`
+  *   will be passed as is.
   *
-  * @param {?object} [opts.copy] Call `copyProps()` on the cloned object.
+  * @param {(object|boolean)} [opts.copy=false] 
+  *   Call `copyProps()` on the cloned object.
   *
-  *   Will pass the original `obj` as the source to copy from.
-  *   Will pass `opts.copy` as the options.
+  *   This is called *after* the normal cloning process, so only properties
+  *   that weren't copied during the cloning process will be copied here.
+  *   This is a leftover from when `CLONE.JSON` was the default cloning mode,
+  *   and this was the only way to restore `function` properties.
+  * 
+  *   If `opts.copy` is an `object` then it will be used as the options
+  *   passed to the `copyProps()` method. If it is `true` then the `opts`
+  *   will be passed as is.
   *
-  * @return {object} - The clone of the object.
+  * @return {object} The clone of the object.
+  * 
   * @alias module:@lumjs/core/obj.clone
   */
 function clone(obj, opts={}) 
@@ -71,14 +157,38 @@ function clone(obj, opts={})
     return obj;
   }
 
-  if (!isObj(opts))
+  if (typeof opts === N)
+  { // The 'mode' option.
+    opts = {mode: opts};
+  }
+  else if (!isObj(opts))
   { // Opts has to be a valid object.
     opts = {};
   }
 
-  const mode    = typeof opts.mode      === N ? opts.mode      : CLONE.DEF;
-  const reclone = typeof opts.addClone  === B ? opts.addClone  : false;
-  const relock  = typeof opts.addLock   === B ? opts.addLock   : false;
+  // The mode is the base option.
+  const mode = typeof opts.mode === N ? opts.mode : CLONE.DEF;
+
+  // Options with defaults based on the mode.
+  const allProps  = opts.all       ?? ALL_PROPS.includes(mode);
+  const useSlice  = opts.slice     ?? SLICE_ARRAYS.includes(mode);
+  const recursive = opts.recursive ?? RECURSIVE.includes(mode);
+
+  // Some that depend on the values of the above options.
+  const descriptors = opts.descriptors ?? (allProps || recursive);
+  const withProto   = opts.prototype   ?? (allProps && recursive);
+
+  // Finally, a few that can be boolean or objects.
+  const subOpts = opt => 
+  {
+    if (isObj(opts[opt]))
+      return opts[opt];
+    else if (opts[opt] === true)
+      return opts;
+  }
+  const reclone = subOpts('addClone');
+  const relock  = subOpts('addLock');
+  const cpProps = subOpts('copy');
 
   let copy;
 
@@ -89,7 +199,7 @@ function clone(obj, opts={})
     //console.debug("::clone using JSON cloning");
     copy = JSON.parse(JSON.stringify(obj));
   }
-  else if (Array.isArray(obj) && SLICE_ARRAYS.includes(mode))
+  else if (Array.isArray(obj) && useSlice)
   { // Make a shallow copy using slice.
     //console.debug("::clone using Array.slice()");
     copy = obj.slice();
@@ -97,10 +207,10 @@ function clone(obj, opts={})
   else
   { // Build a clone using a simple loop.
     //console.debug("::clone using simple loop");
-    copy = {};
+    copy = isArray(obj) ? [] : {};
 
     let props;
-    if (ALL_PROPS.includes(mode))
+    if (allProps)
     { // All object properties.
       //console.debug("::clone getting all properties");
       props = Object.getOwnPropertyNames(obj);
@@ -112,31 +222,74 @@ function clone(obj, opts={})
     }
 
     //console.debug("::clone[props]", props);
+
+    let recOpts;
+    if (recursive)
+    { // Recursive opts; skips addClone, addLock, and copy.
+      recOpts =
+      {
+        mode, recursive, descriptors,
+        all: allProps,
+        slice: useSlice,
+        prototype: withProto,
+      }
+    }
     
     for (const prop of props)
     {
-      let val = obj[prop];
-      if (isObj(val) && RECURSIVE.includes(mode))
-      { // Deep cloning.
-        val = clone(val, {mode});
+      if (descriptors)
+      { // Use descriptor assignment.
+        const objDesc = getProp(obj, prop);
+        if (isObj(objDesc))
+        { // Make a fast, shallow clone of the descriptor.
+          const cloneDesc = clone(objDesc);
+          if (isObj(objDesc.value) && recursive)
+          { // Recursively clone the value.
+            cloneDesc.value = clone(objDesc.value, recOpts);
+          }
+          def(copy, prop, cloneDesc);
+        }
+        else 
+        {
+          console.error("getProperty failed", {obj, prop, props, opts});
+        }
       }
-      copy[prop] = val;
+      else 
+      { // Use direct assignment.
+        let val = obj[prop];
+        if (isObj(val) && recursive)
+        { // Deep cloning.
+          val = clone(val, recOpts);
+        }
+        copy[prop] = val;
+      }
+    } // for prop
+
+  } // simple loop cloning algorithm
+
+  if (withProto)
+  { // Copy the prototype if it is different.
+    const objProto = Object.getPrototypeOf(obj);
+    const copyProto = Object.getPrototypeOf(copy);
+    if (objProto && objProto !== copyProto)
+    { // Update the clone's prototype to match the original.
+      Object.setPrototypeOf(copy, objProto);
     }
   }
 
-  if (reclone)
+  if (isObj(reclone))
   { // Add the clone() method to the clone, with the passed opts as defaults.
-    addClone(copy, opts);
+    addClone(copy, reclone);
   }
 
-  if (opts.copy)
-  { // Pass the clone through the copyProps() function as well.
-    copyProps(obj, copy, opts.copy);
+  if (isObj(relock))
+  { // Add the lock() method to the clone.
+    addLock(copy, relock);
   }
 
-  if (relock)
-  { // Add the lock() method to the clone.
-    addLock(copy, opts);
+  if (isObj(cpProps))
+  { // Pass the clone through the copyProps() function as well.
+    copyProps(obj, copy, cpProps);
   }
 
   return copy;

package/lib/obj/copyprops.js

@@ -27,6 +27,7 @@ const {B,isObj,isComplex,isArray,def: defProp} = require('../types');
  */
 function copyProps(source, target, propOpts)
 {
+  //console.debug("copyProps", source, target, propOpts);
   if (!isComplex(source) || !isComplex(target))
   {
     throw new TypeError("source and target both need to be objects");
@@ -66,9 +67,9 @@ function copyProps(source, target, propOpts)
   }
 
   // For each propDef found, add it to the target.
-  for (let p = 0; p < propDefs.length; p++)
+  for (const prop of propDefs)
   {
-    const prop = propDefs[p];
+    //console.debug(" @prop:", prop);
     if (exclude && exclude.indexOf(prop) !== -1)
       continue; // Excluded property.
 
@@ -82,7 +83,8 @@ function copyProps(source, target, propOpts)
       overwrite = defOverwrite[prop];
     }
 
-    const def = Object.getOwnPropertyDescriptor(source, prop)
+    const def = Object.getOwnPropertyDescriptor(source, prop);
+    //console.debug(" @desc:", def);
     if (def === undefined) continue; // Invalid property.
 
     if (isObj(defOverrides[prop]))
@@ -93,12 +95,15 @@ function copyProps(source, target, propOpts)
         def[key] = val;
       }
     }
+
     if (overwrite || target[prop] === undefined)
     { // Property doesn't already exist, let's add it.
       defProp(target, prop, def);
     }
   }
 
+  //console.debug("copyProps:done", target);
+
   return target;
 } // copyProps()
 

package/lib/obj/getproperty.js

@@ -12,7 +12,8 @@ const {isComplex,isObj} = types;
  * @param {string} prop - Name of the property we want the descriptor of.
  * @param {mixed} [defval] The fallback value if no descriptor is found.  
  * 
- * @returns {mixed} - The descriptor if found, `defval` if not.
+ * @returns {mixed} The descriptor if found, `defval` if not.
+ * @alias module:@lumjs/core/obj.getProperty
  */
 function getProperty(obj, prop, defval)
 {

package/package.json

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