@ygracs/xepg-lib-js 0.0.26-b → 0.0.30

package/CHANGELOG.md

@@ -1,10 +1,23 @@
-#### *v0.0.xx*
+#### *v0.0.30*
 
 Pre-release version.
 
-> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+> - update `xepgdoc-lib.md`;
+> - update dependency on `@ygracs/xml-js6` module to v0.0.9-b;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.4;
 > - update dependency on `@ygracs/dtf-lib-js` module to v0.0.33;
-> - update dependency on `@cntwg/file-helper` module to v0.0.3;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.3.3;
+> - update dependency on `@cntwg/file-helper` module to v0.0.4;
+> - add new class: `TXmlContentDeclaration`;
+> - (`TXEpgContentProvider`) change behavior for methods: `loadFromFile`, `loadFromFileSync`;
+> - (`TXEpgContentProvider`) remove deprecated properties: `SchedulesList`;
+> - (`TXEpgHeaderContainer`) remove deprecated methods: `setProviderInfo`, `setChannelInfo`;
+> - (`TXEpgProviderContainer`) change behavior for methods: `init`;
+> - (`TXEpgChannelContainer`) change behavior for methods: `setInfo`;
+> - (`TXEpgSchedulesList`) add new methods: `checkIndex`;
+> - (`TXEpgSchedulesList`) deprecate methods: `chkIndex`;
+> - (`TXEpgSchedulesList`) remove deprecated methods: `hasSchedules`, `hasNoSchedules`;
+> - other fixes.
 
 #### *v0.0.25*
 

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.11|
+|***rev.*:**|0.0.12|
 |:---|---:|
-|***date***:|2025-08-25|
+|***date***:|2026-06-12|
 
 ## Introduction
 
@@ -48,3 +48,5 @@ For more read the `xepgdoc-lib.md` in the project `doc` directory.
 ### Installation
 
 `npm install @ygracs/xepg-lib-js`
+
+> Note: It's recommended to "pin" a package versions range to its minor releases after installation. To do so use `~` range specifier (*e.g. `~0.0.30`*) in `package.json`.

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.43|
+|***rev.*:**|0.1.46|
 |:---|---:|
-|***date***:|2025-08-25|
+|***date***:|2026-06-12|
 
 ## Introduction
 
@@ -322,11 +322,6 @@ The class constructor receives arguments listed below:
 
 #### class methods
 
-<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`
 
@@ -334,11 +329,6 @@ The class constructor receives arguments listed below:
 
 This method returns `true` if a document contains no schedules.
 
-<a name="TXEpgSchedulesList+hasSchedules"></a>
-##### **hasSchedules()** => `boolean`
-
-> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`isNotEmpty` method](#TXEpgSchedulesList+isNotEmpty) instead.
-
 <a name="TXEpgSchedulesList+isNotEmpty"></a>
 ##### **isNotEmpty()** => `boolean`
 
@@ -351,11 +341,18 @@ This method returns `true` if a document contains at least one schedule.
 
 > since: `v0.0.20`
 
-This method checks if a given `value` represents a valid schedule index and if so returns `true`.
+> WARNING: \[since `v0.0.30`] this method deprecated (*use [`checkIndex`](#TXEpgSchedulesList+checkIndex) method instead*).
+
+<a name="TXEpgSchedulesList+checkIndex"></a>
+##### **checkIndex(value)** => `boolean`
+
+> since: \[`v0.0.30`]
+
+This method checks if the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so `true` is returned.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `value` | `number`, `string` | --- | a value to be verified |
+| `value` | `number` or `string` | --- | a value to be verified |
 
 <a name="TXEpgSchedulesList+schedule"></a>
 ##### **schedule(index)** => `TXEpgScheduleItem`
@@ -523,8 +520,8 @@ 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 |
 
 #### class properties
 
@@ -739,45 +736,11 @@ An object contains the following fields:
 |`chname`|`string`|a name of the channel|
 |`srcurl`|`string`|a link to source|
 
-<a name="TXEpgHeaderContainer+setChannelInfo"></a>
-##### **setChannelInfo(obj)** => `void`
-
-> \[!] WARNING: `[since v0.0.22]` deprecated. Use [`TXEpgChannelContainer.setInfo()`](#TXEpgChannelContainer+setInfo) instead.
-
-This method fills a channel information with a given data.
-
-| parameter name | value type | default value | description |
-|:---|---|---:|:---|
-| `obj` | `xepgChnInfoDesc` | --- | channel info descriptor |
-
-> \[!] NOTE: `[since v0.0.21]` a use of a `string` or `array` types a as values of an `obj` are deprecated and will be dropped soon.
-
-The `obj` parameter can be a string or an array or an object.
-
-If a string is given it mean to contains the `chnid` value.
-
-If an array is given it contains the following fields:
-
-`[ <chnid>, <chname>, <chngid>, <srcurl> ]`
-
-If an object is given it contains the following fields:
-
-|field name|field type|description|
-|:---|---|:---|
-|`chnid`|`string`|a channel ID|
-|`chname`|`string`|a name of the channel|
-|`chngid`|`string`|a channel group|
-|`srcurl`|`string`|a link to source|
-
 <a name="TXEpgHeaderContainer+getProviderInfo"></a>
 ##### **getProviderInfo()** => `xepgProvInfoDesc`
 
 This method returns an object which contains an information about document provider.
 
-##### **setProviderInfo(obj)**
-
-> \[!] WARNING: `[since v0.0.24]` deprecated. Use [`TXEpgProviderContainer.setInfo()`](#TXEpgProviderContainer+setInfo) instead.
-
 <a name="TXEpgHeaderContainer+saveToXMLString"></a>
 ##### **saveToXMLString()** => `string`
 
@@ -804,6 +767,60 @@ This method loads an element content from a string given by a `str` parameter.
 
 This methods throws `Error` if something goes wrong through a parsing process of a string.
 
+<a name="TXmlContentDeclaration"></a>
+### **TXmlContentDeclaration**
+
+> since: `v0.0.30`
+
+This class implements a proxy interface for a document declaration element.
+
+#### class constructor
+
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | a host object for the document content |
+| `options` | `object` | --- | an options settings |
+
+###### `options` parameter
+
+The `options` structure is listed below:
+
+| option name | value type | default value | description |
+|:---|---|---:|:---|
+| `parseOptions` | `object` | `EMPTY_OBJECT` | contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`) |
+
+##### exceptions
+
+If `object` parameter is not a type of `object` or not given a `TypeError` thrown.
+
+#### class properties
+
+<a name="TXmlContentDeclaration+version"></a>
+##### **version**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | returns a version of an XML |
+
+<a name="TXmlContentDeclaration+encoding"></a>
+##### **encoding**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | returns a name of the character set used by the document |
+
+#### class methods (*special*)
+
+##### **init()** => `void`
+
+This method initializes an element with a default values.
+
 <a name="TXEpgContentProvider"></a>
 ### **TXEpgContentProvider**
 
@@ -853,11 +870,6 @@ The `options` structure is listed below:
 |---|---|:---|
 | `TXEpgDTSProvider` | yes | returns a `TXEpgDTSProvider` instance |
 
-<a name="TXEpgContentProvider+SchedulesList"></a>
-##### **SchedulesList**
-
-> \[!] NOTE: `[since v0.0.24]` deprecated. Use [`schedules` property](#TXEpgContentProvider+schedules) instead.
-
 <a name="TXEpgContentProvider+schedules"></a>
 ##### **schedules**
 

package/index.d.ts

@@ -1,21 +1,27 @@
-import {
-  TXmlContentParseOptions,
-} from "@ygracs/xobj-lib-js";
-
-import {
-  TXEpgContentProvider,
-  TXEpgScheduleItem, TXEpgSchedulesList,
-  TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
-} from "./lib/xepgdoc-lib";
-
-import {
-  readAsTagName, readAsAttrName, readAsAttrValue, valueToElementID,
-} from "./lib/xml-base";
-
-export {
-  TXEpgContentProvider,
-  TXEpgScheduleItem, TXEpgSchedulesList,
-  TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
-  readAsTagName, readAsAttrName, readAsAttrValue, valueToElementID,
-  TXmlContentParseOptions,
-};
+import { TXEpgScheduleItem } from "./lib/xepg-sched";
+import { TXEpgSchedulesList } from "./lib/xepg-sched";
+import { TXEpgChannelContainer } from "./lib/xepg-channel";
+
+import {
+  TXmlContentParseOptions,
+} from "@ygracs/xobj-lib-js";
+
+import {
+  TXEpgContentProvider,
+  TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
+  TXmlContentDeclaration,
+} from "./lib/xepgdoc-lib";
+
+import {
+  readAsTagName, readAsAttrName, readAsAttrValue, valueToElementID,
+} from "./lib/xml-base";
+
+export {
+  TXEpgContentProvider,
+  TXEpgScheduleItem, TXEpgSchedulesList,
+  TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
+  TXEpgChannelContainer,
+  TXmlContentDeclaration,
+  readAsTagName, readAsAttrName, readAsAttrValue, valueToElementID,
+  TXmlContentParseOptions,
+};

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.014-20250825]
+// [v0.1.017-20260531]
 
 // === module init block ===
 
@@ -8,6 +8,14 @@ const xObj = require('@ygracs/xobj-lib-js');
 
 const xmlBase = require('./lib/xml-base');
 
+const {
+  TXEpgScheduleItem, TXEpgSchedulesList,
+} = require('./lib/xepg-sched');
+
+const {
+  TXEpgChannelContainer,
+} = require('./lib/xepg-channel');
+
 // === module inner block ===
 
 // === module main block ===
@@ -15,12 +23,14 @@ const xmlBase = require('./lib/xml-base');
 // === module exports block ===
 
 /**/// v1 branch
+module.exports.TXEpgScheduleItem = TXEpgScheduleItem;
+module.exports.TXEpgSchedulesList = TXEpgSchedulesList;
+module.exports.TXEpgChannelContainer = TXEpgChannelContainer;
 module.exports.TXEpgContentProvider = xepgdoc.TXEpgContentProvider;
-module.exports.TXEpgScheduleItem = xepgdoc.TXEpgScheduleItem;
-module.exports.TXEpgSchedulesList = xepgdoc.TXEpgSchedulesList;
 module.exports.TXEpgDTSProvider = xepgdoc.TXEpgDTSProvider;
 module.exports.TXEpgProviderContainer = xepgdoc.TXEpgProviderContainer;
 module.exports.TXEpgHeaderContainer = xepgdoc.TXEpgHeaderContainer;
+module.exports.TXmlContentDeclaration = xepgdoc.TXmlContentDeclaration;
 
 module.exports.readAsTagName = xmlBase.readAsTagName;
 module.exports.readAsAttrName = xmlBase.readAsAttrName;

package/lib/dts-helper.d.ts

@@ -1,37 +1,53 @@
-/**
- * A 'DTS'-type descriptor
- */
-export type DTSysDescr = {
-    /**
-     * - dtstype ID
-     */
-    index: number;
-    /**
-     * - dtstype name
-     */
-    name: string;
-};
-
-/**
- * Checks if a given value is a valid dtstype ID
- */
-export function chkDTSysID(value: number | string): boolean;
-/**
- * Returns a dtstype name by a given dtstype ID
- */
-export function getDTSysName(value: number | string): string;
-/**
- * Returns a dtstype description for a given dtstype ID
- */
-export function getDTSysDescr(value: number | string): DTSysDescr;
-/**
- * Tries to convert a given string to timestamp
- * @todo check TZ
- */
-export function convStringToDTValue(value: string, dts_id?: number | string, tz?: number | string): number;
-/**
- * Tries to convert a given value to its string representation
- * @todo check TZ
- */
-export function convDTValueToString(value: number | string | Date, dts_id?: number | string, tz?: number | string): string;
-export { chkDTSysID as checkDTSysID };
+/**
+ * A 'DTS'-type descriptor
+ */
+export type IDTSysDescr = {
+    /**
+     * - dtstype ID
+     */
+    index: number;
+    /**
+     * - dtstype name
+     */
+    name: string;
+};
+export const IDTSysDescr: IDTSysDescr;
+
+/**
+ *
+ * @inner
+ */
+export function _getDTSTypeValueForXObj(obj: object | null, parseOptions?: object): number;
+/**
+ *
+ * @inner
+ */
+export function _getTZSrcValueFromXObj(obj: object | null, parseOptions?: object): number;
+/**
+ * Checks if a given value is a valid dtstype ID
+ * @deprecated
+ * @todo \[since `v0.0.25`] deprecated. Use {@link checkDTSysID} instead
+ */
+export function chkDTSysID(value: number | string): boolean;
+/**
+ * Checks if a given value is a valid dtstype ID
+ */
+export function checkDTSysID(value: number | string): boolean;
+/**
+ * Returns a dtstype name by a given dtstype ID
+ */
+export function getDTSysName(value: number | string): string;
+/**
+ * Returns a dtstype description for a given dtstype ID
+ */
+export function getDTSysDescr(value: number | string): IDTSysDescr;
+/**
+ * Tries to convert a given string to timestamp
+ * @todo check TZ
+ */
+export function convStringToDTValue(value: string, dts_id?: number | string, tz?: number | string): number;
+/**
+ * Tries to convert a given value to its string representation
+ * @todo check TZ
+ */
+export function convDTValueToString(value: number | string | Date, dts_id?: number | string, tz?: number | string): string;

package/lib/dts-helper.js

@@ -1,71 +1,116 @@
-// [v0.1.049-20260101]
+// [v0.1.053-20260531]
 
 // === module init block ===
 
 const {
   valueToIndex,
+  readAsNumber,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
+  isDateObject,
   convDTValueToISO8601,
   convDTValueToXMLTV, convXMLTVToDTValue,
   convDTValueToDateString,
   tryDTValue,
 } = require('@ygracs/dtf-lib-js');
 
-// === module extra block (helper functions) ===
+const {
+  _getXmlChildElementParam,
+} = require('./xml-base');
 
-// === module main block ===
+// === module inner block ===
 
-/***
- * (* constant definitions *)
+/**
+ * @param {?object} obj - element
+ * @param {object} [parseOptions]  - parser options
+ * @returns {number}
+ * @inner
  */
+function _getDTSTypeValueForXObj(obj, parseOptions) {
+  const result = valueToIndex(
+    _getXmlChildElementParam(obj, 'value', parseOptions)
+  );
+  return checkDTSysID(result) ? result : 0; //-1; // // TODO: [?]
+};
+module.exports._getDTSTypeValueForXObj = _getDTSTypeValueForXObj;
+
+/**
+ *
+ * @param {?object} obj - element
+ * @param {object} [parseOptions]  - parser options
+ * @returns {number}
+ * @inner
+ */
+function _getTZSrcValueFromXObj(obj, parseOptions) {
+  return readAsNumber(_getXmlChildElementParam(obj, 'value', parseOptions));
+};
+module.exports._getTZSrcValueFromXObj = _getTZSrcValueFromXObj;
+
+// === module main block ===
 
 const def_dts_param = [
   'default', 'iso8601', 'xmltv', 'timestamp', 'utc',
 ];
 
-/***
- * (* function definitions *)
- */
-
 /**
  * Checks if a given value is a valid dtstype ID
  * @function chkDTSysID
- * @param {(number|string)} value - value to verify
+ * @param {number|string} value - value to verify
  * @returns {boolean}
+ * @deprecated
+ * @todo \[since `v0.0.25`] deprecated. Use {@link checkDTSysID} instead
  */
 function chkDTSysID(value) {
   const _value = valueToIndex(value);
   return _value !== -1 && def_dts_param[_value] ? true : false;
 };
+module.exports.chkDTSysID = chkDTSysID;
+
+/**
+ * Checks if a given value is a valid dtstype ID
+ * @function checkDTSysID
+ * @param {number|string} value - value to verify
+ * @returns {boolean}
+ */
+function checkDTSysID(value) {
+  const _value = valueToIndex(value);
+  return _value !== -1 && def_dts_param[_value] ? true : false;
+};
+module.exports.checkDTSysID = checkDTSysID;
 
 /**
  * Returns a dtstype name by a given dtstype ID
  * @function getDTSysName
- * @param {(number|string)} value - DTS-type identifier
+ * @param {number|string} value - DTS-type identifier
  * @returns {string}
  */
 function getDTSysName(value) {
   let result = 'undefined';
-  if (chkDTSysID(value)) {
+  if (checkDTSysID(value)) {
     result = def_dts_param[Number(value)];
   };
   return result;
 };
+module.exports.getDTSysName = getDTSysName;
 
 /**
  * A 'DTS'-type descriptor
- * @typedef {Object} DTSysDescr
+ * @typedef {Object} IDTSysDescr
  * @property {number} index - dtstype ID
  * @property {string} name - dtstype name
  */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IDTSysDescr}
+ */
+module.exports.IDTSysDescr = { index: 0, name: '' };
 
 /**
  * Returns a dtstype description for a given dtstype ID
  * @function getDTSysDescr
- * @param {(number|string)} value - DTS-type identifier
- * @returns {DTSysDescr}
+ * @param {number|string} value - DTS-type identifier
+ * @returns {IDTSysDescr}
  */
 function getDTSysDescr(value) {
   let index = valueToIndex(value);
@@ -82,13 +127,14 @@ function getDTSysDescr(value) {
   };
   return { index, name };
 };
+module.exports.getDTSysDescr = getDTSysDescr;
 
 /**
  * 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*>
+ * @param {number|string} [dts_id=0] - DTS-type identifier
+ * @param {number|string} [tz] - <*reserved*>
  * @returns {number}
  * @todo check TZ
  */
@@ -118,8 +164,8 @@ function convStringToDTValue(value, dts_id = 0, tz) {
       case 'xmltv': {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[xmltv]');
-        const dtValue = convXMLTVToDTValue(value, true);
-        if (dtValue !== null) result = dtValue;
+        const dt = convXMLTVToDTValue(value, true);
+        if (dt !== null) result = isDateObject(dt) ? dt.getTime() : dt;
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
@@ -148,13 +194,14 @@ function convStringToDTValue(value, dts_id = 0, tz) {
   };
   return result;
 };
+module.exports.convStringToDTValue = convStringToDTValue;
 
 /**
  * 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*>
+ * @param {number|string|Date} value - some value
+ * @param {number|string} [dts_id=0] - DTS-type identifier
+ * @param {number|string} [tz] - <*reserved*>
  * @returns {string}
  * @todo check TZ
  */
@@ -163,13 +210,13 @@ function convDTValueToString(value, dts_id, tz) {
   let dt_val = isSucceed && dtValue != null ? dtValue.getTime() : new Date(0);
   let result = '';
   let dtstype = valueToIndex(dts_id);
-  if (!chkDTSysID(dtstype)) dtstype = 0;
+  if (!checkDTSysID(dtstype)) dtstype = 0;
   switch (getDTSysName(dtstype)) {
     case 'default': {
       // TODO: check TZ
       //console.log('convDTValueToString => dtstype:[default]');
       result = convDTValueToDateString(dt_val, {
-        src_in_utc: false,
+        //src_in_utc: false,
       });
       //console.log('convDTValueToString => value:['+value+']');
       //console.log('convDTValueToString => result:['+result+']');
@@ -179,9 +226,7 @@ function convDTValueToString(value, dts_id, tz) {
       // TODO: check TZ
       //console.log('convDTValueToString => dtstype:[iso8601]');
       result = convDTValueToISO8601(dt_val, {
-        //use_bs_format: false,
         useBaseFormat: false,
-        src_in_utc: false,
       });
       //console.log('convDTValueToString => value:['+value+']');
       //console.log('convDTValueToString => result:['+result+']');
@@ -190,9 +235,7 @@ function convDTValueToString(value, dts_id, tz) {
     case 'xmltv': {
       // TODO: check TZ
       //console.log('convDTValueToString => dtstype:[xmltv]');
-      result = convDTValueToXMLTV(dt_val, {
-        src_in_utc: false,
-      });
+      result = convDTValueToXMLTV(dt_val, {});
       //console.log('convDTValueToString => value:['+value+']');
       //console.log('convDTValueToString => result:['+result+']');
       break;
@@ -209,16 +252,4 @@ function convDTValueToString(value, dts_id, tz) {
   };
   return result;
 };
-
-/***
- * (* class definitions *)
- */
-
-// === module exports block ===
-
-exports.chkDTSysID = chkDTSysID;
-exports.checkDTSysID = chkDTSysID;
-exports.getDTSysName = getDTSysName;
-exports.getDTSysDescr = getDTSysDescr;
-exports.convStringToDTValue = convStringToDTValue;
-exports.convDTValueToString = convDTValueToString;
+module.exports.convDTValueToString = convDTValueToString;