@ygracs/xepg-lib-js 0.0.19 → 0.0.21

package/lib/xepgdoc-lib.js

@@ -1,9 +1,7 @@
-// [v0.1.056-20240717]
+// [v0.1.081-20250227]
 
 // === module init block ===
 
-const fs = require('fs');
-const fse = require('fs').promises;
 const xmlParser = require('@ygracs/xml-js6');
 
 const {
@@ -18,10 +16,15 @@ const {
 } = require('@ygracs/dtf-lib-js');
 
 const {
-  chkDTSysID, getDTSysName, getDTSysDescr,
+  chkDTSysID, getDTSysDescr,
   convStringToDTValue, convDTValueToString,
 } = require('./dts-helper.js');
 
+const {
+  loadFileSync, loadFile,
+  saveToFileSync, saveToFile,
+} = require('./file-helper.js');
+
 const xObj = require('@ygracs/xobj-lib-js');
 
 const TXmlContentParseOptions = xObj.TXmlContentParseOptions;
@@ -62,8 +65,8 @@ function writeXEpgDocDeclSection(obj, opt){
   let doc_def_enc = XEPG_DEF_ENCODING_VALUE;
   let key_name = defParseOptions.settings.declarationKey;
   if (isPlainObject(opt)) {
-    xml_ver = readAsString(opt.version, xml_ver);
-    doc_def_enc = readAsString(opt.encoding, doc_def_enc);
+    xml_ver = readAsString(opt.version, { defValue: xml_ver });
+    doc_def_enc = readAsString(opt.encoding, { defValue: doc_def_enc });
   };
   if (isPlainObject(obj) && isNotEmptyString(key_name)) {
     obj[key_name] = {};
@@ -72,34 +75,6 @@ function writeXEpgDocDeclSection(obj, opt){
   };
 };
 
-/**
- * @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 ===
 
 /***
@@ -165,14 +140,35 @@ const defParseOptions = new TXmlContentParseOptions();
  */
 
 /**
- * @description This class implements an instance of a EPG-schedules list
+ * @typedef {Object} xepgShedInfoDesc
+ * @property {number} time - a schedule start time
+ * @property {string} title - schedule title
+ * @property {string} [cat] - schedule category
+ * @property {number} [pcmark] - schedule rating
+ * @property {string} [descr] - schedule description
+ * @description A schedule info descriptor
+ */
+
+/**
+ * @classdesc This class implements an interface of a EPG-schedules list
  */
 class TXEpgSchedulesList {
-  #_content = null;
-  #_options = null;
+  /** @property {object[]} */
+  #_content;// = null;
+  /** @property {object} */
+  #_options;// = null;
+  /** @property {?object} */
   #_dts_src = null;
+  /** @property {?object} */
   #_tz_src = null;
 
+  /**
+   * @param {any[]} obj - list of an elements
+   * @param {object} [opt] - options
+   * @param {?object} [opt.dts_src]
+   * @param {?object} [opt.tz_src]
+   * @description Creates an instance of the schedules list
+   */
   constructor(obj, opt) {
     const _content = isArray(obj) ? obj : [];
     const _options = isPlainObject(opt) ? opt : {};
@@ -188,27 +184,48 @@ class TXEpgSchedulesList {
     this.#_tz_src = tz_src;
   }
 
-  #_getItem = function(value){
-    if (this.chkScheduleIndex(value)) {
+  /**
+   * @param {(number|string)} value - element index
+   * @returns {any}
+   * @private
+   * @description Returns a raw schedule element
+   */
+  #_getItem = function(value) {
+    if (this.chkIndex(value)) {
       return this.#_content[Number(value)];
     };
   };
 
-  get schedQty(){
+  /**
+   * Contains a quantity of a schedules
+   * @property {number}
+   * @readonly
+   */
+  get schedQty() {
     return this.#_content.length;
   }
 
   // will deprecate
   //get SchedulesQty(){ return this.#_content.length; }
 
-  get dtstype(){
+  /**
+   * Contains a dtstype ID
+   * @property {number}
+   * @readonly
+   */
+  get dtstype() {
     let result = valueToIndex(
       _getXmlChildElementParam(this.#_dts_src, 'value')
     );
     return chkDTSysID(result) ? result : 0; //-1; // // TODO: [?]
   }
 
-  get curDocTZ(){
+  /**
+   * Contains a TZ-offset
+   * @property {number}
+   * @readonly
+   */
+  get curDocTZ() {
     return (
       this.#_tz_src
       ? convTZStringToValue(readXObjParam(this.#_tz_src).trim())
@@ -216,20 +233,52 @@ class TXEpgSchedulesList {
     );
   }
 
-  hasNoSchedules(){
+  /**
+   * @returns {boolean}
+   * @description Indicates whether an instance has none member
+   */
+  hasNoSchedules() {
     return this.schedQty === 0;
   }
 
-  hasSchedules(){
+  /**
+   * @returns {boolean}
+   * @description Indicates whether an instance has any member
+   */
+  hasSchedules() {
     return this.schedQty > 0;
   }
 
-  chkScheduleIndex(value){
+  /**
+   * @param {(number|string)} value
+   * @returns {boolean}
+   * @deprecated
+   * @description Checks whether a given value is a valid index
+   *              and it fits the index range of an instance
+   */
+  chkScheduleIndex(value) {
+    return this.chkIndex(value);
+  }
+
+  /**
+   * @param {(number|string)} value - index of some element
+   * @returns {boolean}
+   * @since 0.0.18
+   * @description Checks whether a given value is a valid index
+   *              and it fits the index range of an instance
+   */
+  chkIndex(value) {
     const index = valueToIndex(value);
     return index !== -1 && index < this.schedQty;
   }
 
-  getScheduleInfo(index){
+  /**
+   * @param {(number|string)} index - index of some element
+   * @returns {xepgShedInfoDesc}
+   * @description Returns a schedule info item for instance element
+   *              addressed by a given index
+   */
+  getScheduleInfo(index) {
     //console.log('TXEpgSchedulesList => getScheduleInfo() => was called...');
     const curObj = this.#_getItem(index);
     let tmpObj = {};
@@ -257,7 +306,11 @@ class TXEpgSchedulesList {
     return tmpObj;
   }
 
-  getAllSchedulesInfo(){
+  /**
+   * @returns {xepgShedInfoDesc[]}
+   * @description Returns a schedule info for instance members
+   */
+  getAllSchedulesInfo() {
     let result = [];
     for (let i = 0; i < this.schedQty; i++) {
       let item = this.getScheduleInfo(i);
@@ -266,22 +319,45 @@ class TXEpgSchedulesList {
     return result;
   }
 
-  asJSON(){
+  /**
+   * @protected
+   */
+  asJSON() {
     return JSON.stringify(this.#_content, null, 2);
   }
 
 };
 
 /**
- * @description This class implements an instance of a EPG-provider element
+ * @typedef {Object} xepgProvInfoDesc
+ * @property {string} [name] - provider name
+ * @property {string} [version] - provider version
+ * @property {string} schema - document schema
+ * @property {string} doctype - document type
+ * @description A provider info descriptor
+ */
+
+/**
+ * @classdesc This class implements an interface of a EPG-provider element
  */
 class TXEpgProviderContainer {
-  #_content = null;
-  #_options = null;
+  /** @property {Object} */
+  #_host;// = null;
+  /** @property {Object} */
+  #_options;// = null;
+  /** @property {TXmlContentParseOptions} */
+  #_parseOptions;// = null;
+  /** @property {?TXEpgDTSProvider} */
 
+  /**
+   * @param {object} obj
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @description Creates an instance of the EPG-provider element
+   */
   constructor(obj, opt) {
     // load content
-    const _content = isPlainObject(obj) ? obj : {};
+    const _host = isPlainObject(obj) ? obj : {};
     // load options
     const _options = isPlainObject(opt) ? opt : {};
     let {
@@ -291,10 +367,12 @@ class TXEpgProviderContainer {
       parseOptions = new TXmlContentParseOptions(parseOptions);
       _options.parseOptions = parseOptions;
     };
-    // save content source
-    this.#_content = _content;
     // save options
     this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // save content source
+    this.#_host = _host;
     // init instance
     this.#_init();
   }
@@ -311,69 +389,86 @@ class TXEpgProviderContainer {
     //_options.docTypeETagName = docTypeETagName;
   }
 
-  get name(){
-    return _getXmlChildElementParam(this.#_content, 'name').trim();
+  /**
+   * Contains a provider name
+   * @property {string}
+   */
+  get name() {
+    return _getXmlChildElementParam(this.#_host, 'name').trim();
   }
 
-  set name(value){
+  set name(value) {
     this.setName(value);
   }
 
-  get version(){
-    return _getXmlChildElementParam(this.#_content, 'version').trim();
+  /**
+   * Contains a version of a provider
+   * @property {string}
+   */
+  get version() {
+    return _getXmlChildElementParam(this.#_host, 'version').trim();
   }
 
-  set version(value){
-    if (this.name !== '') {
-      const _value = typeof value === 'string' ? value.trim() : '';
-      const item = insertXObjElement(
-        this.#_content,
-        'version',
-        { force: true },
-      );
-      if (item) writeXObjParam(item, _value);
+  set version(value) {
+    if (typeof value === 'string' && this.name !== '') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, 'version', opt);
+      if (item) writeXObjParam(item, value.trim());
     };
   }
 
-  get schema(){
-    return _getXmlChildElementParam(this.#_content, XEPG_DOCSCH_ETAG_NAME).trim();
+  /**
+   * Contains a version of a document schema
+   * @property {string}
+   */
+  get schema() {
+    return _getXmlChildElementParam(this.#_host, XEPG_DOCSCH_ETAG_NAME).trim();
   }
 
-  set schema(value){
-    const _value = typeof value === 'string' ? value.trim() : '';
-    const item = insertXObjElement(
-      this.#_content,
-      XEPG_DOCSCH_ETAG_NAME,
-      { force: true },
-    );
-    if (item) writeXObjParam(item, _value);
+  set schema(value) {
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_DOCSCH_ETAG_NAME, opt);
+      if (item) writeXObjParam(item, value.trim());
+    };
   }
 
-  get doctype(){
-    return _getXmlChildElementParam(this.#_content, XEPG_DOCTYP_ETAG_NAME).trim();
+  /**
+   * Contains a document type
+   * @property {string}
+   */
+  get doctype() {
+    return _getXmlChildElementParam(this.#_host, XEPG_DOCTYP_ETAG_NAME).trim();
   }
 
-  set doctype(value){
-    const _value = typeof value === 'string' ? value.trim() : '';
-    const item = insertXObjElement(
-      this.#_content,
-      XEPG_DOCTYP_ETAG_NAME,
-      { force: true },
-    );
-    if (item) writeXObjParam(item, _value);
+  set doctype(value) {
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_DOCTYP_ETAG_NAME, opt);
+      if (item) writeXObjParam(item, value.trim());
+    };
   }
 
-  setName(value){
-    let isSUCCEED = false;
-    let item = insertXObjElement(this.#_content, 'name', { force: true });
-    if (item) {
-      const name = typeof value === 'string' ? value.trim() : '';
-      isSUCCEED = writeXObjParam(item, name);
+  /**
+   * @param {string} value - provider name
+   * @returns {boolean}
+   * @description Sets a provider name
+   */
+  setName(value) {
+    let isSucceed = false;
+    if (typeof value === 'string') {
+      const name = value.trim();
+      const item = insertXObjElement(this.#_host, 'name', { force: true });
+      if (item) isSucceed = writeXObjParam(item, name);
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
-  getInfo(){
+  /**
+   * @returns {xepgProvInfoDesc}
+   * @description Returns a provider info item
+   */
+  getInfo() {
     return {
       name: this.name,
       version: this.version,
@@ -382,18 +477,26 @@ class TXEpgProviderContainer {
     };
   }
 
-  setInfo(obj){
+  /**
+   * @param {(string[]|xepgProvInfoDesc)} obj - provider info descriptor
+   * @returns {void}
+   * @description Sets a provider info
+   * @todo [since v0.0.21] deprecate use of `obj`-param as array
+   */
+  setInfo(obj) {
     if (!isObject(obj)) return;
     let name = '';
     let version = '';
     let schema = '';
     let doctype = '';
     if (isArray(obj)) {
+      // // TODO: [!] deprecate
       [ name, version, schema, doctype ] = obj;
     } else {
       if (typeof obj.name === 'string') {
         ({ name, version, schema, doctype } = obj);
       } else {
+        // // TODO: [?] deprecate
         name = _getXmlChildElementParam(obj, 'name');
         version = _getXmlChildElementParam(obj, 'version');
         schema = _getXmlChildElementParam(obj, XEPG_DOCSCH_ETAG_NAME);
@@ -411,7 +514,12 @@ class TXEpgProviderContainer {
     this.doctype = doctype;
   }
 
-  init(opt){
+  /**
+   * @param {(xepgProvInfoDesc|string[])} opt - options
+   * @returns {void}
+   * @description Sets an initial instance state
+   */
+  init(opt) {
     let prov_opt = { ...defXEpgDocOptions.defProviderParam };
     let name = '';
     let version = '';
@@ -433,15 +541,44 @@ class TXEpgProviderContainer {
     this.doctype = doctype;
   }
 
+  /**
+   * @returns {string}
+   * @since v0.0.20
+   * @description Returns an instance content as a string in an XML-format.
+   */
+  saveToXMLString() {
+    const options = this.#_parseOptions.js2xml;
+    options.ignoreDocType = true;
+    options.ignoreDeclaration = true;
+    const content = { [`${XEPG_PRVINFO_ETAG_NAME}`]: this.#_host };
+    let result = '';
+    try {
+      result = xmlParser.js2xml(content, options);
+    } catch (err) {
+      //console.log('CHECK: TXEpgHeaderContainer.saveToXMLString() => Error => '+err);
+      result = '';
+      //throw err;
+    };
+    return result;
+  }
+
 };
 
 /**
- * @description This class implements an instance of a DTS-provider element
+ * @classdesc This class implements an instance of a DTS-provider element
  */
-class TXepgDTSProvider {
-  #_content = null;
-  #_options = null;
+class TXEpgDTSProvider {
+  /** @property {object} */
+  #_content;// = null;
+  /** @property {object} */
+  #_options;// = null;
 
+  /**
+   * @param {object} obj
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @description Creates an instance of the DTS-provider element
+   */
   constructor(obj, opt) {
     // load content
     const _content = isPlainObject(obj) ? obj : {};
@@ -462,11 +599,19 @@ class TXepgDTSProvider {
     this.#_init();
   }
 
-  #_init(){
+  /**
+   * @returns {void}
+   * @private
+   */
+  #_init() {
     insertXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
   }
 
-  get dtstype(){
+  /**
+   * Contains a dtstype ID
+   * @property {number}
+   */
+  get dtstype() {
     const item = getXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
     let result = 0; //-1; // // TODO: [?]
     if (isPlainObject(item)) {
@@ -476,7 +621,7 @@ class TXepgDTSProvider {
     return result;
   }
 
-  set dtstype(value){
+  set dtstype(value) {
     let { index, name } = getDTSysDescr(value);
     if (index !== -1) {
       const item = insertXObjElement(
@@ -497,13 +642,18 @@ class TXepgDTSProvider {
     };
   }
 
-  get curDocTZ(){
-    return convTZStringToValue(
+  /**
+   * Contains a TZ-offset
+   * @property {number}
+   */
+  get curDocTZ() {
+    const tz = convTZStringToValue(
       _getXmlChildElementParam(this.#_content, XEPG_DOCTZ_ETAG_NAME)
     );
+    return Number.isNaN(tz) ? 0 : tz;
   }
 
-  set curDocTZ(value){
+  set curDocTZ(value) {
     let _value = convValueToTZString(value);
     if (_value !== '') {
       let item = insertXObjElement(
@@ -518,18 +668,38 @@ class TXepgDTSProvider {
 };
 
 /**
- * @description This class implements an instance of a EPG-header element
+ * @typedef {Object} xepgChnInfoDesc
+ * @property {string} chnid - channel ID
+ * @property {string} chname - channel name
+ * @property {string} [chngid] - channel 'Group ID'
+ * @property {string} [srcurl] - EPG-source URL
+ * @description A channel info descriptor
+ */
+
+/**
+ * @classdesc This class implements an instance of a EPG-header element
  */
 class TXEpgHeaderContainer {
-  #_content = null;
-  #_options = null;
-  #_dtsProv = null;
+  /** @property {Object} */
+  #_host;// = null;
+  /** @property {Object} */
+  #_options;// = null;
+  /** @property {TXmlContentParseOptions} */
+  #_parseOptions;// = null;
+  /** @property {TXEpgDTSProvider} */
+  #_dtsProv;// = null;
 
+  /**
+   * @param {object} obj
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @description Creates an instance of the EPG-header element
+   */
   constructor(obj, opt) {
     // load content
-    const _content = isPlainObject(obj) ? obj : {};
+    const _host = isPlainObject(obj) ? obj : {};
     // load options
-    let _options = isPlainObject(opt) ? opt : {};
+    const _options = isPlainObject(opt) ? opt : {};
     let {
       parseOptions,
     } = _options;
@@ -537,49 +707,79 @@ class TXEpgHeaderContainer {
       parseOptions = new TXmlContentParseOptions(parseOptions);
       _options.parseOptions = parseOptions;
     };
-    // save content source
-    this.#_content = _content;
     // save options
     this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // save content source
+    this.#_host = _host;
     // init DTS-provider
-    this.#_dtsProv = new TXepgDTSProvider(this.#_content, _options);
+    this.#_dtsProv = new TXEpgDTSProvider(_host, _options);
   }
 
-  get dts(){
+  /**
+   * Returns a `TXEpgDTSProvider` instance
+   * @property {TXEpgDTSProvider}
+   * @readonly
+   */
+  get dts() {
     return this.#_dtsProv;
   }
 
-  get dtstype(){
+  /**
+   * Contains a dtstype ID
+   * @property {number}
+   * @todo [since v0.0.22] becomes readonly
+   */
+  get dtstype() {
     return this.#_dtsProv.dtstype;
   }
 
-  set dtstype(value){
+  set dtstype(value) {
     this.#_dtsProv.dtstype = value;
   }
 
-  get curDocTZ(){
+  /**
+   * Contains a TZ-offset
+   * @property {number}
+   * @todo [since v0.0.22] becomes readonly
+   */
+  get curDocTZ() {
     return this.#_dtsProv.curDocTZ;
   }
 
-  set curDocTZ(value){
+  set curDocTZ(value) {
     this.#_dtsProv.curDocTZ = value;
   }
 
-  #_getProv(){
-    const docProv = getXObjElement(this.#_content, XEPG_PRVINFO_ETAG_NAME);
+  /**
+   * @returns {?object}
+   * @private
+   */
+  #_getProv() {
+    const docProv = getXObjElement(this.#_host, XEPG_PRVINFO_ETAG_NAME);
     return isPlainObject(docProv) ? docProv : null;
   }
 
-  #_initProv(){
-    const _content = this.#_content;
-    let docProv = getXObjElement(_content, XEPG_PRVINFO_ETAG_NAME);
+  /**
+   * @returns {?object}
+   * @private
+   */
+  #_initProv() {
+    const _host = this.#_host;
+    let docProv = getXObjElement(_host, XEPG_PRVINFO_ETAG_NAME);
     if (!docProv) {
-      docProv = insertXObjElement(_content, XEPG_PRVINFO_ETAG_NAME);
+      docProv = insertXObjElement(_host, XEPG_PRVINFO_ETAG_NAME);
     };
     return isPlainObject(docProv) ? docProv : null;
   }
 
-  get Provider(){
+  /**
+   * @property {?TXEpgProviderContainer}
+   * @readonly
+   * @description Returns a `TXEpgProviderContainer` instance
+   */
+  get Provider() {
     const docProv = this.#_getProv();
     return (
       docProv
@@ -588,8 +788,12 @@ class TXEpgHeaderContainer {
     );
   }
 
-  getDocumentDT(){
-    let dt_str = _getXmlChildElementParam(this.#_content, XEPG_DOCDTO_ETAG_NAME).trim();
+  /**
+   * @returns {number}
+   * @description Returns a document creation date as a timestamp
+   */
+  getDocumentDT() {
+    let dt_str = _getXmlChildElementParam(this.#_host, XEPG_DOCDTO_ETAG_NAME).trim();
     return (
       dt_str !== ''
       ? convStringToDTValue(dt_str, this.dtstype, this.curDocTZ)
@@ -597,18 +801,26 @@ class TXEpgHeaderContainer {
     );
   }
 
-  setDocumentDT(){
+  /**
+   * @returns {void}
+   * @description Sets a document creation date to a current system time
+   */
+  setDocumentDT() {
     let dt_str = convDTValueToString(Date.now(), this.dtstype, this.curDocTZ);
     let item = insertXObjElement(
-      this.#_content,
+      this.#_host,
       XEPG_DOCDTO_ETAG_NAME,
       { force: true },
     );
     if (item) writeXObjParam(item, dt_str);
   }
 
-  getDocumentEDT(){
-    let dt_str = _getXmlChildElementParam(this.#_content, XEPG_DOCDTE_ETAG_NAME).trim();
+  /**
+   * @returns {number}
+   * @description Returns a document expire date as a timestamp
+   */
+  getDocumentEDT() {
+    let dt_str = _getXmlChildElementParam(this.#_host, XEPG_DOCDTE_ETAG_NAME).trim();
     return (
       dt_str !== ''
       ? convStringToDTValue(dt_str, this.dtstype, this.curDocTZ)
@@ -616,40 +828,58 @@ class TXEpgHeaderContainer {
     );
   }
 
-  setDocumentEDT(value){
+  /**
+   * @param {any} value - document expire date
+   * @returns {void}
+   * @description Sets a document expire date to a given time
+   */
+  setDocumentEDT(value) {
     // TODO: check if value is a DateTime-string
     let dt_str = convDTValueToString(value, this.dtstype, this.curDocTZ);
     let item = insertXObjElement(
-      this.#_content,
+      this.#_host,
       XEPG_DOCDTE_ETAG_NAME,
       { force: true },
     );
     if (item) writeXObjParam(item, dt_str);
   }
 
-  getChannelInfo(){
-    const _content = this.#_content;
+  /**
+   * @returns {xepgChnInfoDesc}
+   * @description Returns a channel info
+   */
+  getChannelInfo() {
+    const _host = this.#_host;
+    /** @type {xepgChnInfoDesc} */
     let item = {
-      chnid: _getXmlChildElementParam(_content, XEPG_CHNID_ETAG_NAME).trim(),
-      chname: _getXmlChildElementParam(_content, XEPG_CHNNAME_ETAG_NAME).trim(),
-      chngid: _getXmlChildElementParam(_content, XEPG_CHNGID_ETAG_NAME).trim(),
-      srcurl: _getXmlChildElementParam(_content, XEPG_CHNURL_ETAG_NAME).trim(),
+      chnid: _getXmlChildElementParam(_host, XEPG_CHNID_ETAG_NAME).trim(),
+      chname: _getXmlChildElementParam(_host, XEPG_CHNNAME_ETAG_NAME).trim(),
+      chngid: _getXmlChildElementParam(_host, XEPG_CHNGID_ETAG_NAME).trim(),
+      srcurl: _getXmlChildElementParam(_host, XEPG_CHNURL_ETAG_NAME).trim(),
     };
     return item;
   }
 
-  setChannelInfo(obj){
+  /**
+   * @param {xepgChnInfoDesc} obj - channel info descriptor
+   * @returns {void}
+   * @description Sets a channel info
+   * @todo [since v0.0.21] deprecate use of `obj`-param as array
+   */
+  setChannelInfo(obj) {
     let chnid = '';
     let chname = '';
     let chngid = '';
     let srcurl = '';
     if (isArray(obj)) {
+      // // TODO: [!] deprecate
       [ chnid, chname, chngid, srcurl ] = obj;
     } else if (isObject(obj)) {
       ({ chnid } = obj);
       if (typeof chnid === 'string') {
         ({ chname, chngid, srcurl } = obj);
       } else {
+        // // TODO: [?] deprecate
         chnid = _getXmlChildElementParam(obj, XEPG_CHNID_ETAG_NAME).trim();
         chname = _getXmlChildElementParam(obj, XEPG_CHNNAME_ETAG_NAME).trim();
         chngid = _getXmlChildElementParam(obj, XEPG_CHNGID_ETAG_NAME).trim();
@@ -671,22 +901,31 @@ class TXEpgHeaderContainer {
       srcurl = typeof srcurl === 'string' ? srcurl.trim() : '';
     };
     let item = null;
-    const _content = this.#_content;
-    item = insertXObjElement(_content, XEPG_CHNID_ETAG_NAME, { force: true });
+    const _host = this.#_host;
+    item = insertXObjElement(_host, XEPG_CHNID_ETAG_NAME, { force: true });
     if (item) writeXObjParam(item, chnid);
-    item = insertXObjElement(_content, XEPG_CHNNAME_ETAG_NAME, { force: true });
+    item = insertXObjElement(_host, XEPG_CHNNAME_ETAG_NAME, { force: true });
     if (item) writeXObjParam(item, chname);
-    item = insertXObjElement(_content, XEPG_CHNGID_ETAG_NAME, { force: true });
+    item = insertXObjElement(_host, XEPG_CHNGID_ETAG_NAME, { force: true });
     if (item) writeXObjParam(item, chngid);
-    item = insertXObjElement(_content, XEPG_CHNURL_ETAG_NAME, { force: true });
+    item = insertXObjElement(_host, XEPG_CHNURL_ETAG_NAME, { force: true });
     if (item) writeXObjParam(item, srcurl);
   }
 
+  /**
+   * @returns {?xepgProvInfoDesc}
+   * @description Returns a provider info
+   */
   getProviderInfo(){
     const docProv = this.Provider;
     return docProv ? docProv.getInfo() : null;
   }
 
+  /**
+   * @param {xepgProvInfoDesc} obj - provider info descriptor
+   * @returns {void}
+   * @description Sets a provider info
+   */
   setProviderInfo(obj){
     if (isArray(obj) || isObject(obj)) {
       let docProv = this.Provider;
@@ -698,17 +937,58 @@ class TXEpgHeaderContainer {
     };
   }
 
+  /**
+   * @returns {string}
+   * @since v0.0.20
+   * @description Returns an instance content as a string in an XML-format.
+   */
+  saveToXMLString() {
+    const options = this.#_parseOptions.js2xml;
+    options.ignoreDocType = true;
+    options.ignoreDeclaration = true;
+    const content = { [`${XEPG_HEADER_ETAG_NAME}`]: this.#_host };
+    let result = '';
+    try {
+      result = xmlParser.js2xml(content, options);
+    } catch (err) {
+      //console.log('CHECK: TXEpgHeaderContainer.saveToXMLString() => Error => '+err);
+      result = '';
+      //throw err;
+    };
+    return result;
+  }
+
 };
 
 /**
- * @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 interface of the container
+ *            that manages a content of a XEPG-document
  */
 class TXEpgContentProvider {
-  #_content = null;
-  #_options = null;
-  #_parseOptions = null;
+  /** @property {Object} */
+  #_content;// = null;
+  /** @property {Object} */
+  #_options;// = null;
+  /** @property {?TXmlContentParseOptions} */
+  #_parseOptions;// = null;
 
+  /**
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @param {boolean} [opt.autoBindRoot] - <*reserved*> ([?] - deprecate)
+   * @description Creates an instance of the XEPG-content provider
+   */
   constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
@@ -731,12 +1011,20 @@ class TXEpgContentProvider {
     this.init();
   }
 
-  #_getRoot(){
+  /**
+   * @returns {?Object}
+   * @private
+   */
+  #_getRoot() {
     const docRoot = getXObjElement(this.#_content, XEPG_ROOT_ETAG_NAME);
     return isPlainObject(docRoot) ? docRoot : null;
   }
 
-  #_initRoot(){
+  /**
+   * @returns {?object}
+   * @private
+   */
+  #_initRoot() {
     const _content = this.#_content;
     let docRoot = getXObjElement(_content, XEPG_ROOT_ETAG_NAME);
     if (!docRoot) {
@@ -748,7 +1036,11 @@ class TXEpgContentProvider {
     return isPlainObject(docRoot) ? docRoot : null;
   }
 
-  #_getHdr(){
+  /**
+   * @returns {?Object}
+   * @private
+   */
+  #_getHdr() {
     const docRoot = this.#_getRoot();
     let docHdr = null;
     if (docRoot) {
@@ -757,7 +1049,11 @@ class TXEpgContentProvider {
     return isPlainObject(docHdr) ? docHdr : null;
   }
 
-  #_initHdr(){
+  /**
+   * @returns {?object}
+   * @private
+   */
+  #_initHdr() {
     let docHdr = this.#_getHdr();
     if (!docHdr) {
       let docRoot = this.#_getRoot();
@@ -769,7 +1065,11 @@ class TXEpgContentProvider {
     return isPlainObject(docHdr) ? docHdr : null;
   }
 
-  #_getBody(){
+  /**
+   * @returns {?Object}
+   * @private
+   */
+  #_getBody() {
     const docRoot = this.#_getRoot();
     let docBody = null;
     if (docRoot) {
@@ -778,7 +1078,11 @@ class TXEpgContentProvider {
     return isPlainObject(docBody) ? docBody : null;
   }
 
-  #_initBody(){
+  /**
+   * @returns {?object}
+   * @private
+   */
+  #_initBody() {
     let docBody = this.#_getBody();
     if (!docBody) {
       let docRoot = this.#_getRoot();
@@ -790,7 +1094,12 @@ class TXEpgContentProvider {
     return isPlainObject(docBody) ? docBody : null;
   }
 
-  get Header(){
+  /**
+   * Returns a `TXEpgHeaderContainer` instance
+   * @property {?TXEpgHeaderContainer}
+   * @readonly
+   */
+  get Header() {
     const docHdr = this.#_getHdr();
     return (
       docHdr
@@ -799,21 +1108,38 @@ class TXEpgContentProvider {
     );
   }
 
-  get Provider(){
+  /**
+   * Returns a `TXEpgProviderContainer` instance
+   * @property {?TXEpgProviderContainer}
+   * @readonly
+   */
+  get Provider() {
     const docHdr = this.Header;
     return docHdr ? docHdr.Provider : null;
   }
 
-  get dts(){
+  /**
+   * Returns a `TXEpgDTSProvider` instance
+   * @property {?TXEpgDTSProvider}
+   * @readonly
+   */
+  get dts() {
     const docHdr = this.Header;
     return docHdr ? docHdr.dts : null;
   }
 
   /* [!] a temporary special method */
-  /* will deprecate */
+  /**
+   * @deprecated
+   */
   get Content(){ return this; }
 
-  get SchedulesList(){
+  /**
+   * Returns a `TXEpgSchedulesList` instance
+   * @property {TXEpgSchedulesList}
+   * @readonly
+   */
+  get SchedulesList() {
     const _options = this.#_options;
     const docBody = this.#_getBody();
     if (docBody && isArray(docBody[XEPG_SCHED_ETAG_NAME])) {
@@ -828,7 +1154,10 @@ class TXEpgContentProvider {
     };
   }
 
-  init(){
+  /**
+   * @returns {void}
+   */
+  init() {
     const _options = this.#_options;
     const _content = this.#_content;
     const {
@@ -880,8 +1209,8 @@ class TXEpgContentProvider {
   }
 
   /**
-   * @param {string}
-   * @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.
@@ -889,88 +1218,77 @@ class TXEpgContentProvider {
   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: TXEpgContentProvider.saveToFile() => Error => '+err);
-            //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err.code);
-            reject(err);
-          };
+          // // TODO: [?] consider check others
+          //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err);
+          //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err.code);
+          reject(err);
         });
-      };
+      }).catch(err => {
+        data.isERR = true;
+        //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err);
+        //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err.code);
+        data.errEvent = 'ERR_XEPG_UNKNOWN';
+        resolve(data);
+      });
     });
   }
 
   /**
-   * @param {string}
-   * @returns {object}
-   * @throws {Error}
+   * @param {string} 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: TXEpgContentProvider.saveToFileSync() => Error => '+err);
-          //console.log('CHECK: TXEpgContentProvider.saveToFileSync() => Error => '+err.code);
-          throw err;
-        };
-      };
+      //console.log('CHECK: TXEpgContentProvider.saveToFileSync() => Error => '+err);
+      //console.log('CHECK: TXEpgContentProvider.saveToFileSync() => Error => '+err.code);
+      data.errEvent = 'ERR_XEPG_UNKNOWN';
+    };
+    if (!data.isERR) {
+      data = saveToFileSync(source, data.content, null);
     };
     return data;
   }
 
-  loadFromXMLString(xmlString, opt) {
+  /**
+   * @param {string} xmlString - a document content in XML-format
+   * @returns {boolean}
+   * @throws {Error}
+   * @since 0.0.18
+   * @description Loads a document content from a string.
+   */
+  loadFromXMLString(xmlString) {
     let isSUCCEED = false;
     if (typeof xmlString === 'string') {
-      let _options = this.#_options;
-      let parseOptions = null;
-      if (isPlainObject(opt)) {
-        parseOptions = new TXmlContentParseOptions(opt);
-        // // TODO: init user options
-      } else {
-        parseOptions = _options.parseOptions;
-      };
+      const { parseOptions } = this.#_options;
       try {
         this.#_content = xmlParser.xml2js(xmlString, parseOptions.xml2js);
         // init a document header element
@@ -997,13 +1315,16 @@ class TXEpgContentProvider {
     return isSUCCEED;
   }
 
+  /**
+   * @deprecated
+   */
   loadFromString(...args){
     return this.loadFromXMLString(...args);
   }
 
   /**
-   * @param {string}
-   * @returns {object}
+   * @param {string} source - path to a file
+   * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
    * @description Loads a document content from a file.
@@ -1011,24 +1332,11 @@ class TXEpgContentProvider {
   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 {
@@ -1039,77 +1347,45 @@ class TXEpgContentProvider {
             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: TXEpgContentProvider.loadFromFile() => Error => '+err);
-            //console.log('CHECK: TXEpgContentProvider.loadFromFile() => Error => '+err.code);
-            reject(err);
-          };
-        });
-      };
+        };
+        resolve(data);
+      }).catch(err => {
+        //console.log('CHECK: TXEpgContentProvider.loadFromFile() => Error => '+err);
+        //console.log('CHECK: TXEpgContentProvider.loadFromFile() => Error => '+err.code);
+        reject(err);
+      });
     });
   }
 
   /**
-   * @param {string}
-   * @returns {object}
-   * @throws {Error}
+   * @param {string} source - path to a file
+   * @returns {fsoDescr}
    * @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: TXEpgContentProvider.loadFromFileSync() => Error => '+err);
-          //console.log('CHECK: TXEpgContentProvider.loadFromFileSync() => Error => '+err.code);
-          throw err;
+          data.errEvent = 'OPS_IS_FAILED';
         };
+      } else {
+        data.isERR = true;
+        data.errEvent = 'NO_CONTENT';
       };
     };
     return data;
   }
 
-  // will  deprecate
-  asXML(opt){
-    let parseOptions = isPlainObject(opt) ? opt : defParseOptions.js2xml;
-    return xmlParser.js2xml(this.#_content, parseOptions);
-  }
-
-  asJSON(){
+  /**
+   * @protected
+   */
+  asJSON() {
     return JSON.stringify(this.#_content, null, 2);
   }
 
@@ -1117,7 +1393,7 @@ class TXEpgContentProvider {
 
 // === module exports block ===
 
-exports.TXepgDTSProvider = TXepgDTSProvider;
+exports.TXEpgDTSProvider = TXEpgDTSProvider;
 exports.TXEpgSchedulesList = TXEpgSchedulesList;
 exports.TXEpgProviderContainer = TXEpgProviderContainer;
 exports.TXEpgHeaderContainer = TXEpgHeaderContainer;
@@ -1127,3 +1403,6 @@ exports.XEPG_DEF_PROVIDER_NAME = XEPG_DEF_PROVIDER_NAME;
 exports.XEPG_DEF_PROVIDER_VER = XEPG_DEF_PROVIDER_VER;
 exports.XEPG_DEF_DOCUMENT_TYPE = XEPG_DEF_DOCUMENT_TYPE;
 exports.XEPG_DEF_DOCUMENT_SCHEMA = XEPG_DEF_DOCUMENT_SCHEMA;
+
+/** @deprecated */
+exports.TXepgDTSProvider = TXEpgDTSProvider;