@lumjs/core 1.0.0-beta.4 → 1.1.0

package/lib/obj/clone.js

@@ -19,6 +19,7 @@ const copyProps = require('./copyprops');
  * | `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']);
 
@@ -43,25 +44,26 @@ const copyProps = require('./copyprops');
   * 
   *   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);
+  //console.debug("clone()", obj, opts);
 
   if (!isComplex(obj))
   { // Doesn't need cloning.
@@ -156,7 +158,7 @@ exports.clone = clone;
   *
   * ```{mode: CLONE.DEF, addClone: true, addLock: false}```
   *
-  * @method Lum._.addClone
+  * @alias module:@lumjs/core/obj.addClone
   */
 function addClone(obj, defOpts=null)
 {
@@ -185,14 +187,14 @@ exports.addClone = addClone;
   * 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)
 {

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/getproperty.js

@@ -0,0 +1,38 @@
+const types = require('../types');
+const {isComplex,isObj} = types;
+
+/**
+ * Get a property descriptor.
+ * 
+ * This is like `Object.getOwnPropertyDescriptor`, except that method
+ * fails if the property is inhereted. This method will travel through
+ * the entire prototype chain until it finds the descriptor.
+ * 
+ * @param {object|function} obj - Object to find a property in.
+ * @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.
+ */
+function getProperty(obj, prop, defval)
+{
+  if (!isComplex(obj)) throw new TypeError("Target must be an object or function");
+  // Yeah it looks like an infinite loop, but it's not.
+  while (true)
+  {
+    const desc = Object.getOwnPropertyDescriptor(obj, prop);
+    if (isObj(desc))
+    { // Found it.
+      return desc;
+    }
+
+    // Didn't find it, so let's try the next object in the prototype chain.
+    obj = Object.getPrototypeOf(obj);
+    if (!isComplex(obj))
+    { // We've gone as far up the prototype chain as we can, bye now!
+      return defval;
+    }
+  }
+}
+
+module.exports = getProperty;

package/lib/obj/index.js

@@ -1,7 +1,7 @@
-// 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');
@@ -9,6 +9,7 @@ const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
+const getProperty = require('./getproperty');
 const 
 {
   getObjectPath,setObjectPath,
@@ -20,4 +21,5 @@ module.exports =
   CLONE, clone, addClone, cloneIfLocked, lock, addLock,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
+  getProperty,
 }

package/lib/obj/lock.js

@@ -5,8 +5,8 @@ const {B, isObj, def} = require('../types');
  * 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:
@@ -14,8 +14,7 @@ const {B, isObj, def} = require('../types');
  * ```{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)
  {
@@ -37,12 +36,17 @@ const {B, isObj, def} = require('../types');
  /**
   * 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)
  {

package/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)
  {

package/lib/obj/ns.js

@@ -1,17 +1,19 @@
 // Import required bits here.
 const 
 {
-  B, root, isObj, needObj, def, nonEmptyArray, notNil
+  B, root, isObj, needObj, def, nonEmptyArray, notNil,
+  doesDescriptorTemplate,
 } = require('../types');
 
 /**
- * Internal: need a String or Array
+ * Need a String or Array
+ * @alias module:@lumjs/core/obj.SOA
  */
 function SOA(name, err=true)
 {
   const msg = (typeof name === S) 
-    ? name + ' ' + this.message 
-    : this.message;
+    ? name + ' ' + SOA.message 
+    : SOA.message;
   return err ? (new TypeError(msg)) : msg;
 }
 SOA.message = "must be a string or non-empty array";
@@ -19,6 +21,17 @@ def(SOA, 'toString', function() { return this.message; });
 
 exports.SOA = SOA;
 
+/**
+ * Get a namespace path string.
+ * 
+ * If it's already a string, return it as is.
+ * If it's an array of strings, join the elements with a `.` character.
+ * 
+ * @param {(string|string[])} ns - A dotted string, or array of paths.
+ * @param {*} name - Name to use in the SOA error 
+ * @returns {string} 
+ * @alias module:@lumjs/core/obj.nsString
+ */
 function nsString(ns, name='Namespace')
 {
   if (nonEmptyArray(ns))
@@ -34,6 +47,17 @@ function nsString(ns, name='Namespace')
 
 exports.nsString = nsString;
 
+/**
+ * Get a namespace path array.
+ * 
+ * If it's already an array, return it as is.
+ * If it's a string, split it into an array, with the `.` delimiter.
+ * 
+ * @param {(string|string[])} ns - A dotted string, or array of paths.
+ * @param {*} name - Name to use in the SOA error 
+ * @returns {string[]} 
+ * @alias module:@lumjs/core/obj.nsArray
+ */
 function nsArray(ns, name='Namespace')
 {
   if (typeof ns === S)
@@ -52,15 +76,20 @@ exports.nsArray = nsArray;
 /**
  * Get a (nested) property from an object with a given path.
  *
- * @param {object} obj - Object we're looking in.
+ * @param {(object|function)} obj - Object we're looking in.
  * @param {(string|Array)} proppath - Property path we're looking for.
  *   Generally a string of dot (`.`) separated nested property names.
- * @param {object} [opts] TBD.
+ * @param {(object|boolean)} [opts] Options changing the behaviours.
+ *   If this is a `boolean` it's assumed to be the `opts.log` option.
+ * @param {boolean} [opts.log=false] Log errors for missing namespaces?
+ * @param {*} [opts.default] A default value if the namespace is not found.
+ * 
  * @return {*} The property if found, or `opts.default` if not.
+ * @alias module:@lumjs/core/obj.getObjectPath
  */
 function getObjectPath(obj, proppath, opts={})
 {
-  needObj(obj);
+  needObj(obj, true);
 
   if (typeof opts === B)
     opts = {log: opts};
@@ -92,19 +121,32 @@ exports.getObjectPath = getObjectPath;
 /**
  * Create a nested property path if it does not exist.
  * 
- * @param {object} obj - Object the property path is for.
+ * @param {(object|function)} obj - Object the property path is for.
  * @param {(string|Array)} proppath - Property path to create.
- * @param {object} [opts] TBD.
- * @return {*} Generally the last object in the nested path.
- *   However the output may vary depending on the options.
+ * @param {object} [opts] Options changing the behaviours.
+ * @param {*} [opts.value] A value to assign to the last property path.
+ * @param {boolean} [opts.overwrite=false] Allow overwriting property paths.
+ *   Only applicable if `opts.value` was also specified.
+ * @param {object} [opts.desc] Descriptor rules for defining the properties.
+ *   Must NOT contain `value`, `get`, or `set` properties.
+ *   Only, `configurable`, `enumerable`, and `writable` are supported.
+ *   Will be ignored if `opts.assign` is `true`.
+ * @param {boolean} [opts.assign=false] Use direct assignment instead of `def()`.
+ * @param {boolean} [opts.returnThis=false] Return `this` variable.
+ * @param {boolean} [opts.returnObj=false] Return the `obj` parameter.
+ * @return {*} Generally the last object in the nested property paths.
+ *   Unless one of `opts.returnThis` or `opts.returnObj` was `true`.
+ * @alias module:@lumjs/core/obj.setObjectPath
  */
 function setObjectPath(obj, proppath, opts={})
 {
-  needObj(obj); needObj(opts);
+  needObj(obj, true, 'obj parameter must be an object or function');
+  needObj(opts, 'opts parameter must be an object');
+
   proppath = nsArray(proppath);
 
   let assign;
-  if (isObj(opts.desc))
+  if (doesDescriptorTemplate(opts.desc))
   { // An explicit descriptor.
     assign = (o,p,v={}) => 
     {
@@ -169,9 +211,15 @@ exports.setObjectPath = setObjectPath;
 
 /**
  * Get a global namespace path if it exists.
+ *
+ * This literally just calls `getObjectPath()` on the `root` object.
  * 
- * - TODO: document this.
- * - TODO: rewrite `ns.get` to use this behind the scenes.
+ * @param {(string|Array)} proppath - Property path we're looking for.
+ *   Generally a string of dot (`.`) separated nested property names.
+ * @param {object} [opts] See `getObjectPath()` for details.
+ * @return {*} The property if found, or `opts.default` if not.
+ * @alias module:@lumjs/core/obj.getNamespace
+ * @see module:@lumjs/core/obj.getObjectPath
  */
 function getNamespace(namespaces, opts={})
 {
@@ -183,12 +231,17 @@ exports.getNamespace = getNamespace;
 /**
  * Create a global namespace path if it does not exist.
  * 
- * - TODO: document this.
- * - TODO: rewrite `ns.add` to use this behind the scenes.
+ * This literally just calls `setObjectPath()` on the `root` object.
+ * 
+ * @param {(string|Array)} proppath - Property path to create.
+ * @param {object} [opts] See `setObjectPath()` for details.
+ * @return {*} See `setObjectPath()` for details.
+ * @alias module:@lumjs/core/obj.setNamespace
+ * @see module:@lumjs/core/obj.setObjectPath
  */
 function setNamespace(namespaces, opts={})
 {
   return setObjectPath(root, namespaces, opts);
 }
 
-exports.setNamespace = setNamespace;
+exports.setNamespace = setNamespace;

package/lib/objectid.js

@@ -4,9 +4,8 @@ const {notNil,def,isNil} = require('./types');
 /**
  * Generate a large random number.
  * 
- * Takes advantage of 
- * 
  * @returns {number}
+ * @alias module:@lumjs/core.randomNumber
  */
 function randomNumber()
 {
@@ -18,6 +17,7 @@ exports.randomNumber = randomNumber;
 /**
  * A class for creating unique identifier objects.
  * Generally only used by my own inernal libraries, thus the name.
+ * @alias module:@lumjs/core.InternalObjectId
  */
 class InternalObjectId
 {
@@ -34,7 +34,6 @@ class InternalObjectId
    * @param {boolean} [opts.useInstance=true] Store object or id value?
    *   If this is `true` (now the default), we store the instance itself.
    *   If this is `false` (the old default), we store just the `id` value.
-   * 
    */
   constructor(opts={})
   {

package/lib/observable.js

@@ -1,11 +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 types = require('./types');
-const {B,F,S,def,isObj,isComplex} = types;
+const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');;
 
 /**
- * Make an object support the observable API.
+ * Make an object support the *Observable* API.
  *
  * Adds `on()`, `off()`, `one()`, and `trigger()` methods.
  * 
@@ -39,6 +36,8 @@ const {B,F,S,def,isObj,isComplex} = types;
  *   In any other case it defaults to `null`.
  *
  * @returns {object} el
+ * 
+ * @exports module:@lumjs/core/observable
  */
 function observable (el={}, opts={}) 
 {
@@ -274,9 +273,10 @@ function observable (el={}, opts={})
 module.exports = observable;
 
 /**
- * See if an object appears to be observable.
+ * See if a value implements the *Observable* interface.
  * 
- * @param {object} obj 
+ * @function module:@lumjs/core/observable.is
+ * @param {*} obj - The expected object/function to test.
  * @returns {boolean}
  */
 function isObservable(obj)
@@ -289,5 +289,19 @@ function isObservable(obj)
 // Add an 'is()' method to `observable` itself.
 def(observable, 'is', isObservable);
 
-// And make it available as `types.doesObservable`
-types.doesObservable = isObservable;
+/**
+ * Does a value implement the Observable interface?
+ * @name module:@lumjs/core/types.doesObservable
+ * @function
+ * @param {*} v - The expected object/function to test.
+ * @returns {boolean}
+ * @see module:@lumjs/core/observable.is
+ */
+
+/**
+ * Extension type for the {@link module:@lumjs/core/observable} interface.
+ * @memberof module:@lumjs/core/types.TYPES
+ * @member {string} OBSERV - Implements the *Observable* interface.
+ */
+
+TYPES.add('OBSERV', 'observable', isObservable, 'doesObservable');

package/lib/opt.js

@@ -1,4 +1,7 @@
-// Simple option handling.
+/**
+ * Functions for working with options and default values.
+ * @module @lumjs/core/opt
+ */
 
 const {U,needObj,needType} = require('./types');
 
@@ -16,6 +19,7 @@ const {U,needObj,needType} = require('./types');
  *                                    be used as `this` for the function.
  *
  * @return {*} Either the specified `opt` value or the default value.
+ * @alias module:@lumjs/core/opt.val
  */
 function val(opt, defvalue, allowNull=false, isLazy=false, lazyThis=null)
 {
@@ -49,6 +53,7 @@ exports.val = val;
  * @param {object} [lazyThis=opts]  Same as `val()`.
  *
  * @return {*} Either the property value, or the default value.
+ * module:@lumjs/core/opt.get
  */
 function get(obj, optname, defvalue, allowNull=true, isLazy=false, lazyThis=obj)
 {

package/lib/strings.js

@@ -1,4 +1,7 @@
-// String methods.
+/**
+ * String and locale related functions.
+ * @module @lumjs/core/strings
+ */
 const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types')
 
 /**
@@ -8,7 +11,8 @@ const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types')
  * 2. If `Intl` exists it will be used.
  * 3. If neither of those exist, uses `'en-US'` as a default.
  * 
- * @returns string - The locale/language string.
+ * @returns {string} - The locale/language string.
+ * @alias module:@lumjs/core/strings.getLocale
  */
 function getLocale()
 {
@@ -42,7 +46,8 @@ exports.getLocale = getLocale;
  * @param {boolean} [lcrest=false] Make the rest of the string lowercase? 
  * @param {string} [locale=getLocale()] The locale/language of the string.
  * 
- * @returns string - The output string.
+ * @returns {string} - The output string.
+ * @alias module:@lumjs/core/strings.ucfirst
  */
 function ucfirst ([ first, ...rest ], lcrest = false, locale = getLocale())
 {
@@ -61,11 +66,13 @@ exports.ucfirst = ucfirst;
  * Make the first character of each *word* in a string uppercase.
  *  
  * @param {string} string - The input string. 
- * @param {boolean} [unicode=false] Use Unicode words? (Only uses ASCII words otherwise)
+ * @param {boolean} [unicode=false] Use *Unicode* words? 
+ *   Only uses simple *PCRE-style* words (`\w`) otherwise.
  * @param {boolean} [lcrest=false] Make the rest of each word lowercase? 
  * @param {string} [locale=getLocale()] The locale/language of the string. 
  * 
  * @returns {string} - The output string.
+ * @alias module:@lumjs/core/strings.ucwords
  */
 function ucwords(string, unicode = false, lcrest = false, locale = getLocale())
 {
@@ -77,6 +84,12 @@ exports.ucwords = ucwords;
 
 /**
  * Is the passed in value a valid `String.replace` search value.
+ * 
+ * Only strings and `RegExp` objects are valid.
+ * 
+ * @param {*} v - Value to check.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/strings.isSearch
  */
 function isSearch(value)
 {
@@ -87,6 +100,12 @@ exports.isSearch = isSearch;
 
 /**
  * Is the passed in value a valid `String.replace` replacement value.
+ * 
+ * Only strings and functions are valid.
+ * 
+ * @param {*} v - Value to check.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/strings.isReplacement
  */
 function isReplacement(value)
 {
@@ -95,6 +114,26 @@ function isReplacement(value)
 
 exports.isReplacement = isReplacement;
 
+/**
+ * Apply multiple replacement rules to a string.
+ * 
+ * @param {string} string - The input string.
+ * @param {object} replacements - Replacement rules.
+ * 
+ *   If this is an `Array` then each item in the array can be:
+ *   - Another array with two items, `[find, replace]`;
+ *   - A `boolean`, will change the current `useAll` settting.
+ * 
+ *   If this is any other kind of `object` then the enumerable
+ *   property *keys* will be used as `find` strings, and the 
+ *   associated *values* will be used as the `replacement` values.
+ * 
+ * @param {boolean} [useAll] Which replacement method will be used.
+ *   If `true` we use `replaceAll()`, if `false` we use `replace()`.
+ *   The default is `false` if `value` is an `Array`, or `true` otherwise.
+ * @returns {string} The output string with all replacements performed.
+ * @alias module:@lumjs/core/strings.replaceItems
+ */
 function replaceItems(string, replacements, useAll)
 {
   needType(S, string);