@ygracs/xepg-lib-js 0.0.20 → 0.0.21

package/lib/xepgdoc-lib.js

@@ -1,9 +1,7 @@
-// [v0.1.077-20241028]
+// [v0.1.081-20250227]
 
 // === module init block ===
 
-const fs = require('fs');
-const fse = require('fs').promises;
 const xmlParser = require('@ygracs/xml-js6');
 
 const {
@@ -18,12 +16,11 @@ const {
 } = 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');
@@ -68,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] = {};
@@ -143,17 +140,31 @@ 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-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,22 +185,23 @@ 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;
   }
 
@@ -197,11 +209,11 @@ class TXEpgSchedulesList {
   //get SchedulesQty(){ return this.#_content.length; }
 
   /**
+   * Contains a dtstype ID
    * @property {number}
    * @readonly
-   * @description Contains a dtstype ID
    */
-  get dtstype(){
+  get dtstype() {
     let result = valueToIndex(
       _getXmlChildElementParam(this.#_dts_src, 'value')
     );
@@ -209,11 +221,11 @@ class TXEpgSchedulesList {
   }
 
   /**
+   * 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 +237,7 @@ class TXEpgSchedulesList {
    * @returns {boolean}
    * @description Indicates whether an instance has none member
    */
-  hasNoSchedules(){
+  hasNoSchedules() {
     return this.schedQty === 0;
   }
 
@@ -233,7 +245,7 @@ class TXEpgSchedulesList {
    * @returns {boolean}
    * @description Indicates whether an instance has any member
    */
-  hasSchedules(){
+  hasSchedules() {
     return this.schedQty > 0;
   }
 
@@ -249,7 +261,7 @@ class TXEpgSchedulesList {
   }
 
   /**
-   * @param {(number|string)} 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
@@ -261,12 +273,12 @@ class TXEpgSchedulesList {
   }
 
   /**
-   * @param {(number|string)} index
-   * @returns {object}
+   * @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){
+  getScheduleInfo(index) {
     //console.log('TXEpgSchedulesList => getScheduleInfo() => was called...');
     const curObj = this.#_getItem(index);
     let tmpObj = {};
@@ -295,10 +307,10 @@ class TXEpgSchedulesList {
   }
 
   /**
-   * @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 +319,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} [opt] - options
    * @param {object} [opt.parseOptions]
    * @description Creates an instance of the EPG-provider element
    */
@@ -366,8 +390,8 @@ class TXEpgProviderContainer {
   }
 
   /**
+   * Contains a provider name
    * @property {string}
-   * @description Contains a provider name
    */
   get name() {
     return _getXmlChildElementParam(this.#_host, 'name').trim();
@@ -378,8 +402,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 +418,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 +434,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 +464,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 +478,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 +515,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 = '';
@@ -549,13 +567,15 @@ class TXEpgProviderContainer {
 /**
  * @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]
+   * @param {object} [opt] - options
    * @param {object} [opt.parseOptions]
    * @description Creates an instance of the DTS-provider element
    */
@@ -583,15 +603,15 @@ 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)) {
@@ -601,7 +621,7 @@ class TXepgDTSProvider {
     return result;
   }
 
-  set dtstype(value){
+  set dtstype(value) {
     let { index, name } = getDTSysDescr(value);
     if (index !== -1) {
       const item = insertXObjElement(
@@ -623,17 +643,17 @@ class TXepgDTSProvider {
   }
 
   /**
+   * 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(
@@ -647,6 +667,15 @@ class TXepgDTSProvider {
 
 };
 
+/**
+ * @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
  */
@@ -655,14 +684,14 @@ class TXEpgHeaderContainer {
   #_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 +714,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;
   }
 
@@ -748,7 +779,7 @@ class TXEpgHeaderContainer {
    * @readonly
    * @description Returns a `TXEpgProviderContainer` instance
    */
-  get Provider(){
+  get Provider() {
     const docProv = this.#_getProv();
     return (
       docProv
@@ -798,7 +829,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,15 +844,6 @@ 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
@@ -839,22 +861,25 @@ class TXEpgHeaderContainer {
   }
 
   /**
-   * @param {object} 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){
+  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();
@@ -888,7 +913,7 @@ class TXEpgHeaderContainer {
   }
 
   /**
-   * @returns {?object}
+   * @returns {?xepgProvInfoDesc}
    * @description Returns a provider info
    */
   getProviderInfo(){
@@ -897,7 +922,7 @@ class TXEpgHeaderContainer {
   }
 
   /**
-   * @param {object} obj
+   * @param {xepgProvInfoDesc} obj - provider info descriptor
    * @returns {void}
    * @description Sets a provider info
    */
@@ -935,6 +960,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 +984,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 +1024,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initRoot(){
+  #_initRoot() {
     const _content = this.#_content;
     let docRoot = getXObjElement(_content, XEPG_ROOT_ETAG_NAME);
     if (!docRoot) {
@@ -1017,7 +1053,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initHdr(){
+  #_initHdr() {
     let docHdr = this.#_getHdr();
     if (!docHdr) {
       let docRoot = this.#_getRoot();
@@ -1046,7 +1082,7 @@ class TXEpgContentProvider {
    * @returns {?object}
    * @private
    */
-  #_initBody(){
+  #_initBody() {
     let docBody = this.#_getBody();
     if (!docBody) {
       let docRoot = this.#_getRoot();
@@ -1059,9 +1095,9 @@ class TXEpgContentProvider {
   }
 
   /**
+   * Returns a `TXEpgHeaderContainer` instance
    * @property {?TXEpgHeaderContainer}
    * @readonly
-   * @description Returns a `TXEpgHeaderContainer` instance
    */
   get Header() {
     const docHdr = this.#_getHdr();
@@ -1073,21 +1109,21 @@ class TXEpgContentProvider {
   }
 
   /**
+   * Returns a `TXEpgProviderContainer` instance
    * @property {?TXEpgProviderContainer}
    * @readonly
-   * @description Returns a `TXEpgProviderContainer` instance
    */
-  get Provider(){
+  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(){
+  get dts() {
     const docHdr = this.Header;
     return docHdr ? docHdr.dts : null;
   }
@@ -1099,11 +1135,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 +1157,7 @@ class TXEpgContentProvider {
   /**
    * @returns {void}
    */
-  init(){
+  init() {
     const _options = this.#_options;
     const _content = this.#_content;
     const {
@@ -1172,20 +1208,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 +1324,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 +1382,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,7 +1393,7 @@ class TXEpgContentProvider {
 
 // === module exports block ===
 
-exports.TXepgDTSProvider = TXepgDTSProvider;
+exports.TXEpgDTSProvider = TXEpgDTSProvider;
 exports.TXEpgSchedulesList = TXEpgSchedulesList;
 exports.TXEpgProviderContainer = TXEpgProviderContainer;
 exports.TXEpgHeaderContainer = TXEpgHeaderContainer;
@@ -1387,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;