@lumjs/core 1.0.0-beta.2 → 1.0.0

package/lib/lazy.js

@@ -1,24 +1,25 @@
 
-const {S,F,isComplex} = require('./types');
-const prop = require('./prop');
-const {DESC} = require('./descriptors');
+const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
+
+/**
+ * @callback module:@lumjs/core~InitFunc 
+ * @param {string} name - The `name` parameter passed to `lazy()`
+ * @this {object} - The `obj` parameter passed to `lazy()`
+ */
 
 /**
  * Build a lazy initializer property.
  *
  * Basically the first time the property is accessed it's built.
  * Subsequent accesses will use the already built property.
- * This is an extension of the {@link prop} method, and indeed an
- * alias called `prop.lazy()` is also available.
+ * This is an extension of the {@link def} method, and indeed an
+ * alias called `def.lazy()` is also available.
  *
- * @param {object} obj - The object to add the property to.
+ * @param {Object} obj - The object to add the property to.
  * @param {string} name - The name of the property to add.
- * @param {function} initfunc - The function to initialize the property.
- * 
- *   This function will have `this` set to the `obj` parameter.
- *   It will also be passed `name` as the sole parameter.
- * 
- * @param {mixed} [onset] How to handle assignment.
+ * @param {module:@lumjs/core~InitFunc} initfunc 
+ *   The function to initialize the property.
+ * @param {*} [onset] How to handle assignment.
  * 
  *   If this is `true` then the new value will be assigned directly,
  *   skipping the initialization process entirely.
@@ -36,29 +37,26 @@ const {DESC} = require('./descriptors');
  * 
  *   If this is anything else, assignment will do nothing at all.
  * 
- * @param {object} [desc=DESC.CONF] The Descriptor for the property.
+ * @param {Object} [desc={}] Descriptor rules for the property.
+ *   We only support two descriptor rules with this function, and
+ *   their default values are the same as the `def()` function.
+ *   - `configurable` → `true`
+ *   - `enumerable` → `false`
+ *   Any other descriptor properties are invalid here.
  *
- * @return {object} The object we defined the property on.
+ * @return {Object} The object we defined the property on.
+ * @alias module:@lumjs/core.lazy
  */
-function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
+function lazy(obj, name, initfunc, onset, desc={})
 {
-  if (!isComplex(obj))
-  {
-    throw new TypeError("obj parameter was not an object");
-  }
-  if (typeof name !== S)
-  {
-    throw new TypeError("name parameter was not a string");
-  }
-  if (typeof initfunc !== F)
-  {
-    throw new TypeError("initfunc parameter was not a function");
-  }
+  needType(COMPLEX, obj, 'obj must be an object');
+  needType(S, name, 'name must be a string');
+  needType(F, initfunc, 'initfunc must be a function');
+  needObj(desc, 'desc parameter was not an object');
 
   let value;
-  let setter = null;
 
-  function getter()
+  desc.get = function()
   {
     if (value === undefined)
     {
@@ -69,23 +67,23 @@ function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
 
   if (onset === true)
   { // Allow direct assignment.
-    setter = function(newval)
+    desc.set = function(newval)
     {
       value = newval;
     }
   }
   else if (onset === false)
   { // Throw an error on assignment.
-    setter = function()
+    desc.set = function()
     {
       throw new ReferenceError("The "+name+" property is read-only");
     }
   }
   else if (typeof onset === F)
   { // A proxy method for assignment.
-    setter = function(newval)
+    desc.set = function(newval)
     {
-      const setval = onset.call(this, newval);
+      const setval = onset.call(this, newval, value);
       if (setval !== undefined)
       {
         value = setval;
@@ -93,10 +91,10 @@ function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
     }
   }
 
-  prop(obj, name, getter, setter, desc);
+  def(obj, name, desc);
 }
 
 // Gotta be one of the greatest lines...
-prop(prop, 'lazy', lazy);
+def(def, 'lazy', lazy);
 
 module.exports = lazy;

package/lib/meta.js

@@ -1,7 +1,20 @@
-
+/**
+ * Meta-programming helpers.
+ * @module @lumjs/core/meta
+ */
 
 /**
  * Get a stacktrace. Differs from browser to browser.
+ *
+ * Uses the `stack` property of an `Error` object as the source.
+ * This is a super simplistic hack. For a more complete solution, try
+ * the `stacktrace-js` library, which will be used in the new `@lumjs/debug`
+ * library as a dependency.
+ *
+ * @param {string} [msg] - A message for the Error object.
+ *
+ * @returns {string[]} An array of stack strings.
+ * @alias module:@lumjs/core/meta.stacktrace
  */
 function stacktrace(msg)
 {
@@ -12,6 +25,7 @@ exports.stacktrace = stacktrace;
 
 /**
  * Abstract classes for Javascript.
+ * @alias module:@lumjs/core/meta.AbstractClass
  */
 class AbstractClass
 {
@@ -38,6 +52,8 @@ exports.AbstractClass = AbstractClass;
 
 /**
  * Function prototypes for async, generator, and async generator functions.
+ * @namespace
+ * @alias module:@lumjs/core/meta.Functions
  */
 const Functions =
 {
@@ -59,3 +75,24 @@ const Functions =
 }
 
 exports.Functions = Functions;
+
+/**
+ * A placeholder function for when something is not implemented.
+ * 
+ * @param {boolean} [fatal=true] If `true` throw Error.
+ *   If `false` use `console.error()` instead.
+ * @param {string} [prefix=''] A prefix for the error message.
+ * 
+ * @returns {void}
+ * @alias module:@lumjs/core/meta.NYI
+ */
+function NYI(fatal=true, prefix='') 
+{ 
+  const msg = prefix+"« NOT YET IMPLEMENTED »";
+  if (fatal)
+    throw new Error(msg);
+  else
+    console.error(msg);
+}
+
+exports.NYI = NYI;

package/lib/modules.js

@@ -1,24 +1,59 @@
-// Stuff specific to mostly Node.js, but browser-shims may wrap this.
+/**
+ * Module helpers.
+ * @module @lumjs/core/modules
+ */
 
 const path = require('path');
-const {S,needObj,needType,isObj} = require('./types');
+const {S,isObj} = require('./types');
 const replace = require('./strings').replaceItems;
 
 /**
  * Get the name of a module.
  *
- * TODO: document this.
+ * @param {(object|string)} module - Either a module object, or filename.
+ *   If it is an `object`, it should be a CommonJS `module` object.
+ *   If it is a `string`, it should be the module filename.
+ * @param {object} [opts] Options.
+ * 
+ * @param {boolean} [opts.useAuto=true] Enable automatic name cleaning.
+ *   If *basename* mode was **not** used, then once all other rules have been 
+ *   applied, strip any leading `.` and `/` characters, and the file extension.
+ * 
+ * @param {boolean} [opts.basename=false] Use `path.basename()`
+ *   This will strip all parent directories, and the file extension.
+ *   If no other rules are specified in the `opts`, then this will
+ *   be applied automatically as a fallback method. If it is set to
+ *   `true` explicitly, then it will be applied *before* any other options.
+ * 
+ * @param {object} [opts.replace] Call {@link module:@lumjs/core/strings.replaceItems}
+ *   This uses the default `useAll` values based on the `object` format.
+ * @param {object} [opts.replaceOne] `replace` but `useAll` set to `false`.
+ * @param {object} [opts.replaceAll] `replace` but `useAll` set to `true`.
+ * @param {(string|string[])} [opts.strip] Sub-strings to remove entirely.
+ * @returns {string} The *name* of a module as per the options set.
+ * @alias module:@lumjs/core/modules.name
  */
 function name(module, opts={})
 {
-  needObj(module);
-  needType(S, module.filename);
+  let filename;
+
+  if (typeof module === S)
+  { // Going to assume a string is the filename.
+    filename = module;
+  }
+  else if (isObj(module) && typeof module.filename === S)
+  { // It's a CommonJS module context object.
+    filename = module.filename;
+  }
+  else
+  { // Sorry, we don't support that.
+    throw new TypeError("Unsupported module parameter");
+  }
 
-  let filename = module.filename;
   const ext = path.extname(filename);
 
   let useFallback = true;
-  let useAuto = !opts.noAuto;
+  let useAuto = opts.useAuto ?? true;
 
   if (opts.basename)
   { // We want to run the basename sequence first.
@@ -72,6 +107,7 @@ function name(module, opts={})
       .replace(RegExp(ext+'$'), '');
   }
 
+  return filename;
 }
 
 exports.name = name;

package/lib/obj/clone.js

@@ -1,21 +1,38 @@
 // 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. |
+ * 
+ * @alias module:@lumjs/core/obj.CLONE
  */
- 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,111 +40,113 @@ 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.
   *
-  * @param {boolean} [opts.addClone=false] - Call {@link Lum._.addClone} on the cloned object.
+  * @param {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.
+  *   the `clone()` method added to the object.
   *
-  * @param {boolean} [opts.addLock=false] - Call {@link Lum._.addLock} on the cloned object.
+  * @param {boolean} [opts.addLock=false] - Call `addLock()` on the cloned object.
   *
-  *   No further options for this, just add a lock() method to the clone.
+  *   No further options for this, just add a `lock()` method to the clone.
   *
-  * @param {?object} [opts.copy] Call {@link Lum._.copy} on the cloned object.
+  * @param {?object} [opts.copy] Call `copyProps()` on the cloned object.
   *
   *   Will pass the original `obj` as the source to copy from.
   *   Will pass `opts.copy` as the options.
   *
   * @return {object} - The clone of the object.
+  * @alias module:@lumjs/core/obj.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 (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("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.
@@ -139,28 +158,28 @@ const copyProps = require('./copyprops');
   *
   * ```{mode: CLONE.DEF, addClone: true, addLock: false}```
   *
-  * @method Lum._.addClone
+  * @alias module:@lumjs/core/obj.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.)
@@ -168,34 +187,34 @@ const copyProps = require('./copyprops');
   * If the object is extensible, it's returned as is.
   *
   * If not, if the object has a `clone()` method it will be used.
-  * Otherwise use the {@link Lum._.clone} method.
+  * Otherwise use our `clone()` function.
   *
   * @param {object} obj - The object to clone if needed.
   * @param {object} [opts] - Options to pass to `clone()` method.
   *
   * @return {object} - Either the original object, or an extensible clone.
   *
-  * @method Lum._.cloneIfLocked
+  * @alias module:@lumjs/core/obj.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/copyall.js

@@ -3,6 +3,8 @@
  *
  * It does no type checking, and has no qualms about overwriting properties.
  * You probably want something like `copyProps` instead.
+ * 
+ * @alias module:@lumjs/core/obj.copyAll
  */
 function copyAll(target, ...sources)
 {
@@ -13,6 +15,7 @@ function copyAll(target, ...sources)
       target[name] = source[name];
     }
   }
+  return target;
 }
 
 module.exports = copyAll;

package/lib/obj/copyprops.js

@@ -23,6 +23,7 @@ const {B,isObj,isComplex,isArray,def: defProp} = require('../types');
  *   if that property can be overwritten or not.
  *
  * @returns {object} The `target` object.
+ * @alias module:@lumjs/core/obj.copyProps
  */
 function copyProps(source, target, propOpts)
 {

package/lib/obj/index.js

@@ -1,18 +1,23 @@
-// Object helper utilities.
-// We *could* use `copyAll` to simply merge everything in here automatically.
-// But I'm going to be more explicit and import everything I want separately.
-// I may change my mind on that in the future, who knows.
+/**
+ * Object helpers sub-module.
+ * @module @lumjs/core/obj
+ */
 
 const copyAll = require('./copyall');
 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,
 }