@lumjs/core 1.0.0-beta.1 → 1.0.0-beta.6

package/{src → 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/{src → 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

@@ -0,0 +1,113 @@
+/**
+ * Module helpers.
+ * @module @lumjs/core/modules
+ */
+
+const path = require('path');
+const {S,isObj} = require('./types');
+const replace = require('./strings').replaceItems;
+
+/**
+ * Get the name of a module.
+ *
+ * @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={})
+{
+  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");
+  }
+
+  const ext = path.extname(filename);
+
+  let useFallback = true;
+  let useAuto = opts.useAuto ?? true;
+
+  if (opts.basename)
+  { // We want to run the basename sequence first.
+    filename = path.basename(filename, ext);
+    useFallback = false;
+    useAuto = false;
+  }
+  
+  if (isObj(opts.replace))
+  { // Replacements using replace() or replaceAll() based on parameter format.
+    useFallback = false;
+    filename = replace(filename, opts.replace);
+  }
+
+  if (isObj(opts.replaceOne))
+  { // Replacements using replace() regardless of parameter format.
+    useFallback = false;
+    filename = replace(filename, opts.replaceOne, false);
+  }
+
+  if (isObj(opts.replaceAll))
+  { // Replacements using replaceAll() regardless of parameter format.
+    useFallback = false;
+    filename = replace(filename, opts.replaceAll, true);
+  }
+
+  if (typeof opts.strip === S)
+  { // A prefix. This always uses replace(), never replaceAll(). 
+    filename = filename.replace(opts.strip, '');
+    useFallback = false;
+  }
+  else if (Array.isArray(opts.strip))
+  { // A list of strings or regexps to strip. Ditto on the use of replace().
+    for (const strip of opts.strip)
+    {
+      filename = filename.replace(strip, '');
+    }
+    useFallback = false;
+  }
+
+  if (useFallback)
+  { // We're going to use the basename, either as a fallback
+    filename = path.basename(filename, ext);
+    useAuto = false;
+  }
+
+  if (useAuto)
+  { // A few automatic rules that normally apply if the fallback was not used.
+    filename = filename
+      .replace(/^[./]+/, '')
+      .replace(RegExp(ext+'$'), '');
+  }
+
+  return filename;
+}
+
+exports.name = name;

package/lib/obj/clone.js

@@ -0,0 +1,220 @@
+// Import *most* required bits here.
+const {B,N,F, isObj, isComplex, def} = require('../types');
+const Enum = require('../enum');
+const copyProps = require('./copyprops');
+
+/**
+ * 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.
+ * 
+ * | 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','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.
+  *
+  * @param {object|function} obj - The object we want to clone.
+  * @param {object} [opts={}] - Options for the cloning process.
+  * 
+  * @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 `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.
+  *
+  * @param {boolean} [opts.addLock=false] - Call `addLock()` on the cloned object.
+  *
+  *   No further options for this, just add a `lock()` method to the clone.
+  *
+  * @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("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.
+  *
+  * @param {object|function} obj - The object to add clone() to.
+  * @param {object} [defOpts=null] Default options for the clone() method.
+  *
+  * If `null` or anything other than an object, the defaults will be:
+  *
+  * ```{mode: CLONE.DEF, addClone: true, addLock: false}```
+  *
+  * @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 = 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.)
+  *
+  * 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 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.
+  *
+  * @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;
+
+// Import `addLock()` here *after* assigning the clone methods.
+const {addLock} = require('./lock');

package/{src → 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/{src → 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

@@ -0,0 +1,23 @@
+/**
+ * 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 ns = require('./ns');
+const 
+{
+  getObjectPath,setObjectPath,
+  getNamespace,setNamespace,
+} = ns;
+
+module.exports =
+{
+  CLONE, clone, addClone, cloneIfLocked, lock, addLock,
+  mergeNested, syncNested, copyProps, copyAll, ns,
+  getObjectPath, setObjectPath, getNamespace, setNamespace,
+}

package/{src → lib}/obj/lock.js

@@ -1,13 +1,12 @@
 // Import *most* required bits here.
 const {B, isObj, def} = require('../types');
-const {getDescriptor, DESC} = require('../descriptors');
 
 /**
  * Lock an object using Object.freeze()
  *
  * @param {object} obj - The object we want to lock.
- * @param {boolean} [clonable=true] Pass to {@link Lum._.addClone} first?
- * @param {object} [cloneOpts=null] Options for addClone.
+ * @param {boolean} [clonable=true] Pass to `addClone()` first?
+ * @param {object} [cloneOpts=null] Options for `addClone()`.
  * @param {boolean} [useSeal=false] Use Object.seal() instead of freeze.
  *
  * If cloneOpts is `null` then we will use the following:
@@ -15,8 +14,7 @@ const {getDescriptor, DESC} = require('../descriptors');
  * ```{mode: CLONE.DEF, addClone: true, addLock: true}```
  *
  * @return {object} The locked object.
- *
- * @method Lum._.lock
+ * @alias module:@lumjs/core/obj.lock
  */
  function lock(obj, clonable=true, cloneOpts=null, useSeal=false)
  {
@@ -38,23 +36,28 @@ const {getDescriptor, DESC} = require('../descriptors');
  /**
   * Add a lock() method to an object.
   *
-  * Adds a wrapper version of {@link Lum._.lock} to the object as a method.
-  *
-  * @param {object} obj - The object we're adding lock() to.
-  * @param {object} opts - Options (TODO: document this).
+  * Adds a wrapper version of `lock()` to the object as a method.
   *
-  * @method Lum._.addLock
+  * @param {object} obj - The object we're adding `lock()` to.
+  * @param {object} [opts] - Options and defaults. 
+  *   In addition to options specific to this function, any options
+  *   supported by `addClone()` may be specified here as well.
+  * @param {object} [opts.lockDesc] Descriptor rules the `lock()` method.
+  * @param {boolean} [opts.addClone=true] Default for `clonable` parameter.
+  * @param {object} [opts.useSeal=false] Default for `useSeal` parameter.
+  * @returns {object} `obj`
+  * @alias module:@lumjs/core/obj.addLock
   */
  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/{src → lib}/obj/merge.js

@@ -20,6 +20,7 @@ const {B, isObj} = require('../types');
  *   as the `opts` argument directly will set this option.
  *
  * @returns {object} The `target` object.
+ * @alias module:@lumjs/core/obj.mergeNested
  */
  function mergeNested(source, target, opts={})
  {
@@ -64,6 +65,7 @@ const {B, isObj} = require('../types');
   * @param {object} [opts2=opts1] Options for the second merge operation.
   *   If this is not specified, `opts2` will be the same as `opts1`.
   *
+  * @alias module:@lumjs/core/obj.syncNested
   */
  function syncNested(obj1, obj2, opts1={}, opts2=opts1)
  {