@ygracs/xobj-lib-js 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+#### *v0.2.3*
+
+Release version.
+
+> - update `xObj.md`;
+> - add a new `reservedKeys` property to a `TXmlContentParseOptions` class;
+> - remove `readXObjParamAsStr` function;
+> - remove `readXObjAttrAsStr` function;
+> - other fixes.
+
+#### *v0.2.2*
+
+Release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.3;
+> - other fixes.
+
 #### *v0.2.1*
 
 Release version.

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.43|
+>|***rev.*:**|0.1.45|
 >|:---|---:|
->|date:|2025-01-28|
+>|date:|2025-07-19|
 
 ## Introduction
 
@@ -158,14 +158,6 @@ The function throws a `TypeError` exception in case:
 - code: `ERR_XOBJ_NPOBJ`
   + if `object` parameter is not an `Object` instance.
 
-#### **readXObjParamAsStr(object\[, defValue \[, key])** => `string`
-
-> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjParam`](#readxobjparamobject-key--string) or [`readXObjParamEx`](#readxobjparamexobject-opt-key--string) instead.*
-
-This function reads a value of an object parameter and returns it as a `string`.
-
-The `defValue` must be of a `string` type, if else the empty string is used.
-
 <a name="readXObjParamEx"></a>
 #### **readXObjParamEx(object\[, options \[, key])** => `string`
 
@@ -419,14 +411,6 @@ The function throws a `TypeError` exception in case:
 - code: `ERR_XOBJ_NPOBJ`
   + if `object` parameter is not an `Object` instance.
 
-#### **readXObjAttrAsStr(object, attr\[, defValue\[, key]])** => `string`
-
-> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjAttr`](#readxobjattrobject-attr-key--string) or [`readXObjAttrEx`](#readxobjattrexobject-attr-opt-key--string) instead.*
-
-This function returns a value of an object attribute. The value is of a `string` type.
-
-The `defValue` must be of a `string` type, if else the empty string is used.
-
 <a name="readXObjAttrEx"></a>
 #### **readXObjAttrEx(object, attr\[, options\[, key]])** => `string`
 
@@ -1161,31 +1145,56 @@ The function throws a `TypeError` exception in case:
 
 ### Base class
 
+<a name="TXmlContentParseOptions"></a>
 #### **TXmlContentParseOptions**
 
 This class implements an interface for handling XML-parse options.
 
 ##### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+###### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`object`|---|---|a host object.|
-|`options`|`object`|---|an options settings.|
+| `options` | `object` | --- | an options settings |
 
 ##### class properties
 
-The table below describes a properties of a `TXmlContentParseOptions` class:
+<a name="TXmlContentParseOptions+settings"></a>
+###### **settings**
 
-|name|read only|description|
-|:---|---|:---|
-|settings|yes|presents a current options|
-|xml2js|yes|returns an options for an XML-to-JS converter|
-|js2xml|yes|returns an options for an JS-to-XML converter|
+| property type | read only | description |
+|---|---|:---|
+| `object` | yes | contains a current options |
+
+<a name="TXmlContentParseOptions+xml2js"></a>
+###### **xml2js**
+
+| property type | read only | description |
+|---|---|:---|
+| `object` | yes | returns an options for an XML-to-JS converter |
+
+<a name="TXmlContentParseOptions+js2xml"></a>
+###### **js2xml**
+
+| property type | read only | description |
+|---|---|:---|
+| `object` | yes | returns an options for a JS-to-XML converter |
+
+<a name="TXmlContentParseOptions+reservedKeys"></a>
+###### **reservedKeys**
+
+| property type | read only | description |
+|---|---|:---|
+| `Set<string>` | yes | returns a set of the reserved key words those must not be used as an element names  |
 
 ##### class methods (*static*)
 
-###### **createNewOptionsSet(obj)**
+<a name="TXmlContentParseOptions.createNewOptionsSet"></a>
+###### **createNewOptionsSet(obj)** => `object`
 
 This method transforms a given object to a set of accepted parser options.

package/lib/xObj-defs.js

@@ -1,13 +1,9 @@
-// [v0.1.060-20240623]
+// [v0.1.064-20250718]
 
 // === module init block ===
 
 const {
-  //valueToIndex,
-  //readAsString, readAsBoolEx, readAsNumberEx,
-  //isNullOrUndef,
-  //isArray, isObject,
-  isPlainObject, //readAsListS,
+  isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
 // === module extra block (helper functions) ===
@@ -35,6 +31,21 @@ const XOBJ_TE_ANES_ECODE = 'ERR_XOBJ_INVARG_ATTR';
 const XOBJ_TE_KNES_EMSG = '<key_name> must be a non-empty string';
 const XOBJ_TE_KNES_ECODE = 'ERR_XOBJ_INVARG_KEY';
 
+const XOBJ_ECODE_TABLE = {
+  XOBJ_TE_NOBJ_EMSG,
+  XOBJ_TE_NOBJ_ECODE,
+  XOBJ_TE_NARR_EMSG,
+  XOBJ_TE_NARR_ECODE,
+  XOBJ_TE_NSTR_EMSG,
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_NPOBJ_EMSG,
+  XOBJ_TE_NPOBJ_ECODE,
+  XOBJ_TE_ANES_EMSG,
+  XOBJ_TE_ANES_ECODE,
+  XOBJ_TE_KNES_EMSG,
+  XOBJ_TE_KNES_ECODE,
+};
+
 const DEF_XML_PARSE_OPTIONS = {
   compact: true,
   declarationKey: '__decl',
@@ -66,16 +77,35 @@ const DEF_XML_PARSE_OPTIONS = {
  * (* class definitions *)
  */
 
+/**
+ * @classdesc Implements a container that provide a functionality to work
+ *    with options for an XML-parser
+ */
 class TXmlContentParseOptions {
+  /** @type {object} */
   #_options = null;
 
-  constructor(param){
+  /**
+   * Creates a container instance
+   * @param {any} [param] - some initial options set
+   */
+  constructor(param) {
     this.#_options = TXmlContentParseOptions.createNewOptionsSet(param);
   }
 
-  get settings(){ return this.#_options }
+  /**
+   * Contains a set of a current settings
+   * @type {object}
+   */
+  get settings() {
+    return this.#_options;
+  }
 
-  get xml2js(){
+  /**
+   * Contains a set of a settings for converting an 'XML' to 'JS'-object
+   * @type {object}
+   */
+  get xml2js() {
     let _settings = this.#_options;
     return {
       compact: _settings.compact,
@@ -99,7 +129,11 @@ class TXmlContentParseOptions {
     };
   }
 
-  get js2xml(){
+  /**
+   * Contains a set of a settings for converting an 'JS'-object to 'XML'
+   * @type {object}
+   */
+  get js2xml() {
     let _settings = this.#_options;
     return {
       compact: _settings.compact,
@@ -123,7 +157,41 @@ class TXmlContentParseOptions {
     };
   }
 
-  static createNewOptionsSet(opt){
+  /**
+   * Contains a set of a reserved key words
+   * @type {Set<string>}
+   */
+  get reservedKeys() {
+    const {
+      declarationKey,
+      attributesKey,
+      textKey,
+      commentKey,
+      cdataKey,
+      nameKey,
+      typeKey,
+      parentKey,
+      elementsKey,
+    } = this.#_options;
+    return new Set([
+      declarationKey,
+      attributesKey,
+      textKey,
+      commentKey,
+      cdataKey,
+      nameKey,
+      typeKey,
+      parentKey,
+      elementsKey,
+    ].filter((key) => typeof key === 'string'));
+  }
+
+  /**
+   * Creates a container instance
+   * @param {any} [opt] - some initial options set
+   * @static
+   */
+  static createNewOptionsSet(opt) {
     if (opt instanceof TXmlContentParseOptions) {
       opt = opt.settings;
     } else if (isPlainObject(opt)) {
@@ -161,6 +229,7 @@ class TXmlContentParseOptions {
 
 module.exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
 module.exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
+module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
 module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
 
 module.exports.TXmlContentParseOptions = TXmlContentParseOptions;

package/lib/xObj-lib.js

@@ -1,39 +1,47 @@
-// [v0.2.099-20250128]
+// [v0.2.105-20250719]
 
 // === module init block ===
 
 const {
-  valueToIndex, valueToIDString,
+  valueToIndex, //valueToIDString,
   readAsString, readAsBoolEx, readAsNumberEx,
   isNullOrUndef,
   isInteger,
   isArray, isObject, isPlainObject,
-  readAsListS,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  XOBJ_TE_NSTR_EMSG,
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_NPOBJ_EMSG,
+  XOBJ_TE_NPOBJ_ECODE,
+  XOBJ_TE_KNES_EMSG,
+  XOBJ_TE_KNES_ECODE,
+} = require('#lib/xObj-defs.js').XOBJ_ECODE_TABLE;
+
 // === module extra block (helper functions) ===
 
 /**
+ * A result of a value check ops.
  * @typedef {Object} RVAL_reason
  * @property {string} code - message ID
  * @property {string} msg - message text
- * @description A result of a value check ops.
  */
 
 /**
+ * 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.
  */
 
 /**
+ * Tries to convert a value into an ID.
  * @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') {
@@ -70,29 +78,15 @@ function evalKeyName(value, opt = true) {
 const XOBJ_DEF_PARAM_TNAME = '__text';
 const XOBJ_DEF_ATTR_TNAME = '__attr';
 
-const XOBJ_TE_INVARG_EMSG = 'invalid argument';
-const XOBJ_TE_NOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (an object expected)`;
-const XOBJ_TE_NOBJ_ECODE = 'ERR_XOBJ_NOBJ';
-const XOBJ_TE_NARR_EMSG = `${XOBJ_TE_INVARG_EMSG} (an array expected)`;
-const XOBJ_TE_NARR_ECODE = 'ERR_XOBJ_NARR';
-const XOBJ_TE_NSTR_EMSG = `${XOBJ_TE_INVARG_EMSG} (a string expected)`;
-const XOBJ_TE_NSTR_ECODE = 'ERR_XOBJ_NSTR';
-const XOBJ_TE_NPOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (a plain object expected)`;
-const XOBJ_TE_NPOBJ_ECODE = 'ERR_XOBJ_NPOBJ';
-const XOBJ_TE_ANES_EMSG = '<attr_name> must be a non-empty string';
-const XOBJ_TE_ANES_ECODE = 'ERR_XOBJ_INVARG_ATTR';
-const XOBJ_TE_KNES_EMSG = '<key_name> must be a non-empty string';
-const XOBJ_TE_KNES_ECODE = 'ERR_XOBJ_INVARG_KEY';
-
 /***
  * (* function definitions *)
  */
 
 /**
+ * Tries to convert a value into an ID.
  * @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: [?]
@@ -126,10 +120,10 @@ function evalXObjEName(value) {
 };
 
 /**
+ * Tries to convert a value into an element name description.
  * @function genXObjENameDescr
  * @param {any} value
  * @returns {object}
- * @description Tries to convert a value into an element name description.
  */
 function genXObjENameDescr(value) {
   let result = null;
@@ -183,13 +177,13 @@ function genXObjENameDescr(value) {
 };
 
 /**
+ * Extracts an element from a given object by its key.
  * @function getXObjElement
  * @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) {
   if (!isPlainObject(obj)) {
@@ -209,12 +203,12 @@ function getXObjElement(obj, name) {
 };
 
 /**
+ * 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 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) {
   let result = null;
@@ -235,20 +229,20 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
 };
 
 /**
+ * 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
- * @description A result of an xObj modification ops
  */
 
 /**
+ * Adds an element addressed by its key to a given object.
  * @function addXObjElement
  * @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) {
   if (!isPlainObject(obj)) {
@@ -286,6 +280,7 @@ function addXObjElement(obj, name) {
 };
 
 /**
+ * An options for an element insertion ops
  * @typedef {Object} OPT_inselops_L
  * @property {boolean} [force=false]
  * @property {boolean} [ripOldies=false]
@@ -293,13 +288,14 @@ function addXObjElement(obj, name) {
  */
 
 /**
+ * Inserts an element addressed by its key into a given object.
  * @function insertXObjElement
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
  * @throws {TypeError} if first param is not an object
- * @description Inserts an element addressed by its key into a given object.
+ * @see insertXObjElementEx
  */
 function insertXObjElement(...args) {
   let item = null;
@@ -320,6 +316,8 @@ function insertXObjElement(...args) {
 };
 
 /**
+ * Inserts an element addressed by its key into a given object.
+ * @since 0.2.0
  * @function insertXObjElementEx
  * @param {object} obj - some object
  * @param {string} name - some child element
@@ -327,8 +325,6 @@ function insertXObjElement(...args) {
  * @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 insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -350,8 +346,12 @@ function insertXObjElementEx(obj, name, opt) {
     obj[key] = prop = item;
     isSucceed = true;
   } else {
-    const _opt = isPlainObject(opt) ? opt : {};
-    let { force, ripOldies, acceptIfList } = _opt;
+    /** @type {OPT_inselops_L} */
+    let {
+      force,
+      ripOldies,
+      acceptIfList,
+    } = isPlainObject(opt) ? opt : {};
     if (typeof force !== 'boolean') force = false;
     if (typeof ripOldies !== 'boolean') ripOldies = false;
     if (typeof acceptIfList !== 'boolean') acceptIfList = false;
@@ -369,12 +369,13 @@ function insertXObjElementEx(obj, name, opt) {
 };
 
 /**
+ * Deletes an element addressed by its key from a given object.
  * @function deleteXObjElement
  * @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.
+ * @see deleteXObjElementEx
  */
 function deleteXObjElement(...args) {
   let isSucceed = false;
@@ -395,13 +396,13 @@ function deleteXObjElement(...args) {
 };
 
 /**
+ * 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}
  * @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) {
   if (!isPlainObject(obj)) {
@@ -427,6 +428,7 @@ function deleteXObjElementEx(obj, name) {
 };
 
 /**
+ * Renames an element addressed by its key.
  * @function renameXObjElement
  * @param {object} obj - some object
  * @param {string} name - some child element
@@ -435,7 +437,6 @@ function deleteXObjElementEx(obj, name) {
  * @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 = '', value = '') {
   if (!isPlainObject(obj)) {
@@ -475,13 +476,13 @@ function renameXObjElement(obj, name = '', value = '') {
 };
 
 /**
+ * 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}
  * @throws {TypeError} if first param is not an object
- * @description Checks whether an attribute is exists.
  */
 function checkXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -504,13 +505,13 @@ function checkXObjAttribute(obj, attr = '', key) {
 };
 
 /**
+ * Deletes an attribute addressed by a given name.
  * @function deleteXObjAttribute
  * @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) {
   let _obj = null;
@@ -536,6 +537,8 @@ function deleteXObjAttribute(obj, attr = '', key) {
 };
 
 /**
+ * Renames an attribute addressed by a given name.
+ * @since 0.2.0
  * @function renameXObjAttribute
  * @param {object} obj - some object
  * @param {string} attr - some attribute ID
@@ -545,8 +548,6 @@ function deleteXObjAttribute(obj, attr = '', key) {
  * @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)) {
@@ -595,13 +596,13 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
 };
 
 /**
+ * Extracts a parameter 'AS IS' from a given object.
  * @function readXObjParamRaw
  * @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 {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) {
   if (!isPlainObject(obj)) {
@@ -620,6 +621,7 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
 };
 
 /**
+ * Writes a parameter 'AS IS' into a given object.
  * @function writeXObjParamRaw
  * @param {object} obj - some object
  * @param {any} value - some value
@@ -627,7 +629,6 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
  * @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) {
   if (!isPlainObject(obj)) {
@@ -651,6 +652,7 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
 };
 
 /**
+ * Extracts an attribute 'AS IS' from a given object.
  * @function readXObjAttrRaw
  * @param {object} obj - some object
  * @param {string} attr - some attribute
@@ -658,7 +660,6 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
  * @returns {any}
  * @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) {
   let _obj = null;
@@ -680,6 +681,7 @@ function readXObjAttrRaw(obj, attr = '', key) {
 };
 
 /**
+ * Writes a parameter into a given object.
  * @function writeXObjAttrRaw
  * @param {object} obj - some object
  * @param {string} attr - some attribute
@@ -688,7 +690,6 @@ function readXObjAttrRaw(obj, attr = '', 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) {
   let { isSucceed, value: name } = evalKeyName(attr, false);
@@ -725,13 +726,12 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
 };
 
 /**
+ * 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 first param is not an object
- * @description Extracts a parameter from a given object
- *              and returns it as string.
  */
 function readXObjParam(obj, key) {
   const opt = {
@@ -750,14 +750,13 @@ function readXObjParam(obj, key) {
 };
 
 /**
+ * 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 first param is not an object
- * @description Extracts a parameter from a given object
- *              and returns it as boolean.
  */
 function readXObjParamAsBool(obj, defValue, key) {
   let result = undefined;
@@ -783,8 +782,7 @@ function readXObjParamAsBool(obj, defValue, key) {
  * @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 number.
+ * Extracts a parameter from a given object and returns it as a number.
  */
 function readXObjParamAsNum(obj, defValue, key) {
   let result = undefined;
@@ -804,14 +802,13 @@ function readXObjParamAsNum(obj, defValue, key) {
 };
 
 /**
+ * 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 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 readXObjParamEx(obj, opt, key) {
@@ -841,13 +838,12 @@ function readXObjParamEx(obj, opt, key) {
 };
 
 /**
+ * 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 first param is not an object
- * @description Extracts a parameter from a given object
- *              and returns it as 'index' value.
  */
 function readXObjParamAsIndex(obj, key) {
   let result = undefined;
@@ -867,14 +863,14 @@ function readXObjParamAsIndex(obj, key) {
 };
 
 /**
+ * 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 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;
@@ -893,6 +889,8 @@ function writeXObjParam(obj, value, key) {
 };
 
 /**
+ * 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
@@ -900,8 +898,6 @@ function writeXObjParam(obj, value, key) {
  * @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;
@@ -924,6 +920,8 @@ function writeXObjParamAsBool(obj, value, defValue, key) {
 };
 
 /**
+ * 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
@@ -931,8 +929,6 @@ function writeXObjParamAsBool(obj, value, defValue, key) {
  * @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;
@@ -955,14 +951,14 @@ function writeXObjParamAsNum(obj, value, defValue, key) {
 };
 
 /**
+ * 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 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;
@@ -985,6 +981,8 @@ function writeXObjParamAsIndex(obj, value, key) {
 };
 
 /**
+ * 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
@@ -992,8 +990,6 @@ function writeXObjParamAsIndex(obj, value, key) {
  * @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, opt, key) {
@@ -1031,14 +1027,13 @@ function writeXObjParamEx(obj, value, opt, key) {
 };
 
 /**
+ * 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 first param is not an object
- * @description Extracts an attribute from a given object
- *              and returns it as string.
  */
 function readXObjAttr(obj, attr, key) {
   const opt = {
@@ -1057,6 +1052,7 @@ function readXObjAttr(obj, attr, key) {
 };
 
 /**
+ * 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
@@ -1064,8 +1060,6 @@ function readXObjAttr(obj, attr, key) {
  * @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) {
   let result = undefined;
@@ -1085,6 +1079,7 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
 };
 
 /**
+ * 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
@@ -1092,8 +1087,6 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
  * @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 number.
  */
 function readXObjAttrAsNum(obj, attr, defValue, key) {
   let result = undefined;
@@ -1113,6 +1106,7 @@ function readXObjAttrAsNum(obj, attr, defValue, key) {
 };
 
 /**
+ * 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
@@ -1120,8 +1114,6 @@ function readXObjAttrAsNum(obj, attr, defValue, key) {
  * @param {string} [key] - some key
  * @returns {string}
  * @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 readXObjAttrEx(obj, attr, opt, key) {
@@ -1151,14 +1143,13 @@ function readXObjAttrEx(obj, attr, opt, key) {
 };
 
 /**
+ * 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 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) {
   let result = undefined;
@@ -1178,6 +1169,8 @@ function readXObjAttrAsIndex(obj, attr, key) {
 };
 
 /**
+ * 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
@@ -1185,8 +1178,6 @@ function readXObjAttrAsIndex(obj, attr, key) {
  * @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;
@@ -1205,6 +1196,8 @@ function writeXObjAttr(obj, attr, value, key) {
 };
 
 /**
+ * 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
@@ -1213,8 +1206,6 @@ function writeXObjAttr(obj, attr, value, key) {
  * @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;
@@ -1237,6 +1228,8 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
 };
 
 /**
+ * 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
@@ -1245,8 +1238,6 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
  * @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;
@@ -1269,6 +1260,8 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
 };
 
 /**
+ * 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
@@ -1276,8 +1269,6 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
  * @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;
@@ -1300,6 +1291,8 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
 };
 
 /**
+ * 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
@@ -1308,8 +1301,6 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
  * @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, opt, key) {
@@ -1347,13 +1338,13 @@ function writeXObjAttrEx(obj, attr, value, opt, key) {
 };
 
 /**
+ * Inserts an elements into a given object.
  * @function insertXObjElements
- * @param {object} obj
- * @param {...string} name
+ * @param {object} obj  - some object
+ * @param {...string} name - some child element name
  * @param {OPT_inselops_L} [opt]
  * @returns {number}
  * @throws {TypeError} if first param is not an object
- * @description Inserts an elements into a given object.
  */
 function insertXObjElements(obj, ...args) {
   if (!isPlainObject(obj)) {
@@ -1375,19 +1366,20 @@ function insertXObjElements(obj, ...args) {
 };
 
 /**
+ * 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
+ * @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
- * @description Inserts a list elements into a given object.
  */
 function insertXObjEList(...args) {
   let item = null;
@@ -1408,15 +1400,15 @@ function insertXObjEList(...args) {
 };
 
 /**
+ * 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
+ * @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 {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)) {
@@ -1431,8 +1423,11 @@ function insertXObjEListEx(obj, name, opt) {
     err.code = code;
     throw err;
   };
-  const _options = isPlainObject(opt) ? opt : {};
-  let { force, ripOldies } = _options;
+  /** @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];
@@ -1457,13 +1452,13 @@ function insertXObjEListEx(obj, name, opt) {
 };
 
 /**
+ * Inserts a chain of an elements into a given object.
  * @function insertXObjEChain
  * @param {object} obj - some object
- * @param {...string} name - some child element
+ * @param {...string} name - some child element name
  * @param {object} [opt] - options
  * @returns {?any}
  * @throws {TypeError} if first param is not an object
- * @description Inserts a chain of an elements into a given object.
  */
 function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {
@@ -1554,8 +1549,3 @@ module.exports.genXObjENameDescr = genXObjENameDescr;
 module.exports.insertXObjElements = insertXObjElements;
 /* experimental */
 module.exports.insertXObjEChain = insertXObjEChain;
-
-/** @deprecated */
-module.exports.readXObjParamAsStr = readXObjParamEx;
-/** @deprecated */
-module.exports.readXObjAttrAsStr = readXObjAttrEx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -18,11 +18,6 @@
   ],
   "scripts": {
     "test": "jest",
-    "test-xobj": "jest xObj",
-    "test-xobj:c1": "jest xObj-lib.1",
-    "test-xobj:c2": "jest xObj-lib.2",
-    "test-xobj:c3": "jest xObj-lib.3",
-    "test-xobj:c4": "jest xObj-lib.4",
     "build-doc-md": "jsdoc2md",
     "build-doc-html": "jsdoc"
   },
@@ -31,10 +26,10 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.2.2"
+    "@ygracs/bsfoc-lib-js": "^0.2.3"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
+    "jest": "^30.0.4",
     "jsdoc-to-markdown": "^9.1.1",
     "minimist": "^1.2.8"
   }