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

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+#### *v0.0.xx*
+
+Pre-release version.
+
+> - 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 `@cntwg/file-helper` module to v0.0.3;
+
+#### *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.

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/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.10|
+|***rev.*:**|0.0.11|
 |:---|---:|
-|***date***:|2025-07-30|
+|***date***:|2025-08-25|
 
 ## Introduction
 
@@ -20,6 +20,7 @@ This module contains the following components:
 
 	+ `readAsTagName`;
 	+ `readAsAttrName`;
+	+ `readAsAttrValue`;
 	+ `valueToElementID`;
 
 - classes:

package/doc/xepgdoc-lib.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.40|
+|***rev.*:**|0.1.43|
 |:---|---:|
-|***date***:|2025-07-30|
+|***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)**
 
@@ -670,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**
 
@@ -822,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**
 
@@ -836,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**
 

package/index.d.ts

@@ -0,0 +1,21 @@
+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,
+};

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.011-20250727]
+// [v0.1.014-20250825]
 
 // === module init block ===
 
@@ -6,6 +6,8 @@ const xepgdoc = require('./lib/xepgdoc-lib.js');
 
 const xObj = require('@ygracs/xobj-lib-js');
 
+const xmlBase = require('./lib/xml-base');
+
 // === module inner block ===
 
 // === module main block ===
@@ -20,9 +22,10 @@ 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;
+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;

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.049-20260101]
 
 // === module init block ===
 
@@ -128,7 +128,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 +160,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;

package/lib/xepgdoc-lib.d.ts

@@ -0,0 +1,596 @@
+/**
+ * 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>;
+};
+/**
+ * A schedule info descriptor
+ */
+export type xepgShedInfoDesc = {
+    /**
+     * - a schedule start time
+     */
+    time: number;
+    /**
+     * - schedule title
+     */
+    title: string;
+    /**
+     * - schedule category
+     */
+    cat?: string;
+    /**
+     * - schedule rating
+     */
+    pcmark?: number;
+    /**
+     * - schedule description
+     */
+    descr?: string;
+};
+/**
+ * An extra options set
+ */
+export type OPT_extra = {
+    /**
+     * - 'DTS'-settings
+     */
+    dts_src?: object;
+    /**
+     * - 'TZ'-settings
+     */
+    tz_src?: object;
+};
+/**
+ * An XEPG-element options set (extend)
+ */
+export type OPT_epgelsett_ex = {
+    /**
+     * - parser options
+     */
+    parseOptions?: InstanceType<typeof TXmlContentParseOptions>;
+    dts_src?: object;
+    tz_src?: object;
+};
+/**
+ * A provider info descriptor
+ */
+export type xepgProvInfoDesc = {
+    /**
+     * - provider name
+     */
+    name?: string;
+    /**
+     * - provider version
+     */
+    version?: string;
+    /**
+     * - document schema
+     */
+    schema: string;
+    /**
+     * - document type
+     */
+    doctype: string;
+};
+/**
+ * A channel info descriptor
+ */
+export type xepgChnInfoDesc = {
+    /**
+     * - channel ID
+     */
+    chnid: string;
+    /**
+     * - channel name
+     */
+    chname: string;
+    /**
+     * - channel 'Group ID'
+     */
+    chngid?: string;
+    /**
+     * - EPG-source URL
+     */
+    srcurl?: string;
+};
+
+/**
+ * An options set for `TXEpgContentProvider`-class
+ */
+export type OPT_epgcpsett = {
+    /**
+     * - parser options
+     */
+    parseOptions?: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - <*deprecated*>
+     */
+    autoBindRoot?: boolean;
+};
+/**
+ * An options set for `TXEpgContentProvider`-class
+ */
+export type XEpgContainerSettings = {
+    /**
+     * - parser options
+     */
+    parseOptions: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - <*deprecated*>
+     */
+    autoBindRoot?: boolean | undefined;
+};
+export const XEPG_DEF_PROVIDER_NAME: "xepg-lib-js";
+export const XEPG_DEF_PROVIDER_VER: "0.0.21";
+export const XEPG_DEF_DOCUMENT_TYPE: "xepg";
+export const XEPG_DEF_DOCUMENT_SCHEMA: string;
+/**
+ * @classdesc This class implements an interface of a DTS-provider element
+ */
+export class TXEpgDTSProvider {
+    /**
+     * Creates an instance of the DTS-provider element
+     */
+    constructor(obj: object, opt?: OPT_epgelsett_bs);
+    /**
+     * Contains a dtstype ID
+     */
+    get dtstype(): number;
+    set dtstype(value: number);
+    /**
+     * Contains a TZ-offset
+     */
+    get curDocTZ(): number;
+    set curDocTZ(value: number);
+    /**
+     * Tries to set a `DTS`-type
+     * @since 0.0.22
+     */
+    setType(value: any): boolean;
+    #private;
+}
+
+/**
+ * @since 0.0.22
+ * @classdesc This class implements an interface of a EPG-schedule element
+ */
+export class TXEpgScheduleItem {
+    /**
+     * Creates an instance of the EPG-schedule element
+     */
+    constructor(obj: object, opt?: OPT_epgelsett_ex, extra?: OPT_extra);
+    /**
+     * Contains a dtstype ID
+     */
+    get dtstype(): number;
+    /**
+     * Contains a TZ-offset
+     */
+    get curDocTZ(): number;
+    /**
+     * Contains a schedule start time as a timestamp
+     */
+    get time(): number;
+    /**
+     * Contains a schedule title
+     */
+    get title(): string;
+    /**
+     * Contains a schedule category
+     */
+    get category(): string;
+    /**
+     * Contains a schedule rating value (aka pcmark)
+     */
+    get rating(): number;
+    /**
+     * Contains a schedule description
+     */
+    get descr(): string;
+    /**
+     * Returns a schedule info item descriptor
+     */
+    getInfo(): xepgShedInfoDesc;
+    /**
+     * Sets a schedule start time.
+     */
+    setTime(value: number | string | Date): boolean;
+    /**
+     * Sets a schedule title.
+     */
+    setTitle(value: string): boolean;
+    /**
+     * Sets a schedule title.
+     */
+    setCategory(value: string): boolean;
+    /**
+     * Sets a schedule rating value.
+     */
+    setRating(value: number | string): boolean;
+    /**
+     * Sets a schedule description.
+     */
+    setDescr(value: string): boolean;
+    /**
+     * Returns an instance content as a string in an XML-format.
+     */
+    saveToXMLString(): string;
+    /**
+     * Loads an element content from a string.
+     * @since v0.0.24
+     * @throws {Error}
+     * @experimental
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of a EPG-schedules list
+ */
+export class TXEpgSchedulesList {
+    /**
+     * Creates an instance of the schedules list
+     */
+    constructor(obj: any[], opt?: OPT_epgelsett_ex, extra?: OPT_extra);
+    /**
+     * Contains a quantity of a schedules
+     * @deprecated
+     * @todo \[since `v0.0.24`] deprecated. Use `TXEpgSchedulesList.count`
+     */
+    get schedQty(): number;
+    /**
+     * Contains a quantity of a schedules
+     * @since v0.0.24
+     */
+    get count(): number;
+    /**
+     * Contains a dtstype ID
+     */
+    get dtstype(): number;
+    /**
+     * Contains a TZ-offset
+     */
+    get curDocTZ(): number;
+    /**
+     * Indicates whether an instance has none member
+     * @deprecated
+     * @todo \[since `v0.0.24`] deprecated. Use `TXEpgSchedulesList.isEmpty`
+     */
+    hasNoSchedules(): boolean;
+    /**
+     * Indicates whether an instance has none member
+     * @since v0.0.24
+     */
+    isEmpty(): boolean;
+    /**
+     * Indicates whether an instance has any member
+     * @deprecated
+     * @todo \[since `v0.0.24`] deprecated. Use `TXEpgSchedulesList.isNotEmpty`
+     */
+    hasSchedules(): boolean;
+    /**
+     * Indicates whether an instance has any member
+     * @since v0.0.24
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks whether a given value is a valid index and it fits the index range
+     * of an instance
+     * @since 0.0.20
+     */
+    chkIndex(value: number | string): boolean;
+    /**
+     * Returns a schedule element addressed by a given index
+     * @since 0.0.22
+     */
+    schedule(index: number | string): TXEpgScheduleItem | null;
+    /**
+     * Returns a schedule info item for instance element addressed
+     * by a given index
+     */
+    getScheduleInfo(index: number | string): xepgShedInfoDesc | null;
+    /**
+     * Returns a schedule info for instance members
+     */
+    getAllSchedulesInfo(): xepgShedInfoDesc[];
+    /**
+     * @protected
+     */
+    protected asJSON(): string;
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: TXEpgScheduleItem | null;
+        } | {
+            done: boolean;
+            value: undefined;
+        };
+        return(): {
+            done: boolean;
+            value: undefined;
+        };
+    };
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of a EPG-provider element
+ */
+export class TXEpgProviderContainer {
+    /**
+     * Creates an instance of the EPG-provider element
+     */
+    constructor(obj: object, opt?: OPT_epgelsett_bs);
+    /**
+     * Contains a provider name
+     */
+    get name(): string;
+    set name(value: string);
+    /**
+     * Contains a version of a provider
+     */
+    get version(): string;
+    set version(value: string);
+    /**
+     * Contains a version of a document schema
+     */
+    get schema(): string;
+    set schema(value: string);
+    /**
+     * Contains a document type
+     */
+    get doctype(): string;
+    set doctype(value: string);
+    /**
+     * Sets a provider name
+     */
+    setName(value: string): boolean;
+    /**
+     * Returns a provider info item
+     */
+    getInfo(): xepgProvInfoDesc;
+    /**
+     * Sets a provider info
+     * @todo [since v0.0.21] deprecate use of `obj`-param as array
+     */
+    setInfo(obj: string[] | xepgProvInfoDesc): void;
+    /**
+     * Sets an initial instance state
+     */
+    init(opt?: xepgProvInfoDesc | string[]): void;
+    /**
+     * Returns an instance content as a string in an XML-format.
+     * @since v0.0.20
+     */
+    saveToXMLString(): string;
+    /**
+     * Loads a element content from a string.
+     * @since v0.0.24
+     * @throws {Error}
+     * @experimental
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    #private;
+}
+
+/**
+ * @since 0.0.22
+ * @classdesc This class implements an interface of a channel element
+ */
+export class TXEpgChannelContainer {
+    /**
+     * Creates an instance of the channel element
+     */
+    constructor(obj: object, 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(): xepgChnInfoDesc;
+    /**
+     * Sets a channel info
+     */
+    setInfo(obj: string | xepgChnInfoDesc): void;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of a EPG-header element
+ */
+export class TXEpgHeaderContainer {
+    /**
+     * Creates an instance of the EPG-header element
+     */
+    constructor(obj: object, opt?: OPT_epgelsett_bs);
+    /**
+     * Returns a `TXEpgDTSProvider` instance
+     */
+    get dts(): TXEpgDTSProvider;
+    /**
+     * Contains a dtstype ID
+     * @todo [since v0.0.22] becomes readonly
+     */
+    get dtstype(): number;
+    set dtstype(value: number);
+    /**
+     * Contains a TZ-offset
+     * @todo [since v0.0.22] becomes readonly
+     */
+    get curDocTZ(): number;
+    set curDocTZ(value: number);
+    /**
+     * Returns a `TXEpgProviderContainer` instance
+     * @since 0.0.22
+     */
+    get provider(): TXEpgProviderContainer | null;
+    /**
+     * Returns a `TXEpgChannelContainer` instance
+     * @since 0.0.22
+     */
+    get channel(): TXEpgChannelContainer | null;
+    /**
+     * Returns a document creation date as a timestamp
+     */
+    getDocumentDT(): number;
+    /**
+     * Sets a document creation date to a current system time
+     */
+    setDocumentDT(): void;
+    /**
+     * Returns a document expire date as a timestamp
+     */
+    getDocumentEDT(): number;
+    /**
+     * Sets a document expire date to a given time
+     */
+    setDocumentEDT(value: any): void;
+    /**
+     * Returns a channel info
+     */
+    getChannelInfo(): xepgChnInfoDesc;
+    /**
+     * Sets a channel info
+     * @deprecated
+     * @todo [since v0.0.22] deprecated. Use `TXEpgChannelContainer.setInfo`
+     */
+    setChannelInfo(obj: xepgChnInfoDesc): void;
+    /**
+     * Returns a provider info
+     */
+    getProviderInfo(): xepgProvInfoDesc | null;
+    /**
+     * Sets a provider info
+     * @deprecated
+     * @todo \[since `v0.0.24`] deprecated. Use `TXEpgProviderContainer.setInfo`
+     */
+    setProviderInfo(obj: xepgProvInfoDesc): void;
+    /**
+     * Returns an instance content as a string in an XML-format.
+     * @since v0.0.20
+     */
+    saveToXMLString(): string;
+    /**
+     * Loads an element content from a string.
+     * @since v0.0.24
+     * @throws {Error}
+     * @experimental
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of the container
+ *            that manages a content of a XEPG-document
+ */
+export class TXEpgContentProvider {
+    /**
+     * Creates an instance of the XEPG-content provider
+     */
+    constructor(opt?: OPT_epgcpsett);
+    /**
+     * Returns a `TXEpgHeaderContainer` instance
+     * @since 0.0.22
+     */
+    get header(): TXEpgHeaderContainer | null;
+    /**
+     * Returns a `TXEpgProviderContainer` instance
+     * @since 0.0.22
+     */
+    get provider(): TXEpgProviderContainer | null;
+    /**
+     * Returns a `TXEpgDTSProvider` instance
+     */
+    get dts(): TXEpgDTSProvider | null;
+    /**
+     * @deprecated
+     */
+    get Content(): this;
+    /**
+     * Returns a `TXEpgSchedulesList` instance
+     * @deprecated
+     * @todo \[since `v0.0.24`] deprecated. Use `TXEpgContentProvider.schedules`
+     */
+    get SchedulesList(): TXEpgSchedulesList;
+    /**
+     * Returns a `TXEpgSchedulesList` instance
+     * @since 0.0.24
+     */
+    get schedules(): TXEpgSchedulesList;
+
+    init(): void;
+    /**
+     * Returns a document content as a string in an XML-format.
+     */
+    saveToXMLString(): string;
+    /**
+     * Saves a document content to a file.
+     * @throws {Error}
+     * @async
+     */
+    saveToFile(source: string): Promise<fsoDescr>;
+    /**
+     * Saves a document content to a file.
+     */
+    saveToFileSync(source: string): fsoDescr;
+    /**
+     * Loads a document content from a string.
+     * @since 0.0.18
+     * @throws {Error}
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    /**
+     * Loads a document content from a file.
+     * @throws {Error}
+     * @async
+     */
+    loadFromFile(source: string): Promise<fsoDescr>;
+    /**
+     * Loads a document content from a file.
+     */
+    loadFromFileSync(source: string): fsoDescr;
+    /**
+     * @protected
+     */
+    protected asJSON(): string;
+    #private;
+}
+import { TXmlContentParseOptions } from "@ygracs/xobj-lib-js";
+import { fsoDescr } from "@cntwg/file-helper";

package/lib/xepgdoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.124-20250730]
+// [v0.2.132-20260122]
 
 // === module init block ===
 
@@ -24,17 +24,27 @@ const {
 const {
   loadFromFileSync, loadFromFile,
   saveToFileSync, saveToFile,
+  // * import types definitions *
+  /** @see fsoDescr from `@cntwg/file-helper` */
+  fsoDescr,
 } = require('@cntwg/file-helper');
 
 const xObj = require('@ygracs/xobj-lib-js');
-
 const {
-  TXmlContentParseOptions,
   getXObjElement,
   insertXObjElement,
   writeXObjParam,
   writeXObjAttr,
+  //TXmlContentParseOptions,
 } = xObj;
+// keep the next line for a type checking work properly :(
+const { TXmlContentParseOptions } = require('@ygracs/xobj-lib-js/lib/xObj-defs');
+
+const {
+  readAsTagName,
+  readAsAttrName,
+  valueToElementID,
+} = require('./xml-base');
 
 // === module inner block ===
 
@@ -167,11 +177,17 @@ function deserializeXObjFromXMLString(node, opt, text, tagName) {
  * @property {TXmlContentParseOptions} [parseOptions] - parser options
  */
 
+/**
+ * An XEPG-element options set (base)
+ * @typedef {Object} XEpgElementConfigBase
+ * @property {TXmlContentParseOptions} parseOptions - parser options
+ */
+
 /**
  * Evaluates an XML-node base settings
  * @function __evalXMLBaseNodeSettings
  * @param {any} value - element settings to evaluate
- * @returns {OPT_epgelsett_bs}
+ * @returns {XEpgElementConfigBase}
  * @inner
  */
 function __evalXMLBaseNodeSettings(value) {
@@ -184,6 +200,7 @@ function __evalXMLBaseNodeSettings(value) {
   if (!(parseOptions instanceof TXmlContentParseOptions)) {
     settings.parseOptions = new TXmlContentParseOptions(parseOptions);
   };
+  // @ts-expect-error
   return settings;
 };
 
@@ -252,73 +269,6 @@ const defParseOptions = new TXmlContentParseOptions();
  * (* function definitions *)
  */
 
-/**
- * Tries to convert a given value to a valid tag name of an XML-element.
- * @since v0.0.23
- * @function readAsTagName
- * @param {any} value - some value
- * @returns {string}
- */
-function readAsTagName(value) {
-  let tagName = valueToIDString(value, { ignoreNumbers: true });
-  if (tagName === null) return '';
-  if (tagName !== '') {
-    // // TODO: do extra checks
-    const template = /[\s\/\\\"\'<>=]/;
-    const trigger = tagName.match(template);
-    if (trigger) {
-      //console.log(trigger);
-      tagName = '';
-    };
-  };
-  return tagName;
-};
-
-/**
- * Tries to convert a given value to a valid name of an XML-attribute.
- * @since v0.0.23
- * @function readAsAttrName
- * @param {any} value - some value
- * @returns {string}
- */
-function readAsAttrName(value) {
-  let attrName = valueToIDString(value, { ignoreNumbers: true });
-  if (attrName === null) return '';
-  if (attrName !== '') {
-    // // TODO: do extra checks
-    const template = /[\s\/\\\"\'<>=]/;
-    const trigger = attrName.match(template);
-    if (trigger) {
-      //console.log(trigger);
-      attrName = '';
-    };
-  };
-  return attrName;
-};
-
-/**
- * Tries to convert a given value to a valid identifier suitable as a value
- * for an "ID-attribute" of an XML-element.
- * @since v0.0.23
- * @function valueToElementID
- * @param {any} value - some value
- * @returns {string}
- */
-function valueToElementID(value) {
-  let id = valueToIDString(value);
-  if (id === null) return '';
-  if (id !== '') {
-    // // TODO: do extra checks
-    const template = /[\s\/\\\"\'<>=]/;
-    const trigger = id.match(template);
-    if (trigger) {
-      //console.log(trigger);
-      id = '';
-    };
-  };
-  return id;
-};
-
 /***
  * (* class definitions *)
  */
@@ -501,13 +451,13 @@ class TXEpgScheduleItem {
   setTime(value) {
     let { isSucceed, value: dtValue } = tryDTValue(value);
     let result = false;
-    if (isSucceed) {
-      dtValue = convDTValueToString(dtValue, this.dtstype, this.curDocTZ);
-      if (dtValue !== '') {
+    if (isSucceed && dtValue != null) {
+      const text = convDTValueToString(dtValue, this.dtstype, this.curDocTZ);
+      if (text !== '') {
         const opt = { force: true };
         const item = insertXObjElement(this.#_host, XEPG_SCHEDTIME_ETAG_NAME, opt);
         if (item) {
-          result = writeXObjParam(item, dtValue, defParseOptions.settings.textKey);
+          result = writeXObjParam(item, text, defParseOptions.settings.textKey);
         };
       };
     };
@@ -678,7 +628,6 @@ class TXEpgSchedulesList {
    * Returns a raw schedule element
    * @param {(number|string)} value - element index
    * @returns {any}
-   * @private
    */
   #_getItem = function(value) {
     if (this.chkIndex(value)) {
@@ -1020,7 +969,7 @@ class TXEpgProviderContainer {
 
   /**
    * Sets an initial instance state
-   * @param {(xepgProvInfoDesc|string[])} opt - options
+   * @param {(xepgProvInfoDesc|string[])} [opt] - options
    * @returns {void}
    */
   init(opt) {
@@ -1325,7 +1274,6 @@ class TXEpgDTSProvider {
 
   /**
    * @returns {void}
-   * @private
    */
   #_init() {
     insertXObjElement(this.#_content, XEPG_DTSINFO_ETAG_NAME);
@@ -1343,7 +1291,7 @@ class TXEpgDTSProvider {
   }
 
   set dtstype(value) {
-    return this.setType(value);
+    this.setType(value);
   }
 
   /**
@@ -1475,7 +1423,6 @@ class TXEpgHeaderContainer {
 
   /**
    * @returns {?object}
-   * @private
    */
   #_getProv() {
     const docProv = getXObjElement(this.#_host, XEPG_PRVINFO_ETAG_NAME);
@@ -1484,7 +1431,6 @@ class TXEpgHeaderContainer {
 
   /**
    * @returns {?object}
-   * @private
    */
   #_initProv() {
     const _host = this.#_host;
@@ -1495,17 +1441,6 @@ class TXEpgHeaderContainer {
     return isPlainObject(docProv) ? docProv : null;
   }
 
-  /**
-   * Returns a `TXEpgProviderContainer` instance
-   * @type {?TXEpgProviderContainer}
-   * @readonly
-   * @deprecated
-   * @todo \[since `v0.0.22`] deprecated. Use `TXEpgHeaderContainer.provider`
-   */
-  get Provider() {
-    return this.provider;
-  }
-
   /**
    * Returns a `TXEpgProviderContainer` instance
    * @since 0.0.22
@@ -1683,20 +1618,16 @@ class TXEpgHeaderContainer {
 };
 
 /**
- * A fs ops description.
- * @typedef {Object} fsoDescr
- * @property {boolean} isERR - flag
- * @property {number} [errCode] - error code
- * @property {string} errEvent - event ID
- * @property {string} [errMsg] - event message
- * @property {string} [source] - path to file
- * @property {any} [content] - file content
+ * An options set for `TXEpgContentProvider`-class
+ * @typedef {Object} OPT_epgcpsett
+ * @property {TXmlContentParseOptions} [parseOptions] - parser options
+ * @property {boolean} [autoBindRoot] - <*deprecated*>
  */
 
 /**
  * An options set for `TXEpgContentProvider`-class
- * @typedef {Object} OPT_epgcpsett
- * @property {TXmlContentParseOptions} [parseOptions] - parser options
+ * @typedef {Object} XEpgContainerSettings
+ * @property {TXmlContentParseOptions} parseOptions - parser options
  * @property {boolean} [autoBindRoot] - <*deprecated*>
  */
 
@@ -1707,7 +1638,7 @@ class TXEpgHeaderContainer {
 class TXEpgContentProvider {
   /** @type {Object} */
   #_content;
-  /** @type {OPT_epgcpsett} */
+  /** @type {XEpgContainerSettings} */
   #_options;
   /** @type {TXmlContentParseOptions} */
   #_parseOptions;
@@ -1719,7 +1650,7 @@ class TXEpgContentProvider {
   constructor(opt) {
     // load options
     const _options = __evalXMLBaseNodeSettings(opt);
-    /** @type {OPT_epgcpsett} */
+    /** @type {XEpgContainerSettings} */
     let {
       parseOptions,
       autoBindRoot, // <*reserved*> ([?] - deprecate)
@@ -1737,7 +1668,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?Object}
-   * @private
    */
   #_getRoot() {
     const docRoot = getXObjElement(this.#_content, XEPG_ROOT_ETAG_NAME);
@@ -1746,7 +1676,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?object}
-   * @private
    */
   #_initRoot() {
     const _content = this.#_content;
@@ -1767,7 +1696,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?Object}
-   * @private
    */
   #_getHdr() {
     const docRoot = this.#_getRoot();
@@ -1780,7 +1708,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?object}
-   * @private
    */
   #_initHdr() {
     let docHdr = this.#_getHdr();
@@ -1796,7 +1723,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?Object}
-   * @private
    */
   #_getBody() {
     const docRoot = this.#_getRoot();
@@ -1809,7 +1735,6 @@ class TXEpgContentProvider {
 
   /**
    * @returns {?object}
-   * @private
    */
   #_initBody() {
     let docBody = this.#_getBody();
@@ -1823,17 +1748,6 @@ class TXEpgContentProvider {
     return isPlainObject(docBody) ? docBody : null;
   }
 
-  /**
-   * Returns a `TXEpgHeaderContainer` instance
-   * @type {?TXEpgHeaderContainer}
-   * @readonly
-   * @deprecated
-   * @todo \[since `v0.0.22`] deprecated. Use `TXEpgContentProvider.header`
-   */
-  get Header() {
-    return this.header;
-  }
-
   /**
    * Returns a `TXEpgHeaderContainer` instance
    * @since 0.0.22
@@ -1849,17 +1763,6 @@ class TXEpgContentProvider {
     );
   }
 
-  /**
-   * Returns a `TXEpgProviderContainer` instance
-   * @type {?TXEpgProviderContainer}
-   * @readonly
-   * @deprecated
-   * @todo \[since `v0.0.22`] deprecated. Use `TXEpgContentProvider.provider`
-   */
-  get Provider() {
-    return this.provider;
-  }
-
   /**
    * Returns a `TXEpgProviderContainer` instance
    * @since 0.0.22
@@ -2156,10 +2059,6 @@ module.exports.XEPG_DEF_PROVIDER_VER = XEPG_DEF_PROVIDER_VER;
 module.exports.XEPG_DEF_DOCUMENT_TYPE = XEPG_DEF_DOCUMENT_TYPE;
 module.exports.XEPG_DEF_DOCUMENT_SCHEMA = XEPG_DEF_DOCUMENT_SCHEMA;
 
-module.exports.readAsTagName = readAsTagName;
-module.exports.readAsAttrName = readAsAttrName;
-module.exports.valueToElementID = valueToElementID;
-
 module.exports.TXEpgDTSProvider = TXEpgDTSProvider;
 module.exports.TXEpgScheduleItem = TXEpgScheduleItem;
 module.exports.TXEpgSchedulesList = TXEpgSchedulesList;

package/lib/xml-base.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tries to convert a given value to a valid tag name of an XML-element.
+ * @since v0.0.23
+ */
+export function readAsTagName(value: any): string;
+/**
+ * Tries to convert a given value to a valid name of an XML-attribute.
+ * @since v0.0.23
+ */
+export function readAsAttrName(value: any): string;
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.25
+ */
+export function readAsAttrValue(value: any): string | null;
+/**
+ * Tries to convert a given value to a valid identifier suitable as a value
+ * for an "ID-attribute" of an XML-element.
+ * @since v0.0.23
+ */
+export function valueToElementID(value: any): string;

package/lib/xml-base.js

@@ -0,0 +1,133 @@
+// [v0.1.002-20250825]
+
+// === module init block ===
+
+const {
+  //valueToIndex,
+  valueToIDString,
+  //readAsString, readAsNumber,
+  //isNotEmptyString,
+  //isArray, isObject, isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+/***
+ * (* helper function definitions *)
+ */
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * Tries to convert a given value to a valid tag name of an XML-element.
+ * @since v0.0.23
+ * @function readAsTagName
+ * @param {any} value - some value
+ * @returns {string}
+ */
+function readAsTagName(value) {
+  let tagName = valueToIDString(value, { ignoreNumbers: true });
+  if (tagName === null) return '';
+  if (tagName !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = tagName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      tagName = '';
+    };
+  };
+  return tagName;
+};
+
+/**
+ * Tries to convert a given value to a valid name of an XML-attribute.
+ * @since v0.0.23
+ * @function readAsAttrName
+ * @param {any} value - some value
+ * @returns {string}
+ */
+function readAsAttrName(value) {
+  let attrName = valueToIDString(value, { ignoreNumbers: true });
+  if (attrName === null) return '';
+  if (attrName !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = attrName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      attrName = '';
+    };
+  };
+  return attrName;
+};
+
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.25
+ * @function readAsAttrValue
+ * @param {any} value - some value
+ * @return {?string}
+ */
+function readAsAttrValue(value) {
+  let result = null;
+  switch (typeof value) {
+    case 'boolean': {
+      result = value.toString();
+      break;
+    }
+    case 'number': {
+      if (Number.isNaN(value)) break;
+      result = value.toString();
+      break;
+    }
+    case 'string': {
+      result = value.trim();
+      break;
+    }
+    default: {}
+  };
+  return result;
+};
+
+/**
+ * Tries to convert a given value to a valid identifier suitable as a value
+ * for an "ID-attribute" of an XML-element.
+ * @since v0.0.23
+ * @function valueToElementID
+ * @param {any} value - some value
+ * @returns {string}
+ */
+function valueToElementID(value) {
+  let id = valueToIDString(value);
+  if (id === null) return '';
+  if (id !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = id.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      id = '';
+    };
+  };
+  return id;
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+module.exports.readAsTagName = readAsTagName;
+module.exports.readAsAttrName = readAsAttrName;
+module.exports.readAsAttrValue = readAsAttrValue;
+module.exports.valueToElementID = valueToElementID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xepg-lib-js",
-  "version": "0.0.24",
+  "version": "0.0.26-b",
   "description": "A library for handling an EPG-sources based on an XEPG-format",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -13,35 +13,42 @@
     "EPG"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/xepgdoc-spec-draft.dtd",
     "doc/*.xepg",
     "doc/*.md",
     "lib/xepgdoc-lib.js",
     "lib/dts-helper.js",
+    "lib/xml-base.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "cross-env TZ='Etc/UTC' jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/file-helper": "^0.0.1",
-    "@ygracs/bsfoc-lib-js": "^0.2.3",
-    "@ygracs/dtf-lib-js": "^0.0.29",
-    "@ygracs/xml-js6": "^0.0.5-b",
-    "@ygracs/xobj-lib-js": "^0.2.3"
+    "@cntwg/file-helper": "^0.0.3",
+    "@ygracs/bsfoc-lib-js": "~0.3.3",
+    "@ygracs/dtf-lib-js": "^0.0.33",
+    "@ygracs/xml-js6": "^0.0.6-b",
+    "@ygracs/xobj-lib-js": "^0.2.8-b"
   },
   "devDependencies": {
-    "cross-env": "^7.0.3",
-    "jest": "^30.0.4",
-    "jsdoc-to-markdown": "^9.1.1",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "~0.0.1-b",
+    "cross-env": "^10.1.0",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }