@ygracs/xepg-lib-js 0.0.22 → 0.0.24

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+#### *v0.0.24*
+
+Pre-release version.
+
+> - update `xepgdoc-lib.md`;
+> - update dependency on `@ygracs/dtf-lib-js` module to v0.0.29;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.3;
+> - (`TXEpgContentProvider`) add new properties: `schedules`;
+> - (`TXEpgContentProvider`) deprecate properties: `SchedulesList`;
+> - (`TXEpgContentProvider`) remove deprecated methods: `loadFromString`;
+> - (`TXEpgHeaderContainer`) add new methods: `loadFromXMLString`;
+> - (`TXEpgHeaderContainer`) deprecate methods: `setProviderInfo`;
+> - (`TXEpgProviderContainer`) add new methods: `loadFromXMLString`;
+> - (`TXEpgSchedulesList`) change constructor behavior on handling params (*see docs for details*);
+> - (`TXEpgSchedulesList`) add new properties: `count`;
+> - (`TXEpgSchedulesList`) deprecate properties: `schedQty`;
+> - (`TXEpgSchedulesList`) add new methods: `isEmpty`, `isNotEmpty`;
+> - (`TXEpgSchedulesList`) deprecate methods: `hasNoSchedules`, `hasSchedules`;
+> - (`TXEpgSchedulesList`) remove deprecated methods: `chkScheduleIndex`;
+> - (`TXEpgSchedulesList`) add iterator method;
+> - (`TXEpgScheduleItem`) change constructor behavior on handling params (*see docs for details*);
+> - (`TXEpgScheduleItem`) add new methods: `loadFromXMLString`;
+> - other fixes.
+
+#### *v0.0.23*
+
+Pre-release version.
+
+> - update `xepgdoc-lib.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.3;
+> - update dependency on `@ygracs/dtf-lib-js` module to v0.0.28;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.2;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.0.5-b;
+> - add dependency on `@cntwg/file-helper` module;
+> - remove `$module/lib/file-helper.js`;
+> - improve behavior for a getter of a `rating` property of a `TXEpgScheduleItem`-class;
+> - add functions: readAsTagName, `readAsAttrName`, valueToElementID;
+> - other fixes.
+
 #### *v0.0.22*
 
 Pre-release version.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.9|
+|***rev.*:**|0.0.10|
 |:---|---:|
-|***date***:|2025-03-06|
+|***date***:|2025-07-30|
 
 ## Introduction
 
@@ -12,10 +12,16 @@ This module provide a base functionality for handling an EPG-sources based on XE
 
 This module contains the following components:
 
-### 1. a set of XEPG-document constants and components
+### 1. a set of XEPG-document constants, functions and components
 
 - constants:
 
+- functions:
+
+	+ `readAsTagName`;
+	+ `readAsAttrName`;
+	+ `valueToElementID`;
+
 - classes:
 
 	+ `TXEpgScheduleItem`;

package/doc/xepgdoc-lib.md

@@ -1,12 +1,12 @@
-|***rev.*:**|0.1.26|
+|***rev.*:**|0.1.40|
 |:---|---:|
-|***date***:|2025-03-06|
+|***date***:|2025-07-30|
 
 ## Introduction
 
 This paper describes a constants and an object classes provided by `xepgdoc-lib.js` module.
 
-### Base type definitions
+## Base type definitions
 
 This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function or a class method descriptions.
 
@@ -63,6 +63,45 @@ This descriptor is an `object` that describes a content provider.
 
 ## Module constants
 
+## Module functions
+
+### Experimental functions
+
+> Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+<a name="readAsTagName"></a>
+#### **readAsTagName(value)** => `string`
+
+> since: \[`v0.0.23`]
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's tag name. If failed an empty string is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
+<a name="readAsAttrName"></a>
+#### **readAsAttrName(value)** => `string`
+
+> since: \[`v0.0.23`]
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's attribute name. If failed an empty string is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
+<a name="valueToElementID"></a>
+#### **valueToElementID(value)**
+
+> since: \[`v0.0.23`]
+
+This function tries to convert a given `value` to the value of a valid identifier which is suitable for an XML-element's ID-attribute. If failed an empty string is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
 ## Module classes
 
 <a name="TXEpgScheduleItem"></a>
@@ -76,14 +115,19 @@ This class provides a functionality for handle an EPG-schedule element.
 
 The class constructor creates a new instance of the class.
 
+##### syntax
+
+`new TXEpgScheduleItem(object[, options[, extra]])`
+
 ##### constructor parameters
 
 The class constructor receives arguments listed below:
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`object`|`object`|---|a host object|
-|`options`|`object`|---|an options settings|
+| `object` | `object` | --- | a host object|
+| `options` | `object` | --- | an options settings|
+| `extra` | `object` | --- | \[*since: `v0.0.24`*] an extra options settings |
 
 #### class properties
 
@@ -193,6 +237,25 @@ This method tries to set a schedule description. If succeed `true` returned.
 
 This method saves an element content to a string in an XML-format.
 
+#### class methods (*experimental*)
+
+> Note: Purpose of those methods will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+<a name="TXEpgScheduleItem+loadFromXMLString"></a>
+##### **loadFromXMLString(str)** => `boolean`
+
+> since: `v0.0.24`
+
+This method loads an element content from a string given by a `str` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `str` | `string` | --- | some content |
+
+###### *exceptions*
+
+This methods throws `Error` if something goes wrong through a parsing process of a string.
+
 <a name="TXEpgSchedulesList"></a>
 ### **TXEpgSchedulesList**
 
@@ -202,20 +265,32 @@ This class provides a functionality for handle an EPG-schedules list.
 
 The class constructor creates a new instance of the class.
 
+##### syntax
+
+`new TXEpgSchedulesList(object[, options[, extra]])`
+
 ##### constructor parameters
 
 The class constructor receives arguments listed below:
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`object`|`array`|---|a host object|
-|`options`|`object`|---|an options settings|
+| `object` | `array` | --- | a host object |
+| `options` | `object` | --- | an options settings |
+| `extra` | `object` | --- | \[*since: `v0.0.24`*] an extra options settings |
 
 #### class properties
 
 <a name="TXEpgSchedulesList+schedQty"></a>
 ##### **schedQty**
 
+> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`count` property](#TXEpgSchedulesList+count) instead.
+
+<a name="TXEpgSchedulesList+count"></a>
+##### **count**
+
+> since: \[`v0.0.24`]
+
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of the elements the container holds |
@@ -239,16 +314,26 @@ The class constructor receives arguments listed below:
 <a name="TXEpgSchedulesList+hasNoSchedules"></a>
 ##### **hasNoSchedules()** => `boolean`
 
+> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`isEmpty` method](#TXEpgSchedulesList+isEmpty) instead.
+
+<a name="TXEpgSchedulesList+isEmpty"></a>
+##### **isEmpty()** => `boolean`
+
+> since: `v0.0.24`
+
 This method returns `true` if a document contains no schedules.
 
 <a name="TXEpgSchedulesList+hasSchedules"></a>
 ##### **hasSchedules()** => `boolean`
 
-This method returns `true` if a document contains at least one schedule.
+> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`isNotEmpty` method](#TXEpgSchedulesList+isNotEmpty) instead.
+
+<a name="TXEpgSchedulesList+isNotEmpty"></a>
+##### **isNotEmpty()** => `boolean`
 
-##### **chkScheduleIndex(value)** => `boolean`
+> since: `v0.0.24`
 
-> WARNING: This method deprecated (*since `v0.0.20`*). Use `chkIndex` instead.
+This method returns `true` if a document contains at least one schedule.
 
 <a name="TXEpgSchedulesList+chkIndex"></a>
 ##### **chkIndex(value)** => `boolean`
@@ -299,14 +384,18 @@ This class implements a structure that holds an information about a program prov
 
 The class constructor creates a new instance of the class.
 
+##### syntax
+
+`new TXEpgProviderContainer(object[, options])`
+
 ##### constructor parameters
 
-The class constructor receives arguments listed below:
+The class constructor receives an arguments listed below:
 
-|name|type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`object`|`object`|---|a host object|
-|`options`|`object`|---|an option settings|
+| `object` | `object` | --- | a host object |
+| `options` | `object` | --- | an option settings |
 
 The `options` structure is listed below:
 
@@ -383,6 +472,25 @@ This method loads information about content provider.
 
 This method saves an element content to a string.
 
+#### class methods (*experimental*)
+
+> Note: Purpose of those methods will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+<a name="TXEpgProviderContainer+loadFromXMLString"></a>
+##### **loadFromXMLString(str)** => `boolean`
+
+> since: `v0.0.24`
+
+This method loads an element content from a string given by a `str` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `str` | `string` | --- | some content |
+
+###### *exceptions*
+
+This methods throws `Error` if something goes wrong through a parsing process of a string.
+
 #### class methods (*special*)
 
 ##### **init()**
@@ -565,7 +673,7 @@ The `options` structure is listed below:
 <a name="TXEpgHeaderContainer+Provider"></a>
 ##### **Provider**
 
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use (`provider` property)[#TXEpgHeaderContainer+provider] instead.
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgHeaderContainer+provider) instead.
 
 <a name="TXEpgHeaderContainer+provider"></a>
 ##### **provider**
@@ -628,7 +736,7 @@ An object contains the following fields:
 <a name="TXEpgHeaderContainer+setChannelInfo"></a>
 ##### **setChannelInfo(obj)** => `void`
 
-> \[!] WARNING: `[since v0.0.22]` deprecated.
+> \[!] WARNING: `[since v0.0.22]` deprecated. Use [`TXEpgChannelContainer.setInfo()`](#TXEpgChannelContainer+setInfo) instead.
 
 This method fills a channel information with a given data.
 
@@ -662,6 +770,8 @@ This method returns an object which contains an information about document provi
 
 ##### **setProviderInfo(obj)**
 
+> \[!] WARNING: `[since v0.0.24]` deprecated. Use [`TXEpgProviderContainer.setInfo()`](#TXEpgProviderContainer+setInfo) instead.
+
 <a name="TXEpgHeaderContainer+saveToXMLString"></a>
 ##### **saveToXMLString()** => `string`
 
@@ -669,6 +779,25 @@ This method returns an object which contains an information about document provi
 
 This method saves an element content to a string.
 
+#### class methods (*experimental*)
+
+> Note: Purpose of those methods will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+<a name="TXEpgHeaderContainer+loadFromXMLString"></a>
+##### **loadFromXMLString(str)** => `boolean`
+
+> since: `v0.0.24`
+
+This method loads an element content from a string given by a `str` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `str` | `string` | --- | some content |
+
+###### *exceptions*
+
+This methods throws `Error` if something goes wrong through a parsing process of a string.
+
 <a name="TXEpgContentProvider"></a>
 ### **TXEpgContentProvider**
 
@@ -696,7 +825,7 @@ The `options` structure is listed below:
 <a name="TXEpgContentProvider+Header"></a>
 ##### **Header**
 
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use (`header` property)[#TXEpgContentProvider+header] instead.
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`header` property](#TXEpgContentProvider+header) instead.
 
 <a name="TXEpgContentProvider+header"></a>
 ##### **header**
@@ -710,7 +839,7 @@ The `options` structure is listed below:
 <a name="TXEpgContentProvider+Provider"></a>
 ##### **Provider**
 
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use (`provider` property)[#TXEpgContentProvider+provider] instead.
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgContentProvider+provider) instead.
 
 <a name="TXEpgContentProvider+provider"></a>
 ##### **provider**
@@ -731,6 +860,13 @@ The `options` structure is listed below:
 <a name="TXEpgContentProvider+SchedulesList"></a>
 ##### **SchedulesList**
 
+> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`schedules` property](#TXEpgContentProvider+schedules) instead.
+
+<a name="TXEpgContentProvider+schedules"></a>
+##### **schedules**
+
+> since: `v0.0.24`
+
 | property type | read only | description |
 |---|---|:---|
 | `TXEpgSchedulesList` | yes | returns a `TXEpgSchedulesList` instance |
@@ -751,10 +887,6 @@ This method saves a document content into a file addressed by `src`.
 |:---|---|---:|:---|
 | `src` | `string` | --- | path to a file |
 
-##### **loadFromString(xmlString, options)** => `boolean`
-
-> WARNING: This method deprecated (*since `v0.0.18`*). Use `loadFromXMLString` instead.
-
 <a name="TXEpgContentProvider+loadFromXMLString"></a>
 ##### **loadFromXMLString(str)** => `boolean`
 

package/index.js

@@ -1,4 +1,4 @@
-// [v0.0.010-20250228]
+// [v0.1.011-20250727]
 
 // === module init block ===
 
@@ -6,7 +6,7 @@ const xepgdoc = require('./lib/xepgdoc-lib.js');
 
 const xObj = require('@ygracs/xobj-lib-js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -20,8 +20,9 @@ module.exports.TXEpgDTSProvider = xepgdoc.TXEpgDTSProvider;
 module.exports.TXEpgProviderContainer = xepgdoc.TXEpgProviderContainer;
 module.exports.TXEpgHeaderContainer = xepgdoc.TXEpgHeaderContainer;
 
+module.exports.readAsTagName = xepgdoc.readAsTagName;
+module.exports.readAsAttrName = xepgdoc.readAsAttrName;
+module.exports.valueToElementID = xepgdoc.valueToElementID;
+
 // re-export stuff from `@ygracs/xobj-lib-js` module
 module.exports.TXmlContentParseOptions = xObj.TXmlContentParseOptions;
-
-/**/// will deprecate
-module.exports.TXepgDTSProvider = xepgdoc.TXepgDTSProvider;

package/lib/dts-helper.js

@@ -1,4 +1,4 @@
-// [v0.1.047-20250225]
+// [v0.1.048-20250727]
 
 // === module init block ===
 
@@ -30,10 +30,10 @@ const def_dts_param = [
  */
 
 /**
+ * Checks if a given value is a valid dtstype ID
  * @function chkDTSysID
  * @param {(number|string)} value - value to verify
  * @returns {boolean}
- * @description Checs if a given value is a valid dtstype ID
  */
 function chkDTSysID(value) {
   const _value = valueToIndex(value);
@@ -41,10 +41,10 @@ function chkDTSysID(value) {
 };
 
 /**
+ * Returns a dtstype name by a given dtstype ID
  * @function getDTSysName
  * @param {(number|string)} value - DTS-type identifier
  * @returns {string}
- * @description Returns a dtstype name by a given dtstype ID
  */
 function getDTSysName(value) {
   let result = 'undefined';
@@ -55,17 +55,17 @@ function getDTSysName(value) {
 };
 
 /**
+ * A 'DTS'-type descriptor
  * @typedef {Object} DTSysDescr
  * @property {number} index - dtstype ID
  * @property {string} name - dtstype name
- * @description A DTS-type descriptor
  */
 
 /**
+ * Returns a dtstype description for a given dtstype ID
  * @function getDTSysDescr
  * @param {(number|string)} value - DTS-type identifier
  * @returns {DTSysDescr}
- * @description Returns a dtstype description for a given dtstype ID
  */
 function getDTSysDescr(value) {
   let index = valueToIndex(value);
@@ -84,12 +84,12 @@ function getDTSysDescr(value) {
 };
 
 /**
+ * Tries to convert a given string to timestamp
  * @function convStringToDTValue
  * @param {string} value - some value
  * @param {(number|string)} [dts_id=0] - DTS-type identifier
  * @param {(number|string)} [tz] - <*reserved*>
  * @returns {number}
- * @description Tries to convert a given string to timestamp
  * @todo check TZ
  */
 function convStringToDTValue(value, dts_id = 0, tz) {
@@ -150,12 +150,12 @@ function convStringToDTValue(value, dts_id = 0, tz) {
 };
 
 /**
+ * Tries to convert a given value to its string representation
  * @function convDTValueToString
  * @param {(number|string|Date)} value - some value
  * @param {(number|string)} [dts_id=0] - DTS-type identifier
  * @param {(number|string)} [tz] - <*reserved*>
  * @returns {string}
- * @description Tries to convert a given value to its string representation
  * @todo check TZ
  */
 function convDTValueToString(value, dts_id, tz) {