@ygracs/xobj-lib-js 0.2.9-b.2 → 0.3.0

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.127-20260222]
+// [v0.3.134-20260303]
 
 // === module init block ===
 
@@ -37,23 +37,32 @@ const {
 
 // === module inner block ===
 
+/**
+ * An error description of a value check ops on fail.
+ * @since 0.3.0
+ * @typedef {Object} IEvalKeyNameReasonOnFail
+ * @property {string} code - message ID
+ * @property {string} msg - message text
+ */
+
 /**
  * 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.
  */
 
 /**
  * An options setting for `evalKeyName` function
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameOptions
  * @property {boolean} [onlyNES] - a flag to accept only a non-empty string values
  */
 
 /**
  * A result of `evalKeyName` function if succeed
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameResultOnSuccess
  * @property {true} isSucceed - ops flag
  * @property {string} value - result value
@@ -61,15 +70,15 @@ const {
 
 /**
  * A result of `evalKeyName` function if failed
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameResultOnFail
  * @property {false} isSucceed - ops flag
- * @property {RVAL_reason} value - reason of fail
+ * @property {IEvalKeyNameReasonOnFail} value - reason of fail
  */
 
 /**
  * A result of `evalKeyName` function
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {(IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail)} IEvalKeyNameResult
  */
 
@@ -78,7 +87,7 @@ const {
  * @typedef {Object} VCOR_evalkname
  * @property {boolean} isSucceed - ops flag
  * @property {(string|RVAL_reason)} value - result value or reson if failed
- * @todo \[from v0.2.x] make obsolete. Use `IEvalKeyNameResult` instead.
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
  */
 
 /**
@@ -165,12 +174,22 @@ function evalXObjEName(value) {
   return name;
 };
 
+/**
+ * Some conditions applied to an element as a result of an element name pattern
+ * evaluation ops.
+ * @since 0.3.0
+ * @typedef {Object} XObjENameDescrConditions
+ * @property {any} name - element name
+ * @property {any} type - element type
+ * @property {any} [value] - some 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 {?object} conditions - some conditions applied to an element
+ * @property {?XObjENameDescrConditions} conditions - some conditions applied to an element
  */
 
 /**
@@ -178,6 +197,7 @@ function evalXObjEName(value) {
  * @function genXObjENameDescr
  * @param {any} value - element name pattern
  * @returns {XObjENameDescr}
+ * @experimental
  */
 function genXObjENameDescr(value) {
   let result = null;
@@ -236,8 +256,8 @@ function genXObjENameDescr(value) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {?any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function getXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
@@ -261,7 +281,7 @@ function getXObjElement(obj, name) {
  * @param {object} obj - some object
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {?object}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
   let result = null;
@@ -293,11 +313,39 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
  * @function addXObjElement
  * @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
+ */
+function addXObjElement(...args) {
+  let item = null;
+  try {
+    ({ item } = addXObjElementEx(...args));
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return item;
+};
+
+/**
+ * Adds an element addressed by its key to a given object.
+ * @since 0.3.0
+ * @function addXObjElementEx
+ * @param {object} obj - some object
+ * @param {string} name - some child element
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-function addXObjElement(obj, name) {
+function addXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
     throw new EvalKeyNameError(
       XOBJ_TE_NPOBJ_EMSG,
@@ -331,6 +379,7 @@ function addXObjElement(obj, name) {
     throw new EvalKeyNameError(msg, { code });
   };
 };
+module.exports.addXObjElementEx = addXObjElementEx;
 
 /**
  * An options for an element insertion ops
@@ -347,7 +396,7 @@ function addXObjElement(obj, name) {
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
 function insertXObjElement(...args) {
@@ -376,8 +425,8 @@ function insertXObjElement(...args) {
  * @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 {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -427,7 +476,7 @@ function insertXObjElementEx(obj, name, opt) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link deleteXObjElementEx} for param details
  */
 function deleteXObjElement(...args) {
@@ -454,8 +503,8 @@ function deleteXObjElement(...args) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function deleteXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
@@ -487,9 +536,9 @@ function deleteXObjElementEx(obj, name) {
  * @param {string} name - some child element
  * @param {string} value - new element ID
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
+ * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
 function renameXObjElement(obj, name = '', value = '') {
   if (!isPlainObject(obj)) {
@@ -532,8 +581,8 @@ function renameXObjElement(obj, name = '', value = '') {
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 function checkXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -560,8 +609,8 @@ function checkXObjAttribute(obj, attr = '', key) {
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
@@ -594,10 +643,10 @@ function deleteXObjAttribute(obj, attr = '', key) {
  * @param {string} value - new attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
- * @throws {EvalKeyNameError} if forth param is not valid identifier
+ * @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
  */
 function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
   if (!isPlainObject(obj)) {
@@ -647,8 +696,8 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
  * @param {object} obj - some object
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -672,8 +721,8 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
  * @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 {EvalKeyNameError} if third param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -707,8 +756,8 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
@@ -735,8 +784,8 @@ function readXObjAttrRaw(obj, attr = '', key) {
  * @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 {EvalKeyNameError} if second param is not valid identifier
+ * @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);
@@ -782,7 +831,7 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
  * @param {object} obj - some object
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjParam(obj, key) {
   const opt = {
@@ -807,7 +856,7 @@ function readXObjParam(obj, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -826,6 +875,7 @@ function readXObjParamAsBool(obj, defValue, key) {
   };
   return readAsBoolEx(result, defValue);
 };
+module.exports.readXObjParamAsBool = readXObjParamAsBool;
 
 /**
  * Extracts a parameter from a given object and returns it as a number.
@@ -834,7 +884,7 @@ function readXObjParamAsBool(obj, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -853,18 +903,17 @@ function readXObjParamAsNum(obj, defValue, key) {
   };
   return readAsNumberEx(result, defValue);
 };
+module.exports.readXObjParamAsNum = readXObjParamAsNum;
 
 /**
- * Extracts a parameter from a given object and returns it as a string.
- * @function readXObjParamEx
+ * Extracts a parameter from a given object and returns it as 'index' value.
+ * @function readXObjParamAsIndex
  * @param {object} obj - some object
- * @param {object} [opt] - options
  * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if first param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ * @returns {number}
+ * @throws {TypeError} if `obj` param is not an object
  */
-function readXObjParamEx(obj, opt, key) {
+function readXObjParamAsIndex(obj, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -878,25 +927,21 @@ function readXObjParamEx(obj, opt, key) {
       }
     };
   };
-  /** @type {OPT_valtostr} */
-  const _opt = isPlainObject(opt) ? opt : {
-    useTrim: false,
-    numberToString: true,
-    boolToString: true,
-    defValue: opt,
-  };
-  return readAsString(result, _opt);
+  return valueToIndex(result);
 };
+module.exports.readXObjParamAsIndex = readXObjParamAsIndex;
 
 /**
- * Extracts a parameter from a given object and returns it as 'index' value.
- * @function 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 {number}
- * @throws {TypeError} if first param is not an object
+ * @returns {string}
+ * @throws {TypeError} if `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function readXObjParamAsIndex(obj, key) {
+function readXObjParamEx(obj, opt, key) {
   let result = undefined;
   try {
     result = readXObjParamRaw(obj, key);
@@ -910,7 +955,14 @@ function readXObjParamAsIndex(obj, key) {
       }
     };
   };
-  return valueToIndex(result);
+  /** @type {OPT_valtostr} */
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
+  };
+  return readAsString(result, _opt);
 };
 
 /**
@@ -921,7 +973,7 @@ function readXObjParamAsIndex(obj, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParam(obj, value, key) {
   let isSucceed = false;
@@ -948,7 +1000,7 @@ function writeXObjParam(obj, value, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsBool(obj, value, defValue, key) {
   let isSucceed = false;
@@ -969,6 +1021,7 @@ function writeXObjParamAsBool(obj, value, defValue, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjParamAsBool = writeXObjParamAsBool;
 
 /**
  * Tries to convert a given value to a number and writes it as a parameter
@@ -979,7 +1032,7 @@ function writeXObjParamAsBool(obj, value, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsNum(obj, value, defValue, key) {
   let isSucceed = false;
@@ -1000,6 +1053,7 @@ function writeXObjParamAsNum(obj, value, defValue, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjParamAsNum = writeXObjParamAsNum;
 
 /**
  * Tries to convert a given value into an 'index' value and writes it
@@ -1009,7 +1063,7 @@ function writeXObjParamAsNum(obj, value, defValue, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsIndex(obj, value, key) {
   let isSucceed = false;
@@ -1030,6 +1084,7 @@ function writeXObjParamAsIndex(obj, value, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
 
 /**
  * Tries to convert a given value to a string and writes it
@@ -1040,7 +1095,7 @@ function writeXObjParamAsIndex(obj, value, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -1084,7 +1139,7 @@ function writeXObjParamEx(obj, value, opt, key) {
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjAttr(obj, attr, key) {
   const opt = {
@@ -1110,7 +1165,7 @@ function readXObjAttr(obj, attr, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -1129,6 +1184,7 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
   };
   return readAsBoolEx(result, defValue);
 };
+module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
 
 /**
  * Extracts an attribute from a given object and returns it as a number.
@@ -1138,7 +1194,7 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -1157,19 +1213,18 @@ function readXObjAttrAsNum(obj, attr, defValue, key) {
   };
   return readAsNumberEx(result, defValue);
 };
+module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
 
 /**
- * Extracts an attribute from a given object and returns it as a string.
- * @function readXObjAttrEx
+ * 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 {object} [opt] - options
  * @param {string} [key] - some key
- * @returns {string}
- * @throws {TypeError} if first param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ * @returns {number}
+ * @throws {TypeError} if `obj` param is not an object
  */
-function readXObjAttrEx(obj, attr, opt, key) {
+function readXObjAttrAsIndex(obj, attr, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -1183,26 +1238,22 @@ function readXObjAttrEx(obj, attr, opt, key) {
       }
     };
   };
-  /** @type {OPT_valtostr} */
-  const _opt = isPlainObject(opt) ? opt : {
-    useTrim: true,
-    numberToString: true,
-    boolToString: true,
-    defValue: opt,
-  };
-  return readAsString(result, _opt);
+  return valueToIndex(result);
 };
+module.exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
 
 /**
- * Extracts an attribute from a given object and returns it as 'index' value.
- * @function 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 {number}
- * @throws {TypeError} if first param is not an object
+ * @returns {string}
+ * @throws {TypeError} if `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-function readXObjAttrAsIndex(obj, attr, key) {
+function readXObjAttrEx(obj, attr, opt, key) {
   let result = undefined;
   try {
     result = readXObjAttrRaw(obj, attr, key);
@@ -1216,7 +1267,14 @@ function readXObjAttrAsIndex(obj, attr, key) {
       }
     };
   };
-  return valueToIndex(result);
+  /** @type {OPT_valtostr} */
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
+  };
+  return readAsString(result, _opt);
 };
 
 /**
@@ -1228,7 +1286,7 @@ function readXObjAttrAsIndex(obj, attr, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttr(obj, attr, value, key) {
   let isSucceed = false;
@@ -1256,7 +1314,7 @@ function writeXObjAttr(obj, attr, value, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
   let isSucceed = false;
@@ -1277,6 +1335,7 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
 
 /**
  * Tries to convert a given value to a number and writes it as an attribute
@@ -1288,7 +1347,7 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
   let isSucceed = false;
@@ -1309,6 +1368,7 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
 
 /**
  * Tries to convert a given value into an 'index' value and writes it
@@ -1319,7 +1379,7 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsIndex(obj, attr, value, key) {
   let isSucceed = false;
@@ -1340,6 +1400,7 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
   };
   return isSucceed;
 };
+module.exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
 
 /**
  * Tries to convert a given value to a string and writes it as an attribute
@@ -1351,7 +1412,7 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @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) {
@@ -1395,7 +1456,8 @@ function writeXObjAttrEx(obj, attr, value, opt, key) {
  * @param {...string} name - some child element name
  * @param {OPT_inselops_L} [opt]
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
 function insertXObjElements(obj, ...args) {
   if (!isPlainObject(obj)) {
@@ -1431,7 +1493,7 @@ function insertXObjElements(obj, ...args) {
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
  * @returns {?(object|object[])}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function insertXObjEList(...args) {
   let item = null;
@@ -1459,8 +1521,8 @@ function insertXObjEList(...args) {
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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)) {
@@ -1510,7 +1572,8 @@ function insertXObjEListEx(obj, name, opt) {
  * @param {...string} name - some child element name
  * @param {object} [opt] - options
  * @returns {?any}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
 function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {
@@ -1572,28 +1635,16 @@ module.exports.clearXObjNode = clearXObjNode;
 
 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;