@cntwg/xml-lib-js 0.0.28 → 0.0.30

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.085-20240801]
+// [v0.1.092-20240922]
 
 // === module init block ===
 
@@ -23,8 +23,8 @@ const {
 
 /**
  * @function checkFsError
- * @param {object}
- * @param {Error}
+ * @param {object} descr
+ * @param {Error} err
  * @returns {object}
  * @inner
  * @description Checs an error code of a fs ops and sets descr info if succeed
@@ -69,8 +69,8 @@ const XML_TE_NROOT_EMSG = 'root element not found';
 
 /**
  * @function readAsTagName
- * @param {any}
- * @return {string}
+ * @param {any} value
+ * @returns {string}
  * @since v0.0.28
  * @description Tries to convert a given value to a valid tag name
  *              of an XML-element.
@@ -92,8 +92,8 @@ function readAsTagName(value) {
 
 /**
  * @function readAsAttrName
- * @param {any}
- * @return {string}
+ * @param {any} value
+ * @returns {string}
  * @since v0.0.28
  * @description Tries to convert a given value to a valid name
  *              of an XML-attribute.
@@ -115,8 +115,8 @@ function readAsAttrName(value) {
 
 /**
  * @function valueToElementID
- * @param {any}
- * @return {string}
+ * @param {any} value
+ * @returns {string}
  * @since v0.0.28
  * @description Tries to convert a given value to a valid identifier
  *              suitable as a value for an "ID-attribute" of an XML-element.
@@ -144,16 +144,18 @@ function valueToElementID(value) {
  * @description This class implements an attributes mapper instance
  */
 class TXmlAttributesMapper {
-  #_host = null;
-  #_options = null;
+  /** @property {?object} */
+  #_host;// = null;
+  /** @property {?object} */
+  #_options;// = null;
 
   /**
-   * @param {object}
+   * @param {object} obj
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
    * @throws {TypeError}
    */
-  constructor(obj, opt){
+  constructor(obj, opt) {
     // init an elements content
     if (!isPlainObject(obj)) throw new TypeError(XML_TE_NOBJ_EMSG);
     this.#_host = obj;
@@ -178,10 +180,10 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @property {array}
+   * @property {Array}
    * @readonly
    */
-  get entries(){
+  get entries() {
     let items = xObj.getXObjAttributes(
       this.#_host,
       this.#_options.settings.attributesKey,
@@ -190,11 +192,11 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Checks whether an attribute exists.
    */
-  hasAttribute(name){
+  hasAttribute(name) {
     let result = false;
     try {
       result = xObj.checkXObjAttribute(
@@ -210,11 +212,11 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {string}
    * @description Returns an attribute value.
    */
-  getAttribute(name){
+  getAttribute(name) {
     let result = '';
     try {
       result = xObj.readXObjAttr(
@@ -230,12 +232,12 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {any}
-   * @returns {bool}
+   * @param {string} name
+   * @param {any} value
+   * @returns {boolean}
    * @description Sets an attribute value.
    */
-  setAttribute(name, value){
+  setAttribute(name, value) {
     const attrName = readAsAttrName(name);
     let result = false;
     if (attrName !== '') {
@@ -255,11 +257,11 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Deletes an attribute.
    */
-  delAttribute(name){
+  delAttribute(name) {
     let result = false;
     try {
       result = xObj.deleteXObjAttribute(
@@ -275,10 +277,36 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @returns {none}
+   * @param {string} name
+   * @param {string} value
+   * @returns {boolean}
+   * @since v0.0.30
+   * @description Renames an attribute.
+   */
+  renameAttribute(name, value) {
+    const newName = readAsAttrName(value);
+    let result = false;
+    if (newName !== '') {
+      try {
+        result = xObj.renameXObjAttribute(
+          this.#_host,
+          name,
+          newName,
+          this.#_options.settings.attributesKey,
+        );
+      } catch (err) {
+        // // TODO: verify what error is thrown
+        result = false;
+      };
+    };
+    return result;
+  }
+
+  /**
+   * @returns {void}
    * @description Deletes all attributes.
    */
-  clear(){
+  clear() {
     xObj.insertXObjElement(
       this.#_host,
       this.#_options.settings.attributesKey,
@@ -295,20 +323,24 @@ class TXmlAttributesMapper {
  * @description This class implements an instance of an element controller
  */
 class TXmlElementController {
-  #_host = null;
-  #_options = null;
-  #_parseOptions = null;
-  #_attributes = null;
+  /** @property {?object} */
+  #_host;// = null;
+  /** @property {?object} */
+  #_options;// = null;
+  /** @property {?object} */
+  #_parseOptions;// = null;
+  /** @property {?TXmlAttributesMapper} */
+  #_attributes;// = null;
   #_name = null;
 
   /**
-   * @param {object}
+   * @param {object} obj
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
-   * @param {bool} [opt.proxyModeEnable=false]
+   * @param {boolean} [opt.proxyModeEnable=false]
    * @throws {TypeError}
    */
-  constructor(obj, opt){
+  constructor(obj, opt) {
     // load options
     let _options = isPlainObject(opt) ? opt : {};
     let {
@@ -317,8 +349,7 @@ class TXmlElementController {
     } = _options;
     if (typeof proxyModeEnable !== 'boolean') proxyModeEnable = false;
     // init an element content
-    if (isObject(obj)) {
-      if (isArray(obj)) return new TXmlElementsListController(obj, opt);
+    if (isPlainObject(obj)) {
       // // TODO: split a plain object and class instances
       this.#_host = obj;
     } else {
@@ -330,20 +361,24 @@ class TXmlElementController {
       this.#_host = {};
     };
     // set parser options
-    if (!isPlainObject(parseOptions)) {
-      _options.parseOptions = parseOptions = {};
-    };
-    let { settings } = parseOptions;
-    if (!isPlainObject(settings)) parseOptions.settings = settings = {};
-    let { textKey } = settings;
-    if (
-      typeof textKey !== 'string'
-      || ((textKey = textKey.trim()) === '')
-    ) {
-      textKey = XML_DEF_PARSE_OPTIONS.textKey;
+    if (!(parseOptions instanceof TXmlContentParseOptions)) {
+      parseOptions = new TXmlContentParseOptions(parseOptions);
+      _options.parseOptions = parseOptions;
     };
+    //if (!isPlainObject(parseOptions)) {
+    //  _options.parseOptions = parseOptions = {};
+    //};
+    //let { settings } = parseOptions;
+    //if (!isPlainObject(settings)) parseOptions.settings = settings = {};
+    //let { textKey } = settings;
+    //if (
+    //  typeof textKey !== 'string'
+    //  || ((textKey = textKey.trim()) === '')
+    //) {
+    //  textKey = XML_DEF_PARSE_OPTIONS.textKey;
+    //};
     // save options
-    settings.textKey = textKey;
+    //settings.textKey = textKey;
     this.#_parseOptions = parseOptions;
     _options.proxyModeEnable = proxyModeEnable;
     this.#_options = _options;
@@ -355,7 +390,7 @@ class TXmlElementController {
    * @property {TXmlAttributesMapper}
    * @readonly
    */
-  get attributes(){
+  get attributes() {
     return this.#_attributes;
   }
 
@@ -364,7 +399,7 @@ class TXmlElementController {
    * @readonly
    * @experimental
    */
-  get name(){
+  get name() {
     let result = '';
     if (this.#_parseOptions.settings.compact) {
       result = xObj.readXObjParam(
@@ -380,53 +415,69 @@ class TXmlElementController {
   /**
    * @property {string}
    */
-  get textValue(){
+  get textValue() {
     return xObj.readXObjParam(this.#_host, this.#_parseOptions.settings.textKey);
   }
 
-  set textValue(value){
+  set textValue(value) {
     xObj.writeXObjParam(this.#_host, value, this.#_parseOptions.settings.textKey);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Checks whether an attribute exists.
    */
-  hasAttribute(name){
+  hasAttribute(name) {
     return this.#_attributes.hasAttribute(name);
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {string}
    * @description Returns an attribute value.
    */
-  getAttribute(name){
+  getAttribute(name) {
     return this.#_attributes.getAttribute(name);
   }
 
   /**
+   * @param {string} name
+   * @param {any} value
+   * @returns {boolean}
+   * @description Sets an attribute value.
    * @see TXmlAttributesMapper.setAttribute
    */
-  setAttribute(...args){
+  setAttribute(...args) {
     return this.#_attributes.setAttribute(...args);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Deletes an attribute.
    */
-  delAttribute(name){
+  delAttribute(name) {
     return this.#_attributes.delAttribute(name);
   }
 
   /**
-   * @returns {array}
+   * @param {string} name
+   * @param {string} value
+   * @returns {boolean}
+   * @since v0.0.30
+   * @description Renames an attribute.
+   * @see TXmlAttributesMapper.renameAttribute
+   */
+  renameAttribute(...args) {
+    return this.#_attributes.renameAttribute(...args);
+  }
+
+  /**
+   * @returns {string[]}
    * @description Returns a text value in format of a `[ <lang>, <text> ]` pair.
    */
-  getTextValue(){
+  getTextValue() {
     return [
       this.#_attributes.getAttribute(XML_LANG_ATTR_TNAME),
       this.textValue,
@@ -434,11 +485,11 @@ class TXmlElementController {
   }
 
   /**
-   * @param {(string|entry)}
-   * @returns {bool}
+   * @param {(string|string[])} value
+   * @returns {boolean}
    * @description Sets a text value.
    */
-  setTextValue(value){
+  setTextValue(value) {
     const _value = valueToEntry(value);
     if (_value !== null) {
       const [ lang, param ] = _value;
@@ -463,8 +514,8 @@ class TXmlElementController {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Checks whether an element has a child element.
    */
   hasChild(name) {
@@ -482,36 +533,32 @@ class TXmlElementController {
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {(null|TXmlElementController|TXmlElementsListController)}
    * @description Returns a child element.
    */
   getChild(name) {
-    let result = xObj.evalXObjEName(name);
-    if (result === null) return null;
-    try {
-      const item = xObj.getXObjElement(this.#_host, result);
-      if (isArray(item)) {
-        result = new TXmlElementsListController(item, this.#_options);
-      } else if (isObject(item)) {
-        result = new TXmlElementController(item, this.#_options);
-      } else {
+    const _name = xObj.evalXObjEName(name);
+    let result = null;
+    if (_name !== null) {
+      try {
+        const item = xObj.getXObjElement(this.#_host, _name);
+        result = TXmlElementController.create(item, this.#_options);
+      } catch (err) {
+        // // TODO: [?] verify what error is thrown
         result = null;
       };
-    } catch (err) {
-      // // TODO: [?] verify what error is thrown
-      result = null;
     };
     return result;
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {object}
    * @protected
    * @description Returns a child element.
    */
-  _getChildRaw(name){
+  _getChildRaw(name) {
     //console.log('CHECK: TXmlElementController._getChildRaw() => was called...');
     //console.log('CHECK: TXmlElementController._getChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
     let item = xObj.getXObjElement(this.#_host, name);
@@ -524,22 +571,25 @@ class TXmlElementController {
   }
 
   /**
-   * @see TXmlElementController.__setChildRaw
+   * @param {string} name
+   * @param {object} obj
+   * @returns {boolean}
    * @protected
    * @description Sets a child element.
+   * @see TXmlElementController.__setChildRaw
    */
-  _setChildRaw(...args){
+  _setChildRaw(...args) {
     //console.log('CHECK: TXmlElementController._setChildRaw() => was called...');
     return TXmlElementController.__setChildRaw(this, ...args);
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {?object}
    * @protected
    * @description Adds a new child element.
    */
-  _addChildRaw(name){//}, obj){
+  _addChildRaw(name) {
     //console.log('CHECK: TXmlElementController._addChild() => was called...');
     //console.log('CHECK: TXmlElementController._addChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
     let result = xObj.addXObjElement(this.#_host, name);
@@ -552,7 +602,7 @@ class TXmlElementController {
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @returns {?TXmlElementController}
    * @description Adds a new child element.
    */
@@ -572,8 +622,8 @@ class TXmlElementController {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name
+   * @returns {boolean}
    * @description Deletes a child element.
    */
   delChild(name) {
@@ -605,34 +655,83 @@ class TXmlElementController {
   }
 
   /**
-   * @returns {none}
+   * @returns {void}
    * @description Deletes all child elements and attributes.
    */
-  clear(){
+  clear() {
     TXmlElementController.clear(this);
   }
 
   /**
-   * @param {object}
+   * @param {string} loadFromXMLString
+   * @returns {boolean}
+   * @throws {Error}
+   * @experimental
+   * @description Loads a element content from a string.
+   */
+  loadFromXMLString(xmlString) {
+    let result = false;
+    if (typeof xmlString === 'string' && xmlString !== '') {
+      const _options = this.#_options;
+      let {
+        proxyModeEnable,
+        parseOptions,
+      } = _options;
+      parseOptions = parseOptions.xml2js;
+      parseOptions.ignoreDocType = true;
+      parseOptions.ignoreDeclaration = true;
+      try {
+        let obj = xmlParser.xml2js(xmlString, parseOptions);
+        if (isPlainObject(obj)) {
+          let list = Object.entries(obj);
+          let item = list[0];
+          obj = item[1];
+          if (isPlainObject(obj)) {
+            if (proxyModeEnable) {
+              let list = Object.entries(obj);
+              const target = this.#_host;
+              this.clear();
+              list.forEach((entry) => {
+                const [key, value] = entry;
+                target[key] = value;
+              });
+            } else {
+              this.#_host = obj;
+            };
+            this.#_attributes = new TXmlAttributesMapper(obj, _options);
+            result = true;
+          };
+        };
+      } catch (err) {
+        //console.log('CHECK: TXmlContentContainer.loadFromXMLString() => Error => '+err);
+        //console.log('CHECK: TXmlContentContainer.loadFromXMLString() => Error => '+err.code);
+        throw err;
+      };
+    };
+    return result;
+  }
+
+  /**
+   * @param {object} item
    * @returns {?object}
    * @protected
    * @static
    * @description Tries to unwraps a given object.
    */
-  static __unwrap(item){
+  static __unwrap(item) {
     return (item instanceof TXmlElementController) ? item.#_host : null;
   }
 
   /**
-   * @param {TXmlElementController}
-   * @param {ID_STRING}
-   * @param {object}
-   * @returns {bool}
+   * @param {TXmlElementController} node
+   * @param {string} name
+   * @param {object} obj
+   * @returns {boolean}
    * @protected
    * @static
    * @description Sets a child element.
    */
-  static __setChildRaw(node, name, obj){
+  static __setChildRaw(node, name, obj) {
     //console.log('CHECK: TXmlElementController.__setChildRaw() => was called...');
     let isSUCCEED = false;
     if (node instanceof TXmlElementController) {
@@ -655,12 +754,12 @@ class TXmlElementController {
   }
 
   /**
-   * @param {object}
-   * @returns {none}
+   * @param {object} obj
+   * @returns {void}
    * @static
    * @description Tries to clean a given object.
    */
-  static clear(obj){
+  static clear(obj) {
     let item = TXmlElementController.__unwrap(obj);
     if (item) {
       for (let prop in item) {
@@ -670,25 +769,51 @@ class TXmlElementController {
     };
   }
 
+  /**
+   * @param {object} obj
+   * @param {object} [opt]
+   * @returns {(null|TXmlElementController|TXmlElementsListController)}
+   * @static
+   * @description Creates new controller element.
+   */
+  static create(obj, opt) {
+    let result = null;
+    try {
+      if (isObject(obj)) {
+        if (isArray(obj)) {
+          result = new TXmlElementsListController(obj, opt);
+        } else {
+          // // TODO: [?] check what kind of object passed in
+          result = new TXmlElementController(obj, opt);
+        };
+      };
+    } catch (err) {
+      result = null;
+    };
+    return result;
+  }
+
 };
 
 /**
  * @description This class implements an instance of a list controller
  */
 class TXmlElementsListController {
-  #_host = null;
-  #_options = null;
+  /** @property {?Array} */
+  #_host;// = null;
+  /** @property {?object} */
+  #_options;// = null;
   #_count = null;
 
   /**
-   * @param {array}
+   * @param {Array} obj
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
-   * @param {bool} [opt.proxyModeEnable=false]
-   * @param {bool} [opt.isNullItemsAllowed=false] - <reserved>
+   * @param {boolean} [opt.proxyModeEnable=false]
+   * @param {boolean} [opt.isNullItemsAllowed=false] - <reserved>
    * @throws {TypeError}
    */
-  constructor(obj, opt){
+  constructor(obj, opt) {
     // load options
     let _options = isPlainObject(opt) ? opt : {};
     let {
@@ -727,7 +852,7 @@ class TXmlElementsListController {
    * @property {number}
    * @readonly
    */
-  get count(){
+  get count() {
     return this.#_host.length;
   }
 
@@ -735,67 +860,67 @@ class TXmlElementsListController {
    * @property {number}
    * @readonly
    */
-  get size(){
+  get size() {
     return this.#_host.length;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
    */
-  get maxIndex(){
+  get maxIndex() {
     return this.#_host.length - 1;
   }
 
   /**
-   * @property {bool}
+   * @property {boolean}
    * @readonly
    */
-  get isNullItemsAllowed(){
+  get isNullItemsAllowed() {
     return readAsBool(this.#_options.isNullItemsAllowed);
   }
 
   /**
-   * @returns {none}
+   * @returns {void}
    * @description Deletes all child elements and attributes.
    */
-  clear(){
+  clear() {
     this.#_host.length = 0;
   }
 
   /**
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks whether an instance holds none element.
    */
-  isEmpty(){
+  isEmpty() {
     return this.count === 0;
   }
 
   /**
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks whether an instance holds at least one element.
    */
-  isNotEmpty(){
+  isNotEmpty() {
     return this.count > 0;
   }
 
   /**
-   * @param {any}
-   * @returns {bool}
+   * @param {any} value
+   * @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){
+  chkIndex(value) {
     const index = valueToIndex(value);
     return index !== -1 && index < this.size;
   }
 
   /**
-   * @param {any}
-   * @returns {bool}
+   * @param {any} obj
+   * @returns {boolean}
    * @description Checks whether or not a given element is valid.
    */
-  isValidItem(obj){
+  isValidItem(obj) {
     return (
       (this.#_options.isNullItemsAllowed && obj === null)
       || isPlainObject(obj)
@@ -803,22 +928,22 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {index}
+   * @param {number} index
    * @returns {?object}
    * @protected
    * @description Returns an element.
    */
-  _getItemRaw(index){
+  _getItemRaw(index) {
     let item = this.#_host[valueToIndex(index)];
     return item !== undefined ? item : null;
   }
 
   /**
-   * @param {index}
+   * @param {number} index
    * @returns {?TXmlElementController}
    * @description Returns an element.
    */
-  getItem(index){
+  getItem(index) {
     let item = this.#_host[valueToIndex(index)];
     // wrap item in container
     return (
@@ -829,12 +954,12 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any}
-   * @returns {index}
+   * @param {any} item
+   * @returns {number}
    * @protected
    * @description Adds a new element.
    */
-  _addItemRaw(item){
+  _addItemRaw(item) {
     let index = -1;
     if (this.isValidItem(item)) {
       index = this.size;
@@ -844,11 +969,11 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any}
-   * @returns {index}
+   * @param {any} item
+   * @returns {number}
    * @description Adds a new element.
    */
-  addItem(item){
+  addItem(item) {
     // unwrap item from container
     if (item instanceof TXmlElementController) {
       item = TXmlElementController.__unwrap(item);
@@ -857,25 +982,25 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {index}
-   * @param {any}
-   * @returns {bool}
+   * @param {number} index
+   * @param {any} item
+   * @returns {boolean}
    * @protected
    * @description Sets a new element.
    */
-  _setItemRaw(index, item){
+  _setItemRaw(index, item) {
     let isSUCCEED = this.chkIndex(index) && this.isValidItem(item);
     if (isSUCCEED) this.#_host[Number(index)] = item; // // TODO: correct count
     return isSUCCEED;
   }
 
   /**
-   * @param {index}
-   * @param {any}
-   * @returns {bool}
+   * @param {string} index
+   * @param {any} item
+   * @returns {boolean}
    * @description Sets a new element.
    */
-  setItem(index, item){
+  setItem(index, item) {
     // unwrap item from container
     if (item instanceof TXmlElementController) {
       item = TXmlElementController.__unwrap(item);
@@ -884,13 +1009,13 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {index}
-   * @param {any}
-   * @returns {bool}
+   * @param {number} index
+   * @param {any} item
+   * @returns {boolean}
    * @protected
    * @description Insertes a new element.
    */
-  _insItemRaw(index, item){
+  _insItemRaw(index, item) {
     index = valueToIndex(index);
     let size = this.size;
     let isSUCCEED = (
@@ -911,12 +1036,12 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {index}
-   * @param {any}
-   * @returns {bool}
+   * @param {number} index
+   * @param {any} item
+   * @returns {boolean}
    * @description Insertes a new element.
    */
-  insItem(index, item){
+  insItem(index, item) {
     // unwrap item from container
     if (item instanceof TXmlElementController) {
       item = TXmlElementController.__unwrap(item);
@@ -925,11 +1050,11 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {number} index
+   * @returns {boolean}
    * @description Deletes an element.
    */
-  delItem(value){
+  delItem(value) {
     let isSUCCEED = this.chkIndex(value);
     if (isSUCCEED) {
       let index = Number(value);
@@ -949,13 +1074,13 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any}
+   * @param {any} items
    * @param {object} [opt]
-   * @param {bool} [opt.useClear=true]
+   * @param {boolean} [opt.useClear=true]
    * @returns {number}
    * @description Loads a list of an elements.
    */
-  loadItems(items, opt){
+  loadItems(items, opt) {
     const _options = isPlainObject(opt) ? opt : {};
     let {
       useClear,
@@ -974,17 +1099,20 @@ class TXmlElementsListController {
  *              that managea content of a document declaration
  */
 class TXmlContentDeclaration {
-  #_host = null;
-  #_options = null;
-  #_ctrls = null;
+  /** @property {?object} */
+  #_host;// = null;
+  /** @property {?object} */
+  #_options;// = null;
+  /** @property {?TXmlElementController} */
+  #_ctrls;// = null;
 
   /**
-   * @param {object}
+   * @param {object} obj
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
    * @throws {TypeError}
    */
-  constructor(obj, opt){
+  constructor(obj, opt) {
     // check <obj>-param
     if (!isPlainObject(obj)) {
       throw new TypeError(`TXmlContentDeclaration : ${XML_TE_NOBJ_EMSG}`);
@@ -1017,30 +1145,30 @@ class TXmlContentDeclaration {
   /**
    * @property {string}
    */
-  get version(){
+  get version() {
     return this.#_ctrls.getAttribute('version');
   }
 
-  set version(value){
+  set version(value) {
     this.#_ctrls.setAttribute('version', value);
   }
 
   /**
    * @property {string}
    */
-  get encoding(){
+  get encoding() {
     return this.#_ctrls.getAttribute('encoding');
   }
 
-  set encoding(value){
+  set encoding(value) {
     this.#_ctrls.setAttribute('encoding', value);
   }
 
   /**
-   * @returns {bool}
+   * @returns {boolean}
    * @description Initializes an instance content.
    */
-  init(){
+  init() {
     const _options = this.#_options;
     this.#_ctrls = new TXmlElementController(
       xObj.insertXObjElement(
@@ -1061,18 +1189,20 @@ class TXmlContentDeclaration {
  * @description This class implements an instance of a root element
  */
 class TXmlContentRootElement extends TXmlElementController {
-  #_content = null;
-  #_options = null;
+  /** @property {?object} */
+  #_content;// = null;
+  /** @property {?object} */
+  #_options;// = null;
 
   /**
-   * @param {object}
+   * @param {object} obj
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
-   * @param {ID_STRING} [opt.rootETagName='']
-   * @param {bool} [opt.autoBindRoot=true]
+   * @param {string} [opt.rootETagName='']
+   * @param {boolean} [opt.autoBindRoot=true]
    * @throws {TypeError}
    */
-  constructor(obj, opt){
+  constructor(obj, opt) {
     // check <obj>-param
     if (!isPlainObject(obj)) {
       throw new TypeError(`TXmlContentRootElement : ${XML_TE_NOBJ_EMSG}`);
@@ -1160,11 +1290,11 @@ class TXmlContentRootElement extends TXmlElementController {
   /**
    * @property {string}
    */
-  get tagName(){
+  get tagName() {
     return this.#_options.rootETagName;
   }
 
-  set tagName(value){
+  set tagName(value) {
     value = readAsString(value, true);
     this.#_options.rootETagName = isNotEmptyString(
       value
@@ -1172,14 +1302,14 @@ class TXmlContentRootElement extends TXmlElementController {
   }
 
   /**
-   * @param {object}
-   * @param {bool} [opt=false]
+   * @param {object} item
+   * @param {boolean} [opt=false]
    * @returns {?object}
    * @protected
    * @static
    * @description Tries to unwraps a given object.
    */
-  static __unwrap(item, opt){
+  static __unwrap(item, opt) {
     return (
       item instanceof TXmlContentRootElement
       && (typeof opt === 'boolean' ? opt : false)
@@ -1195,17 +1325,22 @@ class TXmlContentRootElement extends TXmlElementController {
  *              that managea content of a document
  */
 class TXmlContentContainer {
-  #_content = null;
-  #_options = null;
-  #_parseOptions = null;
-  #_docDecl = null;
-  #_docRoot = null;
+  /** @property {?object} */
+  #_content;// = null;
+  /** @property {?object} */
+  #_options;// = null;
+  /** @property {?object} */
+  #_parseOptions;// = null;
+  /** @property {?TXmlContentDeclaration} */
+  #_docDecl;// = null;
+  /** @property {?TXmlContentRootElement} */
+  #_docRoot;// = null;
 
   /**
    * @param {object} [opt]
    * @param {object} [opt.parseOptions]
    */
-  constructor(opt){
+  constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
     let { parseOptions } = _options;
@@ -1230,26 +1365,27 @@ class TXmlContentContainer {
    * @property {TXmlContentRootElement}
    * @readonly
    */
-  get rootElement(){
+  get rootElement() {
     return this.#_docRoot;
   }
 
   /**
-   * @returns {none}
+   * @returns {void}
    * @description Cleans a document content.
    */
-  clear(){
+  clear() {
     this.#_docDecl.init();
     this.rootElement.clear();
   }
 
   /**
-   * @param {object}
-   * @returns {bool}
+   * @param {object} obj
+   * @param {object} [opt]
+   * @returns {boolean}
    * @protected
    * @description Initializes an instance with a given content.
    */
-  _bindContent(obj, opt){
+  _bindContent(obj, opt) {
     const _options = isPlainObject(opt) ? opt : this.#_options;
     let isSUCCEED = false;
     if (isPlainObject(obj)) {
@@ -1281,7 +1417,7 @@ class TXmlContentContainer {
    * @returns {string}
    * @description Returns a document content as a string in an XML-format.
    */
-  saveToXMLString(){
+  saveToXMLString() {
     let result = '';
     try {
       result = xmlParser.js2xml(this.#_content, this.#_parseOptions.js2xml);
@@ -1293,13 +1429,13 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string}
+   * @param {string} source
    * @returns {object}
    * @throws {Error}
    * @async
    * @description Saves a document content to a file.
    */
-  saveToFile(source){
+  saveToFile(source) {
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
       let data = {
@@ -1337,12 +1473,12 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string}
+   * @param {string} source
    * @returns {object}
    * @throws {Error}
    * @description Saves a document content to a file.
    */
-  saveToFileSync(source){
+  saveToFileSync(source) {
     let data = {
       isSucceed: false,
       source: typeof source === 'string' ? source.trim() : '',
@@ -1374,12 +1510,12 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string}
-   * @returns {bool}
+   * @param {string} loadFromXMLString
+   * @returns {boolean}
    * @throws {Error}
    * @description Loads a document content from a string.
    */
-  loadFromXMLString(xmlString){
+  loadFromXMLString(xmlString) {
     let isSUCCEED = false;
     if (typeof xmlString === 'string') {
       let obj = null;
@@ -1398,13 +1534,13 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string}
+   * @param {string} source
    * @returns {object}
    * @throws {Error}
    * @async
    * @description Loads a document content from a file.
    */
-  loadFromFile(source){
+  loadFromFile(source) {
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
       let data = {
@@ -1452,12 +1588,12 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string}
+   * @param {string} source
    * @returns {object}
    * @throws {Error}
    * @description Loads a document content from a file.
    */
-  loadFromFileSync(source){
+  loadFromFileSync(source) {
     let data = {
       isLoaded: false,
       source: typeof source === 'string' ? source.trim() : '',
@@ -1504,7 +1640,7 @@ class TXmlContentContainer {
    * @protected
    * @description Returns a document content a string in a JSON-format.
    */
-  asJSON(){
+  asJSON() {
     return JSON.stringify(this.#_content, null, 2);
   }