@cntwg/xml-lib-js 0.0.33 → 0.0.34

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+#### *v0.0.34*
+
+Pre-release version.
+
+> - update `xmldoc-lib.md`;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.3;
+> - (`TXmlElementController`) remove methods: `_getChildRaw`, `_addChildRaw`< `_setChildRaw`;
+> - (`TXmlElementsListController`) add special static method: `__getItemRaw`;
+> - (`TXmlElementsListController`) add special static method: `__setItemRaw`;
+> - (`TXmlElementsListController`) deprecate methods: `_getItemRaw`, `_setItemRaw`;
+> - (`TXmlElementsListController`) add iterator method;
+
 #### *v0.0.33*
 
 Pre-release version.

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.37|
+>|***rev.*:**|0.1.40|
 >|:---|---:|
->|date:|2025-02-06|
+>|date:|2025-07-19|
 
 ## Introduction
 
@@ -409,20 +409,6 @@ This method loads an element content from a string given by a `str` parameter.
 
 This methods throws `Error` if something goes wrong through a parsing process of a string.
 
-#### class methods (*special*)
-
-##### **_getChildRaw(name)** => `?any`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__getChildRaw` method of the class*).
-
-##### **_addChildRaw(name)** => `?object`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__addChildRaw` method of the class*).
-
-##### **_setChildRaw(name, obj)** => `boolean`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__setChildRaw` method of the class*).
-
 #### class methods (*static*)
 
 ##### **clear(item)** => `void`
@@ -455,6 +441,8 @@ This method adds an element addressed by `name` as a child element.
 
 ##### **__setChildRaw(node, name, obj)** => `boolean`
 
+> since: \[`v0.0.31`]
+
 This method inserts a given object as a child element addressed by `name`.
 
 <a name="TXmlElementsListController"></a>
@@ -619,7 +607,9 @@ The `options` structure is listed below:
 
 #### class methods (*special*)
 
-##### **_getItemRaw(name)**
+##### **_getItemRaw(index)**
+
+> WARNING: \[since `v0.0.34`] this method deprecated (*use `__getItemRaw`, a static method of the class, instead*).
 
 This method returns an element addressed by `index` as object. If failed `null` is returned.
 
@@ -629,12 +619,30 @@ This method adds an element to a list members as object. If succeed an index of
 
 ##### **_setItemRaw(index, obj)**
 
+> WARNING: \[since `v0.0.34`] this method deprecated (*use `__setItemRaw`, a static method of the class, instead*).
+
 This method replaces an element addressed by `index` with a new element which is saved as raw object. If succeed `true` is returned.
 
 ##### **_insItemRaw(index, obj)**
 
 This method inserts an element as a raw object in the position addressed by `index`. If succeed `true` is returned.
 
+#### class methods (*static, special*)
+
+<a name="TXmlElementsListController.__getItemRaw"></a>
+##### **__getItemRaw(node, index)** => `?any`
+
+> since: \[`v0.0.34`]
+
+This method returns an element addressed by `index` as object. If failed `null` is returned.
+
+<a name="TXmlElementsListController.__setItemRaw"></a>
+##### **__setItemRaw(node, index, item)** => `?any`
+
+> since: \[`v0.0.34`]
+
+This method replaces an element addressed by `index` with a new element which is saved as raw object. If succeed `true` is returned.
+
 <a name="TXmlContentDeclaration"></a>
 ### **TXmlContentDeclaration**
 

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.111-20250415]
+// [v0.2.117-20250719]
 
 // === module init block ===
 
@@ -28,19 +28,19 @@ const {
 // === module extra block (helper functions) ===
 
 /**
+ * An XML-element controller settings.
  * @typedef {Object} OPT_xmlelemsett
  * @property {TXmlContentParseOptions} [parseOptions] - parser options
  * @property {boolean} [proxyModeEnable=false] - mode flag
  * @property {boolean} [isNullItemsAllowed=false] - <reserved>
- * @description An XML-element controller settings.
  */
 
 /**
+ * Evaluates an XML-element settings
  * @function __evalXMLElementSettings
  * @param {any} value - element settings to evaluate
  * @returns {OPT_xmlelemsett}
  * @inner
- * @description Evaluates an XML-element settings
  */
 function __evalXMLElementSettings(value) {
   /** @type {OPT_xmlelemsett} */
@@ -59,22 +59,22 @@ function __evalXMLElementSettings(value) {
 };
 
 /**
+ * An XML-content container settings.
  * @typedef {Object} OPT_xmlcontsett
  * @property {TXmlContentParseOptions} [parseOptions] - parser options
  * @property {boolean} [proxyModeEnable=false] - mode flag
  * @property {boolean} [isNullItemsAllowed=false] - <reserved>
  * @property {string} [rootETagName] - tag name of the root element
  * @property {boolean} [autoBindRoot=true] - mode flag
- * @description An XML-content container settings.
  * @see OPT_xmlelemsett
  */
 
 /**
+ * Evaluates an XML-container settings
  * @function __evalXMLContainerSettings
  * @param {any} value - container settings to evaluate
  * @returns {OPT_xmlcontsett}
  * @inner
- * @description Evaluates an XML-container settings
  */
 function __evalXMLContainerSettings(value) {
   /** @type {OPT_xmlcontsett} */
@@ -110,12 +110,11 @@ const XML_TE_NROOT_EMSG = 'root element not found';
  */
 
 /**
+ * Tries to convert a given value to a valid tag name of an XML-element.
  * @since v0.0.28
  * @function readAsTagName
  * @param {any} value - some value
  * @returns {string}
- * @description Tries to convert a given value to a valid tag name
- *              of an XML-element.
  */
 function readAsTagName(value) {
   let tagName = valueToIDString(value, { ignoreNumbers: true });
@@ -133,12 +132,11 @@ function readAsTagName(value) {
 };
 
 /**
+ * Tries to convert a given value to a valid name of an XML-attribute.
  * @since v0.0.28
  * @function readAsAttrName
  * @param {any} value - some value
  * @returns {string}
- * @description Tries to convert a given value to a valid name
- *              of an XML-attribute.
  */
 function readAsAttrName(value) {
   let attrName = valueToIDString(value, { ignoreNumbers: true });
@@ -156,12 +154,12 @@ function readAsAttrName(value) {
 };
 
 /**
+ * Tries to convert a given value to a valid identifier
+ * suitable as a value for an "ID-attribute" of an XML-element.
  * @since v0.0.28
  * @function valueToElementID
  * @param {any} value - some value
  * @returns {string}
- * @description Tries to convert a given value to a valid identifier
- *              suitable as a value for an "ID-attribute" of an XML-element.
  */
 function valueToElementID(value) {
   let id = valueToIDString(value);
@@ -192,13 +190,12 @@ class TXmlAttributesMapper {
   #_options;
 
   /**
+   * Creates an attributes mapper instance
    * @param {object} obj - some object
    * @param {OPT_xmlelemsett} [opt] - options
    * @throws {TypeError}
-   * @description Creates an attributes mapper instance
    */
   constructor(obj, opt) {
-    // init an elements content
     if (!isPlainObject(obj)) throw new TypeError(XML_TE_NOBJ_EMSG);
     this.#_host = obj;
     // load options
@@ -231,9 +228,9 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Checks whether an attribute exists.
    * @param {string} name - attribute name
    * @returns {boolean}
-   * @description Checks whether an attribute exists.
    */
   hasAttribute(name) {
     let result = false;
@@ -251,9 +248,9 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Returns an attribute value.
    * @param {string} name - attribute name
    * @returns {string}
-   * @description Returns an attribute value.
    */
   getAttribute(name) {
     let result = '';
@@ -271,10 +268,10 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Sets an attribute value.
    * @param {string} name - attribute name
    * @param {any} value - some value
    * @returns {boolean}
-   * @description Sets an attribute value.
    */
   setAttribute(name, value) {
     const attrName = readAsAttrName(name);
@@ -296,9 +293,9 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Deletes an attribute.
    * @param {string} name - attribute name
    * @returns {boolean}
-   * @description Deletes an attribute.
    */
   delAttribute(name) {
     let result = false;
@@ -316,11 +313,11 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Renames an attribute.
    * @since v0.0.30
    * @param {string} name - attribute name
    * @param {string} value - new name
    * @returns {boolean}
-   * @description Renames an attribute.
    */
   renameAttribute(name, value) {
     const newName = readAsAttrName(value);
@@ -342,8 +339,8 @@ class TXmlAttributesMapper {
   }
 
   /**
+   * Deletes all attributes.
    * @returns {void}
-   * @description Deletes all attributes.
    */
   clear() {
     insertXObjElement(
@@ -373,10 +370,10 @@ class TXmlElementController {
   #_name = null;
 
   /**
+   * Creates an instance of an element controller
    * @param {object} obj - some element
    * @param {OPT_xmlelemsett} [opt] - options
    * @throws {TypeError}
-   * @description Creates an instance of an element controller
    */
   constructor(obj, opt) {
     // load options
@@ -445,9 +442,9 @@ class TXmlElementController {
   }
 
   /**
+   * Checks whether an attribute exists.
    * @param {string} name - attribute name
    * @returns {boolean}
-   * @description Checks whether an attribute exists.
    * @see TXmlAttributesMapper.hasAttribute
    */
   hasAttribute(name) {
@@ -455,9 +452,9 @@ class TXmlElementController {
   }
 
   /**
+   * Returns an attribute value.
    * @param {string} name - attribute name
    * @returns {string}
-   * @description Returns an attribute value.
    * @see TXmlAttributesMapper.getAttribute
    */
   getAttribute(name) {
@@ -465,10 +462,10 @@ class TXmlElementController {
   }
 
   /**
+   * Sets an attribute value.
    * @param {string} name - attribute name
    * @param {any} value - some value
    * @returns {boolean}
-   * @description Sets an attribute value.
    * @see TXmlAttributesMapper.setAttribute
    */
   setAttribute(...args) {
@@ -476,9 +473,9 @@ class TXmlElementController {
   }
 
   /**
+   * Deletes an attribute.
    * @param {string} name - attribute name
    * @returns {boolean}
-   * @description Deletes an attribute.
    * @see TXmlAttributesMapper.delAttribute
    */
   delAttribute(name) {
@@ -486,11 +483,11 @@ class TXmlElementController {
   }
 
   /**
+   * Renames an attribute.
    * @since v0.0.30
    * @param {string} name - attribute name
    * @param {string} value - new attribute name
    * @returns {boolean}
-   * @description Renames an attribute.
    * @see TXmlAttributesMapper.renameAttribute
    */
   renameAttribute(...args) {
@@ -498,8 +495,8 @@ class TXmlElementController {
   }
 
   /**
+   * Returns a text value in format of a `[ <lang>, <text> ]` pair.
    * @returns {string[]}
-   * @description Returns a text value in format of a `[ <lang>, <text> ]` pair.
    */
   getTextValue() {
     return [
@@ -509,9 +506,9 @@ class TXmlElementController {
   }
 
   /**
+   * Sets a text value.
    * @param {(string|string[])} value - some text
    * @returns {boolean}
-   * @description Sets a text value.
    */
   setTextValue(value) {
     const _value = valueToEntry(value);
@@ -538,9 +535,9 @@ class TXmlElementController {
   }
 
   /**
+   * Checks whether an element has a child element.
    * @param {string} name - some child element name
    * @returns {boolean}
-   * @description Checks whether an element has a child element.
    */
   hasChild(name) {
     const _name = evalXObjEName(name);
@@ -557,9 +554,9 @@ class TXmlElementController {
   }
 
   /**
+   * Returns a child element.
    * @param {string} name - some child element name
    * @returns {?(TXmlElementController|TXmlElementsListController)}
-   * @description Returns a child element.
    */
   getChild(name) {
     const _name = evalXObjEName(name);
@@ -577,49 +574,9 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
-   * @returns {?any}
-   * @protected
-   * @deprecated
-   * @description Returns a child element.
-   * @see TXmlElementController.__getChildRaw
-   */
-  _getChildRaw(name) {
-    //console.log('CHECK: TXmlElementController._getChildRaw() => was called...');
-    return TXmlElementController.__getChildRaw(this, name);
-  }
-
-  /**
-   * @param {string} name
-   * @param {object} obj
-   * @returns {boolean}
-   * @protected
-   * @deprecated
-   * @description Sets a child element.
-   * @see TXmlElementController.__setChildRaw
-   */
-  _setChildRaw(...args) {
-    //console.log('CHECK: TXmlElementController._setChildRaw() => was called...');
-    return TXmlElementController.__setChildRaw(this, ...args);
-  }
-
-  /**
-   * @param {string} name
-   * @returns {?Object}
-   * @protected
-   * @deprecated
-   * @description Adds a new child element.
-   * @see TXmlElementController.__addChildRaw
-   */
-  _addChildRaw(name) {
-    //console.log('CHECK: TXmlElementController._addChild() => was called...');
-    return TXmlElementController.__addChildRaw(this, name);
-  }
-
-  /**
+   * Adds a new child element.
    * @param {string} name - some child element name
    * @returns {?TXmlElementController}
-   * @description Adds a new child element.
    */
   addChild(name) {
     const _name = evalXObjEName(name);
@@ -637,9 +594,9 @@ class TXmlElementController {
   }
 
   /**
+   * Deletes a child element.
    * @param {string} name - some child element name
    * @returns {boolean}
-   * @description Deletes a child element.
    */
   delChild(name) {
     const _name = evalXObjEName(name);
@@ -670,20 +627,20 @@ class TXmlElementController {
   }
 
   /**
+   * Deletes all child elements and attributes.
    * @returns {void}
-   * @description Deletes all child elements and attributes.
    */
   clear() {
     TXmlElementController.clear(this);
   }
 
   /**
+   * Loads a element content from a string.
    * @since v0.0.30
    * @param {string} xmlString - some content
    * @returns {boolean}
    * @throws {Error}
    * @experimental
-   * @description Loads a element content from a string.
    */
   loadFromXMLString(xmlString) {
     let result = false;
@@ -728,24 +685,24 @@ class TXmlElementController {
   }
 
   /**
+   * Tries to unwraps a given object.
    * @param {object} item
    * @returns {?object}
    * @protected
    * @static
-   * @description Tries to unwraps a given object.
    */
   static __unwrap(item) {
     return (item instanceof TXmlElementController) ? item.#_host : null;
   }
 
   /**
+   * Returns a child element.
    * @since v0.0.31
-   * @param {TXmlElementController} node
-   * @param {string} name
+   * @param {TXmlElementController} node - some element
+   * @param {string} name - child element name
    * @returns {?any}
    * @protected
    * @static
-   * @description Returns a child element.
    */
   static __getChildRaw(node, name) {
     let item = null;
@@ -763,13 +720,13 @@ class TXmlElementController {
   }
 
   /**
+   * Adds a new child element.
    * @since v0.0.31
-   * @param {TXmlElementController} node
-   * @param {string} name
+   * @param {TXmlElementController} node - some element
+   * @param {string} name - child element name
    * @returns {?Object}
    * @protected
    * @static
-   * @description Adds a new child element.
    */
   static __addChildRaw(node, name) {
     const childName = readAsTagName(name);
@@ -790,13 +747,13 @@ class TXmlElementController {
   }
 
   /**
-   * @param {TXmlElementController} node
-   * @param {string} name
-   * @param {object} obj
+   * Sets a child element.
+   * @param {TXmlElementController} node - some element
+   * @param {string} name - child element name
+   * @param {object} obj - raw child element
    * @returns {boolean}
    * @protected
    * @static
-   * @description Sets a child element.
    */
   static __setChildRaw(node, name, obj) {
     const childName = readAsTagName(name);
@@ -813,10 +770,10 @@ class TXmlElementController {
   }
 
   /**
+   * Tries to clean a given object.
    * @param {object} obj
    * @returns {void}
    * @static
-   * @description Tries to clean a given object.
    */
   static clear(obj) {
     let item = TXmlElementController.__unwrap(obj);
@@ -829,12 +786,12 @@ class TXmlElementController {
   }
 
   /**
+   * Creates new controller element.
    * @since v0.0.30
    * @param {object} obj - some object
    * @param {object} [opt] - options
    * @returns {?(TXmlElementController|TXmlElementsListController)}
    * @static
-   * @description Creates new controller element.
    */
   static create(obj, opt) {
     let result = null;
@@ -866,10 +823,10 @@ class TXmlElementsListController {
   #_count = null;
 
   /**
+   * Creates an instance of a list controller
    * @param {object[]} obj - elements list
    * @param {OPT_xmlelemsett} [opt] - options
    * @throws {TypeError}
-   * @description Creates an instance of a list controller
    */
   constructor(obj, opt) {
     // load options
@@ -894,6 +851,22 @@ class TXmlElementsListController {
     this.#_options = _options;
   }
 
+  [Symbol.iterator]() {
+    let index = 0;
+    return {
+      next: () => {
+        if (index < this.count) {
+          return { done: false, value: this.getItem(index++) };
+        } else {
+          return { done: true, value: undefined };
+        };
+      },
+      return() {
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
   /**
    * Contains a quantity of an elements
    * @type {number}
@@ -931,34 +904,34 @@ class TXmlElementsListController {
   }
 
   /**
+   * Deletes all child elements and attributes.
    * @returns {void}
-   * @description Deletes all child elements and attributes.
    */
   clear() {
     this.#_host.length = 0;
   }
 
   /**
+   * Checks whether an instance holds none element.
    * @returns {boolean}
-   * @description Checks whether an instance holds none element.
    */
   isEmpty() {
     return this.count === 0;
   }
 
   /**
+   * Checks whether an instance holds at least one element.
    * @returns {boolean}
-   * @description Checks whether an instance holds at least one element.
    */
   isNotEmpty() {
     return this.count > 0;
   }
 
   /**
+   * Checks whether a given value is a valid index value
+   * and it is not exceeds an index range within the instance.
    * @param {(number|string)} value - some index
    * @returns {boolean}
-   * @description Checks whether a given value is a valid index value
-   *              and it is not exceeds an index range within the instance.
    */
   chkIndex(value) {
     const index = valueToIndex(value);
@@ -966,9 +939,9 @@ class TXmlElementsListController {
   }
 
   /**
+   * Checks whether or not a given element is valid.
    * @param {any} obj - some element
    * @returns {boolean}
-   * @description Checks whether or not a given element is valid.
    */
   isValidItem(obj) {
     return (
@@ -978,20 +951,22 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index
+   * Returns an element.
+   * @param {(number|string)} index - element index
    * @returns {?object}
    * @protected
-   * @description Returns an element.
+   * @deprecated
+   * @todo \[since `v0.0.34`] deprecated and will be removed later, consider
+   *    to use `TXmlElementsListController.__getItemRaw` instead.
    */
   _getItemRaw(index) {
-    let item = this.#_host[valueToIndex(index)];
-    return item !== undefined ? item : null;
+    return TXmlElementsListController.__getItemRaw(this, index);
   }
 
   /**
-   * @param {number} index - element index
+   * Returns an element.
+   * @param {(number|string)} index - element index
    * @returns {?TXmlElementController}
-   * @description Returns an element.
    */
   getItem(index) {
     let item = this.#_host[valueToIndex(index)];
@@ -1004,10 +979,10 @@ class TXmlElementsListController {
   }
 
   /**
+   * Adds a new element.
    * @param {any} item
    * @returns {number}
    * @protected
-   * @description Adds a new element.
    */
   _addItemRaw(item) {
     let index = -1;
@@ -1019,9 +994,9 @@ class TXmlElementsListController {
   }
 
   /**
+   * Adds a new element.
    * @param {any} item - some element
    * @returns {number}
-   * @description Adds a new element.
    */
   addItem(item) {
     // unwrap item from container
@@ -1032,38 +1007,39 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index
+   * Sets a new element.
+   * @param {(number|string)} index - element index
    * @param {any} item
    * @returns {boolean}
    * @protected
-   * @description Sets a new element.
+   * @deprecated
+   * @todo \[since `v0.0.34`] deprecated and will be removed later, consider
+   *    to use `TXmlElementsListController.__setItemRaw` instead.
    */
   _setItemRaw(index, item) {
-    let isSUCCEED = this.chkIndex(index) && this.isValidItem(item);
-    if (isSUCCEED) this.#_host[Number(index)] = item; // // TODO: correct count
-    return isSUCCEED;
+    return TXmlElementsListController.__setItemRaw(this, index, item);
   }
 
   /**
-   * @param {string} index - element index
+   * Sets a new element.
+   * @param {(number|string)} index - element index
    * @param {any} item - some element
    * @returns {boolean}
-   * @description Sets a new element.
    */
   setItem(index, item) {
     // unwrap item from container
     if (item instanceof TXmlElementController) {
       item = TXmlElementController.__unwrap(item);
     };
-    return this._setItemRaw(index, item);
+    return TXmlElementsListController.__setItemRaw(this, index, item);
   }
 
   /**
-   * @param {number} index
+   * Insertes a new element.
+   * @param {(number|string)} index - element index
    * @param {any} item
    * @returns {boolean}
    * @protected
-   * @description Insertes a new element.
    */
   _insItemRaw(index, item) {
     index = valueToIndex(index);
@@ -1086,10 +1062,10 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index - element index
+   * Insertes a new element.
+   * @param {(number|string)} index - element index
    * @param {any} item - some element
    * @returns {boolean}
-   * @description Insertes a new element.
    */
   insItem(index, item) {
     // unwrap item from container
@@ -1100,9 +1076,9 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index - element index
+   * Deletes an element.
+   * @param {(number|string)} value - element index
    * @returns {boolean}
-   * @description Deletes an element.
    */
   delItem(value) {
     let isSUCCEED = this.chkIndex(value);
@@ -1124,16 +1100,16 @@ class TXmlElementsListController {
   }
 
   /**
+   * Settings for the list load ops
    * @typedef {Object} OPT_ELC_loaditems
    * @property {boolean} [useClear=true] - indicates whether to clear the list before load
-   * @description A settings for the list load ops
    */
 
   /**
+   * Loads a list of an elements.
    * @param {any} items - element or a list of an elements
    * @param {OPT_ELC_loaditems} [opt]
    * @returns {number}
-   * @description Loads a list of an elements.
    */
   loadItems(items, opt) {
     const _options = isPlainObject(opt) ? opt : {};
@@ -1147,6 +1123,47 @@ class TXmlElementsListController {
     return this.count - count;
   }
 
+  /**
+   * Returns an element.
+   * @since v0.0.34
+   * @param {TXmlElementsListController} node - some element
+   * @param {(number|string)} index - element index
+   * @returns {?object}
+   * @protected
+   * @static
+   */
+  static __getItemRaw(node, index) {
+    let item = null;
+    if (node instanceof TXmlElementsListController) {
+      item = node.#_host[valueToIndex(index)];
+      if (item === undefined) item = null;
+    };
+    return item;
+  }
+
+  /**
+   * Sets a new element.
+   * @since v0.0.34
+   * @param {TXmlElementsListController} node - some element
+   * @param {(number|string)} index - element index
+   * @param {any} item - new element
+   * @returns {boolean}
+   * @protected
+   * @static
+   */
+  static __setItemRaw(node, index, item) {
+    let isSucceed = false;
+    if (
+      node instanceof TXmlElementsListController
+      && node.chkIndex(index)
+      && node.isValidItem(item)
+    ) {
+      node.#_host[Number(index)] = item; // // TODO: correct count
+      isSucceed = true;
+    };
+    return isSucceed;
+  }
+
 };
 
 /**
@@ -1162,13 +1179,12 @@ class TXmlContentDeclaration {
   #_ctrls;
 
   /**
+   * Creates an instance of the element
    * @param {object} obj - some object
    * @param {OPT_xmlcontsett} [opt] - options
    * @throws {TypeError}
-   * @description Creates an instance of the element
    */
   constructor(obj, opt) {
-    // check <obj>-param
     if (!isPlainObject(obj)) {
       throw new TypeError(`TXmlContentDeclaration : ${XML_TE_NOBJ_EMSG}`);
     };
@@ -1219,8 +1235,8 @@ class TXmlContentDeclaration {
   }
 
   /**
+   * Initializes an instance content.
    * @returns {boolean}
-   * @description Initializes an instance content.
    */
   init() {
     const _options = this.#_options;
@@ -1240,7 +1256,7 @@ class TXmlContentDeclaration {
 
 /**
  * @augments TXmlElementController
- * @description This class implements an instance of a root element
+ * @classdesc This class implements an instance of a root element
  */
 class TXmlContentRootElement extends TXmlElementController {
   /** @type {?object} */
@@ -1249,12 +1265,12 @@ class TXmlContentRootElement extends TXmlElementController {
   #_options;
 
   /**
+   * Creates an instance of a root element.
    * @param {object} obj - some object
    * @param {OPT_xmlcontsett} [opt] - options
    * @throws {TypeError}
    */
   constructor(obj, opt) {
-    // check <obj>-param
     if (!isPlainObject(obj)) {
       throw new TypeError(`TXmlContentRootElement : ${XML_TE_NOBJ_EMSG}`);
     };
@@ -1269,28 +1285,7 @@ class TXmlContentRootElement extends TXmlElementController {
       if (len === 0) {
         rootItem = insertXObjElement(obj, rootETagName);
       } else {
-        const {
-          declarationKey,
-          attributesKey,
-          textKey,
-          commentKey,
-          cdataKey,
-          nameKey,
-          typeKey,
-          parentKey,
-          elementsKey,
-        } = parseOptions.settings;
-        const reservedKeys = new Set([
-          declarationKey,
-          attributesKey,
-          textKey,
-          commentKey,
-          cdataKey,
-          nameKey,
-          typeKey,
-          parentKey,
-          elementsKey,
-        ]);
+        const reservedKeys = parseOptions.reservedKeys;
         let targetKey = '';
         for (let name of entries) {
           if (!reservedKeys.has(name)) {
@@ -1339,12 +1334,12 @@ class TXmlContentRootElement extends TXmlElementController {
   }
 
   /**
+   * Tries to unwraps a given object.
    * @param {object} item
    * @param {boolean} [opt=false]
    * @returns {?object}
    * @protected
    * @static
-   * @description Tries to unwraps a given object.
    */
   static __unwrap(item, opt) {
     return (
@@ -1358,6 +1353,7 @@ class TXmlContentRootElement extends TXmlElementController {
 }
 
 /**
+ * A fs ops description.
  * @typedef {Object} fsoDescr
  * @property {boolean} isERR - flag
  * @property {number} [errCode] - error code
@@ -1365,7 +1361,6 @@ class TXmlContentRootElement extends TXmlElementController {
  * @property {string} [errMsg] - event message
  * @property {string} [source] - path to file
  * @property {any} [content] - file content
- * @description A fs ops description.
  */
 
 /**
@@ -1385,8 +1380,8 @@ class TXmlContentContainer {
   #_docRoot;
 
   /**
+   * Creates an instance of the container
    * @param {OPT_xmlcontsett} [opt] - options
-   * @description Creates an instance of the container
    */
   constructor(opt) {
     // load options
@@ -1414,8 +1409,8 @@ class TXmlContentContainer {
   }
 
   /**
+   * Cleans a document content.
    * @returns {void}
-   * @description Cleans a document content.
    */
   clear() {
     this.#_docDecl.init();
@@ -1423,11 +1418,11 @@ class TXmlContentContainer {
   }
 
   /**
+   * Initializes an instance with a given content.
    * @param {object} obj
    * @param {object} [opt]
    * @returns {boolean}
    * @protected
-   * @description Initializes an instance with a given content.
    */
   _bindContent(obj, opt) {
     let isSUCCEED = false;
@@ -1458,9 +1453,9 @@ class TXmlContentContainer {
   }
 
   /**
+   * Returns a document content as a string in an XML-format.
    * @returns {string}
    * @throws {Error}
-   * @description Returns a document content as a string in an XML-format.
    */
   saveToXMLString() {
     let result = '';
@@ -1474,11 +1469,11 @@ class TXmlContentContainer {
   }
 
   /**
+   * Saves a document content to a file.
    * @param {string} source - a path to a file
    * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
-   * @description Saves a document content to a file.
    */
   saveToFile(source) {
     /**/// main part that return promise as a result
@@ -1515,9 +1510,9 @@ class TXmlContentContainer {
   }
 
   /**
+   * Saves a document content to a file.
    * @param {string} source - path to a file
    * @returns {fsoDescr}
-   * @description Saves a document content to a file.
    */
   saveToFileSync(source) {
     /** @type {fsoDescr} */
@@ -1544,10 +1539,10 @@ class TXmlContentContainer {
   }
 
   /**
+   * Loads a document content from a string.
    * @param {string} xmlString - some content
    * @returns {boolean}
    * @throws {Error}
-   * @description Loads a document content from a string.
    */
   loadFromXMLString(xmlString) {
     let isSUCCEED = false;
@@ -1568,11 +1563,11 @@ class TXmlContentContainer {
   }
 
   /**
+   * Loads a document content from a file.
    * @param {string} source - path to a file
    * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
-   * @description Loads a document content from a file.
    */
   loadFromFile(source) {
     /**/// main part that return promise as a result
@@ -1603,10 +1598,10 @@ class TXmlContentContainer {
   }
 
   /**
+   * Loads a document content from a file.
    * @param {string} source source - path to a file
    * @returns {fsoDescr}
    * @throws {Error}
-   * @description Loads a document content from a file.
    */
   loadFromFileSync(source) {
     const data = loadFromFileSync(source);
@@ -1629,9 +1624,9 @@ class TXmlContentContainer {
   }
 
   /**
+   * Returns a document content a string in a JSON-format.
    * @returns {string}
    * @protected
-   * @description Returns a document content a string in a JSON-format.
    */
   asJSON() {
     return JSON.stringify(this.#_content, null, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -39,10 +39,10 @@
     "@cntwg/file-helper": "^0.0.1",
     "@ygracs/bsfoc-lib-js": "^0.2.3",
     "@ygracs/xml-js6": "^0.0.5-b",
-    "@ygracs/xobj-lib-js": "^0.2.2"
+    "@ygracs/xobj-lib-js": "^0.2.3"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
+    "jest": "^30.0.4",
     "jsdoc-to-markdown": "^9.1.1",
     "minimist": "^1.2.8"
   }