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

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

@@ -0,0 +1,192 @@
+/**
+ * String and locale related functions.
+ * @module @lumjs/core/strings
+ */
+const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types')
+
+/**
+ * Get the locale/language string.
+ * 
+ * 1. If `navigator.language` exists it will be used.
+ * 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.
+ * @alias module:@lumjs/core/strings.getLocale
+ */
+function getLocale()
+{
+  if (isObj(root.navigator) && typeof root.navigator.language === S)
+  {
+    return root.navigator.language;
+  }
+  else if (isObj(root.Intl))
+  {
+    try 
+    {
+      const lang = root.Intl.DateTimeFormat().resolvedOptions().locale;
+      return lang;
+    }
+    catch (err)
+    {
+      console.warn("Attempt to get locale from Intl failed", err);
+    }
+  }
+
+  // A last-ditch fallback.
+  return 'en-US';
+}
+
+exports.getLocale = getLocale;
+
+/**
+ * Make the first character of a string uppercase.
+ * 
+ * @param {string} string - The input string.
+ * @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.
+ * @alias module:@lumjs/core/strings.ucfirst
+ */
+function ucfirst ([ first, ...rest ], lcrest = false, locale = getLocale())
+{
+  first = first.toLocaleUpperCase(locale);
+  rest  = rest.join('');
+  if (lcrest)
+  {
+    rest = rest.toLocaleLowerCase(locale);
+  }
+  return first + rest;
+}
+
+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 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())
+{
+  const regex = unicode ? /[0-9\p{L}]+/ug : /\w+/g;
+  return string.replace(regex, word => ucfirst(word, lcrest, locale));
+}
+
+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)
+{
+  return (typeof value === S || value instanceof RegExp);
+}
+
+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)
+{
+  return (typeof value === S || typeof value === F);
+}
+
+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);
+  needObj(replacements);
+
+  // This will call the appropriate method.
+  function replace()
+  {
+    if (useAll)
+      string = string.replaceAll(...arguments);
+    else
+      string = string.replace(...arguments);
+  }
+
+  if (isArray(replacements))
+  { // An array of arrays of replace/replaceAll parameters.
+    useAll = useAll ?? false; // Defaults to false here if it wasn't set.
+    for (const replacement of replacements)
+    {
+      if (isArray(replacement) && replacement.length == 2
+        && isSearch(replacement[0]) && isReplacement(replacement[1]))
+      { // A set of parameters for the function.
+        replace(...replacement);
+      }
+      else if (typeof replacement === B)
+      { // A boolean will override the current useAll value.
+        useAll = replacement;
+      }
+      else 
+      { // That's not valid.
+        console.error("Invalid replacement value", replacement);
+      }
+    }
+  }
+  else 
+  { // Any other object is a map of find strings to replacement values.
+    useAll = useAll ?? true; // Defaults to true here if it wasn't set.
+    for (const find in replacements)
+    {
+      const value = replacements[find];
+      if (isReplacement(value))
+      { 
+        replace(find, value);
+      }
+      else 
+      { 
+        console.error("Invalid replacement value", value);
+      }
+    }
+  }
+
+  return string;
+}
+
+exports.replaceItems = replaceItems;
+

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,
+ }
+