@ygracs/xepg-lib-js 0.0.23 → 0.0.25

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+#### *v0.0.25*
+
+Pre-release version.
+
+> - update `xepgdoc-lib.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0;
+> - update dependency on `@ygracs/dtf-lib-js` module to v0.0.30;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.4;
+> - move some functions from `$lib/xepgdoc-lib.js` into new `$lib/xml-base.js` module;
+> - add function: `readAsAttrValue`;
+> - (`TXEpgHeaderContainer`) remove deprecated property: `Provider`;
+> - (`TXEpgContentProvider`) remove deprecated properties: `Header`, `Provider`.
+
+#### *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.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.9|
+|***rev.*:**|0.0.11|
 |:---|---:|
-|***date***:|2025-03-06|
+|***date***:|2025-08-25|
 
 ## Introduction
 
@@ -12,10 +12,17 @@ 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`;
+	+ `readAsAttrValue`;
+	+ `valueToElementID`;
+
 - classes:
 
 	+ `TXEpgScheduleItem`;

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.28|
+|***rev.*:**|0.1.43|
 |:---|---:|
-|***date***:|2025-04-24|
+|***date***:|2025-08-25|
 
 ## Introduction
 
@@ -91,6 +91,17 @@ This function tries to convert a given `value` to the value of type which is sui
 |:---|---|---:|:---|
 | `value` | `any` | --- | some value to read |
 
+<a name="readAsAttrValue"></a>
+#### **readAsAttrValue(value)** => `string`
+
+> since: \[`v0.0.25`]
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's attribute. If failed a `null` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+
 <a name="valueToElementID"></a>
 #### **valueToElementID(value)**
 
@@ -115,14 +126,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
 
@@ -232,6 +248,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**
 
@@ -241,20 +276,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 |
@@ -278,16 +325,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.
 
-##### **chkScheduleIndex(value)** => `boolean`
+<a name="TXEpgSchedulesList+isNotEmpty"></a>
+##### **isNotEmpty()** => `boolean`
 
-> WARNING: This method deprecated (*since `v0.0.20`*). Use `chkIndex` instead.
+> since: `v0.0.24`
+
+This method returns `true` if a document contains at least one schedule.
 
 <a name="TXEpgSchedulesList+chkIndex"></a>
 ##### **chkIndex(value)** => `boolean`
@@ -338,14 +395,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:
 
@@ -422,6 +483,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()**
@@ -601,11 +681,6 @@ The `options` structure is listed below:
 |---|---|:---|
 | `number` | no | defines a current TimeZone |
 
-<a name="TXEpgHeaderContainer+Provider"></a>
-##### **Provider**
-
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgHeaderContainer+provider) instead.
-
 <a name="TXEpgHeaderContainer+provider"></a>
 ##### **provider**
 
@@ -667,7 +742,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.
 
@@ -701,6 +776,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`
 
@@ -708,6 +785,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**
 
@@ -732,11 +828,6 @@ The `options` structure is listed below:
 
 #### class properties
 
-<a name="TXEpgContentProvider+Header"></a>
-##### **Header**
-
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`header` property](#TXEpgContentProvider+header) instead.
-
 <a name="TXEpgContentProvider+header"></a>
 ##### **header**
 
@@ -746,11 +837,6 @@ The `options` structure is listed below:
 |---|---|:---|
 | `TXEpgHeaderContainer` | yes | returns a `TXEpgHeaderContainer` instance |
 
-<a name="TXEpgContentProvider+Provider"></a>
-##### **Provider**
-
-> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgContentProvider+provider) instead.
-
 <a name="TXEpgContentProvider+provider"></a>
 ##### **provider**
 
@@ -770,6 +856,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 |
@@ -790,10 +883,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.014-20250825]
 
 // === module init block ===
 
@@ -6,7 +6,9 @@ const xepgdoc = require('./lib/xepgdoc-lib.js');
 
 const xObj = require('@ygracs/xobj-lib-js');
 
-// === module extra block (helper functions) ===
+const xmlBase = require('./lib/xml-base');
+
+// === module inner block ===
 
 // === module main block ===
 
@@ -20,8 +22,10 @@ module.exports.TXEpgDTSProvider = xepgdoc.TXEpgDTSProvider;
 module.exports.TXEpgProviderContainer = xepgdoc.TXEpgProviderContainer;
 module.exports.TXEpgHeaderContainer = xepgdoc.TXEpgHeaderContainer;
 
+module.exports.readAsTagName = xmlBase.readAsTagName;
+module.exports.readAsAttrName = xmlBase.readAsAttrName;
+module.exports.readAsAttrValue = xmlBase.readAsAttrValue;
+module.exports.valueToElementID = xmlBase.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) {