@ygracs/xepg-lib-js 0.0.20 → 0.0.22

package/lib/xepgdoc-lib.js

@@ -1,9 +1,7 @@
-// [v0.1.077-20241028]
+// [v0.2.098-20250306]
 
 // === module init block ===
 
-const fs = require('fs');
-const fse = require('fs').promises;
 const xmlParser = require('@ygracs/xml-js6');
 
 const {
@@ -15,15 +13,15 @@ const {
 
 const {
   convValueToTZString, convTZStringToValue,
+  tryDTValue,
 } = require('@ygracs/dtf-lib-js');
 
 const {
-  chkDTSysID, getDTSysName, getDTSysDescr,
+  chkDTSysID, getDTSysDescr,
   convStringToDTValue, convDTValueToString,
 } = require('./dts-helper.js');
 
 const {
-  checkFsError,
   loadFileSync, loadFile,
   saveToFileSync, saveToFile,
 } = require('./file-helper.js');
@@ -31,8 +29,10 @@ const {
 const xObj = require('@ygracs/xobj-lib-js');
 
 const TXmlContentParseOptions = xObj.TXmlContentParseOptions;
-const insertXObjElement = xObj.insertXObjElement;
-const getXObjElement = xObj.getXObjElement;
+const {
+  getXObjElement,
+  insertXObjElement,
+} = xObj;
 
 // === module extra block (helper functions) ===
 
@@ -58,18 +58,36 @@ function writeXObjAttr(obj, name, value) {
  * === xObj-function wrappers (end) ===
  */
 
-function _getXmlChildElementParam(obj, elem){
+/**
+ * @param {object} obj
+ * @param {string} elem
+ * @returns {string}
+ * @inner
+ */
+function _getXmlChildElementParam(obj, elem) {
   const child = obj ? getXObjElement(obj, elem) : null;
   return child ? readXObjParam(child) : '';
 };
 
-function writeXEpgDocDeclSection(obj, opt){
+/**
+ * @param {object} obj
+ * @returns {number}
+ * @inner
+ */
+function _getDTSTypeValueForXObj(obj) {
+  const result = valueToIndex(
+    _getXmlChildElementParam(obj, 'value')
+  );
+  return chkDTSysID(result) ? result : 0; //-1; // // TODO: [?]
+};
+
+function writeXEpgDocDeclSection(obj, opt) {
   let xml_ver = XEPG_XML_DOC_VERSION;
   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] = {};
@@ -84,6 +102,11 @@ function writeXEpgDocDeclSection(obj, opt){
  * (* constant definitions *)
  */
 
+/**
+ * A list of a document schema version supported by a library
+ */
+const ALLOWED_XEPG_DOCUMENT_SCHEMA = [ '0.2' ];
+
 const XEPG_ROOT_ETAG_NAME = 'epgdoc';
 const XEPG_DEF_NS_NAME = 'tvp';
 const XEPG_DEF_NS_PATH = 'urn:e-doc:epg-doc:xepg';
@@ -109,9 +132,9 @@ const XEPG_SCHEDDESC_ETAG_NAME = `${XEPG_DEF_NS_NAME}:desc`;
 const XEPG_XML_DOC_VERSION = '1.0';
 const XEPG_DEF_ENCODING_VALUE = 'UTF-8';
 const XEPG_DEF_DOCUMENT_TYPE = 'xepg';
-const XEPG_DEF_DOCUMENT_SCHEMA = '0.2';
+const XEPG_DEF_DOCUMENT_SCHEMA = ALLOWED_XEPG_DOCUMENT_SCHEMA[0];
 const XEPG_DEF_PROVIDER_NAME = 'xepg-lib-js';
-const XEPG_DEF_PROVIDER_VER = '0.0.15';
+const XEPG_DEF_PROVIDER_VER = '0.0.21';
 
 const defXEpgDocOptions = {
   xmlns_xepg_pref: XEPG_DEF_NS_NAME,
@@ -143,17 +166,275 @@ const defParseOptions = new TXmlContentParseOptions();
  */
 
 /**
- * @classdesc 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-schedule element
+ */
+class TXEpgScheduleItem {
+  /** @property {object} */
+  #_host;// = null;
+  /** @property {object} */
+  #_options;// = null;
+  /** @property {TXmlContentParseOptions} */
+  #_parseOptions;// = null;
+  /** @property {?object} */
+  #_dts_src = null;
+  /** @property {?object} */
+  #_tz_src = null;
+
+  /**
+   * @param {object} obj - host object
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @param {?object} [opt.dts_src]
+   * @param {?object} [opt.tz_src]
+   * @description Creates an instance of the EPG-schedule element
+   */
+  constructor(obj, opt) {
+    // load content
+    const _host = isPlainObject(obj) ? obj : {};
+    // load options
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      parseOptions,
+      dts_src, tz_src,
+    } = _options;
+    if (!(parseOptions instanceof TXmlContentParseOptions)) {
+      parseOptions = new TXmlContentParseOptions(parseOptions);
+      _options.parseOptions = parseOptions;
+    };
+    if (!isPlainObject(dts_src)) dts_src = null;
+    if (!isPlainObject(tz_src)) tz_src = null;
+    // save content source
+    this.#_host = _host;
+    // save options
+    this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // save refs to a time source priveders
+    this.#_dts_src = dts_src;
+    this.#_tz_src = tz_src;
+  }
+
+  /**
+   * Contains a dtstype ID
+   * @property {number}
+   * @readonly
+   */
+  get dtstype() {
+    return _getDTSTypeValueForXObj(this.#_dts_src);
+  }
+
+  /**
+   * Contains a TZ-offset
+   * @property {number}
+   * @readonly
+   */
+  get curDocTZ() {
+    return (
+      this.#_tz_src
+      ? convTZStringToValue(readXObjParam(this.#_tz_src).trim())
+      : 0
+    );
+  }
+
+  /**
+   * Contains a schedule start time as a timestamp
+   * @property {number}
+   * @readonly
+   */
+  get time() {
+    return convStringToDTValue(
+      _getXmlChildElementParam(this.#_host, XEPG_SCHEDTIME_ETAG_NAME).trim(),
+      this.dtstype, this.curDocTZ
+    );
+  }
+
+  /**
+   * Contains a schedule title
+   * @property {string}
+   * @readonly
+   */
+  get title() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDTITL_ETAG_NAME).trim();
+  }
+
+  /**
+   * Contains a schedule category
+   * @property {string}
+   * @readonly
+   */
+  get category() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDCAT_ETAG_NAME).trim();
+  }
+
+  /**
+   * Contains a schedule rating value (aka pcmark)
+   * @property {number}
+   * @readonly
+   */
+  get rating() {
+    return readAsNumberEx(
+      _getXmlChildElementParam(this.#_host, XEPG_SCHEDPMARK_ETAG_NAME), 0
+    );
+  }
+
+  /**
+   * Contains a schedule description
+   * @property {string}
+   * @readonly
+   */
+  get descr() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDDESC_ETAG_NAME);
+  }
+
+  /**
+   * @returns {xepgShedInfoDesc}
+   * @description Returns a schedule info item descriptor
+   */
+  getInfo() {
+    const {
+      time,
+      title,
+      category: cat,
+      rating: pcmark,
+      descr,
+    } = this;
+    return {
+      time,
+      title,
+      cat,
+      pcmark,
+      descr,
+    };
+  }
+
+  /**
+   * @param {(number|string|Date)} value - some time value
+   * @returns {boolean}
+   * @description Sets a schedule start time.
+   */
+  setTime(value) {
+    let { isSucceed, value: dtValue } = tryDTValue(value);
+    let result = false;
+    if (isSucceed) {
+      dtValue = convDTValueToString(dtValue, this.dtstype, this.curDocTZ);
+      if (dtValue !== '') {
+        const opt = { force: true };
+        const item = insertXObjElement(this.#_host, XEPG_SCHEDTIME_ETAG_NAME, opt);
+        if (item) result = writeXObjParam(item, dtValue);
+      };
+    };
+    return result;
+  }
+
+  /**
+   * @param {string} value - some title
+   * @returns {boolean}
+   * @description Sets a schedule title.
+   */
+  setTitle(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDTITL_ETAG_NAME, opt);
+      if (item) result = writeXObjParam(item, value.trim());
+    };
+    return result;
+  }
+
+  /**
+   * @param {string} value - some title
+   * @returns {boolean}
+   * @description Sets a schedule title.
+   */
+  setCategory(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDCAT_ETAG_NAME, opt);
+      if (item) result = writeXObjParam(item, value.trim());
+    };
+    return result;
+  }
+
+  /**
+   * @param {(number|string)} value - some value
+   * @returns {boolean}
+   * @description Sets a schedule rating value.
+   */
+  setRating(value) {
+    const _value = valueToIndex(value);
+    let result = false;
+    if (_value !== -1) {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDPMARK_ETAG_NAME, opt);
+      if (item) result = writeXObjParam(item, _value);
+    };
+    return result;
+  }
+
+  /**
+   * @param {string} value - some text
+   * @returns {boolean}
+   * @description Sets a schedule description.
+   */
+  setDescr(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDDESC_ETAG_NAME, opt);
+      if (item) result = writeXObjParam(item, value.trim());
+    };
+    return result;
+  }
+
+  /**
+   * @returns {string}
+   * @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_SCHED_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;
+  }
+
+};
+
+/**
+ * @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
-   * @param {object} [opt]
+   * @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
@@ -174,46 +455,41 @@ class TXEpgSchedulesList {
   }
 
   /**
-   * @param {(number|string)} value
-   * @returns {void}
+   * @param {(number|string)} value - element index
+   * @returns {any}
    * @private
+   * @description Returns a raw schedule element
    */
-  #_getItem = function(value){
+  #_getItem = function(value) {
     if (this.chkIndex(value)) {
       return this.#_content[Number(value)];
     };
   };
 
   /**
+   * Contains a quantity of a schedules
    * @property {number}
    * @readonly
-   * @description Contains a quantity of a schedules
    */
-  get schedQty(){
+  get schedQty() {
     return this.#_content.length;
   }
 
-  // will deprecate
-  //get SchedulesQty(){ return this.#_content.length; }
-
   /**
+   * Contains a dtstype ID
    * @property {number}
    * @readonly
-   * @description Contains a dtstype ID
    */
-  get dtstype(){
-    let result = valueToIndex(
-      _getXmlChildElementParam(this.#_dts_src, 'value')
-    );
-    return chkDTSysID(result) ? result : 0; //-1; // // TODO: [?]
+  get dtstype() {
+    return _getDTSTypeValueForXObj(this.#_dts_src);
   }
 
   /**
+   * Contains a TZ-offset
    * @property {number}
    * @readonly
-   * @description Contains a TZ-offset
    */
-  get curDocTZ(){
+  get curDocTZ() {
     return (
       this.#_tz_src
       ? convTZStringToValue(readXObjParam(this.#_tz_src).trim())
@@ -225,7 +501,7 @@ class TXEpgSchedulesList {
    * @returns {boolean}
    * @description Indicates whether an instance has none member
    */
-  hasNoSchedules(){
+  hasNoSchedules() {
     return this.schedQty === 0;
   }
 
@@ -233,7 +509,7 @@ class TXEpgSchedulesList {
    * @returns {boolean}
    * @description Indicates whether an instance has any member
    */
-  hasSchedules(){
+  hasSchedules() {
     return this.schedQty > 0;
   }
 
@@ -243,15 +519,17 @@ class TXEpgSchedulesList {
    * @deprecated
    * @description Checks whether a given value is a valid index
    *              and it fits the index range of an instance
+   * @done [since v0.0.20] deprecated
+   * @todo [from v0.0.23] will be removed
    */
   chkScheduleIndex(value) {
     return this.chkIndex(value);
   }
 
   /**
-   * @param {(number|string)} value
+   * @param {(number|string)} value - index of some element
    * @returns {boolean}
-   * @since 0.0.18
+   * @since 0.0.20
    * @description Checks whether a given value is a valid index
    *              and it fits the index range of an instance
    */
@@ -261,44 +539,39 @@ class TXEpgSchedulesList {
   }
 
   /**
-   * @param {(number|string)} index
-   * @returns {object}
+   * @param {(number|string)} index - index of some element
+   * @returns {?TXEpgScheduleItem}
+   * @since 0.0.22
+   * @description Returns a schedule element addressed by a given index
+   */
+  schedule(index) {
+    const curObj = this.#_getItem(index);
+    let item = null;
+    if (isPlainObject(curObj)) {
+      item = new TXEpgScheduleItem(curObj, {
+        dts_src: this.#_dts_src,
+        tz_src: this.#_tz_src,
+      });
+    };
+    return item;
+  }
+
+  /**
+   * @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 = {};
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+']');
-    //console.log('TXEpgSchedulesList => getScheduleInfo('+index+') => '+JSON.stringify(curObj, null, 2));
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+'] - [time]');
-    tmpObj.time = convStringToDTValue(
-      _getXmlChildElementParam(curObj, XEPG_SCHEDTIME_ETAG_NAME).trim(),
-      this.dtstype, this.curDocTZ
-    );
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+'] - [title]');
-    tmpObj.title = _getXmlChildElementParam(curObj, XEPG_SCHEDTITL_ETAG_NAME).trim();
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+'] - [category]');
-    tmpObj.cat = _getXmlChildElementParam(curObj, XEPG_SCHEDCAT_ETAG_NAME).trim();
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+'] - [pcmark]');
-    tmpObj.pcmark = readAsNumberEx(
-      _getXmlChildElementParam(curObj, XEPG_SCHEDPMARK_ETAG_NAME), 0
-    );
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => index:['+index+'] - [description]');
-    tmpObj.descr = _getXmlChildElementParam(curObj, XEPG_SCHEDDESC_ETAG_NAME);
-    //console.log('TXEpgSchedulesList => getScheduleInfo('+index+') => '+JSON.stringify(curObj, null, 2));
-    //console.log('TXEpgSchedulesList => getScheduleInfo('+index+') => '+JSON.stringify(tmpObj, null, 2));
-    // TODO: wrap tmpObj into container object
-    //console.log('TXEpgSchedulesList => getScheduleInfo() => was left...');
-    return tmpObj;
+  getScheduleInfo(index) {
+    const obj = this.schedule(index);
+    return obj ? obj.getInfo() : null;
   }
 
   /**
-   * @returns {object[]}
+   * @returns {xepgShedInfoDesc[]}
    * @description Returns a schedule info for instance members
    */
-  getAllSchedulesInfo(){
+  getAllSchedulesInfo() {
     let result = [];
     for (let i = 0; i < this.schedQty; i++) {
       let item = this.getScheduleInfo(i);
@@ -307,27 +580,39 @@ class TXEpgSchedulesList {
     return result;
   }
 
-  asJSON(){
+  /**
+   * @protected
+   */
+  asJSON() {
     return JSON.stringify(this.#_content, null, 2);
   }
 
 };
 
 /**
- * @classdesc 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 {
   /** @property {Object} */
   #_host;// = null;
   /** @property {Object} */
   #_options;// = null;
-  /** @property {?TXmlContentParseOptions} */
+  /** @property {TXmlContentParseOptions} */
   #_parseOptions;// = null;
-  /** @property {?TXepgDTSProvider} */
+  /** @property {?TXEpgDTSProvider} */
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
+   * @param {object} obj - host object
+   * @param {object} [opt] - options
    * @param {object} [opt.parseOptions]
    * @description Creates an instance of the EPG-provider element
    */
@@ -366,8 +651,8 @@ class TXEpgProviderContainer {
   }
 
   /**
+   * Contains a provider name
    * @property {string}
-   * @description Contains a provider name
    */
   get name() {
     return _getXmlChildElementParam(this.#_host, 'name').trim();
@@ -378,8 +663,8 @@ class TXEpgProviderContainer {
   }
 
   /**
+   * Contains a version of a provider
    * @property {string}
-   * @description Contains a version of a provider
    */
   get version() {
     return _getXmlChildElementParam(this.#_host, 'version').trim();
@@ -394,8 +679,8 @@ class TXEpgProviderContainer {
   }
 
   /**
+   * Contains a version of a document schema
    * @property {string}
-   * @description Contains a version of a document schema
    */
   get schema() {
     return _getXmlChildElementParam(this.#_host, XEPG_DOCSCH_ETAG_NAME).trim();
@@ -410,8 +695,8 @@ class TXEpgProviderContainer {
   }
 
   /**
+   * Contains a document type
    * @property {string}
-   * @description Contains a document type
    */
   get doctype() {
     return _getXmlChildElementParam(this.#_host, XEPG_DOCTYP_ETAG_NAME).trim();
@@ -440,15 +725,6 @@ class TXEpgProviderContainer {
     return isSucceed;
   }
 
-  /**
-   * @typedef {Object} xepgProvInfoDesc
-   * @property {string} name - provider name
-   * @property {string} version - provider version
-   * @property {string} schema - document schema
-   * @property {string} doctype - document type
-   * @description Contains a provider description
-   */
-
   /**
    * @returns {xepgProvInfoDesc}
    * @description Returns a provider info item
@@ -463,22 +739,25 @@ class TXEpgProviderContainer {
   }
 
   /**
-   * @param {object} 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){
+  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);
@@ -497,11 +776,11 @@ class TXEpgProviderContainer {
   }
 
   /**
-   * @param {object|string[]} opt
+   * @param {(xepgProvInfoDesc|string[])} opt - options
    * @returns {void}
    * @description Sets an initial instance state
    */
-  init(opt){
+  init(opt) {
     let prov_opt = { ...defXEpgDocOptions.defProviderParam };
     let name = '';
     let version = '';
@@ -547,15 +826,224 @@ class TXEpgProviderContainer {
 };
 
 /**
- * @classdesc This class implements an instance of a DTS-provider 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
  */
-class TXepgDTSProvider {
-  #_content = null;
-  #_options = null;
+
+/**
+ * @classdesc This class implements an interface of a channel element
+ */
+class TXEpgChannelContainer {
+  /** @property {object} */
+  #_host;// = null;
+  /** @property {object} */
+  #_options;// = null;
+  /** @property {TXmlContentParseOptions} */
+  #_parseOptions;// = null;
+  /** @property {string} */
+  #_xepgSchema;// = null;
 
   /**
-   * @param {object} obj
-   * @param {object} [opt]
+   * @param {object} obj - host object
+   * @param {object} [opt] - options
+   * @param {object} [opt.parseOptions]
+   * @description Creates an instance of the channel element
+   */
+  constructor(obj, opt) {
+    // load content
+    const _host = isPlainObject(obj) ? obj : {};
+    // load options
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      parseOptions,
+    } = _options;
+    if (!(parseOptions instanceof TXmlContentParseOptions)) {
+      parseOptions = new TXmlContentParseOptions(parseOptions);
+      _options.parseOptions = parseOptions;
+    };
+    // set document schema version
+    this.#_xepgSchema = XEPG_DEF_DOCUMENT_SCHEMA;
+    // save options
+    this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // save content source
+    this.#_host = _host;
+  }
+
+  /**
+   * Contains a channel ID
+   * @returns {string}
+   * @readonly
+   */
+  get id() {
+    return _getXmlChildElementParam(this.#_host, XEPG_CHNID_ETAG_NAME).trim();
+  }
+
+  /**
+   * Contains a channel name
+   * @returns {string}
+   */
+  get name() {
+    return _getXmlChildElementParam(this.#_host, XEPG_CHNNAME_ETAG_NAME).trim();
+  }
+
+  set name(value) {
+    if (typeof value === 'string' && this.id !== '') {
+      const item = insertXObjElement(
+        this.#_host,
+        XEPG_CHNNAME_ETAG_NAME,
+        { force: true },
+      );
+      if (item) writeXObjParam(item, value.trim());
+    };
+  }
+
+  /**
+   * Contains a channel Group ID
+   * @returns {string}
+   */
+  get gid() {
+    return _getXmlChildElementParam(this.#_host, XEPG_CHNGID_ETAG_NAME).trim();
+  }
+
+  set gid(value) {
+    if (typeof value === 'string' && this.id !== '') {
+      const item = insertXObjElement(
+        this.#_host,
+        XEPG_CHNGID_ETAG_NAME,
+        { force: true },
+      );
+      if (item) writeXObjParam(item, value.trim());
+    };
+  }
+
+  /**
+   * Contains a channel source URL
+   * @returns {string}
+   */
+  get url() {
+    return _getXmlChildElementParam(this.#_host, XEPG_CHNURL_ETAG_NAME).trim();
+  }
+
+  set url(value) {
+    if (typeof value === 'string' && this.id !== '') {
+      const item = insertXObjElement(
+        this.#_host,
+        XEPG_CHNURL_ETAG_NAME,
+        { force: true },
+      );
+      if (item) writeXObjParam(item, value.trim());
+    };
+  }
+
+  /**
+   * @param {string} value - channel ID
+   * @returns {boolean}
+   * @description Tries to set a channel ID
+   */
+  setID(value) {
+    let isSucceed = false;
+    if (typeof value === 'string') {
+      const chnid = value.trim();
+      const item = insertXObjElement(
+        this.#_host,
+        XEPG_CHNID_ETAG_NAME,
+        { force: true },
+      );
+      if (item) {
+        isSucceed = writeXObjParam(item, chnid);
+      };
+    };
+    return isSucceed;
+  }
+
+  /**
+   * @returns {xepgChnInfoDesc}
+   * @description Returns a channel info
+   */
+  getInfo() {
+    const {
+      id: chnid,
+      name: chname,
+      gid: chngid,
+      url: srcurl,
+    } = this;
+    /** @type {xepgChnInfoDesc} */
+    return {
+      chnid,
+      chname,
+      chngid,
+      srcurl,
+    };
+  }
+
+  /**
+   * @param {(string|xepgChnInfoDesc)} obj - channel info descriptor
+   * @returns {void}
+   * @description Sets a channel info
+   */
+  setInfo(obj) {
+    let chnid = '';
+    let chname = '';
+    let chngid = '';
+    let srcurl = '';
+    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();
+        srcurl = _getXmlChildElementParam(obj, XEPG_CHNURL_ETAG_NAME).trim();
+      };
+    } else if (typeof obj === 'string') {
+      chnid = obj;
+    } else {
+      return;
+    };
+    chnid = typeof chnid === 'string' ? chnid.trim() : '';
+    if (chnid === '') {
+      chname = '';
+      chngid = '';
+      srcurl = '';
+    } else {
+      chname = typeof chname === 'string' ? chname.trim() : '';
+      chngid = typeof chngid === 'string' ? chngid.trim() : '';
+      srcurl = typeof srcurl === 'string' ? srcurl.trim() : '';
+    };
+    let item = null;
+    const _host = this.#_host;
+    item = insertXObjElement(_host, XEPG_CHNID_ETAG_NAME, { force: true });
+    if (item) writeXObjParam(item, chnid);
+    item = insertXObjElement(_host, XEPG_CHNNAME_ETAG_NAME, { force: true });
+    if (item) writeXObjParam(item, chname);
+    item = insertXObjElement(_host, XEPG_CHNGID_ETAG_NAME, { force: true });
+    if (item) writeXObjParam(item, chngid);
+    item = insertXObjElement(_host, XEPG_CHNURL_ETAG_NAME, { force: true });
+    if (item) writeXObjParam(item, srcurl);
+  }
+
+}
+
+/**
+ * @classdesc This class implements an interface of a DTS-provider element
+ */
+class TXEpgDTSProvider {
+  /** @property {object} */
+  #_content;// = null;
+  /** @property {object} */
+  #_options;// = null;
+
+  /**
+   * @param {object} obj - host object
+   * @param {object} [opt] - options
    * @param {object} [opt.parseOptions]
    * @description Creates an instance of the DTS-provider element
    */
@@ -583,57 +1071,37 @@ class TXepgDTSProvider {
    * @returns {void}
    * @private
    */
-  #_init(){
+  #_init() {
     insertXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
   }
 
   /**
+   * Contains a dtstype ID
    * @property {number}
-   * @description Contains a dtstype ID
    */
-  get dtstype(){
+  get dtstype() {
     const item = getXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
     let result = 0; //-1; // // TODO: [?]
-    if (isPlainObject(item)) {
-      result = valueToIndex(_getXmlChildElementParam(item, 'value'));
-      if (!chkDTSysID(result)) result = 0; //-1; // // TODO: [?]
-    };
+    if (isPlainObject(item)) result = _getDTSTypeValueForXObj(item);
     return result;
   }
 
-  set dtstype(value){
-    let { index, name } = getDTSysDescr(value);
-    if (index !== -1) {
-      const item = insertXObjElement(
-        this.#_content,
-        XEPG_DTSINFO_ETAG_NAME,
-        { force: true },
-      );
-      if (item) {
-        let curItem = insertXObjElement(item, 'value', { force: true });
-        if (
-          curItem
-          && writeXObjParam(curItem, index)
-          && (curItem = insertXObjElement(item, 'name', { force: true }))
-        ) {
-          writeXObjParam(curItem, name);
-        };
-      };
-    };
+  set dtstype(value) {
+    return this.setType(value);
   }
 
   /**
+   * Contains a TZ-offset
    * @property {number}
-   * @description Contains a TZ-offset
    */
-  get curDocTZ(){
+  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(
@@ -645,24 +1113,53 @@ class TXepgDTSProvider {
     };
   }
 
+  /**
+   * @since 0.0.22
+   * @property {(number|string)} value - dtstype ID
+   * @returns {boolean}
+   * @description Tries to set a `DTS`-type
+   */
+  setType(value) {
+    let { index, name } = getDTSysDescr(value);
+    let isSucceed = false;
+    if (index !== -1) {
+      const item = insertXObjElement(
+        this.#_content,
+        XEPG_DTSINFO_ETAG_NAME,
+        { force: true },
+      );
+      if (item) {
+        let curItem = insertXObjElement(item, 'value', { force: true });
+        if (
+          curItem
+          && writeXObjParam(curItem, index)
+          && (curItem = insertXObjElement(item, 'name', { force: true }))
+        ) {
+          isSucceed = writeXObjParam(curItem, name);
+        };
+      };
+    };
+    return isSucceed;
+  }
+
 };
 
 /**
- * @classdesc This class implements an instance of a EPG-header element
+ * @classdesc This class implements an interface of a EPG-header element
  */
 class TXEpgHeaderContainer {
   /** @property {Object} */
   #_host;// = null;
   /** @property {Object} */
   #_options;// = null;
-  /** @property {?TXmlContentParseOptions} */
+  /** @property {TXmlContentParseOptions} */
   #_parseOptions;// = null;
-  /** @property {?TXepgDTSProvider} */
+  /** @property {TXEpgDTSProvider} */
   #_dtsProv;// = null;
 
   /**
    * @param {object} obj
-   * @param {object} [opt]
+   * @param {object} [opt] - options
    * @param {object} [opt.parseOptions]
    * @description Creates an instance of the EPG-header element
    */
@@ -685,39 +1182,41 @@ class TXEpgHeaderContainer {
     // save content source
     this.#_host = _host;
     // init DTS-provider
-    this.#_dtsProv = new TXepgDTSProvider(_host, _options);
+    this.#_dtsProv = new TXEpgDTSProvider(_host, _options);
   }
 
   /**
-   * @property {TXepgDTSProvider}
+   * Returns a `TXEpgDTSProvider` instance
+   * @property {TXEpgDTSProvider}
    * @readonly
-   * @description Returns a `TXepgDTSProvider` instance
    */
-  get dts(){
+  get dts() {
     return this.#_dtsProv;
   }
 
   /**
+   * Contains a dtstype ID
    * @property {number}
-   * @description Contains a dtstype ID
+   * @todo [since v0.0.22] becomes readonly
    */
-  get dtstype(){
+  get dtstype() {
     return this.#_dtsProv.dtstype;
   }
 
-  set dtstype(value){
+  set dtstype(value) {
     this.#_dtsProv.dtstype = value;
   }
 
   /**
+   * Contains a TZ-offset
    * @property {number}
-   * @description Contains a TZ-offset
+   * @todo [since v0.0.22] becomes readonly
    */
-  get curDocTZ(){
+  get curDocTZ() {
     return this.#_dtsProv.curDocTZ;
   }
 
-  set curDocTZ(value){
+  set curDocTZ(value) {
     this.#_dtsProv.curDocTZ = value;
   }
 
@@ -744,11 +1243,22 @@ class TXEpgHeaderContainer {
   }
 
   /**
+   * Returns a `TXEpgProviderContainer` instance
+   * @property {?TXEpgProviderContainer}
+   * @readonly
+   * @deprecated
+   */
+  get Provider() {
+    return this.provider;
+  }
+
+  /**
+   * Returns a `TXEpgProviderContainer` instance
+   * @since 0.0.22
    * @property {?TXEpgProviderContainer}
    * @readonly
-   * @description Returns a `TXEpgProviderContainer` instance
    */
-  get Provider(){
+  get provider() {
     const docProv = this.#_getProv();
     return (
       docProv
@@ -757,6 +1267,16 @@ class TXEpgHeaderContainer {
     );
   }
 
+  /**
+   * Returns a `TXEpgChannelContainer` instance
+   * @since 0.0.22
+   * @property {?TXEpgChannelContainer}
+   * @readonly
+   */
+  get channel() {
+    return new TXEpgChannelContainer(this.#_host, this.#_options);
+  }
+
   /**
    * @returns {number}
    * @description Returns a document creation date as a timestamp
@@ -798,7 +1318,7 @@ class TXEpgHeaderContainer {
   }
 
   /**
-   * @param {any} value
+   * @param {any} value - document expire date
    * @returns {void}
    * @description Sets a document expire date to a given time
    */
@@ -813,100 +1333,52 @@ class TXEpgHeaderContainer {
     if (item) writeXObjParam(item, dt_str);
   }
 
-  /**
-   * @typedef {Object} xepgChnInfoDesc
-   * @property {string} chnid - channel ID
-   * @property {string} chngid - channel 'Group ID'
-   * @property {string} chname - channel name
-   * @property {string} srcurl - EPG-source URL
-   * @description Contains a channel description
-   */
-
   /**
    * @returns {xepgChnInfoDesc}
    * @description Returns a channel info
    */
   getChannelInfo() {
-    const _host = this.#_host;
-    /** @type {xepgChnInfoDesc} */
-    let item = {
-      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;
+    return this.channel.getInfo();
   }
 
   /**
-   * @param {object} obj
+   * @param {xepgChnInfoDesc} obj - channel info descriptor
    * @returns {void}
    * @description Sets a channel info
+   * @deprecated
+   * @todo [since v0.0.21] deprecate use of `obj`-param as array
+   * @todo [since v0.0.22] deprecated
    */
-  setChannelInfo(obj){
-    let chnid = '';
-    let chname = '';
-    let chngid = '';
-    let srcurl = '';
+  setChannelInfo(obj) {
+    let _obj = obj;
     if (isArray(obj)) {
-      [ chnid, chname, chngid, srcurl ] = obj;
-    } else if (isObject(obj)) {
-      ({ chnid } = obj);
-      if (typeof chnid === 'string') {
-        ({ chname, chngid, srcurl } = obj);
-      } else {
-        chnid = _getXmlChildElementParam(obj, XEPG_CHNID_ETAG_NAME).trim();
-        chname = _getXmlChildElementParam(obj, XEPG_CHNNAME_ETAG_NAME).trim();
-        chngid = _getXmlChildElementParam(obj, XEPG_CHNGID_ETAG_NAME).trim();
-        srcurl = _getXmlChildElementParam(obj, XEPG_CHNURL_ETAG_NAME).trim();
-      };
-    } else if (typeof obj === 'string') {
-      chnid = obj;
-    } else {
-      return;
-    };
-    chnid = typeof chnid === 'string' ? chnid.trim() : '';
-    if (chnid === '') {
-      chname = '';
-      chngid = '';
-      srcurl = '';
-    } else {
-      chname = typeof chname === 'string' ? chname.trim() : '';
-      chngid = typeof chngid === 'string' ? chngid.trim() : '';
-      srcurl = typeof srcurl === 'string' ? srcurl.trim() : '';
+      // // TODO: [!] deprecate
+      const [ chnid, chname, chngid, srcurl ] = _obj;
+      _obj = { chnid, chname, chngid, srcurl };
     };
-    let item = null;
-    const _host = this.#_host;
-    item = insertXObjElement(_host, XEPG_CHNID_ETAG_NAME, { force: true });
-    if (item) writeXObjParam(item, chnid);
-    item = insertXObjElement(_host, XEPG_CHNNAME_ETAG_NAME, { force: true });
-    if (item) writeXObjParam(item, chname);
-    item = insertXObjElement(_host, XEPG_CHNGID_ETAG_NAME, { force: true });
-    if (item) writeXObjParam(item, chngid);
-    item = insertXObjElement(_host, XEPG_CHNURL_ETAG_NAME, { force: true });
-    if (item) writeXObjParam(item, srcurl);
+    return this.channel.setInfo(_obj);
   }
 
   /**
-   * @returns {?object}
+   * @returns {?xepgProvInfoDesc}
    * @description Returns a provider info
    */
   getProviderInfo(){
-    const docProv = this.Provider;
+    const docProv = this.provider;
     return docProv ? docProv.getInfo() : null;
   }
 
   /**
-   * @param {object} obj
+   * @param {xepgProvInfoDesc} obj - provider info descriptor
    * @returns {void}
    * @description Sets a provider info
    */
   setProviderInfo(obj){
     if (isArray(obj) || isObject(obj)) {
-      let docProv = this.Provider;
+      let docProv = this.provider;
       if (!docProv) {
         docProv = this.#_initProv();
-        if (docProv) docProv = this.Provider;
+        if (docProv) docProv = this.provider;
       };
       if (docProv) docProv.setInfo(obj);
     };
@@ -935,6 +1407,17 @@ class TXEpgHeaderContainer {
 
 };
 
+/**
+ * @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
@@ -948,7 +1431,7 @@ class TXEpgContentProvider {
   #_parseOptions;// = null;
 
   /**
-   * @param {object} [opt]
+   * @param {object} [opt] - options
    * @param {object} [opt.parseOptions]
    * @param {boolean} [opt.autoBindRoot] - <*reserved*> ([?] - deprecate)
    * @description Creates an instance of the XEPG-content provider
@@ -988,7 +1471,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initRoot(){
+  #_initRoot() {
     const _content = this.#_content;
     let docRoot = getXObjElement(_content, XEPG_ROOT_ETAG_NAME);
     if (!docRoot) {
@@ -1017,7 +1500,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initHdr(){
+  #_initHdr() {
     let docHdr = this.#_getHdr();
     if (!docHdr) {
       let docRoot = this.#_getRoot();
@@ -1046,7 +1529,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initBody(){
+  #_initBody() {
     let docBody = this.#_getBody();
     if (!docBody) {
       let docRoot = this.#_getRoot();
@@ -1059,9 +1542,10 @@ class TXEpgContentProvider {
   }
 
   /**
+   * Returns a `TXEpgHeaderContainer` instance
    * @property {?TXEpgHeaderContainer}
    * @readonly
-   * @description Returns a `TXEpgHeaderContainer` instance
+   * @deprecated
    */
   get Header() {
     const docHdr = this.#_getHdr();
@@ -1073,22 +1557,49 @@ class TXEpgContentProvider {
   }
 
   /**
+   * Returns a `TXEpgHeaderContainer` instance
+   * @since 0.0.22
+   * @property {?TXEpgHeaderContainer}
+   * @readonly
+   */
+  get header() {
+    const docHdr = this.#_getHdr();
+    return (
+      docHdr
+      ? new TXEpgHeaderContainer(docHdr, this.#_options)
+      : null
+    );
+  }
+
+  /**
+   * Returns a `TXEpgProviderContainer` instance
+   * @property {?TXEpgProviderContainer}
+   * @readonly
+   * @deprecated
+   */
+  get Provider() {
+    const docHdr = this.header;
+    return docHdr ? docHdr.provider : null;
+  }
+
+  /**
+   * Returns a `TXEpgProviderContainer` instance
+   * @since 0.0.22
    * @property {?TXEpgProviderContainer}
    * @readonly
-   * @description Returns a `TXEpgProviderContainer` instance
    */
-  get Provider(){
-    const docHdr = this.Header;
-    return docHdr ? docHdr.Provider : null;
+  get provider() {
+    const docHdr = this.header;
+    return docHdr ? docHdr.provider : null;
   }
 
   /**
-   * @property {?TXepgDTSProvider}
+   * Returns a `TXEpgDTSProvider` instance
+   * @property {?TXEpgDTSProvider}
    * @readonly
-   * @description Returns a `TXepgDTSProvider` instance
    */
-  get dts(){
-    const docHdr = this.Header;
+  get dts() {
+    const docHdr = this.header;
     return docHdr ? docHdr.dts : null;
   }
 
@@ -1099,11 +1610,11 @@ class TXEpgContentProvider {
   get Content(){ return this; }
 
   /**
+   * Returns a `TXEpgSchedulesList` instance
    * @property {TXEpgSchedulesList}
    * @readonly
-   * @description Returns a `TXEpgSchedulesList` instance
    */
-  get SchedulesList(){
+  get SchedulesList() {
     const _options = this.#_options;
     const docBody = this.#_getBody();
     if (docBody && isArray(docBody[XEPG_SCHED_ETAG_NAME])) {
@@ -1121,7 +1632,7 @@ class TXEpgContentProvider {
   /**
    * @returns {void}
    */
-  init(){
+  init() {
     const _options = this.#_options;
     const _content = this.#_content;
     const {
@@ -1145,7 +1656,7 @@ class TXEpgContentProvider {
         docHdr,
         XEPG_PRVINFO_ETAG_NAME,
       );
-      if (docProv) this.Provider.init();
+      if (docProv) this.provider.init();
       // initiate document body element
       let docBody = this.#_getBody();
       if (!docBody) docBody = this.#_initBody();
@@ -1172,20 +1683,9 @@ class TXEpgContentProvider {
     return result;
   }
 
-  /**
-   * @typedef {Object} fsoDescr
-   * @property {boolean} isERR - flag
-   * @property {number|undefined} 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.
-   */
-
   /**
    * @param {string} source - a path to a file
-   * @returns {fsoDescr}
+   * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
    * @description Saves a document content to a file.
@@ -1299,7 +1799,7 @@ class TXEpgContentProvider {
 
   /**
    * @param {string} source - path to a file
-   * @returns {fsoDescr}
+   * @returns {Promise<fsoDescr, Error>}
    * @throws {Error}
    * @async
    * @description Loads a document content from a file.
@@ -1357,19 +1857,10 @@ class TXEpgContentProvider {
     return data;
   }
 
-  // will  deprecate
-  /**
-   * @deprecated
-   */
-  asXML(opt){
-    let parseOptions = isPlainObject(opt) ? opt : defParseOptions.js2xml;
-    return xmlParser.js2xml(this.#_content, parseOptions);
-  }
-
   /**
    * @protected
    */
-  asJSON(){
+  asJSON() {
     return JSON.stringify(this.#_content, null, 2);
   }
 
@@ -1377,13 +1868,18 @@ class TXEpgContentProvider {
 
 // === module exports block ===
 
-exports.TXepgDTSProvider = TXepgDTSProvider;
-exports.TXEpgSchedulesList = TXEpgSchedulesList;
-exports.TXEpgProviderContainer = TXEpgProviderContainer;
-exports.TXEpgHeaderContainer = TXEpgHeaderContainer;
-exports.TXEpgContentProvider = TXEpgContentProvider;
-
-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;
+module.exports.TXEpgDTSProvider = TXEpgDTSProvider;
+module.exports.TXEpgScheduleItem = TXEpgScheduleItem;
+module.exports.TXEpgSchedulesList = TXEpgSchedulesList;
+module.exports.TXEpgProviderContainer = TXEpgProviderContainer;
+module.exports.TXEpgChannelContainer = TXEpgChannelContainer;
+module.exports.TXEpgHeaderContainer = TXEpgHeaderContainer;
+module.exports.TXEpgContentProvider = TXEpgContentProvider;
+
+module.exports.XEPG_DEF_PROVIDER_NAME = XEPG_DEF_PROVIDER_NAME;
+module.exports.XEPG_DEF_PROVIDER_VER = XEPG_DEF_PROVIDER_VER;
+module.exports.XEPG_DEF_DOCUMENT_TYPE = XEPG_DEF_DOCUMENT_TYPE;
+module.exports.XEPG_DEF_DOCUMENT_SCHEMA = XEPG_DEF_DOCUMENT_SCHEMA;
+
+/** @deprecated */
+module.exports.TXepgDTSProvider = TXEpgDTSProvider;