@cntwg/xml-lib-js 0.0.25 → 0.0.26

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+#### *v0.0.26*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.2;
+> - improve error handling on file load/save ops for `TXmlContentContainer`;
+> - fix behavior for a `setTextValue` method of a `TXmlElementController`;
+> - add `xml-helper.js` module.
+
 #### *v0.0.25*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2023 Yuri Grachev
+Copyright (c) 2019-2024 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,17 +1,11 @@
-|***rev.*:**|0.1.4|
+|***rev.*:**|0.1.5|
 |:---|---:|
-|***date***:|2023-09-19|
+|***date***:|2024-06-26|
 
 ## Introduction
 
 This module provide a base functionality for handling an XML-documents.
 
-## Use cases
-
-### Installation
-
-`npm install @cntwg/xml-lib-js`
-
 ## Description
 
 This module contains the following components:
@@ -38,3 +32,18 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 	+ `TXmlContentContainer`.
 
 For more read the `xmldoc-lib.md` in the project `doc` directory.
+
+### 3. an `xmlHelper` module extention
+
+- functions:
+
+	+ `getChildByPath`;
+	+ `addChildByPath`.
+
+For more read the `xmldoc-lib.md` in the project `doc` directory.
+
+## Use cases
+
+### Installation
+
+`npm install @cntwg/xml-lib-js`

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.22|
+>|***rev.*:**|0.1.23|
 >|:---|---:|
->|date:|2023-09-19|
+>|date:|2024-06-26|
 
 ## Introduction
 
@@ -189,6 +189,7 @@ This method returns an array witch contain a value of a `textValue` property and
 This method sets the value of a `textValue` property and its `lang` attribute and if succeed returns `true`.
 
 The method received value that can be a string or an array. If value is an array it must be in the following format:
+
 `[ <textValue> ]`
 or
 `[ <lang>, <textValue> ]`.
@@ -501,3 +502,27 @@ This method returns a document content as a string in the JSON-format.
 This method binds a given object as a document content.
 
 For `options` parameter details see the class constructor description.
+
+## Module `xmlHelper`
+
+This section contains functions provided by `xmlHelper` module.
+
+### Experimental functions
+
+> Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+#### **getChildByPath(object, chain)**
+
+> since: \[v0.0.26]
+
+This function tries to get a child element from a given object following path provided by `chain` parameter. If failed `null` is returned.
+
+The `chain` parameter contains an array of an element names.
+
+#### **addChildByPath(object, chain)**
+
+> since: \[v0.0.26]
+
+This function tries to add a new child element into a given object following path provided by `chain` parameter. If succeed a new element returned. If failed `null` is returned.
+
+The `chain` parameter contains an array of an element names. The last name in `chain` is a name of the element which will be added.

package/index.js

@@ -1,9 +1,10 @@
-// [v0.1.011-20230919]
+// [v0.1.012-20240626]
 
 // === module init block ===
 
 const xObj = require('@ygracs/xobj-lib-js');
 const xmldoc = require('./lib/xmldoc-lib.js');
+const xmlHelper = require('./lib/xml-helper.js');
 
 // === module extra block (helper functions) ===
 
@@ -11,16 +12,17 @@ const xmldoc = require('./lib/xmldoc-lib.js');
 
 // === module exports block ===
 
-exports.xObj = xObj;
+module.exports.xObj = xObj;
+module.exports.xmlHelper = xmlHelper;
 
-exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
-exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
+module.exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
+module.exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
 
-exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
+module.exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
 
-exports.TXmlAttributesMapper = xmldoc.TXmlAttributesMapper;
-exports.TXmlElementController = xmldoc.TXmlElementController;
-exports.TXmlElementsListController = xmldoc.TXmlElementsListController;
-exports.TXmlContentDeclaration = xmldoc.TXmlContentDeclaration;
-exports.TXmlContentRootElement = xmldoc.TXmlContentRootElement;
-exports.TXmlContentContainer = xmldoc.TXmlContentContainer;
+module.exports.TXmlAttributesMapper = xmldoc.TXmlAttributesMapper;
+module.exports.TXmlElementController = xmldoc.TXmlElementController;
+module.exports.TXmlElementsListController = xmldoc.TXmlElementsListController;
+module.exports.TXmlContentDeclaration = xmldoc.TXmlContentDeclaration;
+module.exports.TXmlContentRootElement = xmldoc.TXmlContentRootElement;
+module.exports.TXmlContentContainer = xmldoc.TXmlContentContainer;

package/lib/xml-helper.js

@@ -0,0 +1,88 @@
+// [v0.0.001-20240626]
+
+// === module init block ===
+
+const {
+  valueToArray,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  TXmlElementController,
+} = require('./xmldoc-lib');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * @function getChildByPath
+ * @param {TXmlElementController}
+ * @param {array}
+ * @returns {?TXmlElementController}
+ * @description Tries to get a child element.
+ */
+function getChildByPath(obj, chain) {
+  let result = null;
+  if (obj instanceof TXmlElementController) {
+    const list = valueToArray(chain);
+    let child = obj;
+    let isFound = false;
+    for (let name of list) {
+      child = child.getChild(name);
+      if (
+        child !== null
+        && (child instanceof TXmlElementController)
+      ) {
+        isFound = true;
+      } else {
+        isFound = false;
+        break;
+      };
+    };
+    if (isFound) result = child;
+  };
+  return result;
+};
+
+/**
+ * @function addChildByPath
+ * @param {TXmlElementController}
+ * @param {array}
+ * @returns {?TXmlElementController}
+ * @description Tries to get a child element.
+ */
+function addChildByPath(obj, chain){
+  let child = null;
+  if (obj instanceof TXmlElementController) {
+    const list = valueToArray(chain);
+    for (let name of list) {
+      child = item.getChild(name);
+      if (child === null) {
+        child = item.addChild(name);
+      };
+      if ((child instanceof TXmlElementController)) {
+        item = child;
+      } else {
+        child = null; break;
+      };
+    };
+  };
+  return child;
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+module.exports.getChildByPath = getChildByPath;
+module.exports.addChildByPath = addChildByPath;

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.069-20230926]
+// [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,6 +876,13 @@ 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 {
@@ -597,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)) {
@@ -632,6 +942,9 @@ class TXmlContentDeclaration {
     this.init();
   }
 
+  /**
+   * @property {string}
+   */
   get version(){
     return this.#_ctrls.getAttribute('version');
   }
@@ -640,6 +953,9 @@ class TXmlContentDeclaration {
     this.#_ctrls.setAttribute('version', value);
   }
 
+  /**
+   * @property {string}
+   */
   get encoding(){
     return this.#_ctrls.getAttribute('encoding');
   }
@@ -648,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(
@@ -664,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)) {
@@ -753,6 +1085,9 @@ class TXmlContentRootElement extends TXmlElementController {
     //this.init(rootETagName);
   }
 
+  /**
+   * @property {string}
+   */
   get tagName(){
     return this.#_options.rootETagName;
   }
@@ -764,6 +1099,14 @@ class TXmlContentRootElement extends TXmlElementController {
     ) ? 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
@@ -775,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;
@@ -782,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 : {};
@@ -803,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;
@@ -840,6 +1205,10 @@ class TXmlContentContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @returns {string}
+   * @description Returns a document content as a string in an XML-format.
+   */
   saveToXMLString(){
     let result = '';
     try {
@@ -851,6 +1220,13 @@ class TXmlContentContainer {
     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) => {
@@ -874,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,
@@ -912,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') {
@@ -949,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) => {
@@ -982,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,
@@ -1031,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);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -15,6 +15,7 @@
   "files": [
     "doc/xmldoc-lib.md",
     "lib/xmldoc-lib.js",
+    "lib/xml-helper.js",
     "index.js",
     "CHANGELOG.md"
   ],
@@ -26,18 +27,22 @@
     "test-xml:lc": "jest TXmlElementsListController",
     "test-xml:re": "jest TXmlContentRootElement",
     "test-xml:cdec": "jest TXmlContentDeclaration",
-    "test-xml:cc": "jest TXmlContentContainer"
+    "test-xml:cc": "jest TXmlContentContainer",
+    "build-doc-md": "jsdoc2md",
+    "build-doc-html": "jsdoc"
   },
   "imports": {
-    "#lib/*": "./lib/*"
+    "#lib/*": "./lib/*",
+    "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.2.0",
+    "@ygracs/bsfoc-lib-js": "^0.2.1",
     "@ygracs/xml-js6": "^0.0.3-b",
-    "@ygracs/xobj-lib-js": "^0.1.1"
+    "@ygracs/xobj-lib-js": "^0.1.2"
   },
   "devDependencies": {
     "jest": "^29.7.0",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "jsdoc-to-markdown": "^8.0.1"
   }
 }