@lumjs/core 1.38.4 → 1.38.6

package/lib/obj/{ns.js → ns/index.js}

@@ -4,14 +4,22 @@ const
   B, S,
   root, isObj, needObj, def, nonEmptyArray, isNil,
   doesDescriptorTemplate,
-} = require('../types');
+} = require('../../types');
 
-const {df} = require('./df');
+const {df} = require('../df');
 const cp = Object.assign;
 
+const NS = exports.NS = require('./formats');
+const {isFormat} = NS;
+
+// TODO: use the new formats!
+
 /**
- * Need a String or Array
+ * [INTERNAL] Generate an error message for nsString/nsArray functions.
  * @alias module:@lumjs/core/obj.SOA
+ * @param {?string} [name] Name to prefix to error message.
+ * @param {boolean} [err=true] Return an error instance?
+ * @returns {(TypeError|string)} Depends on `err` argument.
  */
 function SOA(name, err=true)
 {
@@ -21,61 +29,170 @@ function SOA(name, err=true)
   return err ? (new TypeError(msg)) : msg;
 }
 SOA.message = "must be a string or non-empty array";
-def(SOA, 'toString', function() { return this.message; });
+df(SOA, 'toString', function() { return this.message; });
 
 exports.SOA = SOA;
 
 /**
- * Get a namespace path string.
+ * Get a namespace path array.
  * 
- * If it's already a string, return it as is.
- * If it's an array of strings, join the elements with a `.` character.
+ * 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.nsString
+ * @param {(object|string)} [opts] Options.
+ * 
+ * If this is a string it will be used as `opts.name`.
+ * 
+ * @param {string} [opts.name="Namespace"] Name to use in the SOA error.
+ * @param {(module:@lumjs/core/obj.NS~Format|Array)} [opts.format] Format.
+ * 
+ * You can specify a single format, or an array of formats, in which case
+ * the canStringify() method will be called on each of them and the first one
+ * that returns true will be used. If none return true, the last one listed
+ * will be used.
+ * 
+ * If this is not specified, then we will call the canParse() method on
+ * Pointer, JSPath, and Simple (in that order) and use the first one that
+ * returns true (or the last one regardless).
+ * 
+ * @returns {string[]} 
+ * @alias module:@lumjs/core/obj.nsArray
  */
-function nsString(ns, name='Namespace')
+function nsArray(ns, opts={})
 {
-  if (nonEmptyArray(ns))
+  if (typeof opts === S) opts = {name: opts};
+
+  if (typeof ns === S)
   {
-    return ns.join('.');
+    let format;
+
+    if (isFormat(opts.format) || Array.isArray(opts.format))
+    {
+      format = opts.format;
+    }
+    else
+    {
+      format = NS.Defaults;
+    }
+
+    if (Array.isArray(format))
+    {
+      let formats = format;
+      for (format of formats)
+      {
+        if (isFormat(format) && format.canParse(ns))
+        {
+          break;
+        }
+      }
+    }
+
+    if (!isFormat(format))
+    { // This shouldn't normally happen, but...
+      throw new TypeError("No valid format found");
+    }
+
+    return format.parse(ns);
   }
-  else if (typeof ns !== S)
+  else if (!nonEmptyArray(ns)) 
   {
-    throw SOA(name);
+    throw SOA(opts.name ?? 'Namespace');
   }
   return ns;
 }
 
-exports.nsString = nsString;
+exports.nsArray = nsArray;
 
 /**
- * Get a namespace path array.
+ * Get a namespace path string.
  * 
- * If it's already an array, return it as is.
- * If it's a string, split it into an array, with the `.` delimiter.
+ * If it's already a string, return it as is.
+ * If it's an array of strings, join the elements with a 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
+ * @param {(object|string)} [opts] Options.
+ * 
+ * If this is a string, it will be used as `opts.name`.
+ *
+ * @param {string} [opts.name="Namespace"] Name to use in the SOA error.
+ * @param {(module:@lumjs/core/obj.NS~Format|Array)} [opts.format] Format.
+ * 
+ * You can specify a single format, or an array of formats, in which case
+ * the canStringify() method will be called on each of them and the first one
+ * that returns true will be used. If none return true, the last one listed
+ * will be used.
+ * 
+ * If this is not specified, then we will check for the legacy `opts.join`
+ * and/or `opts.prefix` options. If at least one of them was found an ad-hoc
+ * format using NS.Simple as a template will be created, composing the `opts`
+ * as overridden format object properties. As making a custom format is
+ * quite simple, both of the legacy options are deprecated.
+ * 
+ * If neither this option nor any of the legacy options were specified,
+ * we will call the canStringify() method on Simple, JSPath, and Pointer
+ * (in that order), and use the first one that returns true.
+ * 
+ * @param {string} [opts.join] Custom format delimiter character(s). 
+ * 
+ * This is **DEPRECATED** and will be removed in v2.x.
+ * 
+ * @param {string} [opts.prefix] Custom format prefix.
+ * 
+ * This is **DEPRECATED** and will be removed in v2.x.
+ * 
+ * @returns {string}
+ * @throws {TypeError} If `ns` was not a valid value.
+ * @alias module:@lumjs/core/obj.nsString
  */
-function nsArray(ns, name='Namespace')
+function nsString(ns, opts={})
 {
-  if (typeof ns === S)
+  if (typeof opts === S) opts = {name: opts};
+
+  if (nonEmptyArray(ns))
   {
-    return ns.split('.');
+    let format;
+
+    if (isFormat(opts.format) || Array.isArray(opts.format))
+    {
+      format = opts.format;
+    }
+    else if (typeof opts.join === S || typeof opts.prefix === S)
+    {
+      format = cp({}, NS.Simple, opts);
+    }
+    else
+    {
+      format = NS.Defaults.slice().reverse();
+    }
+
+    if (Array.isArray(format))
+    {
+      let formats = format;
+      for (format of formats)
+      {
+        if (isFormat(format) && format.canStringify(ns))
+        {
+          break;
+        }
+      }
+    }
+
+    if (!isFormat(format))
+    { // This shouldn't normally happen, but...
+      throw new TypeError("No valid format found");
+    }
+
+    return format.stringify(ns);
   }
-  else if (!nonEmptyArray(ns)) 
+  else if (typeof ns !== S)
   {
-    throw SOA(name);
+    throw SOA(opts.name ?? 'Namespace');
   }
   return ns;
 }
 
-exports.nsArray = nsArray;
+exports.nsString = nsString;
 
 /**
  * Get a (nested) property from an object with a given path.
@@ -87,7 +204,10 @@ exports.nsArray = nsArray;
  * 
  * @param {(object|boolean)} [opts] Options changing the behaviours.
  * 
- * If this is a `boolean` it's assumed to be the `opts.log` option.
+ * If this is a `boolean` it's assumed to be the `opts.log` option;
+ * using a boolean is deprecated and will be removed in v2.x.
+ * 
+ * Any options supported by nsArray() may also be specified here.
  * 
  * @param {boolean} [opts.log=false] Log errors for missing namespaces?
  * @param {boolean} [opts.allowFun=true] Allow `obj` to be a `function` ?
@@ -109,7 +229,7 @@ function getObjectPath(obj, proppath, opts={})
 
   needObj(obj, (opts.allowFun ?? true));
 
-  proppath = nsArray(proppath);
+  proppath = nsArray(proppath, opts);
 
   for (let p = 0; p < proppath.length; p++)
   {
@@ -138,7 +258,10 @@ exports.getObjectPath = getObjectPath;
  * @param {(string|Array)} proppath - Property path to create.
  * @param {(object|boolean)} [opts] Options changing the behaviours.
  * 
- * If this is a `boolean` it's assumed to be the `opts.overwrite` option.
+ * If this is a `boolean` it's assumed to be the `opts.overwrite` option;
+ * using a boolean is deprecated and will be removed in v2.x.
+ * 
+ * Any options supported by nsArray() may also be specified here.
  * 
  * @param {*} [opts.value] A value to assign to the last property path.
  * @param {boolean} [opts.overwrite=false] Allow overwriting property paths.
@@ -181,7 +304,7 @@ function setObjectPath(obj, proppath, opts={})
   const setprop = opts.df ? df : def;
   const propopts = cp({}, opts.def, opts.df);
 
-  proppath = nsArray(proppath);
+  proppath = nsArray(proppath, opts);
 
   let assign;
   if (opts.assign)
@@ -259,13 +382,13 @@ exports.setObjectPath = setObjectPath;
  * The last property name in the path will be the one that is deleted 
  * from its parent object.
  * 
- * @param {object} [opts] Options for `getObjectPath()`
+ * @param {object} [opts] Options for getObjectPath() and nsArray().
  * @returns {*} The value that was removed; or `undefined` if the
  * proppath didn't resolve to a defined value.
  */
 function delObjectPath(obj, proppath, opts={})
 {
-  proppath = nsArray(proppath);
+  proppath = nsArray(proppath, opts);
   const rmProp = proppath.pop();
   const rmFrom = proppath.length
     ? getObjectPath(obj, proppath, opts)
@@ -286,9 +409,9 @@ exports.delObjectPath = delObjectPath;
 /**
  * Build a simple factory object for working with property paths.
  * 
- * @param {(object|function)} value - The target object
- * @param {object} [opts] Default options for the *ObjectPath() functions
- * @returns {object} A frozen factory object
+ * @param {(object|function)} value - The target object.
+ * @param {object} [opts] Default options for the *ObjectPath() functions.
+ * @returns {object} A frozen factory object.
  * 
  * Has `get(path,opts)`, `set(path,opts)`, and `del(path,opts)` methods, 
  * which are wrappers for getObjectPath(), setObjectPath(),