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

package/CHANGELOG.md

@@ -1,18 +1,23 @@
-#### *v0.0.xx*
+#### *v0.0.30*
 
 Pre-release version.
 
 > - update `xepgdoc-lib.md`;
-> - update dependency on `@ygracs/xml-js6` module to v0.0.8-b;
-> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+> - 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 `@ygracs/xobj-lib-js` module to v0.3.0;
-> - 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.45|
+|***rev.*:**|0.1.46|
 |:---|---:|
-|***date***:|2026-03-05|
+|***date***:|2026-06-12|
 
 ## Introduction
 
@@ -341,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`
@@ -513,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
 
@@ -763,7 +770,7 @@ This methods throws `Error` if something goes wrong through a parsing process of
 <a name="TXmlContentDeclaration"></a>
 ### **TXmlContentDeclaration**
 
-> since: `v0.0.2x`
+> since: `v0.0.30`
 
 This class implements a proxy interface for a document declaration element.
 

package/index.d.ts

@@ -1,10 +1,13 @@
+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,
-  TXEpgScheduleItem, TXEpgSchedulesList,
   TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
   TXmlContentDeclaration,
 } from "./lib/xepgdoc-lib";
@@ -17,6 +20,7 @@ export {
   TXEpgContentProvider,
   TXEpgScheduleItem, TXEpgSchedulesList,
   TXEpgDTSProvider, TXEpgProviderContainer, TXEpgHeaderContainer,
+  TXEpgChannelContainer,
   TXmlContentDeclaration,
   readAsTagName, readAsAttrName, readAsAttrValue, valueToElementID,
   TXmlContentParseOptions,

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.015-20260304]
+// [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,9 +23,10 @@ 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;

package/lib/dts-helper.d.ts

@@ -1,7 +1,7 @@
 /**
  * A 'DTS'-type descriptor
  */
-export type DTSysDescr = {
+export type IDTSysDescr = {
     /**
      * - dtstype ID
      */
@@ -11,11 +11,28 @@ export type DTSysDescr = {
      */
     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
  */
@@ -23,7 +40,7 @@ export function getDTSysName(value: number | string): string;
 /**
  * Returns a dtstype description for a given dtstype ID
  */
-export function getDTSysDescr(value: number | string): DTSysDescr;
+export function getDTSysDescr(value: number | string): IDTSysDescr;
 /**
  * Tries to convert a given string to timestamp
  * @todo check TZ
@@ -34,4 +51,3 @@ export function convStringToDTValue(value: string, dts_id?: number | string, tz?
  * @todo check TZ
  */
 export function convDTValueToString(value: number | string | Date, dts_id?: number | string, tz?: number | string): string;
-export { chkDTSysID as checkDTSysID };

package/lib/dts-helper.js

@@ -1,9 +1,10 @@
-// [v0.1.050-20260201]
+// [v0.1.053-20260531]
 
 // === module init block ===
 
 const {
   valueToIndex,
+  readAsNumber,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
@@ -14,59 +15,102 @@ const {
   tryDTValue,
 } = require('@ygracs/dtf-lib-js');
 
+const {
+  _getXmlChildElementParam,
+} = require('./xml-base');
+
 // === module inner block ===
 
-// === module main block ===
+/**
+ * @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;
 
-/***
- * (* constant definitions *)
+/**
+ *
+ * @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);
@@ -83,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
  */
@@ -149,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
  */
@@ -164,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+']');
@@ -180,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+']');
@@ -191,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;
@@ -210,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;

package/lib/xepg-channel.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @deprecated
+ */
+export type setInfoParam = string;
+export const setInfoParam: setInfoParam;
+/**
+ * A channel info descriptor
+ */
+export type IXEpgChnInfoDesc = {
+    /**
+     * - channel ID
+     */
+    chnid: string;
+    /**
+     * - channel name
+     */
+    chname: string;
+    /**
+     * - channel 'Group ID'
+     */
+    chngid?: string;
+    /**
+     * - EPG-source URL
+     */
+    srcurl?: string;
+};
+export const IXEpgChnInfoDesc: IXEpgChnInfoDesc;
+/**
+ * An XEPG-element options set (base)
+ */
+export type OPT_epgelsett_bs = {
+    /**
+     * - parser options
+     */
+    parseOptions?: InstanceType<typeof TXmlContentParseOptions>;
+};
+/**
+ * An XEPG-element options set (base)
+ */
+export type XEpgElementConfigBase = {
+    /**
+     * - parser options
+     */
+    parseOptions: InstanceType<typeof TXmlContentParseOptions>;
+};
+
+/**
+ * This class implements an interface of a channel element
+ * @since 0.0.22
+ */
+export class TXEpgChannelContainer {
+    /**
+     * Creates an instance of the channel element
+     */
+    constructor(obj: INode, opt?: OPT_epgelsett_bs);
+    /**
+     * Contains a channel ID
+     */
+    get id(): string;
+    /**
+     * Contains a channel name
+     */
+    get name(): string;
+    set name(value: string);
+    /**
+     * Contains a channel Group ID
+     */
+    get gid(): string;
+    set gid(value: string);
+    /**
+     * Contains a channel source URL
+     */
+    get url(): string;
+    set url(value: string);
+    /**
+     * Tries to set a channel ID
+     */
+    setID(value: string): boolean;
+    /**
+     * Returns a channel info
+     */
+    getInfo(): IXEpgChnInfoDesc;
+    /**
+     * Sets a channel info
+     */
+    setInfo(obj: setInfoParam | IXEpgChnInfoDesc): void;
+    #private;
+}
+
+import { TXmlContentParseOptions } from "@ygracs/xobj-lib-js";
+import type { INode } from "@ygracs/xobj-lib-js";