@cntwg/xml-lib-js 0.0.24 → 0.0.26

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.067-20230731]
+// [v0.1.077-20240625]
 
 // === module init block ===
 
@@ -9,12 +9,50 @@ const xmlParser = require('@ygracs/xml-js6');
 const {
   valueToIndex, readAsBool, readAsString, isNotEmptyString,
   isArray, isObject, isPlainObject,
-  valueToArray,
+  valueToArray, valueToEntry,
 } = 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 {
+  TXmlContentParseOptions,
+  DEF_XML_PARSE_OPTIONS: XML_DEF_PARSE_OPTIONS,
+} = xObj;
+
+// === module extra block (helper functions) ===
+
+/**
+ * @function checkFsError
+ * @param {object}
+ * @param {Error}
+ * @returns {object}
+ * @inner
+ * @description Checs an error code of a fs ops and sets descr info if succeed
+ */
+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;
+  };
+  return { isSucceed, descr };
+};
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
 
 const XML_DEF_ROOT_ETAG_NAME = 'root';
 const XML_LANG_ATTR_TNAME = 'lang';
@@ -24,16 +62,27 @@ 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) ===
+/***
+ * (* function definitions *)
+ */
 
-// === module main block (class definitions) ===
+/***
+ * (* class definitions *)
+ */
 
+/**
+ * @description This class implements an attributes mapper instance
+ */
 class TXmlAttributesMapper {
   #_host = null;
   #_options = null;
 
+  /**
+   * @param {object}
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   * @throws {TypeError}
+   */
   constructor(obj, opt){
     // init an elements content
     if (!isPlainObject(obj)) throw new TypeError(XML_TE_NOBJ_EMSG);
@@ -58,6 +107,10 @@ class TXmlAttributesMapper {
     this.#_options = parseOptions;
   }
 
+  /**
+   * @property {array}
+   * @readonly
+   */
   get entries(){
     let items = xObj.getXObjAttributes(
       this.#_host,
@@ -66,6 +119,11 @@ class TXmlAttributesMapper {
     return isPlainObject(items) ? Object.entries(items) : [];
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Checks whether an attribute exists.
+   */
   hasAttribute(name){
     let result = false;
     try {
@@ -81,6 +139,11 @@ class TXmlAttributesMapper {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {string}
+   * @description Returns an attribute value.
+   */
   getAttribute(name){
     let result = '';
     try {
@@ -96,6 +159,12 @@ class TXmlAttributesMapper {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {any}
+   * @returns {bool}
+   * @description Sets an attribute value.
+   */
   setAttribute(name, value){
     let result = false;
     try {
@@ -112,6 +181,11 @@ class TXmlAttributesMapper {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Deletes an attribute.
+   */
   delAttribute(name){
     let result = false;
     try {
@@ -127,6 +201,10 @@ class TXmlAttributesMapper {
     return result;
   }
 
+  /**
+   * @returns {none}
+   * @description Deletes all attributes.
+   */
   clear(){
     xObj.insertXObjElement(
       this.#_host,
@@ -140,6 +218,9 @@ class TXmlAttributesMapper {
 
 }
 
+/**
+ * @description This class implements an instance of an element controller
+ */
 class TXmlElementController {
   #_host = null;
   #_options = null;
@@ -147,6 +228,13 @@ class TXmlElementController {
   #_attributes = null;
   #_name = null;
 
+  /**
+   * @param {object}
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   * @param {bool} [opt.proxyModeEnable=false]
+   * @throws {TypeError}
+   */
   constructor(obj, opt){
     // load options
     let _options = isPlainObject(opt) ? opt : {};
@@ -190,10 +278,19 @@ class TXmlElementController {
     this.#_attributes = new TXmlAttributesMapper(obj, _options);
   }
 
+  /**
+   * @property {TXmlAttributesMapper}
+   * @readonly
+   */
   get attributes(){
     return this.#_attributes;
   }
 
+  /**
+   * @property {string}
+   * @readonly
+   * @experimental
+   */
   get name(){
     let result = '';
     if (this.#_parseOptions.settings.compact) {
@@ -207,6 +304,9 @@ class TXmlElementController {
     return result;
   }
 
+  /**
+   * @property {string}
+   */
   get textValue(){
     return xObj.readXObjParam(this.#_host, this.#_parseOptions.settings.textKey);
   }
@@ -215,22 +315,44 @@ class TXmlElementController {
     xObj.writeXObjParam(this.#_host, value, this.#_parseOptions.settings.textKey);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Checks whether an attribute exists.
+   */
   hasAttribute(name){
     return this.#_attributes.hasAttribute(name);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {string}
+   * @description Returns an attribute value.
+   */
   getAttribute(name){
     return this.#_attributes.getAttribute(name);
   }
 
+  /**
+   * @see TXmlAttributesMapper.setAttribute
+   */
   setAttribute(...args){
     return this.#_attributes.setAttribute(...args);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Deletes an attribute.
+   */
   delAttribute(name){
     return this.#_attributes.delAttribute(name);
   }
 
+  /**
+   * @returns {array}
+   * @description Returns a text value in format of a `[ <lang>, <text> ]` pair.
+   */
   getTextValue(){
     return [
       this.#_attributes.getAttribute(XML_LANG_ATTR_TNAME),
@@ -238,30 +360,40 @@ class TXmlElementController {
     ];
   }
 
+  /**
+   * @param {(string|entry)}
+   * @returns {bool}
+   * @description Sets a text value.
+   */
   setTextValue(value){
-    const _value = valueToArray(value);
-    const len = _value.length;
-    if (len > 0) {
-      if (len === 1) {
-        return xObj.writeXObjParam(
-          this.#_host,
-          _value[0],
-          this.#_parseOptions.settings.textKey,
-        );
-      } else {
-        const [ lang, param ] = _value;
-        if (xObj.writeXObjParam(
-          this.#_host,
-          param,
-          this.#_parseOptions.settings.textKey,
-        )) {
-          return this.#_attributes.setAttribute(XML_LANG_ATTR_TNAME, lang);
+    const _value = valueToEntry(value);
+    if (_value !== null) {
+      const [ lang, param ] = _value;
+      if (xObj.writeXObjParam(
+        this.#_host,
+        param,
+        this.#_parseOptions.settings.textKey,
+      )) {
+        const attributes = this.#_attributes;
+        if (lang === '') {
+          if (attributes.hasAttribute(XML_LANG_ATTR_TNAME)) {
+            return attributes.delAttribute(XML_LANG_ATTR_TNAME);
+          } else {
+            return true;
+          };
+        } else {
+          return attributes.setAttribute(XML_LANG_ATTR_TNAME, lang);
         };
       };
     };
     return false;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Checks whether an element has a child element.
+   */
   hasChild(name){
     const _name = xObj.evalXObjEName(name);
     let result = false;
@@ -276,6 +408,11 @@ class TXmlElementController {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {(null|TXmlElementController|TXmlElementsListController)}
+   * @description Returns a child element.
+   */
   getChild(name){
     const _name = xObj.evalXObjEName(name);
     let result = null;
@@ -295,6 +432,12 @@ class TXmlElementController {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {object}
+   * @protected
+   * @description Returns a child element.
+   */
   _getChildRaw(name){
     //console.log('CHECK: TXmlElementController._getChildRaw() => was called...');
     //console.log('CHECK: TXmlElementController._getChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
@@ -307,11 +450,22 @@ class TXmlElementController {
     return item !== undefined ? item : null;
   }
 
+  /**
+   * @see TXmlElementController.__setChildRaw
+   * @protected
+   * @description Sets a child element.
+   */
   _setChildRaw(...args){
     //console.log('CHECK: TXmlElementController._setChildRaw() => was called...');
     return TXmlElementController.__setChildRaw(this, ...args);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {?object}
+   * @protected
+   * @description Adds a new child element.
+   */
   _addChildRaw(name){//}, obj){
     //console.log('CHECK: TXmlElementController._addChild() => was called...');
     //console.log('CHECK: TXmlElementController._addChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
@@ -324,6 +478,11 @@ class TXmlElementController {
     return result.isSucceed ? result.item : null;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {?TXmlElementController}
+   * @description Adds a new child element.
+   */
   addChild(name){
     const _name = xObj.evalXObjEName(name);
     let result = null;
@@ -339,6 +498,11 @@ class TXmlElementController {
     return result;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Deletes a child element.
+   */
   delChild(name){
     const _name = xObj.evalXObjEName(name);
     let isSUCCEED = false;
@@ -368,14 +532,34 @@ class TXmlElementController {
     return isSUCCEED;
   }
 
+  /**
+   * @returns {none}
+   * @description Deletes all child elements and attributes.
+   */
   clear(){
     TXmlElementController.clear(this);
   }
 
+  /**
+   * @param {object}
+   * @returns {?object}
+   * @protected
+   * @static
+   * @description Tries to unwraps a given object.
+   */
   static __unwrap(item){
     return (item instanceof TXmlElementController) ? item.#_host : null;
   }
 
+  /**
+   * @param {TXmlElementController}
+   * @param {ID_STRING}
+   * @param {object}
+   * @returns {bool}
+   * @protected
+   * @static
+   * @description Sets a child element.
+   */
   static __setChildRaw(node, name, obj){
     //console.log('CHECK: TXmlElementController.__setChildRaw() => was called...');
     let isSUCCEED = false;
@@ -398,6 +582,12 @@ class TXmlElementController {
     return isSUCCEED;
   }
 
+  /**
+   * @param {object}
+   * @returns {none}
+   * @static
+   * @description Tries to clean a given object.
+   */
   static clear(obj){
     let item = TXmlElementController.__unwrap(obj);
     if (item) {
@@ -410,11 +600,22 @@ class TXmlElementController {
 
 };
 
+/**
+ * @description This class implements an instance of a list controller
+ */
 class TXmlElementsListController {
   #_host = null;
   #_options = null;
   #_count = null;
 
+  /**
+   * @param {array}
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   * @param {bool} [opt.proxyModeEnable=false]
+   * @param {bool} [opt.isNullItemsAllowed=false] - <reserved>
+   * @throws {TypeError}
+   */
   constructor(obj, opt){
     // load options
     let _options = isPlainObject(opt) ? opt : {};
@@ -450,39 +651,78 @@ class TXmlElementsListController {
     this.#_options = _options;
   }
 
+  /**
+   * @property {number}
+   * @readonly
+   */
   get count(){
     return this.#_host.length;
   }
 
+  /**
+   * @property {number}
+   * @readonly
+   */
   get size(){
     return this.#_host.length;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get maxIndex(){
     return this.#_host.length - 1;
   }
 
+  /**
+   * @property {bool}
+   * @readonly
+   */
   get isNullItemsAllowed(){
     return readAsBool(this.#_options.isNullItemsAllowed);
   }
 
+  /**
+   * @returns {none}
+   * @description Deletes all child elements and attributes.
+   */
   clear(){
     this.#_host.length = 0;
   }
 
+  /**
+   * @returns {bool}
+   * @description Checks whether an instance holds none element.
+   */
   isEmpty(){
     return this.count === 0;
   }
 
+  /**
+   * @returns {bool}
+   * @description Checks whether an instance holds at least one element.
+   */
   isNotEmpty(){
     return this.count > 0;
   }
 
+  /**
+   * @param {any}
+   * @returns {bool}
+   * @description Checks whether a given value is a valid index value
+   *              and it is not exceeds an index range within the instance.
+   */
   chkIndex(value){
     const index = valueToIndex(value);
     return index !== -1 && index < this.size;
   }
 
+  /**
+   * @param {any}
+   * @returns {bool}
+   * @description Checks whether or not a given element is valid.
+   */
   isValidItem(obj){
     return (
       (this.#_options.isNullItemsAllowed && obj === null)
@@ -490,11 +730,22 @@ class TXmlElementsListController {
     );
   }
 
+  /**
+   * @param {index}
+   * @returns {?object}
+   * @protected
+   * @description Returns an element.
+   */
   _getItemRaw(index){
     let item = this.#_host[valueToIndex(index)];
     return item !== undefined ? item : null;
   }
 
+  /**
+   * @param {index}
+   * @returns {?TXmlElementController}
+   * @description Returns an element.
+   */
   getItem(index){
     let item = this.#_host[valueToIndex(index)];
     // wrap item in container
@@ -505,6 +756,12 @@ class TXmlElementsListController {
     );
   }
 
+  /**
+   * @param {any}
+   * @returns {index}
+   * @protected
+   * @description Adds a new element.
+   */
   _addItemRaw(item){
     let index = -1;
     if (this.isValidItem(item)) {
@@ -514,6 +771,11 @@ class TXmlElementsListController {
     return index;
   }
 
+  /**
+   * @param {any}
+   * @returns {index}
+   * @description Adds a new element.
+   */
   addItem(item){
     // unwrap item from container
     if (item instanceof TXmlElementController) {
@@ -522,12 +784,25 @@ class TXmlElementsListController {
     return this._addItemRaw(item);
   }
 
+  /**
+   * @param {index}
+   * @param {any}
+   * @returns {bool}
+   * @protected
+   * @description Sets a new element.
+   */
   _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}
+   * @description Sets a new element.
+   */
   setItem(index, item){
     // unwrap item from container
     if (item instanceof TXmlElementController) {
@@ -536,6 +811,13 @@ class TXmlElementsListController {
     return this._setItemRaw(index, item);
   }
 
+  /**
+   * @param {index}
+   * @param {any}
+   * @returns {bool}
+   * @protected
+   * @description Insertes a new element.
+   */
   _insItemRaw(index, item){
     index = valueToIndex(index);
     let size = this.size;
@@ -556,6 +838,12 @@ class TXmlElementsListController {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @param {any}
+   * @returns {bool}
+   * @description Insertes a new element.
+   */
   insItem(index, item){
     // unwrap item from container
     if (item instanceof TXmlElementController) {
@@ -564,6 +852,11 @@ class TXmlElementsListController {
     return this._insItemRaw(index, item);
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Deletes an element.
+   */
   delItem(value){
     let isSUCCEED = this.chkIndex(value);
     if (isSUCCEED) {
@@ -583,13 +876,18 @@ class TXmlElementsListController {
     return isSUCCEED;
   }
 
+  /**
+   * @param {any}
+   * @param {object} [opt]
+   * @param {bool} [opt.useClear=true]
+   * @returns {number}
+   * @description Loads a list of an elements.
+   */
   loadItems(items, opt){
     const _options = isPlainObject(opt) ? opt : {};
     let {
       useClear,
-      load_as_new,
     } = _options;
-    if (useClear === undefined) useClear = load_as_new;
     if (typeof useClear !== 'boolean') useClear = true;
     if (useClear) this.clear();
     let count = this.count;
@@ -599,11 +897,21 @@ class TXmlElementsListController {
 
 };
 
+/**
+ * @description This class implements an instance of an element
+ *              that managea content of a document declaration
+ */
 class TXmlContentDeclaration {
   #_host = null;
   #_options = null;
   #_ctrls = null;
 
+  /**
+   * @param {object}
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   * @throws {TypeError}
+   */
   constructor(obj, opt){
     // check <obj>-param
     if (!isPlainObject(obj)) {
@@ -634,6 +942,9 @@ class TXmlContentDeclaration {
     this.init();
   }
 
+  /**
+   * @property {string}
+   */
   get version(){
     return this.#_ctrls.getAttribute('version');
   }
@@ -642,6 +953,9 @@ class TXmlContentDeclaration {
     this.#_ctrls.setAttribute('version', value);
   }
 
+  /**
+   * @property {string}
+   */
   get encoding(){
     return this.#_ctrls.getAttribute('encoding');
   }
@@ -650,6 +964,10 @@ class TXmlContentDeclaration {
     this.#_ctrls.setAttribute('encoding', value);
   }
 
+  /**
+   * @returns {bool}
+   * @description Initializes an instance content.
+   */
   init(){
     const _options = this.#_options;
     this.#_ctrls = new TXmlElementController(
@@ -666,10 +984,22 @@ class TXmlContentDeclaration {
 
 };
 
+/**
+ * @augments TXmlElementController
+ * @description This class implements an instance of a root element
+ */
 class TXmlContentRootElement extends TXmlElementController {
   #_content = null;
   #_options = null;
 
+  /**
+   * @param {object}
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   * @param {ID_STRING} [opt.rootETagName='']
+   * @param {bool} [opt.autoBindRoot=true]
+   * @throws {TypeError}
+   */
   constructor(obj, opt){
     // check <obj>-param
     if (!isPlainObject(obj)) {
@@ -755,17 +1085,28 @@ class TXmlContentRootElement extends TXmlElementController {
     //this.init(rootETagName);
   }
 
+  /**
+   * @property {string}
+   */
   get tagName(){
     return this.#_options.rootETagName;
   }
 
   set tagName(value){
-    value = readAsString(value, '', true);
+    value = readAsString(value, true);
     this.#_options.rootETagName = isNotEmptyString(
       value
     ) ? value : XML_DEF_ROOT_ETAG_NAME;
   }
 
+  /**
+   * @param {object}
+   * @param {bool} [opt=false]
+   * @returns {?object}
+   * @protected
+   * @static
+   * @description Tries to unwraps a given object.
+   */
   static __unwrap(item, opt){
     return (
       item instanceof TXmlContentRootElement
@@ -777,6 +1118,10 @@ class TXmlContentRootElement extends TXmlElementController {
 
 }
 
+/**
+ * @description This class implements an instance of a container
+ *              that managea content of a document
+ */
 class TXmlContentContainer {
   #_content = null;
   #_options = null;
@@ -784,6 +1129,10 @@ class TXmlContentContainer {
   #_docDecl = null;
   #_docRoot = null;
 
+  /**
+   * @param {object} [opt]
+   * @param {object} [opt.parseOptions]
+   */
   constructor(opt){
     // load options
     const _options = isPlainObject(opt) ? opt : {};
@@ -805,15 +1154,29 @@ class TXmlContentContainer {
     this.#_docRoot = new TXmlContentRootElement(_content, _options);
   }
 
+  /**
+   * @property {TXmlContentRootElement}
+   * @readonly
+   */
   get rootElement(){
     return this.#_docRoot;
   }
 
+  /**
+   * @returns {none}
+   * @description Cleans a document content.
+   */
   clear(){
     this.#_docDecl.init();
     this.rootElement.clear();
   }
 
+  /**
+   * @param {object}
+   * @returns {bool}
+   * @protected
+   * @description Initializes an instance with a given content.
+   */
   _bindContent(obj, opt){
     const _options = isPlainObject(opt) ? opt : this.#_options;
     let isSUCCEED = false;
@@ -842,19 +1205,28 @@ class TXmlContentContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @returns {string}
+   * @description Returns a document content as a string in an XML-format.
+   */
   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;
   }
 
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @async
+   * @description Saves a document content to a file.
+   */
   saveToFile(source){
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
@@ -878,26 +1250,26 @@ class TXmlContentContainer {
           data.errEvent = 'OPS_IS_SUCCEED';
           resolve(data);
         }).catch(err => {
-          switch (err.code) {
-            case 'ENOENT': {
-              data.isERR = true;
-              data.errEvent = err.code;
-              data.content = '';
-              resolve(data);
-              break;
-            }
-            default: {
-              console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
-              console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
-              reject(err);
-              break;
-            }
+          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);
           };
         });
       };
     });
   }
 
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @description Saves a document content to a file.
+   */
   saveToFileSync(source){
     let data = {
       isSucceed: false,
@@ -916,25 +1288,25 @@ class TXmlContentContainer {
         data.content = this.saveToXMLString();
         fs.writeFileSync(data.source, data.content, 'utf8');
       } catch (err) {
-        switch (err.code) {
-          case 'ENOENT': {
-            data.isERR = true;
-            data.errEvent = err.code;
-            data.content = '';
-            break;
-          }
-          default: {
-            console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
-            console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
-            throw err;
-            break;
-          }
+        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;
         };
       };
     };
     return data;
   }
 
+  /**
+   * @param {string}
+   * @returns {bool}
+   * @throws {Error}
+   * @description Loads a document content from a string.
+   */
   loadFromXMLString(xmlString){
     let isSUCCEED = false;
     if (typeof xmlString === 'string') {
@@ -953,6 +1325,13 @@ class TXmlContentContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @async
+   * @description Loads a document content from a file.
+   */
   loadFromFile(source){
     /**/// main part that return promise as a result
     return new Promise((resolve, reject) => {
@@ -986,26 +1365,26 @@ class TXmlContentContainer {
           };
           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;
-            }
+          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);
           };
         });
       };
     });
   }
 
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @description Loads a document content from a file.
+   */
   loadFromFileSync(source){
     let data = {
       isLoaded: false,
@@ -1035,25 +1414,24 @@ class TXmlContentContainer {
           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;
-          }
+        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;
         };
       };
     };
     return data;
   }
 
+  /**
+   * @returns {string}
+   * @protected
+   * @description Returns a document content a string in a JSON-format.
+   */
   asJSON(){
     return JSON.stringify(this.#_content, null, 2);
   }