@cntwg/xml-lib-js 0.0.30 → 0.0.32

package/lib/xmldoc-lib.js

@@ -1,9 +1,7 @@
-// [v0.1.092-20240922]
+// [v0.2.107-20250208]
 
 // === module init block ===
 
-const fs = require('fs');
-const fse = fs.promises;
 const xmlParser = require('@ygracs/xml-js6');
 
 const {
@@ -13,6 +11,11 @@ const {
   valueToIDString,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  loadFileSync, loadFile,
+  saveToFileSync, saveToFile,
+} = require('./file-helper.js');
+
 const xObj = require('@ygracs/xobj-lib-js');
 const {
   TXmlContentParseOptions,
@@ -22,31 +25,62 @@ const {
 // === module extra block (helper functions) ===
 
 /**
- * @function checkFsError
- * @param {object} descr
- * @param {Error} err
- * @returns {object}
+ * @typedef {Object} OPT_xmlelemsett
+ * @property {object} [parseOptions] - parser options
+ * @property {boolean} [opt.proxyModeEnable=false]
+ * @property {boolean} [opt.isNullItemsAllowed=false] - <reserved>
+ * @description An XML-element controller settings.
+ */
+
+/**
+ * @function __evalXMLElementSettings
+ * @param {any} value - element settings to evaluate
+ * @returns {OPT_xmlelemsett}
  * @inner
- * @description Checs an error code of a fs ops and sets descr info if succeed
+ * @description Evaluates an XML-element settings
  */
-function checkFsError(descr, err) {
-  let isSucceed = false;
-  if (isPlainObject(err) && isPlainObject(descr)) {
-    switch (err.code) {
-      case 'ENOENT':
-      case 'EISDIR':
-      case 'EPERM': {
-        descr.errCode = err.errno;
-        descr.errEvent = err.code;
-        descr.errMsg = `ERR_FILE_${err.code}`;
-        isSucceed = true;
-        break;
-      }
-      default: {}
-    };
-    if (isSucceed) descr.isERR = true;
+function __evalXMLElementSettings(value) {
+  const settings = isPlainObject(value) ? value : {};
+  let {
+    proxyModeEnable,
+    isNullItemsAllowed,
+    parseOptions,
+  } = settings;
+  if (!(parseOptions instanceof TXmlContentParseOptions)) {
+    settings.parseOptions = new TXmlContentParseOptions(parseOptions);
   };
-  return { isSucceed, descr };
+  if (typeof proxyModeEnable !== 'boolean') settings.proxyModeEnable = false;
+  if (typeof isNullItemsAllowed !== 'boolean') settings.isNullItemsAllowed = false;
+  return settings;
+};
+
+/**
+ * @typedef {Object} OPT_xmlcontsett
+ * @augments OPT_xmlelemsett
+ * @property {string} [rootETagName]
+ * @property {boolean} [autoBindRoot=true]
+ * @description An XML-content container settings.
+ */
+
+/**
+ * @function __evalXMLContainerSettings
+ * @param {any} value - container settings to evaluate
+ * @returns {OPT_xmlcontsett}
+ * @inner
+ * @description Evaluates an XML-container settings
+ */
+function __evalXMLContainerSettings(value) {
+  const settings = __evalXMLElementSettings(value);
+  let { rootETagName, autoBindRoot } = settings;
+  if (
+    typeof rootETagName !== 'string'
+    || ((rootETagName = rootETagName.trim()) === '')
+  ) {
+    rootETagName = XML_DEF_ROOT_ETAG_NAME;
+  };
+  settings.rootETagName = rootETagName;
+  if (typeof autoBindRoot !== 'boolean') settings.autoBindRoot = true;
+  return settings;
 };
 
 // === module main block ===
@@ -68,10 +102,10 @@ const XML_TE_NROOT_EMSG = 'root element not found';
  */
 
 /**
+ * @since v0.0.28
  * @function readAsTagName
- * @param {any} value
+ * @param {any} value - some value
  * @returns {string}
- * @since v0.0.28
  * @description Tries to convert a given value to a valid tag name
  *              of an XML-element.
  */
@@ -91,10 +125,10 @@ function readAsTagName(value) {
 };
 
 /**
+ * @since v0.0.28
  * @function readAsAttrName
- * @param {any} value
+ * @param {any} value - some value
  * @returns {string}
- * @since v0.0.28
  * @description Tries to convert a given value to a valid name
  *              of an XML-attribute.
  */
@@ -114,10 +148,10 @@ function readAsAttrName(value) {
 };
 
 /**
+ * @since v0.0.28
  * @function valueToElementID
- * @param {any} value
+ * @param {any} value - some 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.
  */
@@ -141,32 +175,28 @@ function valueToElementID(value) {
  */
 
 /**
- * @description This class implements an attributes mapper instance
+ * @classdesc This class implements an attributes mapper instance
  */
 class TXmlAttributesMapper {
   /** @property {?object} */
-  #_host;// = null;
-  /** @property {?object} */
-  #_options;// = null;
+  #_host;
+  /** @property {OPT_xmlelemsett} */
+  #_options;
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
+   * @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
-    const _options = isPlainObject(opt) ? opt : {};
-    let { parseOptions } = _options;
-    if (!isPlainObject(parseOptions)) {
-      _options.parseOptions = parseOptions = {};
-    };
-    let { settings } = parseOptions;
-    if (!isPlainObject(settings)) parseOptions.settings = settings = {};
+    const _options = __evalXMLElementSettings(opt);
+    const { parseOptions } = _options;
+    const { settings } = parseOptions;
     let { attributesKey } = settings;
     if (
       typeof attributesKey !== 'string'
@@ -180,7 +210,8 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @property {Array}
+   * Contains a list of all instance attributes as a `<name>-<value>` pairs
+   * @property {any[]}
    * @readonly
    */
   get entries() {
@@ -192,7 +223,7 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {boolean}
    * @description Checks whether an attribute exists.
    */
@@ -212,7 +243,7 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {string}
    * @description Returns an attribute value.
    */
@@ -232,8 +263,8 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {string} name
-   * @param {any} value
+   * @param {string} name - attribute name
+   * @param {any} value - some value
    * @returns {boolean}
    * @description Sets an attribute value.
    */
@@ -257,7 +288,7 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {boolean}
    * @description Deletes an attribute.
    */
@@ -277,10 +308,10 @@ class TXmlAttributesMapper {
   }
 
   /**
-   * @param {string} name
-   * @param {string} value
-   * @returns {boolean}
    * @since v0.0.30
+   * @param {string} name - attribute name
+   * @param {string} value - new name
+   * @returns {boolean}
    * @description Renames an attribute.
    */
   renameAttribute(name, value) {
@@ -320,34 +351,32 @@ class TXmlAttributesMapper {
 }
 
 /**
- * @description This class implements an instance of an element controller
+ * @classdesc This class implements an instance of an element controller
  */
 class TXmlElementController {
   /** @property {?object} */
-  #_host;// = null;
-  /** @property {?object} */
-  #_options;// = null;
+  #_host;
+  /** @property {OPT_xmlelemsett} */
+  #_options;
   /** @property {?object} */
-  #_parseOptions;// = null;
+  #_parseOptions;
   /** @property {?TXmlAttributesMapper} */
-  #_attributes;// = null;
+  #_attributes;
   #_name = null;
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
-   * @param {boolean} [opt.proxyModeEnable=false]
+   * @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
-    let _options = isPlainObject(opt) ? opt : {};
-    let {
+    const _options = __evalXMLElementSettings(opt);
+    const {
       proxyModeEnable,
       parseOptions,
     } = _options;
-    if (typeof proxyModeEnable !== 'boolean') proxyModeEnable = false;
     // init an element content
     if (isPlainObject(obj)) {
       // // TODO: split a plain object and class instances
@@ -360,33 +389,16 @@ class TXmlElementController {
       };
       this.#_host = {};
     };
-    // set parser options
-    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;
     this.#_parseOptions = parseOptions;
-    _options.proxyModeEnable = proxyModeEnable;
+    //_options.proxyModeEnable = proxyModeEnable;
     this.#_options = _options;
     // bind atributes mapper
     this.#_attributes = new TXmlAttributesMapper(obj, _options);
   }
 
   /**
+   * Contains an element attribute mapper instance
    * @property {TXmlAttributesMapper}
    * @readonly
    */
@@ -413,6 +425,7 @@ class TXmlElementController {
   }
 
   /**
+   * Contains an element text value
    * @property {string}
    */
   get textValue() {
@@ -424,26 +437,28 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {boolean}
    * @description Checks whether an attribute exists.
+   * @see TXmlAttributesMapper.hasAttribute
    */
   hasAttribute(name) {
     return this.#_attributes.hasAttribute(name);
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {string}
    * @description Returns an attribute value.
+   * @see TXmlAttributesMapper.getAttribute
    */
   getAttribute(name) {
     return this.#_attributes.getAttribute(name);
   }
 
   /**
-   * @param {string} name
-   * @param {any} value
+   * @param {string} name - attribute name
+   * @param {any} value - some value
    * @returns {boolean}
    * @description Sets an attribute value.
    * @see TXmlAttributesMapper.setAttribute
@@ -453,19 +468,20 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - attribute name
    * @returns {boolean}
    * @description Deletes an attribute.
+   * @see TXmlAttributesMapper.delAttribute
    */
   delAttribute(name) {
     return this.#_attributes.delAttribute(name);
   }
 
   /**
-   * @param {string} name
-   * @param {string} value
-   * @returns {boolean}
    * @since v0.0.30
+   * @param {string} name - attribute name
+   * @param {string} value - new attribute name
+   * @returns {boolean}
    * @description Renames an attribute.
    * @see TXmlAttributesMapper.renameAttribute
    */
@@ -485,7 +501,7 @@ class TXmlElementController {
   }
 
   /**
-   * @param {(string|string[])} value
+   * @param {(string|string[])} value - some text
    * @returns {boolean}
    * @description Sets a text value.
    */
@@ -514,7 +530,7 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - some child element name
    * @returns {boolean}
    * @description Checks whether an element has a child element.
    */
@@ -533,8 +549,8 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
-   * @returns {(null|TXmlElementController|TXmlElementsListController)}
+   * @param {string} name - some child element name
+   * @returns {?(TXmlElementController|TXmlElementsListController)}
    * @description Returns a child element.
    */
   getChild(name) {
@@ -554,20 +570,15 @@ class TXmlElementController {
 
   /**
    * @param {string} name
-   * @returns {object}
+   * @returns {?any}
    * @protected
+   * @deprecated
    * @description Returns a child element.
+   * @see TXmlElementController.__getChildRaw
    */
   _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);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item => '+item);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item.name() => ['+name+']');
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item.typeof() => '+typeof item);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item => '+JSON.stringify(item, null, 2));
-    //console.log('CHECK: TXmlElementController._getChildRaw() => was left...');
-    return item !== undefined ? item : null;
+    return TXmlElementController.__getChildRaw(this, name);
   }
 
   /**
@@ -575,6 +586,7 @@ class TXmlElementController {
    * @param {object} obj
    * @returns {boolean}
    * @protected
+   * @deprecated
    * @description Sets a child element.
    * @see TXmlElementController.__setChildRaw
    */
@@ -585,24 +597,19 @@ class TXmlElementController {
 
   /**
    * @param {string} name
-   * @returns {?object}
+   * @returns {?Object}
    * @protected
+   * @deprecated
    * @description Adds a new child element.
+   * @see TXmlElementController.__addChildRaw
    */
   _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);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => result => '+result);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item.name() => ['+name+']');
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item.typeof() => '+typeof result.item);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item => '+JSON.stringify(result.item, null, 2));
-    //console.log('CHECK: TXmlElementController._addChildRaw() => was left...');
-    return result.isSucceed ? result.item : null;
+    return TXmlElementController.__addChildRaw(this, name);
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - some child element name
    * @returns {?TXmlElementController}
    * @description Adds a new child element.
    */
@@ -622,7 +629,7 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} name
+   * @param {string} name - some child element name
    * @returns {boolean}
    * @description Deletes a child element.
    */
@@ -663,7 +670,8 @@ class TXmlElementController {
   }
 
   /**
-   * @param {string} loadFromXMLString
+   * @since v0.0.30
+   * @param {string} xmlString - some content
    * @returns {boolean}
    * @throws {Error}
    * @experimental
@@ -722,6 +730,57 @@ class TXmlElementController {
     return (item instanceof TXmlElementController) ? item.#_host : null;
   }
 
+  /**
+   * @since v0.0.31
+   * @param {TXmlElementController} node
+   * @param {string} name
+   * @returns {?any}
+   * @protected
+   * @static
+   * @description Returns a child element.
+   */
+  static __getChildRaw(node, name) {
+    let item = null;
+    if (node instanceof TXmlElementController) {
+      try {
+        const obj = node.#_host;
+        item = xObj.getXObjElement(obj, name);
+        if (item === undefined) item = null;
+      } catch (err) {
+        // // TODO: [?] check what kind of error thrown
+        item = null;
+      };
+    };
+    return item;
+  }
+
+  /**
+   * @since v0.0.31
+   * @param {TXmlElementController} node
+   * @param {string} name
+   * @returns {?Object}
+   * @protected
+   * @static
+   * @description Adds a new child element.
+   */
+  static __addChildRaw(node, name) {
+    const childName = readAsTagName(name);
+    let item = null;
+    if (
+      node instanceof TXmlElementController
+      && childName !== ''
+    ) {
+      try {
+        const obj = node.#_host;
+        ({ item } = xObj.addXObjElement(obj, childName));
+      } catch (err) {
+        // // TODO: [?] check what kind of error thrown
+        item = null;
+      };
+    };
+    return item;
+  }
+
   /**
    * @param {TXmlElementController} node
    * @param {string} name
@@ -732,25 +791,17 @@ class TXmlElementController {
    * @description Sets a child element.
    */
   static __setChildRaw(node, name, obj) {
-    //console.log('CHECK: TXmlElementController.__setChildRaw() => was called...');
-    let isSUCCEED = false;
-    if (node instanceof TXmlElementController) {
-      let item = null;
-      if (isArray(obj)) {
-        //console.log('CHECK: TXmlElementController.__setChildRaw() => <obj> is array...');
-        item = xObj.insertXObjEList(node.#_host, name, { force: true });
-        // load elements
-        for (let element of obj) {
-          if (isPlainObject(element)) item.push(element);
-        };
-      } else if (isObject(obj)) {
-        //console.log('CHECK: TXmlElementController.__setChildRaw() => <obj> is object...');
-        item = xObj.insertXObjElement(node.#_host, name, { force: true });
-        // // TODO: set element
-      };
-      if (item) isSUCCEED = true;
+    const childName = readAsTagName(name);
+    let isSucceed = false;
+    if (
+      node instanceof TXmlElementController
+      && childName !== ''
+      && isObject(obj)
+    ) {
+      node.#_host[childName] = obj;
+      isSucceed = true;
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
@@ -770,9 +821,10 @@ class TXmlElementController {
   }
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
-   * @returns {(null|TXmlElementController|TXmlElementsListController)}
+   * @since v0.0.30
+   * @param {object} obj - some object
+   * @param {object} [opt] - options
+   * @returns {?(TXmlElementController|TXmlElementsListController)}
    * @static
    * @description Creates new controller element.
    */
@@ -796,39 +848,27 @@ class TXmlElementController {
 };
 
 /**
- * @description This class implements an instance of a list controller
+ * @classdesc This class implements an instance of a list controller
  */
 class TXmlElementsListController {
-  /** @property {?Array} */
-  #_host;// = null;
-  /** @property {?object} */
-  #_options;// = null;
+  /** @property {?object[]} */
+  #_host;
+  /** @property {OPT_xmlelemsett} */
+  #_options;
   #_count = null;
 
   /**
-   * @param {Array} obj
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
-   * @param {boolean} [opt.proxyModeEnable=false]
-   * @param {boolean} [opt.isNullItemsAllowed=false] - <reserved>
+   * @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
-    let _options = isPlainObject(opt) ? opt : {};
-    let {
+    const _options = __evalXMLElementSettings(opt);
+    const {
       proxyModeEnable,
-      isNullItemsAllowed,
-      parseOptions,
     } = _options;
-    if (typeof proxyModeEnable !== 'boolean') proxyModeEnable = false;
-    if (typeof isNullItemsAllowed !== 'boolean') isNullItemsAllowed = false;
-    // set parser options
-    if (!isPlainObject(parseOptions)) {
-      _options.parseOptions = parseOptions = {};
-    };
-    let { settings } = parseOptions;
-    if (!isPlainObject(settings)) parseOptions.settings = settings = {};
     // init an elements list content
     if (isArray(obj)) {
       this.#_host = obj;
@@ -843,12 +883,11 @@ class TXmlElementsListController {
       };
     };
     // save options
-    _options.proxyModeEnable = proxyModeEnable;
-    _options.isNullItemsAllowed = isNullItemsAllowed;
     this.#_options = _options;
   }
 
   /**
+   * Contains a quantity of an elements
    * @property {number}
    * @readonly
    */
@@ -857,6 +896,7 @@ class TXmlElementsListController {
   }
 
   /**
+   * Contains a quantity of an elements
    * @property {number}
    * @readonly
    */
@@ -865,6 +905,7 @@ class TXmlElementsListController {
   }
 
   /**
+   * Contains a maximum possible element index in the list
    * @property {number}
    * @readonly
    */
@@ -873,6 +914,7 @@ class TXmlElementsListController {
   }
 
   /**
+   * Indicates whether a `null`-element is allowed
    * @property {boolean}
    * @readonly
    */
@@ -905,7 +947,7 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any} value
+   * @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.
@@ -916,7 +958,7 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any} obj
+   * @param {any} obj - some element
    * @returns {boolean}
    * @description Checks whether or not a given element is valid.
    */
@@ -939,7 +981,7 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index
+   * @param {number} index - element index
    * @returns {?TXmlElementController}
    * @description Returns an element.
    */
@@ -969,7 +1011,7 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any} item
+   * @param {any} item - some element
    * @returns {number}
    * @description Adds a new element.
    */
@@ -995,8 +1037,8 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {string} index
-   * @param {any} item
+   * @param {string} index - element index
+   * @param {any} item - some element
    * @returns {boolean}
    * @description Sets a new element.
    */
@@ -1036,8 +1078,8 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index
-   * @param {any} item
+   * @param {number} index - element index
+   * @param {any} item - some element
    * @returns {boolean}
    * @description Insertes a new element.
    */
@@ -1050,7 +1092,7 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {number} index
+   * @param {number} index - element index
    * @returns {boolean}
    * @description Deletes an element.
    */
@@ -1074,9 +1116,14 @@ class TXmlElementsListController {
   }
 
   /**
-   * @param {any} items
-   * @param {object} [opt]
-   * @param {boolean} [opt.useClear=true]
+   * @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
+   */
+
+  /**
+   * @param {any} items - element or a list of an elements
+   * @param {OPT_ELC_loaditems} [opt]
    * @returns {number}
    * @description Loads a list of an elements.
    */
@@ -1095,22 +1142,22 @@ class TXmlElementsListController {
 };
 
 /**
- * @description This class implements an instance of an element
- *              that managea content of a document declaration
+ * @classdesc This class implements an instance of an element
+ *            that managea content of a document declaration
  */
 class TXmlContentDeclaration {
   /** @property {?object} */
-  #_host;// = null;
-  /** @property {?object} */
-  #_options;// = null;
+  #_host;
+  /** @property {OPT_xmlcontsett} */
+  #_options;
   /** @property {?TXmlElementController} */
-  #_ctrls;// = null;
+  #_ctrls;
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
+   * @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
@@ -1118,14 +1165,11 @@ class TXmlContentDeclaration {
       throw new TypeError(`TXmlContentDeclaration : ${XML_TE_NOBJ_EMSG}`);
     };
     // load options
-    let _options = isPlainObject(opt) ? opt : {};
+    const _options = __evalXMLContainerSettings(opt);
     // set parser options
-    let { parseOptions } = _options;
-    if (!isPlainObject(parseOptions)) {
-      _options.parseOptions = parseOptions = {};
-    };
-    let { settings } = parseOptions;
-    if (!isPlainObject(settings)) parseOptions.settings = settings = {};
+    //let { parseOptions } = _options;
+    let { settings } = _options.parseOptions;
+    //if (!isPlainObject(settings)) parseOptions.settings = settings = {};
     let { declarationKey } = settings;
     if (
       typeof declarationKey !== 'string'
@@ -1143,6 +1187,7 @@ class TXmlContentDeclaration {
   }
 
   /**
+   * Contains a version of an XML
    * @property {string}
    */
   get version() {
@@ -1154,6 +1199,7 @@ class TXmlContentDeclaration {
   }
 
   /**
+   * Contains a document character set
    * @property {string}
    */
   get encoding() {
@@ -1190,16 +1236,13 @@ class TXmlContentDeclaration {
  */
 class TXmlContentRootElement extends TXmlElementController {
   /** @property {?object} */
-  #_content;// = null;
-  /** @property {?object} */
-  #_options;// = null;
+  #_content;
+  /** @property {OPT_xmlcontsett} */
+  #_options;
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
-   * @param {string} [opt.rootETagName='']
-   * @param {boolean} [opt.autoBindRoot=true]
+   * @param {object} obj - some object
+   * @param {OPT_xmlcontsett} [opt] - options
    * @throws {TypeError}
    */
   constructor(obj, opt) {
@@ -1208,18 +1251,8 @@ class TXmlContentRootElement extends TXmlElementController {
       throw new TypeError(`TXmlContentRootElement : ${XML_TE_NOBJ_EMSG}`);
     };
     // load options
-    const _options = isPlainObject(opt) ? opt : {};
+    const _options = __evalXMLContainerSettings(opt);
     let { rootETagName, autoBindRoot, parseOptions } = _options;
-    if (
-      typeof rootETagName !== 'string'
-      || ((rootETagName = rootETagName.trim()) === '')
-    ) {
-      rootETagName = XML_DEF_ROOT_ETAG_NAME;
-    };
-    if (typeof autoBindRoot !== 'boolean') autoBindRoot = true;
-    if (!(parseOptions instanceof TXmlContentParseOptions)) {
-      parseOptions = new TXmlContentParseOptions(parseOptions);
-    };
     // get root element
     let rootItem = obj[rootETagName];
     if (obj[rootETagName] === undefined) {
@@ -1278,13 +1311,9 @@ class TXmlContentRootElement extends TXmlElementController {
     super(rootItem, _options);
     // save options
     _options.rootETagName = rootETagName;
-    _options.autoBindRoot = autoBindRoot;
-    _options.parseOptions = parseOptions;
     this.#_options = _options;
     // bind a documents content
     this.#_content = obj;
-    // init a content root element
-    //this.init(rootETagName);
   }
 
   /**
@@ -1295,7 +1324,7 @@ class TXmlContentRootElement extends TXmlElementController {
   }
 
   set tagName(value) {
-    value = readAsString(value, true);
+    value = readAsString(value, { useTrim: true });
     this.#_options.rootETagName = isNotEmptyString(
       value
     ) ? value : XML_DEF_ROOT_ETAG_NAME;
@@ -1321,40 +1350,46 @@ class TXmlContentRootElement extends TXmlElementController {
 }
 
 /**
- * @description This class implements an instance of a container
- *              that managea content of a document
+ * @typedef {Object} fsoDescr
+ * @property {boolean} isERR - flag
+ * @property {number} [errCode] - error code
+ * @property {string} errEvent - event ID
+ * @property {string} errMsg - event message
+ * @property {string} source - path to file
+ * @property {any} content - file content
+ * @description A fs ops description.
+ */
+
+/**
+ * @classdesc This class implements an instance of a container
+ *            that managea content of a document
  */
 class TXmlContentContainer {
   /** @property {?object} */
-  #_content;// = null;
+  #_content;
+  /** @property {OPT_xmlcontsett} */
+  #_options;
   /** @property {?object} */
-  #_options;// = null;
-  /** @property {?object} */
-  #_parseOptions;// = null;
+  #_parseOptions;
   /** @property {?TXmlContentDeclaration} */
-  #_docDecl;// = null;
+  #_docDecl;
   /** @property {?TXmlContentRootElement} */
-  #_docRoot;// = null;
+  #_docRoot;
 
   /**
-   * @param {object} [opt]
-   * @param {object} [opt.parseOptions]
+   * @param {OPT_xmlcontsett} [opt] - options
+   * @description Creates an instance of the container
    */
   constructor(opt) {
     // load options
-    const _options = isPlainObject(opt) ? opt : {};
-    let { parseOptions } = _options;
-    if (!(parseOptions instanceof TXmlContentParseOptions)) {
-      parseOptions = new TXmlContentParseOptions(parseOptions);
-    };
+    const _options = __evalXMLContainerSettings(opt);
+    const { parseOptions } = _options;
     // save options
-    _options.parseOptions = parseOptions;
     this.#_options = _options;
     // save parser options
     this.#_parseOptions = parseOptions;
     // init a documents content
-    let _content = {};
-    this.#_content = _content;
+    const _content = this.#_content = {};
     // init a content declaration element
     this.#_docDecl = new TXmlContentDeclaration(_content, _options);
     // init a content root element
@@ -1386,14 +1421,14 @@ class TXmlContentContainer {
    * @description Initializes an instance with a given content.
    */
   _bindContent(obj, opt) {
-    const _options = isPlainObject(opt) ? opt : this.#_options;
     let isSUCCEED = false;
     if (isPlainObject(obj)) {
-      let { parseOptions } = _options;
-      if (!(parseOptions instanceof TXmlContentParseOptions)) {
-        parseOptions = new TXmlContentParseOptions(parseOptions);
-        _options.parseOptions = parseOptions;
-      };
+      const _options = __evalXMLContainerSettings(
+        isPlainObject(opt)
+        ? opt
+        : this.#_options
+      );
+      const { parseOptions } = _options;
       const _docDecl = new TXmlContentDeclaration(obj, _options);
       const _docRoot = new TXmlContentRootElement(obj, _options);
       // // TODO: check elements
@@ -1429,8 +1464,8 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string} source
-   * @returns {object}
+   * @param {string} source - a path to a file
+   * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
    * @description Saves a document content to a file.
@@ -1438,73 +1473,62 @@ class TXmlContentContainer {
   saveToFile(source) {
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
+      /** @type {fsoDescr} */
       let data = {
-        isSucceed: false,
-        source: typeof source === 'string' ? source.trim() : '',
-        content: '',
         isERR: false,
+        errCode: 0,
         errEvent: '',
+        errMsg: '',
+        source: '',
+        content: '',
       };
-      if (data.source === '') {
-        data.isERR = true;
-        data.errEvent = (
-          typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
-        );
-        resolve(data);
-      } else {
+      (new Promise((resolve, reject) => {
         data.content = this.saveToXMLString();
-        fse.writeFile(data.source, data.content, 'utf8').then(result => {
-          data.isSucceed = true;
-          data.errEvent = 'OPS_IS_SUCCEED';
+        resolve(true);
+      })).then(result => {
+        saveToFile(source, data.content, null).then(data => {
           resolve(data);
         }).catch(err => {
-          let { isSucceed } = checkFsError(data, err);
-          if (isSucceed) {
-            data.content = '';
-            resolve(data);
-          } else {
-            //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
-            //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
-            reject(err);
-          };
+          // // TODO: [?] consider check others
+          //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
+          //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
+          reject(err);
         });
-      };
+      }).catch(err => {
+        data.isERR = true;
+        //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
+        //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
+        data.errEvent = 'ERR_XML_UNKNOWN';
+        resolve(data);
+      });
     });
   }
 
   /**
-   * @param {string} source
-   * @returns {object}
-   * @throws {Error}
+   * @param {string} source source - path to a file
+   * @returns {fsoDescr}
    * @description Saves a document content to a file.
    */
   saveToFileSync(source) {
+    /** @type {fsoDescr} */
     let data = {
-      isSucceed: false,
-      source: typeof source === 'string' ? source.trim() : '',
-      content: '',
       isERR: false,
+      errCode: 0,
       errEvent: '',
+      errMsg: '',
+      source: '',
+      content: '',
     };
-    if (data.source === '') {
+    try {
+      data.content = this.saveToXMLString();
+    } catch (err) {
       data.isERR = true;
-      data.errEvent = (
-        typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
-      );
-    } else {
-      try {
-        data.content = this.saveToXMLString();
-        fs.writeFileSync(data.source, data.content, 'utf8');
-      } catch (err) {
-        let { isSucceed } = checkFsError(data, err);
-        if (isSucceed) {
-          data.content = '';
-        } else {
-          //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
-          //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
-          throw err;
-        };
-      };
+      //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
+      //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
+      data.errEvent = 'ERR_XML_UNKNOWN';
+    };
+    if (!data.isERR) {
+      data = saveToFileSync(source, data.content, null);
     };
     return data;
   }
@@ -1534,8 +1558,8 @@ class TXmlContentContainer {
   }
 
   /**
-   * @param {string} source
-   * @returns {object}
+   * @param {string} source - path to a file
+   * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
    * @description Loads a document content from a file.
@@ -1543,24 +1567,11 @@ class TXmlContentContainer {
   loadFromFile(source) {
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
-      let data = {
-        isLoaded: false,
-        source: typeof source === 'string' ? source.trim() : '',
-        content: '',
-        isERR: false,
-        errEvent: '',
-      };
-      if (data.source === '') {
-        data.isERR = true;
-        data.errEvent = (
-          typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
-        );
-        resolve(data);
-      } else {
-        fse.readFile(data.source, 'utf8').then(result => {
-          data.content = result;
-          if (result !== '') {
-            if (this.loadFromXMLString(result)) {
+      loadFile(source).then(data => {
+        if (!data.isERR) {
+          if (data.content !== '') {
+            if (this.loadFromXMLString(data.content)) {
+              // // TODO:
               data.isLoaded = true;
               data.errEvent = 'OPS_IS_SUCCEED';
             } else {
@@ -1571,65 +1582,37 @@ class TXmlContentContainer {
             data.isERR = true;
             data.errEvent = 'NO_CONTENT';
           };
-          resolve(data);
-        }).catch(err => {
-          let { isSucceed } = checkFsError(data, err);
-          if (isSucceed) {
-            data.content = '';
-            resolve(data);
-          } else {
-            //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err);
-            //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err.code);
-            reject(err);
-          };
-        });
-      };
+        };
+        resolve(data);
+      }).catch(err => {
+        //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err);
+        //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err.code);
+        reject(err);
+      });
     });
   }
 
   /**
-   * @param {string} source
-   * @returns {object}
+   * @param {string} source source - path to a file
+   * @returns {fsoDescr}
    * @throws {Error}
    * @description Loads a document content from a file.
    */
   loadFromFileSync(source) {
-    let data = {
-      isLoaded: false,
-      source: typeof source === 'string' ? source.trim() : '',
-      content: '',
-      isERR: false,
-      errEvent: '',
-    };
-    if (data.source === '') {
-      data.isERR = true;
-      data.errEvent = (
-        typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
-      );
-    } else {
-      try {
-        data.content = fs.readFileSync(data.source, 'utf8');
-        if (data.content !== '') {
-          if (this.loadFromXMLString(data.content)) {
-            data.isLoaded = true;
-            data.errEvent = 'OPS_IS_SUCCEED';
-          } else {
-            data.isERR = true;
-            data.errEvent = 'OPS_IS_FAILED';
-          };
+    const data = loadFileSync(source);
+    if (!data.isERR) {
+      if (data.content !== '') {
+        if (this.loadFromXMLString(data.content)) {
+          // // TODO:
+          data.isLoaded = true;
+          data.errEvent = 'OPS_IS_SUCCEED';
         } else {
           data.isERR = true;
-          data.errEvent = 'NO_CONTENT';
-        };
-      } catch (err) {
-        let { isSucceed } = checkFsError(data, err);
-        if (isSucceed) {
-          data.content = '';
-        } else {
-          //console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err);
-          //console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err.code);
-          throw err;
+          data.errEvent = 'OPS_IS_FAILED';
         };
+      } else {
+        data.isERR = true;
+        data.errEvent = 'NO_CONTENT';
       };
     };
     return data;