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

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+#### *v0.0.xx*
+
+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/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;
+> - add new class: `TXmlContentDeclaration`;
+> - (`TXEpgContentProvider`) change behavior for methods: `loadFromFile`, `loadFromFileSync`;
+> - (`TXEpgContentProvider`) remove deprecated properties: `SchedulesList`;
+> - (`TXEpgHeaderContainer`) remove deprecated methods: `setProviderInfo`, `setChannelInfo`;
+> - (`TXEpgSchedulesList`) remove deprecated methods: `hasSchedules`, `hasNoSchedules`;
+
 #### *v0.0.25*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2025 Yuri Grachev
+Copyright (c) 2019-2026 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.43|
+|***rev.*:**|0.1.45|
 |:---|---:|
-|***date***:|2025-08-25|
+|***date***:|2026-03-05|
 
 ## 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`
 
@@ -739,45 +729,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 +760,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.2x`
+
+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 +863,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

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

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.014-20250825]
+// [v0.1.015-20260304]
 
 // === module init block ===
 
@@ -21,6 +21,7 @@ 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

@@ -0,0 +1,37 @@
+/**
+ * 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 };

package/lib/dts-helper.js

@@ -1,4 +1,4 @@
-// [v0.1.048-20250727]
+// [v0.1.050-20260201]
 
 // === module init block ===
 
@@ -7,13 +7,14 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
+  isDateObject,
   convDTValueToISO8601,
   convDTValueToXMLTV, convXMLTVToDTValue,
   convDTValueToDateString,
   tryDTValue,
 } = require('@ygracs/dtf-lib-js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -118,8 +119,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;
@@ -128,7 +129,7 @@ function convStringToDTValue(value, dts_id = 0, tz) {
         // TODO: check TZ
         //console.log('convStringToDTValue => dtstype:[timestamp]');
         const { isSucceed, value: dtValue } = tryDTValue(value);
-        if (isSucceed) result = dtValue.getTime();
+        if (isSucceed && dtValue != null) result = dtValue.getTime();
         //console.log('convStringToDTValue => value:['+value+']');
         //console.log('convStringToDTValue => result:['+result+']');
         break;
@@ -160,7 +161,7 @@ function convStringToDTValue(value, dts_id = 0, tz) {
  */
 function convDTValueToString(value, dts_id, tz) {
   let { isSucceed, value: dtValue } = tryDTValue(value);
-  let dt_val = isSucceed ? dtValue.getTime() : new Date(0);
+  let dt_val = isSucceed && dtValue != null ? dtValue.getTime() : new Date(0);
   let result = '';
   let dtstype = valueToIndex(dts_id);
   if (!chkDTSysID(dtstype)) dtstype = 0;