@ygracs/xobj-lib-js 0.3.1 → 0.3.2

package/lib/xObj-lib.js

@@ -1,15 +1,15 @@
-// [v0.3.134-20260303]
+// [v0.3.138-20260530]
 
 // === module init block ===
 
 const {
-  valueToIndex, //valueToIDString,
+  valueToIndex,
   readAsString, readAsBoolEx, readAsNumberEx,
   isNullOrUndef,
   isInteger,
   isArray, isObject, isPlainObject,
   // * import types definitions *
-  OPT_valtostr,
+  IValueToStringTransformOptions,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
@@ -21,6 +21,8 @@ const {
   XOBJ_DEF_TNAMES,
 } = require('./xObj-defs');
 
+// === module inner block ===
+
 const {
   XOBJ_TE_NSTR_EMSG,
   XOBJ_TE_NSTR_ECODE,
@@ -32,10 +34,16 @@ const {
 
 const {
   XOBJ_DEF_PARAM_TNAME,
-  XOBJ_DEF_ATTR_TNAME,
 } = XOBJ_DEF_TNAMES;
 
-// === module inner block ===
+/**
+ * A result of a value check ops.
+ * @typedef {Object} RVAL_reason
+ * @property {string} code - message ID
+ * @property {string} msg - message text
+ * @deprecated
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ */
 
 /**
  * An error description of a value check ops on fail.
@@ -47,10 +55,11 @@ const {
 
 /**
  * A result of a value check ops.
- * @typedef {Object} RVAL_reason
- * @property {string} code - message ID
- * @property {string} msg - message text
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ * @typedef {Object} VCOR_evalkname
+ * @property {boolean} isSucceed - ops flag
+ * @property {string|IEvalKeyNameReasonOnFail} value - result value or reson if failed
+ * @deprecated
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
  */
 
 /**
@@ -79,22 +88,19 @@ const {
 /**
  * A result of `evalKeyName` function
  * @since 0.3.0
- * @typedef {(IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail)} IEvalKeyNameResult
+ * @typedef {IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail} IEvalKeyNameResult
  */
-
 /**
- * A result of a value check ops.
- * @typedef {Object} VCOR_evalkname
- * @property {boolean} isSucceed - ops flag
- * @property {(string|RVAL_reason)} value - result value or reson if failed
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IEvalKeyNameResult}
  */
+module.exports.IEvalKeyNameResult = { isSucceed: true, value: '' };
 
 /**
  * Tries to convert a value into an ID.
  * @function evalKeyName
  * @param {any} value - key to validate
- * @param {(boolean|IEvalKeyNameOptions)} [opt=true] - some options
+ * @param {boolean|IEvalKeyNameOptions} [opt=true] - some options
  * @returns {IEvalKeyNameResult}
  * @inner
  */
@@ -126,22 +132,15 @@ function evalKeyName(value, opt = true) {
     value: key,
   };
 };
+module.exports.evalKeyName = evalKeyName;
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
 /**
  * Tries to convert a value into an ID.
  * @function evalXObjEName
  * @param {any} value - some value to evaluate
- * @returns {(null|number|string)}
+ * @returns {null|number|string}
  */
 function evalXObjEName(value) {
   //return valueToIDString(value); // // TODO: [?]
@@ -188,7 +187,7 @@ function evalXObjEName(value) {
  * A result of an element name pattern evaluation ops.
  * @typedef {Object} XObjENameDescr
  * @property {boolean} isERR - ops flag
- * @property {(null|number|string)} name - element name
+ * @property {null|number|string} name - element name
  * @property {?XObjENameDescrConditions} conditions - some conditions applied to an element
  */
 
@@ -250,6 +249,22 @@ function genXObjENameDescr(value) {
   return result;
 };
 
+/**
+ *
+ * @since 0.3.2
+ * @typedef {Object<string, any>} INode
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {INode}
+ */
+module.exports.INode = {};
+/**
+ * A list of a `INode`-elements
+ * @since 0.3.2
+ * @typedef {INode[]} INodeList
+ */
+
 /**
  * Extracts an element from a given object by its key.
  * @function getXObjElement
@@ -274,49 +289,58 @@ function getXObjElement(obj, name) {
   const { code, msg } = key;
   throw new EvalKeyNameError(msg, { code });
 };
-
-/**
- * Extracts an attributes from a given object by its key.
- * @function getXObjAttributes
- * @param {object} obj - some object
- * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
- * @returns {?object}
- * @throws {TypeError} if `obj` param is not an object
- */
-function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
-  let result = null;
-  try {
-    result = getXObjElement(obj, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE :
-      case XOBJ_TE_KNES_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return isPlainObject(result) ? result : null;
-};
+module.exports.getXObjElement = getXObjElement;
 
 /**
  * A result of an xObj modification ops
  * @typedef {Object} RVAL_emodif
  * @property {boolean} isSucceed - flag that indicates whether an ops is succeed or not
  * @property {?(object|object[])} item - some element as a result
+ * @deprecated
+ * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
  */
 
 /**
- * Adds an element addressed by its key to a given object.
- * @function addXObjElement
+ * A result of an xObj modification ops if failed
+ * @since 0.3.2
+ * @typedef {Object} INodeModifResultOnFail
+ * @property {false} isSucceed - flag that indicates whether an ops is succeed or not
+ * @property {null} item - some element as a result
+ */
+
+/**
+ * A result of an xObj modification ops if succeed
+ * @since 0.3.2
+ * @typedef {Object} INodeModifResultOnSuccess
+ * @property {true} isSucceed - flag that indicates whether an ops is succeed or not
+ * @property {object|object[]} item - some element as a result
+ */
+
+/**
+ * A result of an xObj modification ops
+ * @since 0.3.2
+ * @typedef {INodeModifResultOnFail|INodeModifResultOnSuccess} INodeModifResult
+ */
+
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {INodeModifResult}
+ */
+module.exports.INodeModifResult = { isSucceed: false, item: null };
+
+/**
+ *
+ * @callback addXObjElementFn
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {?object}
- * @throws {TypeError} if `obj` param is not an object
  * @see {@link addXObjElementEx} for param details
  */
+/**
+ * Adds an element addressed by its key to a given object.
+ * @type {addXObjElementFn}
+ * @throws {TypeError} if `obj` param is not an object
+ */
 function addXObjElement(...args) {
   let item = null;
   try {
@@ -334,6 +358,7 @@ function addXObjElement(...args) {
   };
   return item;
 };
+module.exports.addXObjElement = addXObjElement;
 
 /**
  * Adds an element addressed by its key to a given object.
@@ -341,7 +366,7 @@ function addXObjElement(...args) {
  * @function addXObjElementEx
  * @param {object} obj - some object
  * @param {string} name - some child element
- * @returns {RVAL_emodif}
+ * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -354,6 +379,7 @@ function addXObjElementEx(obj, name) {
   };
   const { isSucceed, value: key } = evalKeyName(name);
   if (isSucceed) {
+    /** @type {INode} */
     const item = {};
     let prop = obj[key];
     let isSucceed = false;
@@ -390,15 +416,19 @@ module.exports.addXObjElementEx = addXObjElementEx;
  */
 
 /**
- * Inserts an element addressed by its key into a given object.
- * @function insertXObjElement
+ *
+ * @callback insertXObjElementFn
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
- * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
+/**
+ * Inserts an element addressed by its key into a given object.
+ * @type {insertXObjElementFn}
+ * @throws {TypeError} if `obj` param is not an object
+ */
 function insertXObjElement(...args) {
   let item = null;
   try {
@@ -416,6 +446,7 @@ function insertXObjElement(...args) {
   };
   return item;
 };
+module.exports.insertXObjElement = insertXObjElement;
 
 /**
  * Inserts an element addressed by its key into a given object.
@@ -424,7 +455,7 @@ function insertXObjElement(...args) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
- * @returns {RVAL_emodif}
+ * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -437,6 +468,7 @@ function insertXObjElementEx(obj, name, opt) {
   };
   const { isSucceed, value: key } = evalKeyName(name);
   if (isSucceed) {
+    /** @type {INode} */
     const item = {};
     let prop = obj[key];
     let isSucceed = false;
@@ -469,16 +501,21 @@ function insertXObjElementEx(obj, name, opt) {
     throw new EvalKeyNameError(msg, { code });
   };
 };
+module.exports.insertXObjElementEx = insertXObjElementEx;
 
 /**
- * Deletes an element addressed by its key from a given object.
- * @function deleteXObjElement
+ *
+ * @callback deleteXObjElementFn
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
  * @see {@link deleteXObjElementEx} for param details
  */
+/**
+ * Deletes an element addressed by its key from a given object.
+ * @type {deleteXObjElementFn}
+ * @throws {TypeError} if `obj` param is not an object
+ */
 function deleteXObjElement(...args) {
   let isSucceed = false;
   try {
@@ -496,13 +533,14 @@ function deleteXObjElement(...args) {
   };
   return isSucceed;
 };
+module.exports.deleteXObjElement = deleteXObjElement;
 
 /**
  * Deletes an element addressed by its key from a given object.
  * @function deleteXObjElementEx
  * @param {object} obj - some object
  * @param {string} name - some child element
- * @returns {RVAL_emodif}
+ * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -528,6 +566,7 @@ function deleteXObjElementEx(obj, name) {
     throw new EvalKeyNameError(msg, { code });
   };
 };
+module.exports.deleteXObjElementEx = deleteXObjElementEx;
 
 /**
  * Renames an element addressed by its key.
@@ -573,1100 +612,196 @@ function renameXObjElement(obj, name = '', value = '') {
   };
   return isSucceed;
 };
+module.exports.renameXObjElement = renameXObjElement;
 
 /**
- * Checks whether an attribute is exists.
- * @function checkXObjAttribute
- * @param {object} obj - some object
- * @param {string} attr - some attribute ID
- * @param {string} [key] - some key
- * @returns {boolean}
+ * Inserts an elements into a given object.
+ * @function insertXObjElements
+ * @param {object} obj  - some object
+ * @param {...string} name - some child element name
+ * @param {OPT_inselops_L} [opt]
+ * @returns {number}
  * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ * @experimental
  */
-function checkXObjAttribute(obj, attr = '', key) {
-  let _obj = null;
-  try {
-    _obj = getXObjAttributes(obj, key);
-  } catch (err) {
-    throw err;
+function insertXObjElements(obj, ...args) {
+  if (!isPlainObject(obj)) {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
-  if (_obj === null) return false;
-  const { isSucceed, value: name } = evalKeyName(attr, false);
-  if (isSucceed) {
-    if (name === '') return false;
-  } else {
-    const { code, msg } = name;
-    throw new EvalKeyNameError(msg, { code });
+  let count = 0;
+  let len = args.length;
+  const opt = (
+    len > 0 && isPlainObject(args[len - 1])
+    ? (len--, args.pop())
+    : {}
+  );
+  for (let key of args) {
+    if (insertXObjElement(obj, key, opt) !== null) count++;
   };
-  return _obj[name] !== undefined;
+  return count;
 };
 
 /**
- * Deletes an attribute addressed by a given name.
- * @function deleteXObjAttribute
+ * An options for an element insertion ops
+ * @typedef {Object} OPT_inselops_S
+ * @property {boolean} [force=false]
+ * @property {boolean} [ripOldies=false]
+ */
+
+/**
+ * Inserts a list elements into a given object.
+ * @function insertXObjEList
  * @param {object} obj - some object
- * @param {string} attr - some attribute ID
- * @param {string} [key] - some key
- * @returns {boolean}
+ * @param {string} name - some child element name
+ * @param {OPT_inselops_S} [opt] - options
+ * @returns {?(object|object[])}
  * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
-function deleteXObjAttribute(obj, attr = '', key) {
-  let _obj = null;
+function insertXObjEList(...args) {
+  let item = null;
   try {
-    _obj = getXObjAttributes(obj, key);
+    ({ item } = insertXObjEListEx(...args));
   } catch (err) {
-    throw err;
-  };
-  if (_obj === null) return false;
-  const { isSucceed, value: name } = evalKeyName(attr, false);
-  if (isSucceed) {
-    let isSucceed = false;
-    if (name !== '') {
-      // // TODO: catch errors in strict mode
-      isSucceed = delete _obj[name];
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
     };
-    return isSucceed;
-  } else {
-    const { code, msg } = name;
-    throw new EvalKeyNameError(msg, { code });
   };
+  return item;
 };
 
 /**
- * Renames an attribute addressed by a given name.
+ * Inserts a list elements into a given object.
  * @since 0.2.0
- * @function renameXObjAttribute
+ * @function insertXObjEListEx
  * @param {object} obj - some object
- * @param {string} attr - some attribute ID
- * @param {string} value - new attribute ID
- * @param {string} [key] - some key
- * @returns {boolean}
+ * @param {string} name - some child element name
+ * @param {OPT_inselops_S} [opt] - options
+ * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `attr` param is not valid identifier
- * @throws {EvalKeyNameError} if `value` param is not valid identifier
- * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
+function insertXObjEListEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
     throw new EvalKeyNameError(
       XOBJ_TE_NPOBJ_EMSG,
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  const opt = false;
-  const { isSucceed, value: _key } = evalKeyName(key, opt);
+  const { isSucceed, value: key } = evalKeyName(name);
   if (isSucceed) {
+    /** @type {OPT_inselops_S} */
+    let {
+      force,
+      ripOldies,
+    } = isPlainObject(opt) ? opt : {};
+    if (typeof force !== 'boolean') force = false;
+    if (typeof ripOldies !== 'boolean') ripOldies = false;
+    let prop = obj[key];
     let isSucceed = false;
-    if (_key !== '') {
-      let _obj = obj[_key];
-      if (isPlainObject(_obj)) {
-        const { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
-        if (!isAcceptON) {
-          const { code, msg } = oname;
-          throw new EvalKeyNameError(msg, { code });
-        };
-        const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
-        if (!isAcceptNN) {
-          const { code, msg } = nname;
-          throw new EvalKeyNameError(msg, { code });
-        };
-        if (oname !== '' && oname in _obj && nname !== '') {
-          if (oname !== nname) {
-            _obj = Object.entries(_obj);
-            const index = _obj.findIndex((item) => item[0] === oname);
-            _obj[index][0] = nname;
-            obj[_key] = Object.fromEntries(_obj);
-          };
-          isSucceed = true;
-        };
+    if (
+      isNullOrUndef(prop)
+      || (force && (ripOldies || !isObject(prop)))
+    ) {
+      obj[key] = prop = [];
+      isSucceed = true;
+    } else {
+      if (isObject(prop)) {
+        if (!isArray(prop)) prop = [ prop ];
+        obj[key] = prop;
+        isSucceed = true;
       };
     };
-    return isSucceed;
+    return {
+      isSucceed,
+      item: isSucceed ? prop  : null,
+    };
   } else {
-    const { code, msg } = _key;
+    const { code, msg } = key;
     throw new EvalKeyNameError(msg, { code });
   };
 };
 
 /**
- * Extracts a parameter 'AS IS' from a given object.
- * @function readXObjParamRaw
+ * Inserts a chain of an elements into a given object.
+ * @function insertXObjEChain
  * @param {object} obj - some object
- * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
- * @returns {any}
+ * @param {...string} name - some child element name
+ * @param {object} [opt] - options
+ * @returns {?any}
  * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ * @experimental
  */
-function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
+function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {
     throw new EvalKeyNameError(
       XOBJ_TE_NPOBJ_EMSG,
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  const { isSucceed, value: _key } = evalKeyName(key, false);
-  if (!isSucceed) {
-    const { code, msg } = _key;
-    throw new EvalKeyNameError(msg, { code });
+  let result = null;
+  let len = args.length;
+  const opt = (
+    len > 0 && isPlainObject(args[len - 1])
+    ? (len--, args.pop())
+    : {}
+  );
+  if (len > 0) {
+    let parent = obj;
+    let child = null;
+    let isSucceed = false;
+    for (let key of args) {
+      child = insertXObjElement(parent, key, opt);
+      isSucceed = isPlainObject(child);
+      if (!isSucceed) break;
+      parent = child;
+    };
+    result = isSucceed ? parent : null;
   };
-  return _key !== '' ? obj[_key] : undefined;
+  return result;
 };
 
 /**
- * Writes a parameter 'AS IS' into a given object.
- * @function writeXObjParamRaw
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
+ * Clears a given node
+ * @param {object|object[]} node - some node
  * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ * @throws {TypeError} if `node`-param is not an object or array
  */
-function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
-  if (!isPlainObject(obj)) {
+function clearXObjNode(node) {
+  if (isObject(node)) {
+    if (isArray(node)) {
+      node.length = 0;
+      return true;
+    };
+    let isSucceed = false;
+    for (const key in node) {
+      // // TODO: catch errors in strict mode
+      isSucceed = delete node[key];
+    };
+    return isSucceed;
+  } else {
     throw new EvalKeyNameError(
       XOBJ_TE_NPOBJ_EMSG,
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  const { isSucceed, value: _key } = evalKeyName(key, false);
-  if (isSucceed) {
-    if (
-      _key === ''
-      || value === undefined
-      || isObject(value)
-      || typeof value === 'function'
-    ) {
-      return false;
-    };
-    obj[_key] = value;
-    return true;
-  } else {
-    const { code, msg } = _key;
-    throw new EvalKeyNameError(msg, { code });
-  };
 };
-
-/**
- * Extracts an attribute 'AS IS' from a given object.
- * @function readXObjAttrRaw
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {string} [key] - some key
- * @returns {any}
- * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `attr` param is not valid identifier
- */
-function readXObjAttrRaw(obj, attr = '', key) {
-  let _obj = null;
-  try {
-    _obj = getXObjAttributes(obj, key);
-  } catch (err) {
-    throw err;
-  };
-  if (_obj !== null) {
-    const { isSucceed, value: name } = evalKeyName(attr, false);
-    if (!isSucceed) {
-      const { code, msg } = name;
-      throw new EvalKeyNameError(msg, { code });
-    };
-    if (name !== '') return _obj[name];
-  };
-};
-
-/**
- * Writes a parameter into a given object.
- * @function writeXObjAttrRaw
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `attr` param is not valid identifier
- */
-function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
-  const { isSucceed, value: name } = evalKeyName(attr, false);
-  if (isSucceed) {
-    let isSucceed = false;
-    if (
-      name !== ''
-      && value !== undefined
-      && !isObject(value)
-      && typeof value !== 'function'
-    ) {
-      let _obj = null;
-      try {
-        const opt = { force: true, acceptIfList: true };
-        _obj = insertXObjElement(obj, key, opt);
-      } catch (err) {
-        throw err;
-      };
-      if (isArray(_obj)) {
-        // force a replacement of the old element if it's array
-        try {
-          const opt = { force: true, ripOldies: true };
-          _obj = insertXObjElement(obj, key, opt);
-        } catch (err) {
-          throw err;
-        };
-      };
-      if (_obj !== null) {
-        _obj[name] = value;
-        isSucceed = true;
-      };
-    };
-    return isSucceed;
-  } else {
-    const { code, msg } = name;
-    throw new EvalKeyNameError(msg, { code });
-  };
-};
-
-/**
- * Extracts a parameter from a given object and returns it as a string.
- * @function readXObjParam
- * @param {object} obj - some object
- * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if `obj` param is not an object
- */
-function readXObjParam(obj, key) {
-  const opt = {
-    useTrim: false,
-    numberToString: true,
-    boolToString: true,
-    defValue: '',
-  };
-  let result = undefined;
-  try {
-    result = readXObjParamEx(obj, opt, key);
-  } catch (err) {
-    throw err;
-  };
-  return result;
-};
-
-/**
- * Extracts a parameter from a given object and returns it as a boolean.
- * @function readXObjParamAsBool
- * @param {object} obj - some object
- * @param {boolean} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
- */
-function readXObjParamAsBool(obj, defValue, key) {
-  let result = undefined;
-  try {
-    result = readXObjParamRaw(obj, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return readAsBoolEx(result, defValue);
-};
-module.exports.readXObjParamAsBool = readXObjParamAsBool;
-
-/**
- * Extracts a parameter from a given object and returns it as a number.
- * @function readXObjParamAsNum
- * @param {object} obj - some object
- * @param {number} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {number}
- * @throws {TypeError} if `obj` param is not an object
- * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
- */
-function readXObjParamAsNum(obj, defValue, key) {
-  let result = undefined;
-  try {
-    result = readXObjParamRaw(obj, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return readAsNumberEx(result, defValue);
-};
-module.exports.readXObjParamAsNum = readXObjParamAsNum;
-
-/**
- * Extracts a parameter from a given object and returns it as 'index' value.
- * @function readXObjParamAsIndex
- * @param {object} obj - some object
- * @param {string} [key] - some key
- * @returns {number}
- * @throws {TypeError} if `obj` param is not an object
- */
-function readXObjParamAsIndex(obj, key) {
-  let result = undefined;
-  try {
-    result = readXObjParamRaw(obj, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return valueToIndex(result);
-};
-module.exports.readXObjParamAsIndex = readXObjParamAsIndex;
-
-/**
- * Extracts a parameter from a given object and returns it as a string.
- * @function readXObjParamEx
- * @param {object} obj - some object
- * @param {object} [opt] - options
- * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if `obj` param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
- */
-function readXObjParamEx(obj, opt, key) {
-  let result = undefined;
-  try {
-    result = readXObjParamRaw(obj, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  /** @type {OPT_valtostr} */
-  const _opt = isPlainObject(opt) ? opt : {
-    useTrim: false,
-    numberToString: true,
-    boolToString: true,
-    defValue: opt,
-  };
-  return readAsString(result, _opt);
-};
-
-/**
- * Tries to convert a given value to a string and writes it as a parameter
- * into a given object.
- * @function writeXObjParam
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjParam(obj, value, key) {
-  let isSucceed = false;
-  try {
-    const opt = {
-      useTrim: false,
-      numberToString: true,
-      boolToString: true,
-      defValue: '',
-    };
-    isSucceed = writeXObjParamEx(obj, value, opt, key);
-  } catch (err) {
-    throw err;
-  };
-  return isSucceed;
-};
-
-/**
- * Tries to convert a given value to a boolean and writes it as a parameter
- * into a given object.
- * @function writeXObjParamAsBool
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {boolean} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjParamAsBool(obj, value, defValue, key) {
-  let isSucceed = false;
-  if (value !== undefined || typeof defValue === 'boolean') {
-    const _value = readAsBoolEx(value, defValue).toString();
-    try {
-      isSucceed = writeXObjParamRaw(obj, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjParamAsBool = writeXObjParamAsBool;
-
-/**
- * Tries to convert a given value to a number and writes it as a parameter
- * into a given object.
- * @function writeXObjParamAsNum
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {number} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjParamAsNum(obj, value, defValue, key) {
-  let isSucceed = false;
-  if (value !== undefined || typeof defValue === 'number') {
-    const _value = readAsNumberEx(value, defValue).toString();
-    try {
-      isSucceed = writeXObjParamRaw(obj, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjParamAsNum = writeXObjParamAsNum;
-
-/**
- * Tries to convert a given value into an 'index' value and writes it
- * as a parameter into a given object.
- * @function writeXObjParamAsIndex
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjParamAsIndex(obj, value, key) {
-  let isSucceed = false;
-  if (value !== undefined) {
-    const _value = valueToIndex(value).toString();
-    try {
-      isSucceed = writeXObjParamRaw(obj, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
-
-/**
- * Tries to convert a given value to a string and writes it
- * as a parameter into a given object.
- * @function writeXObjParamEx
- * @param {object} obj - some object
- * @param {any} value - some value
- * @param {object} [opt] - options
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
- */
-function writeXObjParamEx(obj, value, opt, key) {
-  let isSucceed = false;
-  if (value !== undefined && typeof value !== 'function') {
-    let _opt = opt;
-    if (!isPlainObject(_opt)) {
-      const defValue = readAsString(_opt, {
-        useTrim: false,
-        numberToString: true,
-        boolToString: true,
-      });
-      _opt = {
-        useTrim: false,
-        numberToString: true,
-        boolToString: true,
-        defValue,
-      };
-    };
-    const _value = readAsString(value, _opt);
-    try {
-      isSucceed = writeXObjParamRaw(obj, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-
-/**
- * Extracts an attribute from a given object and returns it as a string.
- * @function readXObjAttr
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if `obj` param is not an object
- */
-function readXObjAttr(obj, attr, key) {
-  const opt = {
-    useTrim: true,
-    numberToString: true,
-    boolToString: true,
-    defValue: '',
-  };
-  let result = undefined;
-  try {
-    result = readXObjAttrEx(obj, attr, opt, key);
-  } catch (err) {
-    throw err;
-  };
-  return result;
-};
-
-/**
- * Extracts an attribute from a given object and returns it as a boolean.
- * @function readXObjAttrAsBool
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {boolean} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
- */
-function readXObjAttrAsBool(obj, attr, defValue, key) {
-  let result = undefined;
-  try {
-    result = readXObjAttrRaw(obj, attr, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return readAsBoolEx(result, defValue);
-};
-module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
-
-/**
- * Extracts an attribute from a given object and returns it as a number.
- * @function readXObjAttrAsNum
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {number} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {number}
- * @throws {TypeError} if `obj` param is not an object
- * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
- */
-function readXObjAttrAsNum(obj, attr, defValue, key) {
-  let result = undefined;
-  try {
-    result = readXObjAttrRaw(obj, attr, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return readAsNumberEx(result, defValue);
-};
-module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
-
-/**
- * Extracts an attribute from a given object and returns it as 'index' value.
- * @function readXObjAttrAsIndex
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {string} [key] - some key
- * @returns {number}
- * @throws {TypeError} if `obj` param is not an object
- */
-function readXObjAttrAsIndex(obj, attr, key) {
-  let result = undefined;
-  try {
-    result = readXObjAttrRaw(obj, attr, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return valueToIndex(result);
-};
-module.exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
-
-/**
- * Extracts an attribute from a given object and returns it as a string.
- * @function readXObjAttrEx
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {object} [opt] - options
- * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if `obj` param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
- */
-function readXObjAttrEx(obj, attr, opt, key) {
-  let result = undefined;
-  try {
-    result = readXObjAttrRaw(obj, attr, key);
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  /** @type {OPT_valtostr} */
-  const _opt = isPlainObject(opt) ? opt : {
-    useTrim: true,
-    numberToString: true,
-    boolToString: true,
-    defValue: opt,
-  };
-  return readAsString(result, _opt);
-};
-
-/**
- * Tries to convert a given value to a string and writes it as an attribute
- * into a given object.
- * @function writeXObjAttr
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjAttr(obj, attr, value, key) {
-  let isSucceed = false;
-  try {
-    const opt = {
-      useTrim: true,
-      numberToString: true,
-      boolToString: true,
-      defValue: '',
-    };
-    isSucceed = writeXObjAttrEx(obj, attr, value, opt, key);
-  } catch (err) {
-    throw err;
-  };
-  return isSucceed;
-};
-
-/**
- * Tries to convert a given value to a boolean and writes it as an attribute
- * into a given object.
- * @function writeXObjAttrAsBool
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {boolean} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
-  let isSucceed = false;
-  if (value !== undefined || typeof defValue === 'boolean') {
-    const _value = readAsBoolEx(value, defValue).toString();
-    try {
-      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
-
-/**
- * Tries to convert a given value to a number and writes it as an attribute
- * into a given object.
- * @function writeXObjAttrAsNum
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {number} [defValue] - default value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
-  let isSucceed = false;
-  if (value !== undefined || typeof defValue === 'number') {
-    const _value = readAsNumberEx(value, defValue).toString();
-    try {
-      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
-
-/**
- * Tries to convert a given value into an 'index' value and writes it
- * as an attribute into a given object.
- * @function writeXObjAttrAsIndex
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- */
-function writeXObjAttrAsIndex(obj, attr, value, key) {
-  let isSucceed = false;
-  if (value !== undefined) {
-    const _value = valueToIndex(value).toString();
-    try {
-      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-module.exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
-
-/**
- * Tries to convert a given value to a string and writes it as an attribute
- * into a given object.
- * @function writeXObjAttrEx
- * @param {object} obj - some object
- * @param {string} attr - some attribute
- * @param {any} value - some value
- * @param {object} [opt] - options
- * @param {string} [key] - some key
- * @returns {boolean}
- * @throws {TypeError} if `obj` param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
- */
-function writeXObjAttrEx(obj, attr, value, opt, key) {
-  let isSucceed = false;
-  if (value !== undefined && typeof value !== 'function') {
-    let _opt = opt;
-    if (!isPlainObject(_opt)) {
-      const defValue = readAsString(_opt, {
-        useTrim: true,
-        numberToString: true,
-        boolToString: true,
-      });
-      _opt = {
-        useTrim: true,
-        numberToString: true,
-        boolToString: true,
-        defValue,
-      };
-    };
-    const _value = readAsString(value, _opt);
-    try {
-      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-        }
-      };
-    };
-  };
-  return isSucceed;
-};
-
-/**
- * Inserts an elements into a given object.
- * @function insertXObjElements
- * @param {object} obj  - some object
- * @param {...string} name - some child element name
- * @param {OPT_inselops_L} [opt]
- * @returns {number}
- * @throws {TypeError} if `obj` param is not an object
- * @experimental
- */
-function insertXObjElements(obj, ...args) {
-  if (!isPlainObject(obj)) {
-    throw new EvalKeyNameError(
-      XOBJ_TE_NPOBJ_EMSG,
-      { code: XOBJ_TE_NPOBJ_ECODE },
-    );
-  };
-  let count = 0;
-  let len = args.length;
-  const opt = (
-    len > 0 && isPlainObject(args[len - 1])
-    ? (len--, args.pop())
-    : {}
-  );
-  for (let key of args) {
-    if (insertXObjElement(obj, key, opt) !== null) count++;
-  };
-  return count;
-};
-
-/**
- * An options for an element insertion ops
- * @typedef {Object} OPT_inselops_S
- * @property {boolean} [force=false]
- * @property {boolean} [ripOldies=false]
- */
-
-/**
- * Inserts a list elements into a given object.
- * @function insertXObjEList
- * @param {object} obj - some object
- * @param {string} name - some child element name
- * @param {OPT_inselops_S} [opt] - options
- * @returns {?(object|object[])}
- * @throws {TypeError} if `obj` param is not an object
- */
-function insertXObjEList(...args) {
-  let item = null;
-  try {
-    ({ item } = insertXObjEListEx(...args));
-  } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE :
-      case XOBJ_TE_KNES_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-      }
-    };
-  };
-  return item;
-};
-
-/**
- * Inserts a list elements into a given object.
- * @since 0.2.0
- * @function insertXObjEListEx
- * @param {object} obj - some object
- * @param {string} name - some child element name
- * @param {OPT_inselops_S} [opt] - options
- * @returns {RVAL_emodif}
- * @throws {TypeError} if `obj` param is not an object
- * @throws {EvalKeyNameError} if `nmae` param is not valid identifier
- */
-function insertXObjEListEx(obj, name, opt) {
-  if (!isPlainObject(obj)) {
-    throw new EvalKeyNameError(
-      XOBJ_TE_NPOBJ_EMSG,
-      { code: XOBJ_TE_NPOBJ_ECODE },
-    );
-  };
-  const { isSucceed, value: key } = evalKeyName(name);
-  if (isSucceed) {
-    /** @type {OPT_inselops_S} */
-    let {
-      force,
-      ripOldies,
-    } = isPlainObject(opt) ? opt : {};
-    if (typeof force !== 'boolean') force = false;
-    if (typeof ripOldies !== 'boolean') ripOldies = false;
-    let prop = obj[key];
-    let isSucceed = false;
-    if (
-      isNullOrUndef(prop)
-      || (force && (ripOldies || !isObject(prop)))
-    ) {
-      obj[key] = prop = [];
-      isSucceed = true;
-    } else {
-      if (isObject(prop)) {
-        if (!isArray(prop)) prop = [ prop ];
-        obj[key] = prop;
-        isSucceed = true;
-      };
-    };
-    return {
-      isSucceed,
-      item: isSucceed ? prop  : null,
-    };
-  } else {
-    const { code, msg } = key;
-    throw new EvalKeyNameError(msg, { code });
-  };
-};
-
-/**
- * Inserts a chain of an elements into a given object.
- * @function insertXObjEChain
- * @param {object} obj - some object
- * @param {...string} name - some child element name
- * @param {object} [opt] - options
- * @returns {?any}
- * @throws {TypeError} if `obj` param is not an object
- * @experimental
- */
-function insertXObjEChain(obj, ...args) {
-  if (!isPlainObject(obj)) {
-    throw new EvalKeyNameError(
-      XOBJ_TE_NPOBJ_EMSG,
-      { code: XOBJ_TE_NPOBJ_ECODE },
-    );
-  };
-  let result = null;
-  let len = args.length;
-  const opt = (
-    len > 0 && isPlainObject(args[len - 1])
-    ? (len--, args.pop())
-    : {}
-  );
-  if (len > 0) {
-    let parent = obj;
-    let child = null;
-    let isSucceed = false;
-    for (let key of args) {
-      child = insertXObjElement(parent, key, opt);
-      isSucceed = isPlainObject(child);
-      if (!isSucceed) break;
-      parent = child;
-    };
-    result = isSucceed ? parent : null;
-  };
-  return result;
-};
-
-/**
- * Clears a given node
- * @param {(object|object[])} node - some node
- * @returns {boolean}
- * @throws {TypeError} if `node`-param is not an object or array
- */
-function clearXObjNode(node) {
-  if (isObject(node)) {
-    if (isArray(node)) {
-      node.length = 0;
-      return true;
-    };
-    let isSucceed = false;
-    for (const key in node) {
-      // // TODO: catch errors in strict mode
-      isSucceed = delete node[key];
-    };
-    return isSucceed;
-  } else {
-    throw new EvalKeyNameError(
-      XOBJ_TE_NPOBJ_EMSG,
-      { code: XOBJ_TE_NPOBJ_ECODE },
-    );
-  };
-};
-module.exports.clearXObjNode = clearXObjNode;
+module.exports.clearXObjNode = clearXObjNode;
 
 // === module exports block ===
 
-module.exports.readXObjParamRaw = readXObjParamRaw;
-module.exports.readXObjParam = readXObjParam;
-module.exports.readXObjParamEx = readXObjParamEx;
-module.exports.writeXObjParamRaw = writeXObjParamRaw;
-module.exports.writeXObjParam = writeXObjParam;
-module.exports.writeXObjParamEx = writeXObjParamEx;
-
-module.exports.readXObjAttrRaw = readXObjAttrRaw;
-module.exports.readXObjAttr = readXObjAttr;
-module.exports.readXObjAttrEx = readXObjAttrEx;
-module.exports.writeXObjAttrRaw = writeXObjAttrRaw;
-module.exports.writeXObjAttr = writeXObjAttr;
-module.exports.writeXObjAttrEx = writeXObjAttrEx;
-
-module.exports.getXObjAttributes = getXObjAttributes;
-module.exports.checkXObjAttribute = checkXObjAttribute;
-module.exports.deleteXObjAttribute = deleteXObjAttribute;
-module.exports.renameXObjAttribute = renameXObjAttribute;
-
-module.exports.getXObjElement = getXObjElement;
-module.exports.addXObjElement = addXObjElement;
-module.exports.insertXObjElement = insertXObjElement;
-module.exports.insertXObjElementEx = insertXObjElementEx;
-module.exports.deleteXObjElement = deleteXObjElement;
-module.exports.deleteXObjElementEx = deleteXObjElementEx;
-module.exports.renameXObjElement = renameXObjElement;
-
 module.exports.evalXObjEName = evalXObjEName;
 module.exports.insertXObjEList = insertXObjEList;
 module.exports.insertXObjEListEx = insertXObjEListEx;
 
-// * inner *
-module.exports.evalKeyName = evalKeyName;
-
 // * experimental *
 module.exports.genXObjENameDescr = genXObjENameDescr;
 module.exports.insertXObjElements = insertXObjElements;