@ygracs/xepg-lib-js 0.0.19 → 0.0.20

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+#### *v0.0.20*
+
+Pre-release version.
+
+> - `xepgdoc-lib.md` updated;
+> - update dependency on `@ygracs/dtf-lib-js` module to v0.0.26;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.2.0;
+> - add method `saveToXMLString` of `TXEpgHeaderContainer` class;
+> - add method `saveToXMLString` of `TXEpgProviderContainer` class;
+> - add method `chkIndex` of `TXEpgSchedulesList` class;
+> - deprecate method `chkScheduleIndex` of `TXEpgSchedulesList` class;
+> - some fixes in `dts-helper.js` lib-module;
+> - `$module/lib/file-helper.js` added.
+
 #### *v0.0.19*
 
 Pre-release version.

package/README.md

@@ -1,16 +1,12 @@
-|***rev.*:**|0.0.5|
+|***rev.*:**|0.0.6|
 |:---|---:|
-|***date***:|2022-12-06|
+|***date***:|2024-10-29|
 
 ## Introduction
 
 This module provide a base functionality for handling an EPG-sources based on XEPG-format.
 
-> For more information about a XEPG-format see `xepgdoc-spec.md`in the project `doc` directory.
-
-## Use cases
-
-This module was make for use as a library in a development of a Web-apps based on [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) as main target.
+> For more information about a XEPG-format see `xepgdoc-spec.md` in the project `doc` directory.
 
 ## Description
 
@@ -37,3 +33,9 @@ For more read the `xepgdoc-lib.md` in the project `doc` directory.
 - classes:
 
 	+ `TXmlContentParseOptions`;
+
+## Use cases
+
+### Installation
+
+`npm install @ygracs/xepg-lib-js`

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.14|
+|***rev.*:**|0.0.15|
 |:---|---:|
-|***date***:|2024-07-17|
+|***date***:|2024-10-28|
 
 ## Introduction
 
@@ -16,11 +16,15 @@ This class provides a functionality for handle an EPG-schedules list.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
-|`object`|---|---|a host object|
+|`object`|`array`|---|a host object|
 |`options`|`object`|---|an options settings|
 
 #### class properties
@@ -35,23 +39,29 @@ The table below describes a properties of a `TXEpgSchedulesList` class:
 
 #### class methods
 
-##### **hasNoSchedules()**
+##### **hasNoSchedules()** => `boolean`
 
 This method returns `true` if a document contains no schedules.
 
-##### **hasSchedules()**
+##### **hasSchedules()** => `boolean`
 
 This method returns `true` if a document contains at least one schedule.
 
-##### **chkScheduleIndex(value)**
+##### **chkScheduleIndex(value)** => `boolean`
+
+> WARNING: This method deprecated (*since `v0.0.20`*). Use `chkIndex` instead.
+
+##### **chkIndex(value)** => `boolean`
+
+> since: `v0.0.20`
 
 This method checks if a given `value` represents a valid schedule index and if so returns `true`.
 
-##### **getScheduleInfo(index)**
+##### **getScheduleInfo(index)** => `object`
 
 This method returns an object that contains a schedule information.
 
-##### **getAllSchedulesInfo()**
+##### **getAllSchedulesInfo()** => `object[]`
 
 This method returns an array that contains an information for all available schedules.
 
@@ -65,12 +75,16 @@ This class implements a structure that holds an information about a program prov
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
-|`object`|---|---|a host object|
-|`options`|---|---|an option settings|
+|`object`|`object`|---|a host object|
+|`options`|`object`|---|an option settings|
 
 The `options` structure is listed below:
 
@@ -91,18 +105,32 @@ The table below describes a properties of a `TXEpgProviderContainer` class:
 
 #### class methods
 
-##### **setName(value)**
+##### **setName(value)** => `boolean`
 
 This method sets a name of a provider to a given `value`.
 
-##### **getInfo()**
+##### **getInfo()** => `object`
 
-This method returns an `object` that contains information about content provider.
+This method returns an `object` that contains information about content provider. An object contains a field listed in the table below:
 
-##### **setInfo(obj)**
+|property name|value type|description|
+|:---|---|:---|
+|`name`|`string`|a provider name|
+|`version`|`string`|a provider version|
+|`schema`|`string`|a document schema version|
+|`doctype`|`string`|a document type|
+
+
+##### **setInfo(obj)** => `void`
 
 This method loads information about content provider.
 
+##### **saveToXMLString()** => `string`
+
+> since: `v0.0.20`
+
+This method saves an element content to a string.
+
 #### class methods (*special*)
 
 ##### **init()**
@@ -111,7 +139,11 @@ This method loads information about content provider.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -137,7 +169,11 @@ The table below describes a properties of a `TXEpgDTSProvider` class:
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -163,23 +199,23 @@ The table below describes a properties of a `TXEpgHeaderContainer` class:
 
 #### class methods
 
-##### **getDocumentDT()**
+##### **getDocumentDT()** => `number`
 
-This method returns a time value of a document creation.
+This method returns a time value of a document creation as a timestamp.
 
-##### **setDocumentDT()**
+##### **setDocumentDT()** => `void`
 
 This method sets a time value of a document creation.
 
-##### **getDocumentEDT()**
+##### **getDocumentEDT()** => `number`
 
-This method returns a time value from which a document is expired.
+This method returns a time value from which a document is expired as a timestamp.
 
-##### **setDocumentEDT(value)**
+##### **setDocumentEDT(value)** => `void`
 
 This method sets a time value at which a document will be expired.
 
-##### **getChannelInfo()**
+##### **getChannelInfo()** => `object`
 
 This method returns an object which contains a channel information.
 
@@ -187,12 +223,12 @@ An object contains the following fields:
 
 |field name|field type|description|
 |:---|---|:---|
-|`chnid`|`ID_STRING`|a channel ID|
+|`chnid`|`srting`|a channel ID|
+|`chngid`|`string`|a channel 'Group ID'|
 |`chname`|`string`|a name of the channel|
-|`chngid`|`ID_STRING`|a channel group|
 |`srcurl`|`string`|a link to source|
 
-##### **setChannelInfo(obj)**
+##### **setChannelInfo(obj)** => `void`
 
 This method fills a channel information with a given data.
 
@@ -208,22 +244,32 @@ If an object is given it contains the following fields:
 
 |field name|field type|description|
 |:---|---|:---|
-|`chnid`|`ID_STRING`|a channel ID|
+|`chnid`|`string`|a channel ID|
 |`chname`|`string`|a name of the channel|
-|`chngid`|`ID_STRING`|a channel group|
+|`chngid`|`string`|a channel group|
 |`srcurl`|`string`|a link to source|
 
-##### **getProviderInfo()**
+##### **getProviderInfo()** => `object`
 
 This method returns an object which contains an information about document provider.
 
 ##### **setProviderInfo(obj)**
 
+##### **saveToXMLString()** => `string`
+
+> since: `v0.0.20`
+
+This method saves an element content to a string.
+
 ### **TXEpgContentProvider**
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -249,41 +295,39 @@ The table below describes a properties of a `TXEpgContentProvider` class:
 
 #### class methods
 
-##### **loadFromString(xmlString, options)**
+##### **loadFromString(xmlString, options)** => `boolean`
 
 > WARNING: This method deprecated (*since `v0.0.18`*). Use `loadFromXMLString` instead.
 
-##### **loadFromXMLString(xmlString, options)**
+##### **loadFromXMLString(xmlString, options)** => `boolean`
 
 > since: `v0.0.18`
 
 This method loads a document content from string containing text in XML format.
 
-##### **loadFromFile(src)**
+##### **loadFromFile(src)** => `object`
 
 This method loads a document content from a file. A `src` provided a string that is a path to the file.
 
-##### **loadFromFileSync(src)**
+##### **loadFromFileSync(src)** => `object`
 
 This method loads a document content from a file. A `src` provided a string that is a path to the file.
 
-##### **saveToXMLString()**
+##### **saveToXMLString()** => `string`
 
 This method saves a document content to a string.
 
-##### **saveToFile(src)**
+##### **saveToFile(src)** => `object`
 
 This method saves a document content to a file. A `src` provided a string that is a path to the file.
 
-##### **saveToFileSync(src)**
+##### **saveToFileSync(src)** => `object`
 
 This method saves a document content to a file. A `src` provided a string that is a path to the file.
 
 ##### **asXML(options)**
 
-This method saves a document content to a string.
-
-> Note: will deprecate. Use `saveToXMLString` instead.
+> WARNING: This method deprecated (*since `v0.0.18`*). Use `saveToXMLString` instead.
 
 #### class methods (*special*)
 

package/lib/dts-helper.js

@@ -1,4 +1,4 @@
-// [v0.1.043-20230711]
+// [v0.1.045-20240829]
 
 // === module init block ===
 
@@ -11,21 +11,42 @@ const {
   convDTValueToISO8601,
   convDTValueToXMLTV, convXMLTVToDTValue,
   convDTValueToDateString,
+  tryDTValue,
 } = require('@ygracs/dtf-lib-js');
 
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
 const def_dts_param = [
   'default', 'iso8601', 'xmltv', 'timestamp', 'utc',
 ];
 
-// === module extra block (helper functions) ===
-
-// === module main block (function definitions) ===
+/***
+ * (* function definitions *)
+ */
 
+/**
+ * @function chkDTSysID
+ * @param {(number|string)} value
+ * @returns {boolean}
+ * @description Checs if a given value is a valid dtstype ID
+ */
 function chkDTSysID(value){
   const _value = valueToIndex(value);
   return _value !== -1 && def_dts_param[_value] ? true : false;
 };
 
+/**
+ * @function getDTSysName
+ * @param {(number|string)} value
+ * @returns {string}
+ * @description Returns a dtstype name by a given dtstype ID
+ */
 function getDTSysName(value){
   let result = 'undefined';
   if (chkDTSysID(value)) {
@@ -34,6 +55,19 @@ function getDTSysName(value){
   return result;
 };
 
+/**
+ * @typedef DTSysDescr
+ * @type {object}
+ * @property {number} index - dtstype ID
+ * @property {string} name - dtstype name
+ */
+
+/**
+ * @function getDTSysDescr
+ * @param {(number|string)} value
+ * @returns {DTSysDescr}
+ * @description Returns a dtstype description for a given dtstype ID
+ */
 function getDTSysDescr(value){
   let index = valueToIndex(value);
   let name = 'undefined';
@@ -50,15 +84,23 @@ function getDTSysDescr(value){
   return { index, name };
 };
 
-function convStringToDTValue(value, dts_id, tz){
+/**
+ * @function convStringToDTValue
+ * @param {string} value
+ * @param {(number|string)} [dts_id=0]
+ * @param {(number|string)} [tz]
+ * @returns {number}
+ * @description Tries to convert a given string to timestamp
+ */
+function convStringToDTValue(value, dts_id = 0, tz){
+  const dtstype = getDTSysName(dts_id);
   let result = 0;
-  let dtstype = valueToIndex(dts_id);
-  let dt_str = typeof value === 'string' ? value : '';
-  if (chkDTSysID(dtstype)) {
-    switch (getDTSysName(dtstype)) {
+  if (dtstype !== 'undefined') {
+    switch (dtstype) {
       case 'default': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[default]');
+        let dt_str = typeof value === 'string' ? value : '';
         result = (new Date(dt_str)).getTime();
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
@@ -67,7 +109,8 @@ function convStringToDTValue(value, dts_id, tz){
       case 'iso8601': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[iso8601]');
-        result = (new Date(dt_str)).getTime();
+        let dtStr = typeof value === 'string' ? value : '';
+        if (dtStr !== '') result = (new Date(dtStr)).getTime();
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
@@ -75,7 +118,8 @@ function convStringToDTValue(value, dts_id, tz){
       case 'xmltv': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[xmltv]');
-        result = (new Date(convXMLTVToDTValue(dt_str))).getTime();
+        const dtValue = convXMLTVToDTValue(value, true);
+        if (dtValue !== null) result = dtValue;
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
@@ -83,7 +127,8 @@ function convStringToDTValue(value, dts_id, tz){
       case 'timestamp': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[timestamp]');
-        result = Number(dt_str);
+        const { isSucceed, value: dtValue } = tryDTValue(value);
+        if (isSucceed) result = dtValue.getTime();
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
@@ -91,20 +136,27 @@ function convStringToDTValue(value, dts_id, tz){
       case 'utc': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[utc]');
-        result = (new Date(Date.UTC(dt_str))).getTime();
+        let dtStr = typeof value === 'string' ? value : '';
+        if (dtStr !== '') result = (new Date(Date.UTC(dtStr))).getTime();
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
       }
-      default: {
-        break;
-      }
+      default: {}
     };
     if (Number.isNaN(result)) result = 0;
   };
   return result;
 };
 
+/**
+ * @function convDTValueToString
+ * @param {(number|string|Date)} value
+ * @param {(number|string)} dts_id
+ * @param {(number|string)} tz
+ * @returns {string}
+ * @description Tries to convert a given value to its string representation
+ */
 function convDTValueToString(value, dts_id, tz){
   let result = '';
   let dt_val = (
@@ -163,7 +215,9 @@ function convDTValueToString(value, dts_id, tz){
   return result;
 };
 
-// === module main block (class definitions) ===
+/***
+ * (* class definitions *)
+ */
 
 // === module exports block ===