@lumjs/core 1.0.0-beta.2 → 1.0.0-beta.4

package/lib/obj/clone.js

@@ -1,21 +1,37 @@
 // Import *most* required bits here.
 const {B,N,F, isObj, isComplex, def} = require('../types');
 const Enum = require('../enum');
-const {getDescriptor, DESC} = require('../descriptors');
 const copyProps = require('./copyprops');
 
 /**
  * An enum of supported modes for the `clone` method.
  * 
- * `CLONE.DEFAULT` → Shallow clone of enumerable properties for most objects.
- * `CLONE.JSON`    → Deep clone using JSON serialization (Arrays included.)
- * `CLONE.FULL`    → Shallow clone of all object properties.
- * `CLONE.ALL`     → Shallow clone of all properties (Arrays included.)
+ * - **P** = All properties. If unchecked, enumerable properties only.
+ * - **A** = Uses `Array.slice()` shortcut for shallow Array cloning.
+ * - **R** = Recursive (deep) cloning of nested objects.
+ * 
+ * | 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. |
  * 
  */
- const CLONE = Enum(['DEF','JSON','FULL','ALL']);
+ const CLONE = Enum(['DEF','FULL','ALL','DEEP','ENTIRE','JSON']);
 
  exports.CLONE = CLONE;
+
+ // A list of modes that should use the array.slice shallow shortcut.
+ 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];
+
+ // A list of modes that should do recursive cloning of objects.
+ const RECURSIVE = [CLONE.DEEP, CLONE.ENTIRE];
  
  /**
   * Clone an object or function.
@@ -23,10 +39,7 @@ const copyProps = require('./copyprops');
   * @param {object|function} obj - The object we want to clone.
   * @param {object} [opts={}] - Options for the cloning process.
   * 
-  * @param {number} [opts.mode=MODE_DEFAULT] - One of the `CLONE.*` enum values.
-  *
-  *   For any mode that doesn't saay "Arrays included", Array objects will
-  *   use a shortcut technique of `obj.slice()` to create the clone.
+  * @param {number} [opts.mode=CLONE.DEF] - One of the `CLONE.*` enum values.
   * 
   *   Note: The `CLONE` enum is also aliased as `clone.MODE` as an alternative.
   *
@@ -46,88 +59,92 @@ const copyProps = require('./copyprops');
   *
   * @return {object} - The clone of the object.
   */
- function clone(obj, opts={}) 
- {
-   //console.debug("Lum~clone()", obj, opts);
- 
-   if (!isComplex(obj))
-   { // Doesn't need cloning.
-     //console.debug("no cloning required");
-     return obj;
-   }
- 
-   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;
- 
-   let copy;
- 
-   //console.debug("::clone", {mode, reclone, relock});
- 
-   if (mode === CLONE.JSON)
-   { // Deep clone enumerable properties using JSON trickery.
-     //console.debug("::clone using JSON cloning");
-     copy = JSON.parse(JSON.stringify(obj));
-   }
-   else if (mode !== CLONE.ALL && Array.isArray(obj))
-   { // Make a shallow copy using slice.
-     //console.debug("::clone using Array.slice()");
-     copy = obj.slice();
-   }
-   else
-   { // Build a clone using a simple loop.
-     //console.debug("::clone using simple loop");
-     copy = {};
- 
-     let props;
-     if (mode === CLONE.ALL || mode === CLONE.FULL)
-     { // All object properties.
-       //console.debug("::clone getting all properties");
-       props = Object.getOwnPropertyNames(obj);
-     }
-     else
-     { // Enumerable properties.
-       //console.debug("::clone getting enumerable properties");
-       props = Object.keys(obj);
-     }
- 
-     //console.debug("::clone[props]", props);
- 
-     for (let p = 0; p < props.length; p++)
-     {
-       let prop = props[p];
-       copy[prop] = obj[prop];
-     }
-   }
- 
-   if (reclone)
-   { // Add the clone() method to the clone, with the passed opts as defaults.
-     addClone(copy, opts);
-   }
- 
-   if (opts.copy)
-   { // Pass the clone through the copyProps() function as well.
-     copyProps(obj, copy, opts.copy);
-   }
- 
-   if (relock)
-   { // Add the lock() method to the clone.
-     addLock(copy, opts);
-   }
- 
-   return copy;
- }
- 
- // Alias the CLONE enum as clone.MODE
- def(clone, 'MODE', CLONE);
- 
- // Export the clone here.
- exports.clone = clone;
+function clone(obj, opts={}) 
+{
+  //console.debug("Lum~clone()", obj, opts);
+
+  if (!isComplex(obj))
+  { // Doesn't need cloning.
+    //console.debug("no cloning required");
+    return obj;
+  }
+
+  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;
+
+  let copy;
+
+  //console.debug("::clone", {mode, reclone, relock});
+
+  if (mode === CLONE.JSON)
+  { // Deep clone enumerable properties using JSON trickery.
+    //console.debug("::clone using JSON cloning");
+    copy = JSON.parse(JSON.stringify(obj));
+  }
+  else if (Array.isArray(obj) && SLICE_ARRAYS.includes(mode))
+  { // Make a shallow copy using slice.
+    //console.debug("::clone using Array.slice()");
+    copy = obj.slice();
+  }
+  else
+  { // Build a clone using a simple loop.
+    //console.debug("::clone using simple loop");
+    copy = {};
+
+    let props;
+    if (ALL_PROPS.includes(mode))
+    { // All object properties.
+      //console.debug("::clone getting all properties");
+      props = Object.getOwnPropertyNames(obj);
+    }
+    else
+    { // Enumerable properties.
+      //console.debug("::clone getting enumerable properties");
+      props = Object.keys(obj);
+    }
+
+    //console.debug("::clone[props]", props);
+    
+    for (const prop of props)
+    {
+      let val = obj[prop];
+      if (isObj(val) && RECURSIVE.includes(mode))
+      { // Deep cloning.
+        val = clone(val, {mode});
+      }
+      copy[prop] = val;
+    }
+  }
+
+  if (reclone)
+  { // Add the clone() method to the clone, with the passed opts as defaults.
+    addClone(copy, opts);
+  }
+
+  if (opts.copy)
+  { // Pass the clone through the copyProps() function as well.
+    copyProps(obj, copy, opts.copy);
+  }
+
+  if (relock)
+  { // Add the lock() method to the clone.
+    addLock(copy, opts);
+  }
+
+  return copy;
+}
+
+// Alias the CLONE enum as clone.MODE
+def(clone, 'MODE', CLONE);
+
+// Export the clone here.
+exports.clone = clone;
  
  /**
   * Add a clone() method to an object.
@@ -141,26 +158,26 @@ const copyProps = require('./copyprops');
   *
   * @method Lum._.addClone
   */
- function addClone(obj, defOpts=null)
- {
-   if (!isObj(defOpts))
-   { // Assign a default set of defaults.
-     defOpts = {mode: CLONE.DEF, addClone: true, addLock: false};
-   }
- 
-   const defDesc = getDescriptor(defOpts.cloneDesc ?? DESC.CONF);
- 
-   defDesc.setValue(function (opts)
-   {
-     if (!isObj(opts)) 
-       opts = defOpts;
-     return clone(obj, opts);
-   });
- 
-   return def(obj, 'clone', defDesc);
- }
- 
- exports.addClone = addClone; 
+function addClone(obj, defOpts=null)
+{
+  if (!isObj(defOpts))
+  { // Assign a default set of defaults.
+    defOpts = {mode: CLONE.DEF, addClone: true, addLock: false};
+  }
+
+  const defDesc = defOpts.cloneDesc ?? {};
+
+  defDesc.value = function (opts)
+  {
+    if (!isObj(opts)) 
+      opts = defOpts;
+    return clone(obj, opts);
+  }
+
+  return def(obj, 'clone', defDesc);
+}
+
+exports.addClone = addClone; 
  
  /**
   * Clone an object if it's not extensible (locked, sealed, frozen, etc.)
@@ -177,25 +194,25 @@ const copyProps = require('./copyprops');
   *
   * @method Lum._.cloneIfLocked
   */
- function cloneIfLocked(obj, opts)
- {
-   if (!Object.isExtensible(obj))
-   {
-     if (typeof obj.clone === F)
-     { // Use the object's clone() method.
-       return obj.clone(opts);
-     }
-     else
-     { // Use our own clone method.
-       return clone(obj, opts);
-     }
-   }
- 
-   // Return the object itself, it's fine.
-   return obj;
- }
- 
- exports.cloneIfLocked = cloneIfLocked;
+function cloneIfLocked(obj, opts)
+{
+  if (!Object.isExtensible(obj))
+  {
+    if (typeof obj.clone === F)
+    { // Use the object's clone() method.
+      return obj.clone(opts);
+    }
+    else
+    { // Use our own clone method.
+      return clone(obj, opts);
+    }
+  }
+
+  // Return the object itself, it's fine.
+  return obj;
+}
+
+exports.cloneIfLocked = cloneIfLocked;
 
 // Import `addLock()` here *after* assigning the clone methods.
 const {addLock} = require('./lock');

package/lib/obj/index.js

@@ -8,11 +8,16 @@ const copyProps = require('./copyprops');
 const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
-const {SOA,nsString,nsArray,getObjectPath,setObjectPath} = require('./ns');
+const ns = require('./ns');
+const 
+{
+  getObjectPath,setObjectPath,
+  getNamespace,setNamespace,
+} = ns;
 
 module.exports =
 {
   CLONE, clone, addClone, cloneIfLocked, lock, addLock,
-  mergeNested, syncNested, SOA, nsString, nsArray,
-  getObjectPath, setObjectPath, copyProps, copyAll,
+  mergeNested, syncNested, copyProps, copyAll, ns,
+  getObjectPath, setObjectPath, getNamespace, setNamespace,
 }

package/lib/obj/lock.js

@@ -1,6 +1,5 @@
 // Import *most* required bits here.
 const {B, isObj, def} = require('../types');
-const {getDescriptor, DESC} = require('../descriptors');
 
 /**
  * Lock an object using Object.freeze()
@@ -47,14 +46,14 @@ const {getDescriptor, DESC} = require('../descriptors');
   */
  function addLock(obj, opts)
  {
-   const defDesc = getDescriptor(opts.lockDesc ?? DESC.CONF);
-   defDesc.setValue(function(obj, cloneable, cloneOpts, useSeal)
+   const defDesc = opts.lockDesc ?? {};
+   defDesc.value = function(obj, cloneable, cloneOpts, useSeal)
    {
      if (typeof cloneable !== B) clonable = opts.addClone ?? true;
      if (!isObj(cloneOpts)) cloneOpts = opts; // Yup, just a raw copy.
      if (typeof useSeal !== B) useSeal = opts.useSeal ?? false;
      return lock(obj, cloneable, cloneOpts, useSeal);
-   });
+   }
    return def(obj, 'lock', defDesc);
  }
  

package/lib/observable.js

@@ -1,7 +1,8 @@
 // This library was original based on the observable library from riot.js,
 // but has been refactored and expanded a lot since then.
 
-const {B,F,S,def,isObj,isComplex} = require('./types');;
+const types = require('./types');
+const {B,F,S,def,isObj,isComplex} = types;
 
 /**
  * Make an object support the observable API.
@@ -289,4 +290,4 @@ function isObservable(obj)
 def(observable, 'is', isObservable);
 
 // And make it available as `types.doesObservable`
-require('./types').doesObservable = isObservable;
+types.doesObservable = isObservable;

package/lib/types/basics.js

@@ -0,0 +1,142 @@
+const {O, F, S, SY} = require('./js');
+
+/**
+ * See if a value is a non-null `object`.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ */
+ function isObj(v) { return (typeof v === O && v !== null); }
+
+ /**
+  * See if a value is *complex* (i.e. either `object` or `function`).
+  * Like `isObj()`, `null` does not count as an `object`.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  */
+ 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}
+  */
+ 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}
+  */
+ function notNil(v) { return (v !== undefined && v !== null); }
+ 
+ /**
+  * See if a value is a scalar.
+  * For the purposes of this, a scalar is any value which
+  * is neither *nil* nor *complex*.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  */
+ function isScalar(v) { return (notNil(v) && !isComplex(v)); }
+ 
+ /**
+  * See if a value is an `Array` object.
+  * This is literally just a copy of `Array.isArray`.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  */
+ const isArray = Array.isArray;
+ 
+ /**
+  * See if a value is a `TypedArray` object.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  */
+ function isTypedArray(v)
+ {
+   return (ArrayBuffer.isView(v) && !(v instanceof DataView));
+ }
+ 
+ /**
+  * See if a value is a non-empty Array.
+  * @param {*} v - The value we're testing.
+  * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
+  *   If `false` (default) we want a regular `Array`.
+  * @returns {boolean}
+  */
+ function nonEmptyArray(v, typed=false)
+ {
+   if (typed)
+     return (isTypedArray(v) && v.length > 0);
+   else
+     return (isArray(v) && v.length > 0);
+ }
+ 
+ /**
+  * See if a value is an `arguments` object.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  */
+ function isArguments(v) 
+ {
+   return Object.prototype.toString.call(v) === '[object Arguments]';
+ }
+
+ /**
+ * See if a value is a Property name.
+ * @param {*} v - The value we're testing.
+ * @returns {boolean}
+ */
+function isProperty(v)
+{
+  const t = typeof v;
+  return (t === S || t === SY);
+}
+
+/**
+ * See if an object can be used as a valid descriptor.
+ * 
+ * Basically in order to be considered a valid descriptor, 
+ * one of the the following sets of rules must be true:
+ * 
+ *  - A Data Descriptor:
+ *      - Has a `value` property.
+ *      - Does not have a `get` property.
+ *      - Does not have a `set` property.
+ *  - An Accessor Descriptor:
+ *      - Has a `get` and/or `set` property.
+ *      - Does not have a `value` property.
+ *      - Does not have a `writable` property.
+ * 
+ * @param {object} obj - The object we are testing. 
+ * @returns {boolean} - Is the object a valid descriptor?
+ */
+ function doesDescriptor(obj)
+ {
+   if (isObj(obj))
+   {
+     const hasValue    = (obj.value !== undefined);
+     const hasGetter   = (typeof obj.get === F);
+     const hasSetter   = (typeof obj.set === F);
+     const hasWritable = (obj.writable !== undefined);
+ 
+     if (hasValue && !hasGetter && !hasSetter)
+     { // We have a value, and no getter or setter.
+       return true;
+     }
+     else if ((hasGetter || hasSetter) && !hasValue && !hasWritable)
+     { // We have a getter or setter, and no value or writable properties.
+       return true;
+     }
+   }
+ 
+   // Nothing matched, not a valid descriptor rule.
+   return false;
+ }
+
+ // Now export those.
+ module.exports =
+ {
+  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+  nonEmptyArray, isArguments, isProperty, doesDescriptor,
+ }
+