@lumjs/core 1.0.0-beta.2 → 1.0.0

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

@@ -5,13 +5,14 @@ const
 } = 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 +20,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 +46,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)
@@ -57,6 +80,7 @@ exports.nsArray = nsArray;
  *   Generally a string of dot (`.`) separated nested property names.
  * @param {object} [opts] TBD.
  * @return {*} The property if found, or `opts.default` if not.
+ * @alias module:@lumjs/core/obj.getObjectPath
  */
 function getObjectPath(obj, proppath, opts={})
 {
@@ -97,6 +121,7 @@ exports.getObjectPath = getObjectPath;
  * @param {object} [opts] TBD.
  * @return {*} Generally the last object in the nested path.
  *   However the output may vary depending on the options.
+ * @alias module:@lumjs/core/obj.setObjectPath
  */
 function setObjectPath(obj, proppath, opts={})
 {
@@ -169,9 +194,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 +214,18 @@ 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 {*} Generally the last object in the nested path.
+ *   However the output may vary depending on the options.
+ * @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,10 +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 {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.
  * 
@@ -38,6 +36,8 @@ const {B,F,S,def,isObj,isComplex} = require('./types');;
  *   In any other case it defaults to `null`.
  *
  * @returns {object} el
+ * 
+ * @exports module:@lumjs/core/observable
  */
 function observable (el={}, opts={}) 
 {
@@ -273,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)
@@ -288,5 +289,19 @@ function isObservable(obj)
 // Add an 'is()' method to `observable` itself.
 def(observable, 'is', isObservable);
 
-// And make it available as `types.doesObservable`
-require('./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);

package/lib/types/basics.js

@@ -0,0 +1,154 @@
+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}
+ * @alias module:@lumjs/core/types.isObj
+ */
+ 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}
+  * @alias module:@lumjs/core/types.isComplex
+  */
+ 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}
+  * @alias module:@lumjs/core/types.isNil
+  */
+ 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}
+  * @alias module:@lumjs/core/types.notNil
+  */
+ 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}
+  * @alias module:@lumjs/core/types.isScalar
+  */
+ 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`.
+  * @function
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  * @alias module:@lumjs/core/types.isArray
+  */
+ const isArray = Array.isArray;
+ 
+ /**
+  * See if a value is a `TypedArray` object.
+  * @param {*} v - The value we're testing.
+  * @returns {boolean}
+  * @alias module:@lumjs/core/types.isTypedArray
+  */
+ 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}
+  * @alias module:@lumjs/core/types.nonEmptyArray
+  */
+ 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}
+  * @alias module:@lumjs/core/types.isArguments
+  */
+ 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}
+ * @alias module:@lumjs/core/types.isProperty
+ */
+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?
+ * @alias module:@lumjs/core/types.doesDescriptor
+ */
+ 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,
+ }
+