@cntwg/xml-lib-js 0.0.16

package/lib/xmldoc-lib.js

@@ -0,0 +1,1025 @@
+// [v0.1.045-20220906]
+
+// === module init block ===
+
+const fs = require('fs');
+const fse = fs.promises;
+const xmlParser = require('@ygracs/xml-js6');
+
+const {
+  valueToIndex, readAsBool, readAsString, isNotEmptyString,
+  isArray, isObject, isPlainObject,
+  valueToArray,
+} = require('@ygracs/bsfoc-lib-js');
+
+const xObj = require('@ygracs/xobj-lib-js');
+const TXmlContentParseOptions = xObj.TXmlContentParseOptions;
+const XML_DEF_PARSE_OPTIONS = xObj.DEF_XML_PARSE_OPTIONS;
+
+const XML_DEF_ROOT_ETAG_NAME = 'root';
+const XML_LANG_ATTR_TNAME = 'lang';
+
+const XML_TE_INVARG_EMSG = 'invalid argument';
+const XML_TE_NOBJ_EMSG = `${XML_TE_INVARG_EMSG} (an object is expected)`;
+const XML_TE_NARR_EMSG = `${XML_TE_INVARG_EMSG} (an array is expected)`;
+const XML_TE_NROOT_EMSG = 'root element not found';
+
+// === module extra block (helper functions) ===
+
+// === module main block (function definitions) ===
+
+// === module main block (class definitions) ===
+
+class TXmlAttributesMapper {
+  #_host = null;
+  #_options = null;
+
+  constructor(obj, opt){
+    // init an elements content
+    this.#_host = isPlainObject(obj) ? obj : {};
+    // load options
+    let _options = (
+      isPlainObject(opt) && isPlainObject(opt.parseOptions)
+      ? opt.parseOptions
+      : {}
+    );
+    let { settings: _settings } = _options;
+    if (!isPlainObject(_settings)) _options.settings = _settings = {};
+    let { attributesKey } = _settings;
+    if (
+      typeof attributesKey !== 'string'
+      || ((attributesKey = attributesKey.trim()) === '')
+    ) {
+      attributesKey = XML_DEF_PARSE_OPTIONS.attributesKey;
+    };
+    // save options
+    _settings.attributesKey = attributesKey;
+    this.#_options = _options;
+  }
+
+  get entries(){
+    let items = xObj.getXObjAttributes(
+      this.#_host,
+      this.#_options.settings.attributesKey,
+    );
+    return isPlainObject(items) ? Object.entries(items) : [];
+  }
+
+  hasAttribute(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return false;
+    };
+    // // TODO: await implementation for class method provided by xObj
+    let item = xObj.getXObjAttributes(
+      this.#_host,
+      this.#_options.settings.attributesKey,
+    );
+    return isPlainObject(item) && item[name] !== undefined;
+  }
+
+  getAttribute(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return '';
+    };
+    return xObj.readXObjAttr(
+      this.#_host,
+      name,
+      this.#_options.settings.attributesKey,
+    );
+  }
+
+  setAttribute(attr, value){
+    let name = '';
+    if (
+      typeof attr !== 'string' || ((name = attr.trim()) === '')
+      || value === undefined
+    ) {
+      return false;
+    };
+    return xObj.writeXObjAttr(
+      this.#_host,
+      name,
+      value,
+      this.#_options.settings.attributesKey,
+    );
+  }
+
+  delAttribute(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return false;
+    };
+    // // TODO: await implementation for class method provided by xObj
+    let items = xObj.getXObjAttributes(
+      this.#_host,
+      this.#_options.settings.attributesKey,
+    );
+    let isSUCCEED = isPlainObject(items);
+    if (isSUCCEED) {
+      // // TODO: catch errors in strict mode
+      isSUCCEED = delete items[name];
+    };
+    return isSUCCEED;
+  }
+
+  clear(){
+    xObj.insertXObjElement(
+      this.#_host,
+      this.#_options.settings.attributesKey,
+      {
+        force: true,
+        rip_oldies: true,
+      },
+    );
+  }
+
+}
+
+class TXmlElementController {
+  #_host = null;
+  #_options = null;
+  #_p_opts = null;
+  #_attributes = null;
+  #_name = null;
+
+  constructor(obj, opt){
+    // load options
+    let _options = isPlainObject(opt) ? opt : {};
+    let { proxyModeEnable } = _options;
+    if (typeof proxyModeEnable !== 'boolean') proxyModeEnable = false;
+    // init an elements content
+    if (isObject(obj)) {
+      if (isArray(obj)) return new TXmlElementsListController(obj, opt);
+      // // TODO: split a plain object and class instances
+      this.#_host = obj;
+    } else {
+      if (proxyModeEnable) {
+        let msg = [
+          'TXmlElementController in "proxyMode":', XML_TE_NOBJ_EMSG,
+        ].join(' ');
+        throw new TypeError(msg);
+      };
+      this.#_host = {};
+    };
+    // set parser options
+    let { parseOptions: _parseOptions } = _options;
+    if (!isPlainObject(_parseOptions)) _parseOptions = {};
+    let { settings: _settings } = _parseOptions;
+    if (!isPlainObject(_settings)) {
+      _parseOptions.settings = _settings = {};
+      // // TODO: set defaults
+    };
+    // save parser options
+    _options.parseOptions = _parseOptions;
+    this.#_p_opts = _parseOptions;
+    // save options
+    _options.proxyModeEnable = proxyModeEnable;
+    this.#_options = _options;
+    // bind atributes mapper
+    this.#_attributes = new TXmlAttributesMapper(obj, _options);
+  }
+
+  get attributes(){
+    return this.#_attributes;
+  }
+
+  get name(){
+    let result = '';
+    if (this.#_p_opts.settings.compact) {
+      result = xObj.readXObjParam(this.#_host, this.#_p_opts.settings.nameKey);
+    } else {
+      // TODO: read name of element in non-compact mode
+    };
+    return result;
+  }
+
+  get textValue(){
+    return xObj.readXObjParam(this.#_host, this.#_p_opts.settings.textKey);
+  }
+
+  set textValue(value){
+    xObj.writeXObjParam(this.#_host, value, this.#_p_opts.settings.textKey);
+  }
+
+  hasAttribute(name){
+    return this.#_attributes.hasAttribute(name);
+  }
+
+  getAttribute(name){
+    return this.#_attributes.getAttribute(name);
+  }
+
+  setAttribute(...args){
+    return this.#_attributes.setAttribute(...args);
+  }
+
+  delAttribute(name){
+    return this.#_attributes.delAttribute(name);
+  }
+
+  getTextValue(){
+    return [
+      this.#_attributes.getAttribute(XML_LANG_ATTR_TNAME),
+      this.textValue,
+    ];
+  }
+
+  setTextValue(value){
+    value = valueToArray(value);
+    let val_size = value.length;
+    if (val_size === 1) {
+      return xObj.writeXObjParam(
+        this.#_host,
+        value[0],
+        this.#_p_opts.settings.textKey,
+      );
+    } else if (val_size > 1) {
+      if (xObj.writeXObjParam(
+        this.#_host,
+        value[1],
+        this.#_p_opts.settings.textKey,
+      )) {
+        return this.#_attributes.setAttribute(XML_LANG_ATTR_TNAME, value[0]);
+      };
+    };
+    return false;
+  }
+
+  getChild(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return null;
+    };
+    let item = xObj.getXObjElement(this.#_host, name);
+    if (isArray(item)) {
+      item = new TXmlElementsListController(item, this.#_options);
+    } else if (isObject(item)) {
+      item = new TXmlElementController(item, this.#_options);
+    } else {
+      item = null;
+    };
+    return item;
+  }
+
+  _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;
+  }
+
+  _setChildRaw(name, obj){
+    //console.log('CHECK: TXmlElementController._setChildRaw() => was called...');
+    let isSUCCEED = false; let item = null;
+    if (isArray(obj)) {
+      //console.log('CHECK: TXmlElementController._setChildRaw() => <obj> is array...');
+      item = xObj.insertXObjEList(this.#_host, name, 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(this.#_host, name, true);
+      // // TODO: set element
+    };
+    if (item) isSUCCEED = true;
+    return isSUCCEED;
+  }
+
+  _addChildRaw(name){//}, obj){
+    //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;
+  }
+
+  addChild(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return null;
+    };
+    let result = xObj.addXObjElement(this.#_host, name);
+    if (!result.isSucceed) return null;
+    return new TXmlElementController(result.item, this.#_options);
+  }
+
+  delChild(value){
+    let name = '';
+    if (
+      typeof value !== 'string' || ((name = value.trim()) === '')
+    ) {
+      return false;
+    };
+    let item = xObj.getXObjElement(this.#_host, name);
+    if (isArray(item)) {
+      //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => [object Array]');
+    } else if (isObject(item)) {
+      return xObj.deleteXObjElement(this.#_host, name);
+    } else {
+      //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => ['+typeof item+']');
+      //console.log('CHECK: TXmlElementController.delChild() => item.value() => ['+item+']');
+    };
+    return false;
+  }
+
+  clear(){
+    TXmlElementController.clear(this);
+  }
+
+  static __unwrap(item){
+    return (item instanceof TXmlElementController) ? item.#_host : null;
+  }
+
+  static clear(obj){
+    let item = TXmlElementController.__unwrap(obj);
+    if (item) {
+      for (let prop in item) {
+        // // TODO: catch errors in strict mode
+        delete item[prop];
+      };
+    };
+  }
+
+};
+
+class TXmlElementsListController {
+  #_host = null;
+  #_options = null;
+  #_count = null;
+
+  constructor(obj, opt){
+    // load options
+    let _options = isPlainObject(opt) ? opt : {};
+    let { proxyModeEnable, isNullItemsAllowed } = _options;
+    if (typeof proxyModeEnable !== 'boolean') proxyModeEnable = false;
+    if (typeof isNullItemsAllowed !== 'boolean') isNullItemsAllowed = false;
+    // set parser options
+    let { parseOptions: _parseOptions } = _options;
+    if (!isPlainObject(_parseOptions)) _parseOptions = {};
+    let { settings: _settings } = _parseOptions;
+    if (!isPlainObject(_settings)) {
+      _parseOptions.settings = _settings = {};
+      // // TODO: set defaults
+    };
+    // init an elements list content
+    if (isArray(obj)) {
+      this.#_host = obj;
+    } else {
+      if (proxyModeEnable) {
+        let msg = [
+          'TXmlElementsListController in "proxyMode":', XML_TE_NARR_EMSG,
+        ].join(' ');
+        throw new TypeError(msg);
+      } else {
+        // // TODO: split a plain object and class instances
+        this.#_host = [];
+      };
+    };
+    // save parser options
+    _options.parseOptions = _parseOptions;
+    // save options
+    _options.proxyModeEnable = proxyModeEnable;
+    _options.isNullItemsAllowed = isNullItemsAllowed;
+    this.#_options = _options;
+  }
+
+  get count(){
+    return this.#_host.length;
+  }
+
+  get size(){
+    return this.#_host.length;
+  }
+
+  get maxIndex(){
+    return this.#_host.length - 1;
+  }
+
+  get isNullItemsAllowed(){
+    return readAsBool(this.#_options.isNullItemsAllowed);
+  }
+
+  clear(){
+    this.#_host.length = 0;
+  }
+
+  isEmpty(){
+    return this.count === 0;
+  }
+
+  isNotEmpty(){
+    return this.count > 0;
+  }
+
+  chkIndex(value){
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.size;
+  }
+
+  isValidItem(obj){
+    return (
+      (this.#_options.isNullItemsAllowed && obj === null) || isPlainObject(obj)
+    );
+  }
+
+  _getItemRaw(index){
+    let item = this.#_host[valueToIndex(index)];
+    return item !== undefined ? item : null;
+  }
+
+  getItem(index){
+    let item = this.#_host[valueToIndex(index)];
+    // wrap item in container
+    return (
+      isPlainObject(item)
+      ? new TXmlElementController(item, this.#_options)
+      : null
+    );
+  }
+
+  _addItemRaw(item){
+    let index = -1;
+    if (this.isValidItem(item)) {
+      index = this.size;
+      this.#_host.push(item); // // TODO: correct count
+    };
+    return index;
+  }
+
+  addItem(item){
+    // unwrap item from container
+    if (item instanceof TXmlElementController) {
+      item = TXmlElementController.__unwrap(item);
+    };
+    return this._addItemRaw(item);
+  }
+
+  _setItemRaw(index, item){
+    let isSUCCEED = this.chkIndex(index) && this.isValidItem(item);
+    if (isSUCCEED) this.#_host[Number(index)] = item; // // TODO: correct count
+    return isSUCCEED;
+  }
+
+  setItem(index, item){
+    // unwrap item from container
+    if (item instanceof TXmlElementController) {
+      item = TXmlElementController.__unwrap(item);
+    };
+    return this._setItemRaw(index, item);
+  }
+
+  _insItemRaw(index, item){
+    index = valueToIndex(index);
+    let size = this.size;
+    let isSUCCEED = (
+      index !== -1 && size >= index && this.isValidItem(item)
+    );
+    if (isSUCCEED) {
+      if (size > index) {
+        if (this.#_host[index] === null) {
+          this.#_host[index] = item; // // TODO: correct count
+        } else {
+          this.#_host.splice(index, 0, item);  // // TODO: correct count
+        };
+      } else {
+        this.#_host.push(item); // // TODO: correct count
+      };
+    };
+    return isSUCCEED;
+  }
+
+  insItem(index, item){
+    // unwrap item from container
+    if (item instanceof TXmlElementController) {
+      item = TXmlElementController.__unwrap(item);
+    };
+    return this._insItemRaw(index, item);
+  }
+
+  delItem(value){
+    let isSUCCEED = this.chkIndex(value);
+    if (isSUCCEED) {
+      let index = Number(value);
+      if (this.#_options.isNullItemsAllowed) {
+        this.#_host[index] = null; // // TODO: correct count
+      } else {
+        if (index === 0) {
+          this.#_host.shift(); // // TODO: correct count
+        } else if (index === this.maxIndex) {
+          this.#_host.pop(); // // TODO: correct count
+        } else {
+          this.#_host.splice(index, 1); // // TODO: correct count
+        };
+      };
+    };
+    return isSUCCEED;
+  }
+
+  loadItems(items, opt){
+    let act_as_new = true;
+    if (isPlainObject(opt)) {
+      act_as_new = readAsBool(opt.load_as_new, act_as_new);
+    };
+    if (act_as_new) this.clear();
+    let count = this.count;
+    valueToArray(items).forEach((item) => { this.addItem(item); });
+    return this.count - count;
+  }
+
+};
+
+class TXmlContentDeclaration {
+  #_host = null;
+  #_options = null;
+  #_ctrls = null;
+
+  constructor(obj, opt){
+    // check <obj>-param
+    if (!isPlainObject(obj)) {
+      /*let msg = [
+        'TXmlContentDeclaration :', XML_TE_NOBJ_EMSG,
+      ].join(' ');*/
+      throw new TypeError(`TXmlContentDeclaration : ${XML_TE_NOBJ_EMSG}`);
+    };
+    // load options
+    let _options = isPlainObject(opt) ? opt : {};
+    // set parser options
+    let { parseOptions: _parseOptions } = _options;
+    if (!isPlainObject(_parseOptions)) _parseOptions = {};
+    let { settings: _settings } = _parseOptions;
+    if (!isPlainObject(_settings)) _parseOptions.settings = _settings = {};
+    let { declarationKey } = _settings;
+    if (
+      typeof declarationKey !== 'string'
+      || ((declarationKey = declarationKey.trim()) === '')
+    ) {
+      declarationKey = XML_DEF_PARSE_OPTIONS.declarationKey;
+    };
+    // // TODO: set defaults
+    // save parser options
+    _options.parseOptions = _parseOptions;
+    _settings.declarationKey = declarationKey;
+    // save options
+    this.#_options = _options;
+    // bind a documents content
+    this.#_host = obj;
+    // init a content declaration element
+    this.init();
+  }
+
+  get version(){
+    return this.#_ctrls.getAttribute('version');
+  }
+
+  set version(value){
+    this.#_ctrls.setAttribute('version', value);
+  }
+
+  get encoding(){
+    return this.#_ctrls.getAttribute('encoding');
+  }
+
+  set encoding(value){
+    this.#_ctrls.setAttribute('encoding', value);
+  }
+
+  init(){
+    let _options = this.#_options;
+    this.#_ctrls = new TXmlElementController(
+      xObj.insertXObjElement(
+        this.#_host,
+        _options.parseOptions.settings.declarationKey,
+      ),
+      this._options,
+    );
+    // // TODO: set version & encoding
+    if (!isNotEmptyString(this.version)) this.version = '1.0';
+    if (!isNotEmptyString(this.encoding)) this.encoding = 'UTF-8';
+  }
+
+};
+
+class TXmlContentRootElement extends TXmlElementController {
+  #_content = null;
+  #_options = null;
+
+  constructor(obj, opt){
+    // check <obj>-param
+    if (!isPlainObject(obj)) {
+      throw new TypeError(`TXmlContentRootElement : ${XML_TE_NOBJ_EMSG}`);
+    };
+    // load options
+    const _options = isPlainObject(opt) ? 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) {
+      const entries = Object.keys(obj);
+      const len = entries.length;
+      if (len === 0) {
+        rootItem = xObj.insertXObjElement(obj, rootETagName, false);
+      } else if (autoBindRoot) {
+        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,
+        ]);
+        let targetKey = '';
+        for (let name of entries) {
+          if (!reservedKeys.has(name)) {
+            targetKey = name;
+            break;
+          };
+        };
+        if (targetKey === '') {
+          rootItem = xObj.insertXObjElement(obj, rootETagName, false);
+        } else {
+          rootItem = obj[targetKey];
+          rootETagName = targetKey;
+          if (!isPlainObject(rootItem)) {
+            rootItem = xObj.insertXObjElement(obj, rootETagName, false);
+          };
+        };
+      } else {
+        throw new TypeError(`TXmlContentRootElement : ${XML_TE_NROOT_EMSG}`);
+      };
+    } else if (!isPlainObject(rootItem)) {
+      rootItem = xObj.insertXObjElement(obj, rootETagName, false);
+    };
+    // init parent class instance
+    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);
+  }
+
+  get tagName(){
+    return this.#_options.rootETagName;
+  }
+
+  set tagName(value){
+    value = readAsString(value, '', true);
+    this.#_options.rootETagName = isNotEmptyString(
+      value
+    ) ? value : XML_DEF_ROOT_ETAG_NAME;
+  }
+
+  //* will deprecate */
+  /*init(name){
+    //console.log('CHECK: TXmlContentRootElement.init() => was called...');
+    //console.log('CHECK: TXmlContentRootElement.init() => (*1) name:['+name+']');
+    let _options = this.#_options;
+    name = readAsString(name, _options.rootETagName, true);
+    // // TODO: check if name is valid
+    //console.log('CHECK: TXmlContentRootElement.init() => (*2)  name:['+name+']');
+    if (!isPlainObject(this.#_content[name])) this.#_content[name] = {};
+    this.#_ctrls = new TXmlElementController(this.#_content[name], _options);
+    //console.log('CHECK: TXmlContentRootElement.init() => was left...');
+  }*/
+
+  static __unwrap(item, opt){
+    return (
+      item instanceof TXmlContentRootElement
+      && (typeof opt === 'boolean' ? opt : false)
+      ? item.#_content :
+      TXmlElementController.__unwrap(item)
+    );
+  }
+
+}
+
+class TXmlContentContainer {
+  #_content = null;
+  #_options = null;
+  #_parseOptions = null;
+  #_docDecl = null;
+  #_docRoot = null;
+
+  constructor(opt){
+    // load options
+    const _options = isPlainObject(opt) ? opt : {};
+    let { parseOptions } = _options;
+    if (!(parseOptions instanceof TXmlContentParseOptions)) {
+      parseOptions = new TXmlContentParseOptions(parseOptions);
+    };
+    // save options
+    _options.parseOptions = parseOptions;
+    this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // init a documents content
+    let _content = {};
+    this.#_content = _content;
+    // init a content declaration element
+    this.#_docDecl = new TXmlContentDeclaration(_content, _options);
+    // init a content root element
+    this.#_docRoot = new TXmlContentRootElement(_content, _options);
+  }
+
+  get rootElement(){
+    return this.#_docRoot;
+  }
+
+  clear(){
+    this.#_docDecl.init();
+    this.rootElement.clear();
+  }
+
+  _bindContent(obj, opt){
+    //console.log('CHECK: TXmlContentContainer._bindContent() => was called...');
+    const _options = isPlainObject(opt) ? opt : this.#_options;
+    let isSUCCEED = false;
+    if (isPlainObject(obj)) {
+      let { rootETagName, parseOptions } = _options;
+      rootETagName = (
+        typeof rootETagName === 'string' ? rootETagName.trim() : ''
+      );
+      //if (rootETagName !== '' && isPlainObject(obj[rootETagName])) {
+        //console.log('CHECK: TXmlContentContainer._bindContent() => rootETagName:['+rootETagName+']');
+        if (!(parseOptions instanceof TXmlContentParseOptions)) {
+          parseOptions = new TXmlContentParseOptions(parseOptions);
+          _options.parseOptions = parseOptions;
+        };
+        const _docDecl = new TXmlContentDeclaration(obj, _options);
+        const _docRoot = new TXmlContentRootElement(obj, _options);
+        // // TODO: check elements
+        isSUCCEED = true;
+        if (isSUCCEED) {
+          // save options
+          this.#_options = _options;
+          // save parser options
+          this.#_parseOptions = parseOptions;
+          // save content
+          this.#_content = obj;
+          // bind refs to controllers
+          this.#_docDecl = _docDecl;
+          this.#_docRoot = _docRoot;
+        };
+      //};
+    };
+    //console.log('CHECK: TXmlContentContainer.constructor() => _content => '+JSON.stringify(this.#_content, null, 2));
+    //console.log('CHECK: TXmlContentContainer._bindContent() => result:['+isSUCCEED+']');
+    //console.log('CHECK: TXmlContentContainer._bindContent() => was left...');
+    return isSUCCEED;
+  }
+
+  saveToXMLString(){
+    let result = '';
+    //let isERR = false;
+    try {
+      result = xmlParser.js2xml(this.#_content, this.#_parseOptions.js2xml);
+    } catch (err) {
+      console.log('CHECK: TXmlContentContainer.saveToXMLString() => Error => '+err);
+      //isERR = true;
+      throw err;
+    };
+    return result;
+  }
+
+  saveToFile(source){
+    /**/// main part that return promise as a result
+    return new Promise((resolve, reject) => {
+      let data = {
+        isSucceed: false,
+        source: typeof source === 'string' ? source.trim : '',
+        content: '',
+        isERR: false,
+        errEvent: '',
+      };
+      if (data.source !== '') {
+        data.content = this.saveToXMLString();
+        fse.writeFile(data.source, data.content, 'utf8').then(result => {
+          data.isSucceed = true;
+          data.errEvent = 'OPS_IS_SUCCEED';
+          resolve(data);
+        }).catch(err => {
+          console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
+          console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
+          reject(err);
+        });
+      } else {
+        data.isERR = true;
+        data.errEvent = 'EMPTY_SRCLINK';
+        resolve(data);
+      };
+    });
+  }
+
+  saveToFileSync(source){
+    //console.log('CHECK: TXmlContentContainer.saveToFileSync() => was called...');
+    let data = {
+      isSucceed: false,
+      source: typeof source === 'string' ? source.trim() : '',
+      content: '',
+      isERR: false,
+      errEvent: '',
+    };
+    if (data.source !== '') {
+      try {
+        data.content = this.saveToXMLString();
+        fs.writeFileSync(data.source, data.content, 'utf8');
+      } catch (err) {
+        console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
+        console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
+        throw err;
+      };
+    } else {
+      data.isERR = true;
+      data.errEvent = 'EMPTY_SRCLINK';
+    };
+    //console.log('CHECK: TXmlContentContainer.saveToFileSync() => was left...');
+    return data;
+  }
+
+  loadFromXMLString(xmlString){
+    let isSUCCEED = false;
+    if (typeof xmlString === 'string') {
+      let obj = null;
+      try {
+        obj = xmlParser.xml2js(xmlString, this.#_parseOptions.xml2js);
+        if (isPlainObject(obj)) {
+          isSUCCEED = this._bindContent(obj, this.#_options);
+        };
+      } catch (err) {
+        console.log('CHECK: TXmlContentContainer.loadFromXMLString() => Error => '+err);
+        console.log('CHECK: TXmlContentContainer.loadFromXMLString() => Error => '+err.code);
+        throw err;
+      };
+    };
+    return isSUCCEED;
+  }
+
+  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)) {
+              data.isLoaded = true;
+              data.errEvent = 'OPS_IS_SUCCEED';
+            } else {
+              data.isERR = true;
+              data.errEvent = 'OPS_IS_FAILED';
+            };
+          } else {
+            data.isERR = true;
+            data.errEvent = 'NO_CONTENT';
+          };
+          resolve(data);
+        }).catch(err => {
+          switch (err.code) {
+            case 'ENOENT':
+            case 'EISDIR':
+              data.isERR = true;
+              data.errEvent = err.code;
+              resolve(data);
+              break;
+            default:
+              console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err);
+              console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err.code);
+              reject(err);
+              break;
+          };
+        });
+      };
+    });
+  }
+
+  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';
+          };
+        } else {
+          data.isERR = true;
+          data.errEvent = 'NO_CONTENT';
+        };
+      } catch (err) {
+        switch (err.code) {
+          case 'ENOENT':
+          case 'EISDIR':
+          data.isERR = true;
+          data.errEvent = err.code;
+          break;
+          default:
+          console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err);
+          console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err.code);
+          throw err;
+          break;
+        };
+      };
+    };
+    return data;
+  }
+
+  asJSON(){
+    return JSON.stringify(this.#_content, null, 2);
+  }
+
+};
+
+// === module exports block ===
+
+exports.DEF_XML_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS; // will deprecate
+exports.DEF_XML_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME; // will deprecate
+
+exports.XML_DEF_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS;
+exports.XML_DEF_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME;
+
+exports.TXmlAttributesMapper = TXmlAttributesMapper;
+exports.TXmlElementController = TXmlElementController;
+exports.TXmlElementsListController = TXmlElementsListController;
+exports.TXmlContentParseOptions = TXmlContentParseOptions;
+exports.TXmlContentDeclaration = TXmlContentDeclaration;
+exports.TXmlContentRootElement = TXmlContentRootElement;
+exports.TXmlContentContainer = TXmlContentContainer;