@ygracs/xobj-lib-js 0.1.2 → 0.2.1

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.063-20240624]
+// [v0.2.099-20250128]
 
 // === module init block ===
 
@@ -13,6 +13,54 @@ const {
 
 // === module extra block (helper functions) ===
 
+/**
+ * @typedef {Object} RVAL_reason
+ * @property {string} code - message ID
+ * @property {string} msg - message text
+ * @description 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
+ * @description A result of a value check ops.
+ */
+
+/**
+ * @function evalKeyName
+ * @param {any} value - key to validate
+ * @param {boolean} [opt=true]
+ * @returns {VCOR_evalkname}
+ * @inner
+ * @description Tries to convert a value into an ID.
+ */
+function evalKeyName(value, opt = true) {
+  if (typeof value !== 'string') {
+    return {
+      isSucceed: false,
+      value: {
+        code: XOBJ_TE_NSTR_ECODE,
+        msg: XOBJ_TE_NSTR_EMSG,
+      },
+    };
+  };
+  const key = value.trim();
+  if (opt && key === '') {
+    return {
+      isSucceed: false,
+      value: {
+        code: XOBJ_TE_KNES_ECODE,
+        msg: XOBJ_TE_KNES_EMSG,
+      },
+    };
+  };
+  return {
+    isSucceed: true,
+    value: key,
+  };
+};
+
 // === module main block ===
 
 /***
@@ -40,7 +88,13 @@ const XOBJ_TE_KNES_ECODE = 'ERR_XOBJ_INVARG_KEY';
  * (* function definitions *)
  */
 
-function evalXObjEName(value){
+/**
+ * @function evalXObjEName
+ * @param {any} value - some value to evaluate
+ * @returns {(null|number|string)}
+ * @description Tries to convert a value into an ID.
+ */
+function evalXObjEName(value) {
   //return valueToIDString(value); // // TODO: [?]
   let name = value;
   switch (typeof name) {
@@ -71,7 +125,13 @@ function evalXObjEName(value){
   return name;
 };
 
-function genXObjENameDescr(value){
+/**
+ * @function genXObjENameDescr
+ * @param {any} value
+ * @returns {object}
+ * @description Tries to convert a value into an element name description.
+ */
+function genXObjENameDescr(value) {
   let result = null;
   let name = null;
   let conditions = null;
@@ -124,28 +184,24 @@ function genXObjENameDescr(value){
 
 /**
  * @function getXObjElement
- * @param {object}
- * @param {ID_STRING}
- * @returns {?object}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @returns {?any}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
  * @description Extracts an element from a given object by its key.
  */
-function getXObjElement(obj, name){
-  let err = null;
+function getXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
+  let { isSucceed, value: key } = evalKeyName(name);
+  if (!isSucceed) {
+    const { code, msg } = key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
   // TODO: [?] check type of obj[key_name]
@@ -154,13 +210,13 @@ function getXObjElement(obj, name){
 
 /**
  * @function getXObjAttributes
- * @param {object}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {?object}
- * @throws {TypeError}
+ * @throws {TypeError} if first param is not an object
  * @description Extracts an attributes from a given object by its key.
  */
-function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
+function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
   let result = null;
   try {
     result = getXObjElement(obj, key);
@@ -172,46 +228,48 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
   return isPlainObject(result) ? result : null;
 };
 
+/**
+ * @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
+ * @description A result of an xObj modification ops
+ */
+
 /**
  * @function addXObjElement
- * @param {object}
- * @param {ID_STRING}
- * @returns {?object}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @returns {RVAL_emodif}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
  * @description Adds an element addressed by its key to a given object.
  */
-function addXObjElement(obj, name){
-  let err = null;
+function addXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
+  let { isSucceed, value: key } = evalKeyName(name);
+  if (!isSucceed) {
+    const { code, msg } = key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
   const item = {};
   let prop = obj[key];
-  let isSUCCEED = false;
-  // // TODO: [?] consider wheter or not do ops if new_key exists
+  isSucceed = false;
+  // // TODO: [?] consider whether or not do ops if new_key exists
   if (isNullOrUndef(prop)) {
     obj[key] = prop = item;
-    isSUCCEED = true;
+    isSucceed = true;
   } else if (isObject(prop)) {
     if (isArray(prop)) {
       prop.push(item);
@@ -219,394 +277,489 @@ function addXObjElement(obj, name){
       obj[key] = [ prop, item ];
     };
     prop = item;
-    isSUCCEED = true;
+    isSucceed = true;
   };
   return {
-    isSucceed: isSUCCEED,
-    item: isSUCCEED ? prop : null,
+    isSucceed,
+    item: isSucceed ? prop : null,
   };
 };
 
+/**
+ * @typedef {Object} OPT_inselops_L
+ * @property {boolean} [force=false]
+ * @property {boolean} [ripOldies=false]
+ * @property {boolean} [acceptIfList=false]
+ */
+
 /**
  * @function insertXObjElement
- * @param {object}
- * @param {ID_STRING}
- * @param {object} [opt]
- * @param {bool} [opt.force=false]
- * @param {bool} [opt.ripOldies=false]
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
- * @throws {TypeError}
+ * @throws {TypeError} if first param is not an object
+ * @description Inserts an element addressed by its key into a given object.
+ */
+function insertXObjElement(...args) {
+  let item = null;
+  try {
+    ({ item } = insertXObjElementEx(...args));
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return item;
+};
+
+/**
+ * @function insertXObjElementEx
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @param {OPT_inselops_L} [opt] - options
+ * @returns {RVAL_emodif}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ * @since 0.2.0
  * @description Inserts an element addressed by its key into a given object.
  */
-function insertXObjElement(obj, name, opt){
-  let err = null;
+function insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
+  let { isSucceed, value: key } = evalKeyName(name);
+  if (!isSucceed) {
+    const { code, msg } = key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
-    throw err;
-  };
-  const _options = isPlainObject(opt) ? opt : {};
-  let { force, ripOldies } = _options;
-  if (typeof force !== 'boolean') force = false;
-  if (typeof ripOldies !== 'boolean') ripOldies = false;
+  const item = {};
   let prop = obj[key];
-  let isACCEPTED = (
-    isNullOrUndef(prop)
-    || (force && (ripOldies || !isPlainObject(prop)))
-  );
-  if (isACCEPTED) {
-    obj[key] = prop = {};
+  isSucceed = false;
+  if (isNullOrUndef(prop)) {
+    obj[key] = prop = item;
+    isSucceed = true;
   } else {
-    isACCEPTED = isPlainObject(prop);
+    const _opt = isPlainObject(opt) ? opt : {};
+    let { force, ripOldies, acceptIfList } = _opt;
+    if (typeof force !== 'boolean') force = false;
+    if (typeof ripOldies !== 'boolean') ripOldies = false;
+    if (typeof acceptIfList !== 'boolean') acceptIfList = false;
+    if (force && (ripOldies || !isObject(prop))) {
+      obj[key] = prop = item;
+      isSucceed = true;
+    } else {
+      isSucceed = isPlainObject(prop) || (isArray(prop) && acceptIfList);
+    };
+  };
+  return {
+    isSucceed,
+    item: isSucceed ? prop : null,
   };
-  return isACCEPTED ? prop : null;
 };
 
 /**
  * @function deleteXObjElement
- * @param {object}
- * @param {ID_STRING}
- * @returns {bool}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
  * @description Deletes an element addressed by its key from a given object.
  */
-function deleteXObjElement(obj, name){
-  let err = null;
-  if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
-  };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
-    throw err;
+function deleteXObjElement(...args) {
+  let isSucceed = false;
+  try {
+    ({ isSucceed } = deleteXObjElementEx(...args));
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
   };
-  let result = false;
-  // // TODO: catch errors in strict mode
-  result = delete obj[key];
-  return result;
+  return isSucceed;
 };
 
 /**
  * @function deleteXObjElementEx
- * @param {object}
- * @param {ID_STRING}
- * @returns {object}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @returns {RVAL_emodif}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
  * @description Deletes an element addressed by its key from a given object.
  */
-function deleteXObjElementEx(obj, name){
-  let err = null;
+function deleteXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
+  let { isSucceed, value: key } = evalKeyName(name);
+  if (!isSucceed) {
+    const { code, msg } = key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
   let prop = obj[key];
-  let result = false;
+  isSucceed = false;
   // // TODO: catch errors in strict mode
-  result = delete obj[key];
+  isSucceed = delete obj[key];
   return {
-    isSucceed: result,
-    item: result && isObject(prop) ? prop : null,
+    isSucceed,
+    item: isSucceed && isObject(prop) ? prop : null,
   };
 };
 
 /**
  * @function renameXObjElement
- * @param {object}
- * @param {ID_STRING} - old key
- * @param {ID_STRING} - new key
- * @returns {bool}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @param {string} value - new element ID
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is not a string
+ * @throws {TypeError} if third param is not a string
  * @description Renames an element addressed by its key.
  */
-function renameXObjElement(obj, name, newName){
-  let err = null;
+function renameXObjElement(obj, name = '', value = '') {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string' || typeof newName !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
+  const opt = false;
+  let { isSucceed: isAcceptON, value: oname } = evalKeyName(name, opt);
+  if (!isAcceptON) {
+    const { code, msg } = oname;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const key = name.trim();
-  const newKey = newName.trim();
-  if (key === '' || newKey === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
+  let { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+  if (!isAcceptNN) {
+    const { code, msg } = nname;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const prop = obj[key];
-  let result = false;
-  if (prop !== undefined) {
-    if (key === newKey) return isObject(prop);
-    // // TODO:  consider wheter or not do ops if new_key exists
-    // // TODO: catch errors in strict mode
-    result = delete obj[key];
-    if (result) {
-      obj[newKey] = isObject(prop) ? prop : {};
+  let isSucceed = false;
+  if (oname !== '' && oname in obj && nname !== '') {
+    isSucceed = true;
+    if (oname !== nname) {
+      const prop = obj[oname];
+      obj[nname] = prop;
+      isSucceed = delete obj[oname];
+      if (!isSucceed) {
+        // undo change if failed delete old element
+        delete obj[nname];
+      };
     };
   };
-  return result;
+  return isSucceed;
 };
 
 /**
  * @function checkXObjAttribute
- * @param {object}
- * @param {ID_STRING}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Checks wheter an attribute is exists.
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Checks whether an attribute is exists.
  */
-function checkXObjAttribute(obj, attr = '', key){
-  if (typeof attr !== 'string') {
-    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  let objAttr = null;
+function checkXObjAttribute(obj, attr = '', key) {
+  let _obj = null;
   try {
-    objAttr = getXObjAttributes(obj, key);
+    _obj = getXObjAttributes(obj, key);
   } catch (err) {
     throw err;
   };
-  const attrName = attr.trim();
-  let result = false;
-  if (
-    objAttr !== null
-    && attrName !== ''
-    && objAttr[attrName] !== undefined
-  ) {
-    result = true;
+  if (_obj === null) return false;
+  let { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    if (name === '') return false;
+  } else {
+    const { code, msg } = name;
+    const err = new TypeError(msg);
+    err.code = code;
+    throw err;
   };
-  return result;
+  return _obj[name] !== undefined;
 };
 
 /**
  * @function deleteXObjAttribute
- * @param {object}
- * @param {ID_STRING}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Deletes an attribute addressed by a given key.
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Deletes an attribute addressed by a given name.
  */
-function deleteXObjAttribute(obj, attr = '', key){
-  if (typeof attr !== 'string') {
-    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  let objAttr = null;
+function deleteXObjAttribute(obj, attr = '', key) {
+  let _obj = null;
   try {
-    objAttr = getXObjAttributes(obj, key);
+    _obj = getXObjAttributes(obj, key);
   } catch (err) {
     throw err;
   };
-  const attrName = attr.trim();
-  let result = false;
-  if (objAttr !== null && attrName !== '') {
+  if (_obj === null) return false;
+  let { isSucceed, value: name } = evalKeyName(attr, false);
+  if (!isSucceed) {
+    const { code, msg } = name;
+    const err = new TypeError(msg);
+    err.code = code;
+    throw err;
+  };
+  isSucceed = false;
+  if (name !== '') {
     // // TODO: catch errors in strict mode
-    result = delete objAttr[attrName];
+    isSucceed = delete _obj[name];
   };
-  return result;
+  return isSucceed;
+};
+
+/**
+ * @function renameXObjAttribute
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} value - new attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is not an object
+ * @throws {TypeError} if third param is not an object
+ * @since 0.2.0
+ * @description Renames an attribute addressed by a given name.
+ */
+function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
+  if (!isPlainObject(obj)) {
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  const opt = false;
+  let { isSucceed, value: _key } = evalKeyName(key, opt);
+  if (!isSucceed) {
+    const { code, msg } = _key;
+    const err = new TypeError(msg);
+    err.code = code;
+    throw err;
+  };
+  isSucceed = false;
+  if (_key !== '') {
+    let _obj = obj[_key];
+    if (isPlainObject(_obj)) {
+      let { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
+      if (!isAcceptON) {
+        const { code, msg } = oname;
+        const err = new TypeError(msg);
+        err.code = code;
+        throw err;
+      };
+      let { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+      if (!isAcceptNN) {
+        const { code, msg } = nname;
+        const err = new TypeError(msg);
+        err.code = code;
+        throw err;
+      };
+      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;
+      };
+    };
+  };
+  return isSucceed;
 };
 
 /**
  * @function readXObjParamRaw
- * @param {object}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {any}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ * @description Extracts a parameter 'AS IS' from a given object.
  */
-function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME){
-  let err = null;
+function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof key !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
+  let { isSucceed, value: _key } = evalKeyName(key, false);
+  if (!isSucceed) {
+    const { code, msg } = _key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const _key = key.trim();
   return _key !== '' ? obj[_key] : undefined;
 };
 
 /**
  * @function writeXObjParamRaw
- * @param {object}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @param {object} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ * @description Writes a parameter 'AS IS' into a given object.
  */
-function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME){
-  let err = null;
+function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof key !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
+  let { isSucceed, value: _key } = evalKeyName(key, false);
+  if (!isSucceed) {
+    const { code, msg } = _key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const _key = key.trim();
-  let isSUCCEED = false;
-  if (_key !== '' && value !== undefined){
+  if (_key === '' || value === undefined) {
+    isSucceed = false;
+  } else {
     obj[_key] = value;
-    isSUCCEED = true;
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function readXObjAttrRaw
- * @param {object}
- * @param {ID_STRING}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
  * @returns {any}
- * @throws {TypeError}
- * @description Extracts an attribute from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ * @description Extracts an attribute 'AS IS' from a given object.
  */
-function readXObjAttrRaw(obj, attr = '', key){
-  if (typeof attr !== 'string') {
-    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  let objAttr = null;
+function readXObjAttrRaw(obj, attr = '', key) {
+  let _obj = null;
   try {
-    objAttr = getXObjAttributes(obj, key);
+    _obj = getXObjAttributes(obj, key);
   } catch (err) {
     throw err;
   };
-  const attrName = attr.trim();
-  if (objAttr !== null && attrName !== '') return objAttr[attrName];
+  if (_obj !== null) {
+    let { isSucceed, value: name } = evalKeyName(attr, false);
+    if (!isSucceed) {
+      const { code, msg } = name;
+      const err = new TypeError(msg);
+      err.code = code;
+      throw err;
+    };
+    if (name !== '') return _obj[name];
+  };
 };
 
 /**
  * @function writeXObjAttrRaw
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
+ * @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 first param is not an object
+ * @throws {TypeError} if third param is not a string
  * @description Writes a parameter into a given object.
  */
-function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME){
-  if (typeof attr !== 'string') {
-    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
+function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
+  let { isSucceed, value: name } = evalKeyName(attr, false);
+  if (!isSucceed) {
+    const { code, msg } = name;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
-  const attrName = attr.trim();
-  let objAttr = null;
-  let isSUCCEED = false;
-  if (attrName !== '' && value !== undefined) {
+  isSucceed = false;
+  if (name !== '' && value !== undefined) {
+    let _obj = null;
     try {
-      objAttr = insertXObjElement(obj, key, { force: true });
+      const opt = { force: true, acceptIfList: true };
+      _obj = insertXObjElement(obj, key, opt);
     } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE :
-        case XOBJ_TE_KNES_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-          break;
-        }
+      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 (objAttr !== null) {
-      objAttr[attrName] = value;
-      isSUCCEED = true;
+    if (_obj !== null) {
+      _obj[name] = value;
+      isSucceed = true;
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function readXObjParam
- * @param {object}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts a parameter from a given object
+ *              and returns it as string.
  */
-function readXObjParam(obj, key){
+function readXObjParam(obj, key) {
+  const opt = {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+    defValue: '',
+  };
   let result = undefined;
   try {
-    result = readXObjParamRaw(obj, key);
+    result = readXObjParamEx(obj, opt, key);
   } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-        break;
-      }
-    };
+    throw err;
   };
-  return readAsString(result, {
-    useTrim: false,
-    numberToString: true,
-    boolToString: true,
-  });
+  return result;
 };
 
 /**
- * @function readXObjParam
- * @param {object}
- * @param {bool}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @function readXObjParamAsBool
+ * @param {object} obj - some object
+ * @param {boolean} [defValue] - default value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts a parameter from a given object
+ *              and returns it as boolean.
  */
-function readXObjParamAsBool(obj, defValue, key){
+function readXObjParamAsBool(obj, defValue, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -617,7 +770,6 @@ function readXObjParamAsBool(obj, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -625,15 +777,16 @@ function readXObjParamAsBool(obj, defValue, key){
 };
 
 /**
- * @function readXObjParam
- * @param {object}
- * @param {number}
- * @param {ID_STRING} [key]
+ * @function readXObjParamAsNum
+ * @param {object} obj - some object
+ * @param {number} [defValue] - default value
+ * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts a parameter from a given object
+ *              and returns it as number.
  */
-function readXObjParamAsNum(obj, defValue, key){
+function readXObjParamAsNum(obj, defValue, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -644,7 +797,6 @@ function readXObjParamAsNum(obj, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -652,15 +804,17 @@ function readXObjParamAsNum(obj, defValue, key){
 };
 
 /**
- * @function readXObjParam
- * @param {object}
- * @param {string}
- * @param {ID_STRING} [key]
+ * @function readXObjParamEx
+ * @param {object} obj - some object
+ * @param {object} [opt] - options
+ * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts a parameter from a given object
+ *              and returns it as string.
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function readXObjParamAsStr(obj, defValue, key){
+function readXObjParamEx(obj, opt, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -671,27 +825,31 @@ function readXObjParamAsStr(obj, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
-  return readAsString(result, {
-    useTrim: false,
-    numberToString: true,
-    boolToString: true,
-    defValue,
-  });
+  let _opt = opt;
+  if (!isPlainObject(_opt)) {
+    _opt = {
+      useTrim: false,
+      numberToString: true,
+      boolToString: true,
+      defValue: _opt,
+    };
+  };
+  return readAsString(result, _opt);
 };
 
 /**
- * @function readXObjParam
- * @param {object}
- * @param {ID_STRING} [key]
- * @returns {index}
- * @throws {TypeError}
- * @description Extracts a parameter from a given object.
+ * @function readXObjParamAsIndex
+ * @param {object} obj - some object
+ * @param {string} [key] - some key
+ * @returns {number}
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts a parameter from a given object
+ *              and returns it as 'index' value.
  */
-function readXObjParamAsIndex(obj, key){
+function readXObjParamAsIndex(obj, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -702,7 +860,6 @@ function readXObjParamAsIndex(obj, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -711,54 +868,47 @@ function readXObjParamAsIndex(obj, key){
 
 /**
  * @function writeXObjParam
- * @param {object}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @param {object} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Tries to convert a given value to a string
+ *              and writes it as a parameter into a given object.
  */
-function writeXObjParam(obj, value, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
-    const _value = readAsString(value, {
+function writeXObjParam(obj, value, key) {
+  let isSucceed = false;
+  try {
+    const opt = {
       useTrim: false,
       numberToString: true,
       boolToString: true,
-    });
-    try {
-      isSUCCEED = writeXObjParamRaw(obj, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-          break;
-        }
-      };
+      defValue: '',
     };
+    isSucceed = writeXObjParamEx(obj, value, opt, key);
+  } catch (err) {
+    throw err;
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjParamAsBool
- * @param {object}
- * @param {any}
- * @param {bool}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a boolean
+ *              and writes it as a parameter into a given object.
  */
-function writeXObjParamAsBool(obj, value, defValue, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
+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);
+      isSucceed = writeXObjParamRaw(obj, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -766,30 +916,30 @@ function writeXObjParamAsBool(obj, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjParamAsNum
- * @param {object}
- * @param {any}
- * @param {number}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a number
+ *              and writes it as a parameter into a given object.
  */
-function writeXObjParamAsNum(obj, value, defValue, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
+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);
+      isSucceed = writeXObjParamRaw(obj, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -797,29 +947,29 @@ function writeXObjParamAsNum(obj, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjParamAsIndex
- * @param {object}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @param {object} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Tries to convert a given value into an 'index' value
+ *              and writes it as a parameter into a given object.
  */
-function writeXObjParamAsIndex(obj, value, key){
-  let isSUCCEED = false;
+function writeXObjParamAsIndex(obj, value, key) {
+  let isSucceed = false;
   if (value !== undefined) {
     const _value = valueToIndex(value).toString();
     try {
-      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+      isSucceed = writeXObjParamRaw(obj, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -827,40 +977,45 @@ function writeXObjParamAsIndex(obj, value, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjParamEx
- * @param {object}
- * @param {any}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @param {object} obj - some object
+ * @param {any} value - some value
+ * @param {object} [opt] - options
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if first param is not an object
+ * @description Tries to convert a given value to a string
+ *              and writes it as a parameter into a given object.
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function writeXObjParamEx(obj, value, defValue, key){
-  let isSUCCEED = false;
+function writeXObjParamEx(obj, value, opt, key) {
+  let isSucceed = false;
   if (value !== undefined) {
-    const _defValue = readAsString(defValue, {
-      useTrim: false,
-      numberToString: true,
-      boolToString: true,
-    });
-    const _value = readAsString(value, {
-      useTrim: false,
-      numberToString: true,
-      boolToString: true,
-      defValue: _defValue,
-    });
+    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);
+      isSucceed = writeXObjParamRaw(obj, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -868,56 +1023,51 @@ function writeXObjParamEx(obj, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function readXObjAttr
- * @param {object}
- * @param {ID_STRING}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError}
- * @description Extracts an attribute from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts an attribute from a given object
+ *              and returns it as string.
  */
-function readXObjAttr(obj, attr, key){
+function readXObjAttr(obj, attr, key) {
+  const opt = {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+    defValue: '',
+  };
   let result = undefined;
   try {
-    result = readXObjAttrRaw(obj, attr, key);
+    result = readXObjAttrEx(obj, attr, opt, key);
   } catch (err) {
-    switch (err.code) {
-      case XOBJ_TE_NSTR_ECODE : {
-        break;
-      }
-      default: {
-        throw err;
-        break;
-      }
-    };
+    throw err;
   };
-  return readAsString(result, {
-    useTrim: true,
-    numberToString: true,
-    boolToString: true,
-  });
+  return result;
 };
 
 /**
  * @function readXObjAttrAsBool
- * @param {object}
- * @param {ID_STRING}
- * @param {bool}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Extracts an attribute from a given object.
+ * @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 first param is not an object
+ * @description Extracts an attribute from a given object
+ *              and returns it as boolean.
  */
-function readXObjAttrAsBool(obj, attr, defValue, key){
+function readXObjAttrAsBool(obj, attr, defValue, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -928,7 +1078,6 @@ function readXObjAttrAsBool(obj, attr, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -937,15 +1086,16 @@ function readXObjAttrAsBool(obj, attr, defValue, key){
 
 /**
  * @function readXObjAttrAsNum
- * @param {object}
- * @param {ID_STRING}
- * @param {number}
- * @param {ID_STRING} [key]
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute
+ * @param {number} [defValue] - default value
+ * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError}
- * @description Extracts an attribute from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts an attribute from a given object
+ *              and returns it as number.
  */
-function readXObjAttrAsNum(obj, attr, defValue, key){
+function readXObjAttrAsNum(obj, attr, defValue, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -956,7 +1106,6 @@ function readXObjAttrAsNum(obj, attr, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -964,16 +1113,18 @@ function readXObjAttrAsNum(obj, attr, defValue, key){
 };
 
 /**
- * @function readXObjAttrAsStr
- * @param {object}
- * @param {ID_STRING}
- * @param {string}
- * @param {ID_STRING} [key]
+ * @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}
- * @description Extracts an attribute from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts an attribute from a given object
+ *              and returns it as string.
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function readXObjAttrAsStr(obj, attr, defValue, key){
+function readXObjAttrEx(obj, attr, opt, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -984,28 +1135,32 @@ function readXObjAttrAsStr(obj, attr, defValue, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
-  return readAsString(result, {
-    useTrim: true,
-    numberToString: true,
-    boolToString: true,
-    defValue,
-  });
+  let _opt = opt;
+  if (!isPlainObject(_opt)) {
+    _opt = {
+      useTrim: true,
+      numberToString: true,
+      boolToString: true,
+      defValue: _opt,
+    };
+  };
+  return readAsString(result, _opt);
 };
 
 /**
  * @function readXObjAttrAsIndex
- * @param {object}
- * @param {ID_STRING}
- * @param {ID_STRING} [key]
- * @returns {index}
- * @throws {TypeError}
- * @description Extracts an attribute from a given object.
+ * @param {object} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
+ * @returns {number}
+ * @throws {TypeError} if first param is not an object
+ * @description Extracts an attribute from a given object
+ *              and returns it as 'index' value.
  */
-function readXObjAttrAsIndex(obj, attr, key){
+function readXObjAttrAsIndex(obj, attr, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -1016,7 +1171,6 @@ function readXObjAttrAsIndex(obj, attr, key){
       }
       default: {
         throw err;
-        break;
       }
     };
   };
@@ -1025,56 +1179,49 @@ function readXObjAttrAsIndex(obj, attr, key){
 
 /**
  * @function writeXObjAttr
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a string
+ *              and writes it as an attribute into a given object.
  */
-function writeXObjAttr(obj, attr, value, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
-    const _value = readAsString(value, {
+function writeXObjAttr(obj, attr, value, key) {
+  let isSucceed = false;
+  try {
+    const opt = {
       useTrim: true,
       numberToString: true,
       boolToString: true,
-    });
-    try {
-      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
-    } catch (err) {
-      switch (err.code) {
-        case XOBJ_TE_NSTR_ECODE : {
-          break;
-        }
-        default: {
-          throw err;
-          break;
-        }
-      };
+      defValue: '',
     };
+    isSucceed = writeXObjAttrEx(obj, attr, value, opt, key);
+  } catch (err) {
+    throw err;
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjAttrAsBool
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {bool}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a boolean
+ *              and writes it as an attribute into a given object.
  */
-function writeXObjAttrAsBool(obj, attr, value, defValue, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
+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);
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -1082,31 +1229,31 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjAttrAsNum
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {number}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a number
+ *              and writes it as an attribute into a given object.
  */
-function writeXObjAttrAsNum(obj, attr, value, defValue, key){
-  let isSUCCEED = false;
-  if (value !== undefined) {
+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);
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -1114,30 +1261,30 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjAttrAsIndex
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value into an 'index' value
+ *              and writes it as an attribute into a given object.
  */
-function writeXObjAttrAsIndex(obj, attr, value, key){
-  let isSUCCEED = false;
+function writeXObjAttrAsIndex(obj, attr, value, key) {
+  let isSucceed = false;
   if (value !== undefined) {
     const _value = valueToIndex(value).toString();
     try {
-      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -1145,41 +1292,46 @@ function writeXObjAttrAsIndex(obj, attr, value, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function writeXObjAttrEx
- * @param {object}
- * @param {ID_STRING}
- * @param {any}
- * @param {any}
- * @param {ID_STRING} [key]
- * @returns {bool}
- * @throws {TypeError}
- * @description Writes a parameter into a given object.
+ * @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 first param is not an object
+ * @description Tries to convert a given value to a string
+ *              and writes it as an attribute into a given object.
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function writeXObjAttrEx(obj, attr, value, defValue, key){
-  let isSUCCEED = false;
+function writeXObjAttrEx(obj, attr, value, opt, key) {
+  let isSucceed = false;
   if (value !== undefined) {
-    const _defValue = readAsString(defValue, {
-      useTrim: true,
-      numberToString: true,
-      boolToString: true,
-    });
-    const _value = readAsString(value, {
-      useTrim: true,
-      numberToString: true,
-      boolToString: true,
-      defValue: _defValue,
-    });
+    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);
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
     } catch (err) {
       switch (err.code) {
         case XOBJ_TE_NSTR_ECODE : {
@@ -1187,125 +1339,158 @@ function writeXObjAttrEx(obj, attr, value, defValue, key){
         }
         default: {
           throw err;
-          break;
         }
       };
     };
   };
-  return isSUCCEED;
+  return isSucceed;
 };
 
 /**
  * @function insertXObjElements
- * @param {object}
- * @param {...ID_STRING} args - list of a keys
- * @param {object} [opt]
+ * @param {object} obj
+ * @param {...string} name
+ * @param {OPT_inselops_L} [opt]
  * @returns {number}
- * @throws {TypeError}
+ * @throws {TypeError} if first param is not an object
  * @description Inserts an elements into a given object.
  */
-function insertXObjElements(obj, ...args){
+function insertXObjElements(obj, ...args) {
   if (!isPlainObject(obj)) {
-    let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  const len = args.length;
-  const hasOpt = len > 0 && isPlainObject(args[len - 1]);
-  const opt = hasOpt ? args.pop() : {};
-  const names = readAsListS({
-    useTrim: true,
-    keepEmpty: false,
-  }, ...args);
   let count = 0;
-  for (let key of names) {
+  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;
 };
 
+/**
+ * @typedef {Object} OPT_inselops_S
+ * @property {boolean} [force=false]
+ * @property {boolean} [ripOldies=false]
+ */
+
 /**
  * @function insertXObjEList
- * @param {object}
- * @param {ID_STRING}
- * @param {object} [opt]
- * @param {bool} [opt.force=false]
- * @param {bool} [opt.ripOldies=false]
- * @returns {?any}
- * @throws {TypeError}
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @param {OPT_inselops_S} [opt] - options
+ * @returns {?(object|object[])}
+ * @throws {TypeError} if first param is not an object
  * @description Inserts a list elements into a given object.
  */
-function insertXObjEList(obj, name, opt){
-  let err = null;
+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;
+};
+
+/**
+ * @function insertXObjEListEx
+ * @param {object} obj - some object
+ * @param {string} name - some child element
+ * @param {OPT_inselops_S} [opt] - options
+ * @returns {RVAL_emodif}
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ * @since 0.2.0
+ * @description Inserts a list elements into a given object.
+ */
+function insertXObjEListEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
-    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  if (typeof name !== 'string') {
-    err = new TypeError(XOBJ_TE_NSTR_EMSG);
-    err.code = XOBJ_TE_NSTR_ECODE;
-    throw err;
-  };
-  const key = name.trim();
-  if (key === '') {
-    err = new TypeError(XOBJ_TE_KNES_EMSG);
-    err.code = XOBJ_TE_KNES_ECODE;
+  let { isSucceed, value: key } = evalKeyName(name);
+  if (!isSucceed) {
+    const { code, msg } = key;
+    const err = new TypeError(msg);
+    err.code = code;
     throw err;
   };
   const _options = isPlainObject(opt) ? opt : {};
   let { force, ripOldies } = _options;
   if (typeof force !== 'boolean') force = false;
   if (typeof ripOldies !== 'boolean') ripOldies = false;
-  let item = obj[key];
-  let isACCEPTED = (
-    isNullOrUndef(item)
-    || (force && (ripOldies || !isArray(item)))
-  );
-  if (isACCEPTED) {
-    obj[key] = item = [];
+  let prop = obj[key];
+  isSucceed = false;
+  if (
+    isNullOrUndef(prop)
+    || (force && (ripOldies || !isObject(prop)))
+  ) {
+    obj[key] = prop = [];
+    isSucceed = true;
   } else {
-    isACCEPTED = isArray(item);
-    if (!isACCEPTED && isPlainObject(item)) {
-      obj[key] = item = [ item ];
-      isACCEPTED = true;
+    if (isObject(prop)) {
+      if (!isArray(prop)) prop = [ prop ];
+      obj[key] = prop;
+      isSucceed = true;
     };
   };
-  return isACCEPTED ? item  : null;
+  return {
+    isSucceed,
+    item: isSucceed ? prop  : null,
+  };
 };
 
 /**
  * @function insertXObjEChain
- * @param {object}
- * @param {ID_STRING}
- * @param {...ID_STRING} args - a list of keys
- * @param {object} [opt]
+ * @param {object} obj - some object
+ * @param {...string} name - some child element
+ * @param {object} [opt] - options
  * @returns {?any}
- * @throws {TypeError}
+ * @throws {TypeError} if first param is not an object
  * @description Inserts a chain of an elements into a given object.
  */
-function insertXObjEChain(obj, ...args){
+function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {
-    let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
     err.code = XOBJ_TE_NPOBJ_ECODE;
     throw err;
   };
-  const len = args.length;
-  const hasOpt = len > 0 && isPlainObject(args[len - 1]);
-  const opt = hasOpt ? args.pop() : {};
-  const names = readAsListS({
-    useTrim: true,
-    keepEmpty: false,
-  }, ...args);
-  let curObj = obj;
-  let isSUCCEED = false;
-  for (let key of names) {
-    obj = insertXObjElement(obj, key, opt);
-    isSUCCEED = isPlainObject(obj);
-    if (!isSUCCEED) break;
-    curObj = obj;
-  };
-  return isSUCCEED ? curObj : null;
+  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;
 };
 
 /***
@@ -1314,50 +1499,63 @@ function insertXObjEChain(obj, ...args){
 
 // === module exports block ===
 
-exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
-exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
-
-exports.evalXObjEName = evalXObjEName;
-
-exports.readXObjParamRaw = readXObjParamRaw;
-exports.readXObjParam = readXObjParam;
-exports.readXObjParamAsBool = readXObjParamAsBool;
-exports.readXObjParamAsNum = readXObjParamAsNum;
-exports.readXObjParamAsStr = readXObjParamAsStr;
-exports.readXObjParamAsIndex = readXObjParamAsIndex;
-exports.writeXObjParamRaw = writeXObjParamRaw;
-exports.writeXObjParam = writeXObjParam;
-exports.writeXObjParamAsBool = writeXObjParamAsBool;
-exports.writeXObjParamAsNum = writeXObjParamAsNum;
-exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
-exports.writeXObjParamEx = writeXObjParamEx;
-
-exports.readXObjAttrRaw = readXObjAttrRaw;
-exports.readXObjAttr = readXObjAttr;
-exports.readXObjAttrAsBool = readXObjAttrAsBool;
-exports.readXObjAttrAsNum = readXObjAttrAsNum;
-exports.readXObjAttrAsStr = readXObjAttrAsStr;
-exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
-exports.writeXObjAttrRaw = writeXObjAttrRaw;
-exports.writeXObjAttr = writeXObjAttr;
-exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
-exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
-exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
-exports.writeXObjAttrEx = writeXObjAttrEx;
-
-exports.getXObjAttributes = getXObjAttributes;
-exports.checkXObjAttribute = checkXObjAttribute;
-exports.deleteXObjAttribute = deleteXObjAttribute;
-
-exports.getXObjElement = getXObjElement;
-exports.insertXObjElement = insertXObjElement;
-exports.addXObjElement = addXObjElement;
-exports.deleteXObjElement = deleteXObjElement;
-exports.deleteXObjElementEx = deleteXObjElementEx;
-exports.renameXObjElement = renameXObjElement;
-
-exports.insertXObjElements = insertXObjElements;
-exports.insertXObjEList = insertXObjEList;
-exports.insertXObjEChain = insertXObjEChain;
-
-exports.genXObjENameDescr = genXObjENameDescr;
+module.exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
+module.exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
+
+module.exports.readXObjParamRaw = readXObjParamRaw;
+module.exports.readXObjParam = readXObjParam;
+module.exports.readXObjParamAsBool = readXObjParamAsBool;
+module.exports.readXObjParamAsNum = readXObjParamAsNum;
+module.exports.readXObjParamEx = readXObjParamEx;
+module.exports.readXObjParamAsIndex = readXObjParamAsIndex;
+module.exports.writeXObjParamRaw = writeXObjParamRaw;
+module.exports.writeXObjParam = writeXObjParam;
+module.exports.writeXObjParamAsBool = writeXObjParamAsBool;
+module.exports.writeXObjParamAsNum = writeXObjParamAsNum;
+module.exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
+module.exports.writeXObjParamEx = writeXObjParamEx;
+
+module.exports.readXObjAttrRaw = readXObjAttrRaw;
+module.exports.readXObjAttr = readXObjAttr;
+module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
+module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
+module.exports.readXObjAttrEx = readXObjAttrEx;
+module.exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
+module.exports.writeXObjAttrRaw = writeXObjAttrRaw;
+module.exports.writeXObjAttr = writeXObjAttr;
+module.exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
+module.exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
+module.exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
+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;
+/* experimental */
+module.exports.insertXObjElements = insertXObjElements;
+/* experimental */
+module.exports.insertXObjEChain = insertXObjEChain;
+
+/** @deprecated */
+module.exports.readXObjParamAsStr = readXObjParamEx;
+/** @deprecated */
+module.exports.readXObjAttrAsStr = readXObjAttrEx;