@ygracs/xepg-lib-js 0.0.17 → 0.0.18

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+#### *v0.0.18*
+
+Pre-release version.
+
+> - `xepgdoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
+> - updated dependency on `@ygracs/dtf-lib-js` module to v0.0.25;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.2;
+> - add method `loadFromXMLString` of `TXEpgContentProvider` class;
+> - deprecate method `loadFromString` of `TXEpgContentProvider` class;
+> - other fixes.
+
 #### *v0.0.17*
 
 Pre-release version.

package/LICENSE

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

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.13|
+|***rev.*:**|0.0.14|
 |:---|---:|
-|***date***:|2022-12-06|
+|***date***:|2024-07-17|
 
 ## Introduction
 
@@ -251,6 +251,12 @@ The table below describes a properties of a `TXEpgContentProvider` class:
 
 ##### **loadFromString(xmlString, options)**
 
+> WARNING: This method deprecated (*since `v0.0.18`*). Use `loadFromXMLString` instead.
+
+##### **loadFromXMLString(xmlString, options)**
+
+> since: `v0.0.18`
+
 This method loads a document content from string containing text in XML format.
 
 ##### **loadFromFile(src)**
@@ -277,7 +283,7 @@ This method saves a document content to a file. A `src` provided a string that i
 
 This method saves a document content to a string.
 
-> Note: will deprecate.
+> Note: will deprecate. Use `saveToXMLString` instead.
 
 #### class methods (*special*)
 

package/lib/xepgdoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.054-20230326]
+// [v0.1.056-20240717]
 
 // === module init block ===
 
@@ -28,6 +28,84 @@ const TXmlContentParseOptions = xObj.TXmlContentParseOptions;
 const insertXObjElement = xObj.insertXObjElement;
 const getXObjElement = xObj.getXObjElement;
 
+// === module extra block (helper functions) ===
+
+/*
+ * === xObj-function wrappers (start) ===
+ */
+
+function readXObjParam(obj){
+  return xObj.readXObjParam(obj, defParseOptions.settings.textKey);
+};
+
+function writeXObjParam(obj, value){
+  return xObj.writeXObjParam(obj, value, defParseOptions.settings.textKey);
+};
+
+function writeXObjAttr(obj, name, value) {
+  return xObj.writeXObjAttr(
+    obj, name, value, defParseOptions.settings.attributesKey
+  );
+};
+
+/*
+ * === xObj-function wrappers (end) ===
+ */
+
+function _getXmlChildElementParam(obj, elem){
+  const child = obj ? getXObjElement(obj, elem) : null;
+  return child ? readXObjParam(child) : '';
+};
+
+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);
+  };
+  if (isPlainObject(obj) && isNotEmptyString(key_name)) {
+    obj[key_name] = {};
+    writeXObjAttr(obj[key_name], 'version', xml_ver);
+    writeXObjAttr(obj[key_name], 'encoding', doc_def_enc);
+  };
+};
+
+/**
+ * @function checkFsError
+ * @param {object}
+ * @param {Error}
+ * @returns {object}
+ * @inner
+ * @description Checs an error code of a fs ops and sets descr info if succeed
+ */
+function checkFsError(descr, err) {
+  let isSucceed = false;
+  if (isPlainObject(err) && isPlainObject(descr)) {
+    switch (err.code) {
+      case 'ENOENT':
+      case 'EISDIR':
+      case 'EPERM': {
+        descr.errCode = err.errno;
+        descr.errEvent = err.code;
+        descr.errMsg = `ERR_FILE_${err.code}`;
+        isSucceed = true;
+        break;
+      }
+      default: {}
+    };
+    if (isSucceed) descr.isERR = true;
+  };
+  return { isSucceed, descr };
+};
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
 const XEPG_ROOT_ETAG_NAME = 'epgdoc';
 const XEPG_DEF_NS_NAME = 'tvp';
 const XEPG_DEF_NS_PATH = 'urn:e-doc:epg-doc:xepg';
@@ -56,6 +134,7 @@ const XEPG_DEF_DOCUMENT_TYPE = 'xepg';
 const XEPG_DEF_DOCUMENT_SCHEMA = '0.2';
 const XEPG_DEF_PROVIDER_NAME = 'xepg-lib-js';
 const XEPG_DEF_PROVIDER_VER = '0.0.15';
+
 const defXEpgDocOptions = {
   xmlns_xepg_pref: XEPG_DEF_NS_NAME,
   xmlns_xepg_path: XEPG_DEF_NS_PATH,
@@ -77,50 +156,17 @@ const defXEpgDocOptions = {
 const defParseOptions = new TXmlContentParseOptions();
 //console.log('CHECK: defParseOptions => '+JSON.stringify(defParseOptions, null, 2));
 
-// === module extra block (helper functions) ===
+/***
+ * (* function definitions *)
+ */
 
-// === xObj-function wrappers (start) ===
-
-function readXObjParam(obj){
-  return xObj.readXObjParam(obj, defParseOptions.settings.textKey);
-};
-
-function writeXObjParam(obj, value){
-  return xObj.writeXObjParam(obj, value, defParseOptions.settings.textKey);
-};
-
-function writeXObjAttr(obj, name, value) {
-  return xObj.writeXObjAttr(
-    obj, name, value, defParseOptions.settings.attributesKey
-  );
-};
-
-// === xObj-function wrappers (end) ===
-
-function _getXmlChildElementParam(obj, elem){
-  const child = obj ? getXObjElement(obj, elem) : null;
-  return child ? readXObjParam(child) : '';
-};
-
-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);
-  };
-  if (isPlainObject(obj) && isNotEmptyString(key_name)) {
-    obj[key_name] = {};
-    writeXObjAttr(obj[key_name], 'version', xml_ver);
-    writeXObjAttr(obj[key_name], 'encoding', doc_def_enc);
-  };
-};
-
-// === module main block (function definitions) ===
-
-// === module main block (class definitions) ===
+/***
+ * (* class definitions *)
+ */
 
+/**
+ * @description This class implements an instance of a EPG-schedules list
+ */
 class TXEpgSchedulesList {
   #_content = null;
   #_options = null;
@@ -159,7 +205,7 @@ class TXEpgSchedulesList {
     let result = valueToIndex(
       _getXmlChildElementParam(this.#_dts_src, 'value')
     );
-    return chkDTSysID(result) ? result : -1;
+    return chkDTSysID(result) ? result : 0; //-1; // // TODO: [?]
   }
 
   get curDocTZ(){
@@ -226,6 +272,9 @@ class TXEpgSchedulesList {
 
 };
 
+/**
+ * @description This class implements an instance of a EPG-provider element
+ */
 class TXEpgProviderContainer {
   #_content = null;
   #_options = null;
@@ -374,10 +423,10 @@ class TXEpgProviderContainer {
     } else {
       ({ name, version, schema, doctype } = _options);
     };
-    name = readAsString(name, prov_opt.name, true);
-    version = readAsString(version, prov_opt.version, true);
-    doctype = readAsString(doctype, prov_opt.doctype, true);
-    schema = readAsString(schema, prov_opt.schema, true);
+    name = readAsString(name, { defValue: prov_opt.name, useTrim: true });
+    version = readAsString(version, { defValue: prov_opt.version, useTrim: true });
+    doctype = readAsString(doctype, { defValue: prov_opt.doctype, useTrim: true });
+    schema = readAsString(schema, { defValue: prov_opt.schema, useTrim: true });
     this.name = name;
     this.version = version;
     this.schema = schema;
@@ -386,6 +435,9 @@ class TXEpgProviderContainer {
 
 };
 
+/**
+ * @description This class implements an instance of a DTS-provider element
+ */
 class TXepgDTSProvider {
   #_content = null;
   #_options = null;
@@ -416,10 +468,10 @@ class TXepgDTSProvider {
 
   get dtstype(){
     const item = getXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
-    let result = -1;
+    let result = 0; //-1; // // TODO: [?]
     if (isPlainObject(item)) {
       result = valueToIndex(_getXmlChildElementParam(item, 'value'));
-      if (!chkDTSysID(result)) result = -1;
+      if (!chkDTSysID(result)) result = 0; //-1; // // TODO: [?]
     };
     return result;
   }
@@ -465,6 +517,9 @@ class TXepgDTSProvider {
 
 };
 
+/**
+ * @description This class implements an instance of a EPG-header element
+ */
 class TXEpgHeaderContainer {
   #_content = null;
   #_options = null;
@@ -645,16 +700,21 @@ class TXEpgHeaderContainer {
 
 };
 
+/**
+ * @description This class implements an instance of a container
+ *              that managea content of a document
+ */
 class TXEpgContentProvider {
   #_content = null;
   #_options = null;
+  #_parseOptions = null;
 
-  constructor(opt){
+  constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
     let {
       parseOptions,
-      autoBindRoot,
+      autoBindRoot, // <*reserved*> ([?] - deprecate)
     } = _options;
     if (!(parseOptions instanceof TXmlContentParseOptions)) {
       parseOptions = new TXmlContentParseOptions(parseOptions);
@@ -664,6 +724,8 @@ class TXEpgContentProvider {
     // save options
     //_options.autoBindRoot = autoBindRoot; //* // TODO:
     this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
     // init document content
     this.#_content = {};
     this.init();
@@ -802,41 +864,72 @@ class TXEpgContentProvider {
     };
   }
 
-  saveToXMLString(){
-    return xmlParser.js2xml(
-      this.#_content,
-      this.#_options.parseOptions.js2xml,
-    );
+  /**
+   * @returns {string}
+   * @description Returns a document content as a string in an XML-format.
+   */
+  saveToXMLString() {
+    let result = '';
+    try {
+      result = xmlParser.js2xml(this.#_content, this.#_parseOptions.js2xml);
+    } catch (err) {
+      //console.log('CHECK: TXEpgContentProvider.saveToXMLString() => Error => '+err);
+      throw err;
+    };
+    return result;
   }
 
-  saveToFile(src_link){
-    let saveFile = function(obj){
-      return new Promise(function(resolve, reject) {
-        let { src_link } = obj;
-        if (
-          typeof src_link !== 'string'
-          || ((src_link = src_link.trim()) === '')
-        ) {
-          resolve(false);
-        };
-        fs.writeFile(src_link, obj.content, (err) => {
-          if (err) reject(err);
-          resolve(true);
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @async
+   * @description Saves a document content to a file.
+   */
+  saveToFile(source) {
+    /**/// main part that return promise as a result
+    return new Promise((resolve, reject) => {
+      let data = {
+        isSucceed: 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 {
+        data.content = this.saveToXMLString();
+        fse.writeFile(data.source, data.content, 'utf8').then(result => {
+          data.isSucceed = true;
+          data.errEvent = 'OPS_IS_SUCCEED';
+          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);
+          };
         });
-      });
-    };
-    let loadContent = (opt) => { return this.asXML(opt); };
-    return new Promise(function(resolve, reject){
-      let tmpObj = { src_link: src_link };
-      tmpObj.content = loadContent();
-      saveFile(tmpObj).then(result => {
-        resolve(result);
-      }).catch(err => { reject(err); });
+      };
     });
   }
 
-  saveToFileSync(source){
-    //console.log('CHECK: TXEpgContentProvider.saveToFileSync() => was called...');
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @description Saves a document content to a file.
+   */
+  saveToFileSync(source) {
     let data = {
       isSucceed: false,
       source: typeof source === 'string' ? source.trim() : '',
@@ -844,24 +937,30 @@ class TXEpgContentProvider {
       isERR: false,
       errEvent: '',
     };
-    if (data.source !== '') {
+    if (data.source === '') {
+      data.isERR = true;
+      data.errEvent = (
+        typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
+      );
+    } else {
       try {
-        data.content = this.asXML();
+        data.content = this.saveToXMLString();
         fs.writeFileSync(data.source, data.content, 'utf8');
       } catch (err) {
-        console.log('CHECK: TXEpgContentProvider.saveToFileSync() => Error => '+err);
-        console.log('CHECK: TXEpgContentProvider.saveToFileSync() => Error => '+err.code);
-        throw 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;
+        };
       };
-    } else {
-      data.isERR = true;
-      data.errEvent = 'EMPTY_SRCLINK';
     };
-    //console.log('CHECK: TXEpgContentProvider.saveToFileSync() => was left...');
     return data;
   }
 
-  loadFromString(xmlString, opt){
+  loadFromXMLString(xmlString, opt) {
     let isSUCCEED = false;
     if (typeof xmlString === 'string') {
       let _options = this.#_options;
@@ -891,83 +990,27 @@ class TXEpgContentProvider {
           isSUCCEED = true;
         };
       } catch (err) {
-        console.log('CHECK: TXEpgContentProvider.loadFromString() => err => '+err);
+        //console.log('CHECK: TXEpgContentProvider.loadFromString() => err => '+err);
         throw err;
       };
     };
     return isSUCCEED;
   }
 
-  loadFromFile(source){
-    /**/// extend part that return promise as a result
-    const loadFile = function(source){
-      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 != '') {
-              data.isLoaded = true;
-              data.errEvent = 'OPS_IS_SUCCEED';
-            } else {
-              data.isERR = true;
-              data.errEvent = 'NO_CONTENT';
-            };
-            resolve(data);
-          }).catch(err => {
-            switch (err.code) {
-              case 'ENOENT':
-              case 'EISDIR':
-                data.isERR = true;
-                data.errEvent = err.code;
-                resolve(data);
-                break;
-              default:
-                console.log('CHECK: TXEpgContentProvider.loadFromFile() => [1] loadFile() => Error => '+err.code);
-                reject(err);
-                break;
-            };
-          });
-        };
-      });
-    };
-    /**/// main part that return promise as a result
-    return new Promise((resolve, reject) => {
-      loadFile(source).then(data => {
-        if (data.isLoaded) {
-          if (this.loadFromString(data.content)) {
-            data.isLoaded = true;
-            data.errEvent = 'OPS_IS_SUCCEED';
-          } else {
-            data.isERR = true;
-            data.errEvent = 'OPS_IS_FAILED';
-          };
-        } else {
-          //console.log('CHECK: TXEpgContentProvider.loadFromFile() => result.isERR:['+data.isERR+']');
-          //console.log('CHECK: TXEpgContentProvider.loadFromFile() => result.errEvent:['+data.errEvent+']');
-        };
-        resolve(data);
-      }).catch(err => {
-        console.log('CHECK: TXEpgContentProvider.loadFromFile() => loadFile().err() => '+err);
-        reject(err);
-      });
-    });
+  loadFromString(...args){
+    return this.loadFromXMLString(...args);
   }
 
-  loadFromFileSync(source){
-    const loadFile = function(source){
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @async
+   * @description Loads a document content from a file.
+   */
+  loadFromFile(source) {
+    /**/// main part that return promise as a result
+    return new Promise((resolve, reject) => {
       let data = {
         isLoaded: false,
         source: typeof source === 'string' ? source.trim() : '',
@@ -980,56 +1023,84 @@ class TXEpgContentProvider {
         data.errEvent = (
           typeof source === 'string' ? 'EMPTY_SRCLINK' : 'NO_SRCLINK'
         );
+        resolve(data);
       } else {
-        try {
-          data.content = fs.readFileSync(data.source, 'utf8');
-          if (data.content !== '') {
-            data.isLoaded = true;
-            data.errEvent = 'OPS_IS_SUCCEED';
+        fse.readFile(data.source, 'utf8').then(result => {
+          data.content = result;
+          if (result !== '') {
+            if (this.loadFromXMLString(result)) {
+              data.isLoaded = true;
+              data.errEvent = 'OPS_IS_SUCCEED';
+            } else {
+              data.isERR = true;
+              data.errEvent = 'OPS_IS_FAILED';
+            };
           } else {
             data.isERR = true;
             data.errEvent = 'NO_CONTENT';
           };
-        } catch (err) {
-          switch (err.code) {
-            case 'ENOENT':
-            case 'EISDIR':
-              data.isERR = true;
-              data.errEvent = err.code;
-              break;
-            default:
-              console.log('CHECK: TXEpgContentProvider.loadFromFileSync() => [1] loadFile() => Error => '+err.code);
-              throw err;
-              break;
+          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);
           };
-        };
+        });
       };
-      return data;
-    };
-    let result = {
+    });
+  }
+
+  /**
+   * @param {string}
+   * @returns {object}
+   * @throws {Error}
+   * @description Loads a document content from a file.
+   */
+  loadFromFileSync(source) {
+    let data = {
       isLoaded: false,
+      source: typeof source === 'string' ? source.trim() : '',
+      content: '',
       isERR: false,
       errEvent: '',
     };
-    try {
-      result = loadFile(source);
-      if (result.isLoaded) {
-        if (this.loadFromString(result.content)) {
-          result.isLoaded = true;
-          result.errEvent = 'OPS_IS_SUCCEED';
+    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';
+          };
         } else {
-          result.isERR = true;
-          result.errEvent = 'OPS_IS_FAILED';
+          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;
         };
-      } else {
-        //console.log('CHECK: TXEpgContentProvider.loadFromFileSync() => result.isERR:['+result.isERR+']');
-        //console.log('CHECK: TXEpgContentProvider.loadFromFileSync() => result.errEvent:['+result.errEvent+']');
       };
-    } catch (err) {
-      console.log('CHECK: TXEpgContentProvider.loadFromFileSync() => loadFile().err() => '+err);
-      throw err;
     };
-    return result;
+    return data;
   }
 
   // will  deprecate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xepg-lib-js",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "A library for handling an EPG-sources based on an XEPG-format",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -28,20 +28,24 @@
     "test-xepg:cp": "jest TXEpgContentProvider",
     "win:test": "set TZ='Etc/UTC' && jest",
     "win:test-xepg": "set TZ='Etc/UTC' && jest ./test",
-    "win:test-xepg:hc": "set TZ='Etc/UTC' && jest TXEpgHeader"
+    "win:test-xepg:hc": "set TZ='Etc/UTC' && jest TXEpgHeader",
+    "build-doc-md": "jsdoc2md",
+    "build-doc-html": "jsdoc"
   },
   "imports": {
-    "#lib/*": "./lib/*"
+    "#lib/*": "./lib/*",
+    "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.1.3",
-    "@ygracs/dtf-lib-js": "^0.0.22",
+    "@ygracs/bsfoc-lib-js": "^0.2.1",
+    "@ygracs/dtf-lib-js": "^0.0.25",
     "@ygracs/xml-js6": "^0.0.3-b",
-    "@ygracs/xobj-lib-js": "^0.0.14-rc4"
+    "@ygracs/xobj-lib-js": "^0.1.2"
   },
   "devDependencies": {
     "cross-env": "^7.0.3",
     "jest": "^29.6.1",
+    "jsdoc-to-markdown": "^8.0.1",
     "minimist": "^1.2.8"
   }
 }