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

package/lib/xepg-sched.js

@@ -0,0 +1,587 @@
+// [v0.3.152-20260612]
+
+// === module init block ===
+
+const {
+  valueToIndex,
+  readAsNumber,
+  isArray, isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  tryDTValue,
+} = require('@ygracs/dtf-lib-js');
+
+const {
+  convStringToDTValue, convDTValueToString,
+  _getDTSTypeValueForXObj, _getTZSrcValueFromXObj,
+} = require('./dts-helper.js');
+
+const xObj = require('@ygracs/xobj-lib-js');
+const {
+  insertXObjElement,
+  writeXObjParam,
+  //TXmlContentParseOptions,
+  //DEF_XML_PARSE_OPTIONS: XML_DEF_PARSE_OPTIONS,
+} = xObj;
+// keep the next line for a type checking work properly :(
+const { TXmlContentParseOptions } = require('@ygracs/xobj-lib-js/lib/xObj-defs');
+// keep the next line for a type checking work properly :(
+const { INode } = require('@ygracs/xobj-lib-js/lib/xObj-lib');
+
+const {
+  //readAsTagName,
+  //readAsAttrName,
+  //valueToElementID,
+  serializeXObjToXMLString, deserializeXObjFromXMLString,
+  _getXmlChildElementParam,
+} = require('./xml-base');
+
+const {
+  XEPG_DEF_TNAMES,
+  defParseOptionsSettings,
+} = require('./xepg-defs');
+
+// === module inner block ===
+
+const {
+  XEPG_SCHED_ETAG_NAME,
+  XEPG_SCHEDTIME_ETAG_NAME,
+  XEPG_SCHEDTITL_ETAG_NAME,
+  XEPG_SCHEDCAT_ETAG_NAME,
+  XEPG_SCHEDPMARK_ETAG_NAME,
+  XEPG_SCHEDDESC_ETAG_NAME,
+} = XEPG_DEF_TNAMES;
+
+/**
+ * An XEPG-element options set (base)
+ * @typedef {Object} OPT_epgelsett_bs
+ * @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 {XEpgElementConfigBase}
+ * @inner
+ */
+function __evalXMLBaseNodeSettings(value) {
+  /** @type {OPT_epgelsett_bs} */
+  let settings = isPlainObject(value) ? value : {};
+  if (settings instanceof Map) settings = Object.fromEntries(settings);
+  let {
+    parseOptions,
+  } = settings;
+  if (!(parseOptions instanceof TXmlContentParseOptions)) {
+    settings.parseOptions = new TXmlContentParseOptions(parseOptions);
+  };
+  // @ts-expect-error
+  return settings;
+};
+
+// === module main block ===
+
+/**
+ * A schedule info descriptor
+ * @typedef {Object} IXEpgShedInfoDesc
+ * @property {number} time - a schedule start time
+ * @property {string} title - schedule title
+ * @property {string} [cat] - schedule category
+ * @property {number} [pcmark] - schedule rating
+ * @property {string} [descr] - schedule description
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IXEpgShedInfoDesc}
+ */
+module.exports.IXEpgShedInfoDesc = { time: 0, title: '' };
+
+/**
+ * An extra options set
+ * @typedef {Object} OPT_extra
+ * @property {object} [dts_src] - 'DTS'-settings
+ * @property {object} [tz_src] - 'TZ'-settings
+ */
+
+/**
+ * An XEPG-element options set (extend)
+ * @typedef {Object} OPT_epgelsett_ex
+ * @property {TXmlContentParseOptions} [parseOptions] - parser options
+ * @property {object} [dts_src]
+ * @property {object} [tz_src]
+ */
+
+/**
+ * @since 0.0.22
+ * @classdesc This class implements an interface of a EPG-schedule element
+ */
+class TXEpgScheduleItem {
+  /** @type {INode} */
+  #_host;
+  /** @type {OPT_epgelsett_ex} */
+  #_options;
+  /** @type {TXmlContentParseOptions} */
+  #_parseOptions;
+  /** @type {?object} */
+  #_dts_src = null;
+  /** @type {?object} */
+  #_tz_src = null;
+
+  /**
+   * Creates an instance of the EPG-schedule element
+   * @param {INode} obj - host object
+   * @param {OPT_epgelsett_ex} [opt] - options
+   * @param {OPT_extra} [extra] - \[since `v0.0.24`] extra options
+   */
+  constructor(obj, opt, extra) {
+    // load content
+    const _host = isPlainObject(obj) ? obj : {};
+    // load options
+    /** @type {OPT_epgelsett_ex} */
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      parseOptions,
+    } = _options;
+    if (!(parseOptions instanceof TXmlContentParseOptions)) {
+      parseOptions = new TXmlContentParseOptions(parseOptions);
+      _options.parseOptions = parseOptions;
+    };
+    let {
+      dts_src = _options.dts_src,
+      tz_src = _options.tz_src,
+    } = isPlainObject(extra) ? extra : {};
+    if (!isPlainObject(dts_src)) dts_src = null;
+    if (!isPlainObject(tz_src)) tz_src = null;
+    // save content source
+    this.#_host = _host;
+    // save options
+    this.#_options = _options;
+    // save parser options
+    this.#_parseOptions = parseOptions;
+    // save refs to a time source priveders
+    this.#_dts_src = dts_src;
+    this.#_tz_src = tz_src;
+  }
+
+  /**
+   * Contains a dtstype ID
+   * @type {number}
+   * @readonly
+   */
+  get dtstype() {
+    return _getDTSTypeValueForXObj(this.#_dts_src);
+  }
+
+  /**
+   * Contains a TZ-offset
+   * @type {number}
+   * @readonly
+   */
+  get curDocTZ() {
+    return _getTZSrcValueFromXObj(this.#_tz_src);
+  }
+
+  /**
+   * Contains a schedule start time as a timestamp
+   * @type {number}
+   * @readonly
+   */
+  get time() {
+    return convStringToDTValue(
+      _getXmlChildElementParam(this.#_host, XEPG_SCHEDTIME_ETAG_NAME).trim(),
+      this.dtstype, this.curDocTZ
+    );
+  }
+
+  /**
+   * Contains a schedule title
+   * @type {string}
+   * @readonly
+   */
+  get title() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDTITL_ETAG_NAME).trim();
+  }
+
+  /**
+   * Contains a schedule category
+   * @type {string}
+   * @readonly
+   */
+  get category() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDCAT_ETAG_NAME).trim();
+  }
+
+  /**
+   * Contains a schedule rating value (aka pcmark)
+   * @type {number}
+   * @readonly
+   */
+  get rating() {
+    return readAsNumber(
+      _getXmlChildElementParam(this.#_host, XEPG_SCHEDPMARK_ETAG_NAME), 0
+    );
+  }
+
+  /**
+   * Contains a schedule description
+   * @type {string}
+   * @readonly
+   */
+  get descr() {
+    return _getXmlChildElementParam(this.#_host, XEPG_SCHEDDESC_ETAG_NAME);
+  }
+
+  /**
+   * Returns a schedule info item descriptor
+   * @returns {IXEpgShedInfoDesc}
+   */
+  getInfo() {
+    const {
+      time,
+      title,
+      category: cat,
+      rating: pcmark,
+      descr,
+    } = this;
+    return {
+      time,
+      title,
+      cat,
+      pcmark,
+      descr,
+    };
+  }
+
+  /**
+   * Sets a schedule start time.
+   * @param {number|string|Date} value - some time value
+   * @returns {boolean}
+   */
+  setTime(value) {
+    let { isSucceed, value: dtValue } = tryDTValue(value);
+    let result = false;
+    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, text, defParseOptionsSettings.textKey);
+        };
+      };
+    };
+    return result;
+  }
+
+  /**
+   * Sets a schedule title.
+   * @param {string} value - some title
+   * @returns {boolean}
+   */
+  setTitle(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDTITL_ETAG_NAME, opt);
+      if (item) {
+        result = writeXObjParam(item, value.trim(), defParseOptionsSettings.textKey);
+      };
+    };
+    return result;
+  }
+
+  /**
+   * Sets a schedule title.
+   * @param {string} value - some title
+   * @returns {boolean}
+   */
+  setCategory(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDCAT_ETAG_NAME, opt);
+      if (item) {
+        result = writeXObjParam(item, value.trim(), defParseOptionsSettings.textKey);
+      };
+    };
+    return result;
+  }
+
+  /**
+   * Sets a schedule rating value.
+   * @param {number|string} value - some value
+   * @returns {boolean}
+   */
+  setRating(value) {
+    const _value = valueToIndex(value);
+    let result = false;
+    if (_value !== -1) {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDPMARK_ETAG_NAME, opt);
+      if (item) {
+        result = writeXObjParam(item, _value, defParseOptionsSettings.textKey);
+      };
+    };
+    return result;
+  }
+
+  /**
+   * Sets a schedule description.
+   * @param {string} value - some text
+   * @returns {boolean}
+   */
+  setDescr(value) {
+    let result = false;
+    if (typeof value === 'string') {
+      const opt = { force: true };
+      const item = insertXObjElement(this.#_host, XEPG_SCHEDDESC_ETAG_NAME, opt);
+      if (item) {
+        result = writeXObjParam(item, value.trim(), defParseOptionsSettings.textKey);
+      };
+    };
+    return result;
+  }
+
+  /**
+   * Returns an instance content as a string in an XML-format.
+   * @returns {string}
+   */
+  saveToXMLString() {
+    const options = this.#_parseOptions.js2xml;
+    options.ignoreDocType = true;
+    options.ignoreDeclaration = true;
+    return serializeXObjToXMLString(
+      this.#_host,
+      options,
+      XEPG_SCHED_ETAG_NAME,
+    );
+  }
+
+  /**
+   * Loads an element content from a string.
+   * @since v0.0.24
+   * @param {string} xmlString - some content
+   * @returns {boolean}
+   * @throws {Error}
+   * @experimental
+   */
+  loadFromXMLString(xmlString) {
+    const options = this.#_parseOptions.xml2js;
+    options.ignoreDocType = true;
+    options.ignoreDeclaration = true;
+    return deserializeXObjFromXMLString(
+      this.#_host,
+      options,
+      xmlString,
+      XEPG_SCHED_ETAG_NAME,
+    );
+  }
+
+};
+module.exports.TXEpgScheduleItem = TXEpgScheduleItem;
+
+/**
+ * @classdesc This class implements an interface of a EPG-schedules list
+ */
+class TXEpgSchedulesList {
+  /** @type {INode[]} */
+  #_content;
+  /** @type {OPT_epgelsett_ex} */
+  #_options;
+  /** @type {?object} */
+  #_dts_src = null;
+  /** @type {?object} */
+  #_tz_src = null;
+
+  /**
+   * Creates an instance of the schedules list
+   * @param {INode[]} obj - list of an elements
+   * @param {OPT_epgelsett_ex} [opt] - options
+   * @param {OPT_extra} [extra] - \[since `v0.0.24`] extra options
+   */
+  constructor(obj, opt, extra) {
+    const _content = isArray(obj) ? obj : [];
+    /** @type {OPT_epgelsett_ex} */
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      dts_src = _options.dts_src,
+      tz_src = _options.tz_src,
+    } = isPlainObject(extra) ? extra : {};
+    if (!isPlainObject(dts_src)) dts_src = null;
+    if (!isPlainObject(tz_src)) tz_src = null;
+    // save content source
+    this.#_content = _content;
+    // save options
+    this.#_options = _options;
+    // save refs to a time source priveders
+    this.#_dts_src = dts_src;
+    this.#_tz_src = tz_src;
+  }
+
+  [Symbol.iterator]() {
+    let index = 0;
+    return {
+      next: () => {
+        if (index < this.count) {
+          return { done: false, value: this.schedule(index++) };
+        } else {
+          return { done: true, value: undefined };
+        };
+      },
+      return() {
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
+  /**
+   * Returns a raw schedule element
+   * @param {number|string} value - element index
+   * @returns {any}
+   */
+  #_getItem(value) {
+    if (this.checkIndex(value)) {
+      return this.#_content[Number(value)];
+    };
+  };
+
+  /**
+   * Contains a quantity of a schedules
+   * @type {number}
+   * @readonly
+   * @deprecated
+   * @todo \[since `v0.0.24`] deprecated. Use `TXEpgSchedulesList.count`
+   */
+  get schedQty() {
+    return this.#_content.length;
+  }
+
+  /**
+   * Contains a quantity of a schedules
+   * @since v0.0.24
+   * @type {number}
+   * @readonly
+   */
+  get count() {
+    return this.#_content.length;
+  }
+
+  /**
+   * Contains a dtstype ID
+   * @type {number}
+   * @readonly
+   */
+  get dtstype() {
+    return _getDTSTypeValueForXObj(this.#_dts_src);
+  }
+
+  /**
+   * Contains a TZ-offset
+   * @type {number}
+   * @readonly
+   */
+  get curDocTZ() {
+    return _getTZSrcValueFromXObj(this.#_tz_src);
+  }
+
+  /**
+   * Indicates whether an instance has none member
+   * @since v0.0.24
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.count === 0;
+  }
+
+  /**
+   * Indicates whether an instance has any member
+   * @since v0.0.24
+   * @returns {boolean}
+   */
+  isNotEmpty() {
+    return this.count > 0;
+  }
+
+  /**
+   * Checks whether a given value is a valid index and it fits the index range
+   * of an instance
+   * @since 0.0.20
+   * @param {number|string} value - index of some element
+   * @returns {boolean}
+   * @deprecated
+   * @todo \[since v0.0.30] deprecated. Use {@link checkIndex} instead
+   */
+  chkIndex(value) {
+    return this.checkIndex(value);
+  }
+
+  /**
+   * Checks whether a given value is a valid index and it fits the index range
+   * of an instance
+   * @since 0.0.30
+   * @param {number|string} value - index of some element
+   * @returns {boolean}
+   */
+  checkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * Returns a schedule element addressed by a given index
+   * @since 0.0.22
+   * @param {number|string} index - index of some element
+   * @returns {?TXEpgScheduleItem}
+   */
+  schedule(index) {
+    const curObj = this.#_getItem(index);
+    let item = null;
+    if (isPlainObject(curObj)) {
+      item = new TXEpgScheduleItem(curObj, {
+        dts_src: this.#_dts_src,
+        tz_src: this.#_tz_src,
+      });
+    };
+    return item;
+  }
+
+  /**
+   * Returns a schedule info item for instance element addressed
+   * by a given index
+   * @param {number|string} index - index of some element
+   * @returns {?IXEpgShedInfoDesc}
+   */
+  getScheduleInfo(index) {
+    const obj = this.schedule(index);
+    return obj ? obj.getInfo() : null;
+  }
+
+  /**
+   * Returns a schedule info for instance members
+   * @returns {IXEpgShedInfoDesc[]}
+   */
+  getAllSchedulesInfo() {
+    let result = [];
+    for (let i = 0; i < this.count; i++) {
+      let item = this.getScheduleInfo(i);
+      if (isPlainObject(item)) result.push(item);
+    };
+    return result;
+  }
+
+  /**
+   * @protected
+   */
+  asJSON() {
+    return JSON.stringify(this.#_content, null, 2);
+  }
+
+};
+module.exports.TXEpgSchedulesList = TXEpgSchedulesList;