@ygracs/chn-alias-list 0.0.3

package/lib/chn-alias-list.js

@@ -0,0 +1,759 @@
+// [v0.1.033-20241021]
+
+// === module init block ===
+
+const {
+  isArray, isPlainObject,
+  valueToArray, valueToIndex, valueToIDString,
+  readAsString,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  loadJSONFromFileSync, saveJSONToFileSync,
+} = require('#lib/file-helper.js');
+
+// === module extra block (helper functions) ===
+
+/**
+ * @function convertLangTextValueToString
+ * @param {array} data - contains a data to be printed
+ * @param {object} [opt]
+ * @returns {string}
+ * @inner
+ * @description Converts a <Lang, Text> key-pair to string
+ */
+function convertLangTextValueToString(data, opt) {
+  let name = [ '', '' ];
+  let result = '';
+  if (isArray(data)) name = data;
+  let [ lang, text ] = name;
+  if (lang === '') {
+    result = text;
+  } else if (text !== '') {
+    result = `(${lang}): ${text}`;
+  };
+  return result;
+};
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * @typedef {Object} fsoDescr
+ * @property {boolean} isERR - flag
+ * @property {number|undefined} errCode - error code
+ * @property {string} errEvent - event ID
+ * @property {string} errMsg - event message
+ * @property {string} source - path to file
+ * @property {any} content - file content
+ * @description A fs ops description.
+ */
+
+/**
+ * @typedef {Object} RVAL_loadaliasff
+ * @property {fsoDescr} descr - ops description
+ * @property {(null|TChnAliasItem|TChnAliasList)} result - loaded content
+ * @description A result of `loadAliasFromFile...`
+ */
+
+/**
+ * @function loadAliasFromFileSync
+ * @param {string} src - a path to some file
+ * @param {any} [opt] - <reserved>
+ * @returns {RVAL_loadaliasff}
+ * @description Loads an alias from a file
+ */
+function loadAliasFromFileSync(src, opt) {
+  let { descr, obj } = loadJSONFromFileSync(src, opt);
+  let result = null;
+  if (!descr.isERR) {
+    if (isArray(obj)) {
+      result = new TChnAliasList();
+      let count = result.loadItems(obj);
+      // // TODO: [?]
+    } else {
+      result = TChnAliasItem.create(obj);
+    };
+  };
+  return { descr, result };
+};
+
+/**
+ * @function saveAliasToFileSync
+ * @param {string} src - a path to some file
+ * @param {Array} content - content
+ * @param {any} [opt] - <reserved>
+ * @returns {fsoDescr}
+ * @description Saves an alias to a file
+ */
+function saveAliasToFileSync(src, content, opt) {
+  const obj = isArray(content) ? content : null;
+  let result = null;
+  //===
+  result = saveJSONToFileSync(src, obj, opt);
+  return result;
+};
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * @classdesc This class implements an interface of the name record
+ */
+class TChnNameRecord {
+  /** @property {string} */
+  #_lang;
+  /** @property {string} */
+  #_value;
+
+  /**
+   * @description Creates an instance of the name record
+   */
+  constructor() {
+    this.reset();
+  }
+
+  /**
+   * @property {string} - defines a language
+   * @readonly
+   */
+  get lang() {
+    return this.#_lang;
+  }
+
+  /**
+   * @property {string} - defines a value of the record
+   * @readonly
+   */
+  get text() {
+    return this.#_value;
+  }
+
+  /**
+   * @property {array} - a value of the record
+   */
+  get value() {
+    return [ this.#_lang, this.#_value ];
+  }
+
+  set value(data) {
+    this.setValue(data);
+  }
+
+  /**
+   * @param {any} data - a value of the record
+   * @returns {boolean}
+   * @description Sets the record value
+   */
+  setValue(data) {
+    let _data = data;
+    let isSucceed = false;
+    if (_data !== undefined) {
+      if (isPlainObject(_data)) {
+        let { lang, text } = _data;
+        _data = [ lang, text ];
+      } else {
+        _data = valueToArray(_data);
+      };
+      switch (_data.length) {
+        case 0: {
+          break;
+        }
+        case 1: {
+          _data = [ '', _data[0] ];
+        }
+        default: {
+          let [ lang, value = null ] = _data;
+          if (value !== null && typeof value !== 'boolean') {
+            value = readAsString(value, { numberToString: true });
+            lang = value !== '' ? valueToIDString(lang) : null;
+            if (lang === null) lang = '';
+            this.#_lang = lang;
+            this.#_value = value;
+            isSucceed = true;
+          };
+        }
+      };
+    };
+    return isSucceed;
+  }
+
+  /**
+   * @param {any} opt - <reserved>
+   * @returns {string}
+   * @description Returns value as a formated string
+   */
+  toFormatString(opt) {
+    return convertLangTextValueToString(this.value, opt);
+  }
+
+  /**
+   * @returns {void}
+   * @description Clears the record
+   */
+  reset() {
+    this.#_lang = '';
+    this.#_value = '';
+  }
+
+};
+
+/**
+ * @callback forEachProcEx
+ * @param {any} item
+ * @param {number} [index]
+ * @param {any[]} [arr]
+ * @returns {void}
+ * @description user defined procedure to process an array elements
+ */
+
+/**
+ * @classdesc This class implements an interface of the name records list
+ */
+class TChnNamesList {
+  /** @property {TChnNameRecord[]} */
+  #_items;
+
+  /**
+   * @description Creates an instance of the name records list
+   */
+  constructor() {
+    this.#_items = [];
+  }
+
+  /**
+   * @property {number} - contains a quantity of a name records
+   * @readonly
+   */
+  get count() {
+    return this.#_items.length;
+  }
+
+  /**
+   * @property {TChnNameRecord[]} - contains a list of a name records
+   * @readonly
+   */
+  get value() {
+    const result = [];
+    this.#_items.forEach((item, i) => {
+      result.push(item.value);
+    });
+    return result;
+  }
+
+  /**
+   * @returns {boolean}
+   * @description Returns a flag whether a list is empty or not
+   */
+  isEmpty() {
+    return this.count === 0;
+  }
+
+  /**
+   * @returns {boolean}
+   * @description Returns a flag whether a list has any members
+   */
+  isNotEmpty() {
+    return this.count > 0;
+  }
+
+  /**
+   * @param {any} value - a value to be verified
+   * @returns {boolean}
+   * @description Checks whether a given value is an index and fits
+   *              an Index range within the instance
+   */
+  chkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * @param {string} value - a name
+   * @returns {number}
+   * @description Searches an index of a given name
+   */
+  getIndex(value) {
+    const opt = { numberToString: true };
+    const name = readAsString(value, opt);
+    let index = -1;
+    if (name !== '') {
+      index = this.#_items.findIndex((item) => name === item.text);
+    };
+    return index;
+  }
+
+  /**
+   * @param {number} value - an element index
+   * @returns {?TChnNameRecord}
+   * @description Returns a name record
+   */
+  getName(value) {
+    return this.chkIndex(value) ? this.#_items[Number(value)] : null;
+  }
+
+  /**
+   * @param {any} data - a value of a name record
+   * @returns {boolean}
+   * @description Adds a new name record to a list members
+   */
+  addName(data) {
+    const _data = data instanceof TChnNameRecord ? data.value : data;
+    const item = new TChnNameRecord();
+    const isSucceed = item.setValue(_data) && item.text !== '';
+    if (isSucceed) this.#_items.push(item);
+    return isSucceed;
+  }
+
+  /**
+   * @param {number} value - an element index
+   * @returns {boolean}
+   * @description Tries to delete a name record addressed by a given index
+   */
+  delName(value) {
+    let isSucceed = this.chkIndex(value)
+    if (isSucceed) this.#_items.splice(Number(value), 1);
+    return isSucceed;
+  }
+
+  /**
+   * @param {any} list - an element or a list of an elements
+   * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
+   * @returns {number}
+   * @description Loads a new name records
+   */
+  loadNames(list, opt) {
+    const useClear = typeof opt === 'boolean' ? opt : true;
+    const items = valueToArray(list);
+    let count = 0;
+    if (items.length) {
+      if (useClear) this.clear();
+      items.forEach((item) => { if (this.addName(item)) count++; });
+    };
+    return count;
+  };
+
+  /**
+   * @returns {void}
+   * @description Removes all of the instance members
+   */
+  clear() {
+    this.#_items.length = 0;
+  }
+
+  /**
+   * @param {forEachProcEx} cb - a callback function
+   * @returns {void}
+   * @description Calls given function for each name record
+   */
+  forEach(cb) {
+    if (typeof cb === 'function') this.#_items.forEach(cb);
+  }
+
+};
+
+/**
+ * @classdesc This class implements an interface of the channel item
+ */
+class TChnAliasItem {
+  /** @property {string} */
+  #_id = '';
+  /** @property {string} */
+  #_alias = '';
+  /** @property {TChnNamesList} */
+  #_names;
+  /** @property {object} */
+  #_status;
+
+  /**
+   * @description Creates an instance of the channel item
+   */
+  constructor() {
+    this.#_names = new TChnNamesList();
+    this.#_status = {
+      isEnabled: true,
+      isActive: true,
+    };
+    //===
+  }
+
+  /**
+   * @property {string} - defines a channel ID
+   */
+  get id() {
+    return this.#_id;
+  }
+
+  set id(value) {
+    this.setID(value);
+  }
+
+  /**
+   * @property {string} - defines a channel alias
+   */
+  get alias() {
+    return this.#_alias;
+  }
+
+  set alias(value) {
+    this.setAlias(value);
+  }
+
+  /**
+   * @property {TChnNamesList} - contains a list of a name records
+   * @readonly
+   */
+  get names() {
+    return this.#_names;
+  }
+
+  /**
+   * @property {string} - defines an instance status
+   * @readonly
+   */
+  get status() {
+    const { isActive, isEnabled } = this.#_status;
+    if (!isEnabled || this.#_id === '') return 'disabled';
+    return isActive ? 'up' : 'down';
+  }
+
+  /**
+   * @param {string} value - a channel ID
+   * @returns {boolean}
+   * @description Sets a channel ID
+   */
+  setID(value) {
+    const id = valueToIDString(value);
+    const isSucceed = id !== null;
+    if (isSucceed) this.#_id = id;
+    return isSucceed;
+  }
+
+  /**
+   * @param {string} value - a channel alias
+   * @returns {boolean}
+   * @description Sets a channel alias
+   */
+  setAlias(value) {
+    const alias = valueToIDString(value);
+    const isSucceed = alias !== null;
+    if (isSucceed) this.#_alias = alias;
+    return isSucceed;
+  }
+
+  /**
+   * @param {number} value
+   * @returns {?TChnNameRecord}
+   * @deprecated
+   * @description Returns a name record
+   * @see TChnNamesList.getName
+   */
+  getName(value) {
+    return this.#_names.getName(value);
+  }
+
+  /**
+   * @param {any} data - a name record
+   * @returns {boolean}
+   * @description Adds a new name record
+   * @see TChnNamesList.addName
+   */
+  addName(data) {
+    return this.#_names.addName(data);
+  }
+
+  /**
+   * @param {array} list - a list of an elements
+   * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
+   * @returns {number}
+   * @description Loads a list of a new name records
+   * @see TChnNamesList.loadNames
+   */
+  loadNames(...args) {
+    return this.#_names.loadNames(...args);
+  }
+
+  /**
+   * @returns {void}
+   * @description Sets item status to enabled
+   */
+  enable() {
+    this.#_status.isEnabled = true;
+  }
+
+  /**
+   * @returns {void}
+   * @description Sets item status to disabled
+   */
+  disable() {
+    this.#_status.isEnabled = false;
+  }
+
+  /**
+   * @returns {void}
+   * @description Sets item status to active/running
+   */
+  up() {
+    this.#_status.isActive = true;
+  }
+
+  /**
+   * @returns {void}
+   * @description Sets item status to inactive/stopped
+   */
+  down() {
+    this.#_status.isActive = false;
+  }
+
+  /**
+   * @param {string} value - a status value
+   * @returns {boolean}
+   * @description Sets item status
+   */
+  setStatus(value) {
+    const status = readAsString(value);
+    let result = true;
+    switch (status) {
+      case 'disabled': {
+        this.disable();
+        break;
+      }
+      case 'enabled': {
+        this.enable();
+        break;
+      }
+      case 'up': {
+        this.up();
+        break;
+      }
+      case 'down': {
+        this.down();
+        break;
+      }
+      default: {
+        result = false;
+      }
+    };
+    return result;
+  }
+
+  /**
+   * @returns {Object}
+   * @protected
+   * @description Provides an interface to an instance representation
+   *              for JSON.stringify()
+   */
+  toJSON() {
+    const { id, alias, names, status } = this;
+    return {
+      id,
+      alias,
+      name: names.value,
+      status,
+    };
+  }
+
+  /**
+   * @param {object} obj - an init data
+   * @returns {?TChnAliasItem}
+   * @static
+   * @description Creates a new alias element
+   */
+  static create(obj) {
+    let result = null;
+    if (isPlainObject(obj)) {
+      const item = new TChnAliasItem();
+      if (item.setID(obj.id)) {
+        const { isDisabled } = obj; /* only for compatibility purpose */
+        let { alias, name, status } = obj;
+        if (obj instanceof TChnAliasItem) name = obj.names.value;
+        item.setAlias(alias);
+        item.loadNames(name);
+        if (typeof isDisabled === 'boolean') {
+          // // TODO: process "status"
+          if (isDisabled) item.disable();
+        } else {
+          item.setStatus(status);
+        };
+        result = item;
+      };
+    };
+    return result;
+  }
+
+};
+
+/**
+ * @classdesc This class implements an interface of the channel items list
+ */
+class TChnAliasList {
+  /** @property {TChnAliasItem[]} */
+  #_items;
+
+  /**
+   * @description Creates an instance of the channel items list
+   */
+  constructor() {
+    this.#_items = [];
+  }
+
+  /**
+   * @property {number} - contains a quantity of the elements
+   * @readonly
+   */
+  get count() {
+    return this.#_items.length;
+  }
+
+  /**
+   * @property {boolean} - defines if the instance has any items
+   * @readonly
+   * @deprecated
+   */
+  get hasItems() {
+    return this.#_items.length > 0;
+  }
+
+  /**
+   * @returns {boolean}
+   * @description Returns a flag whether a list is empty or not
+   */
+  isEmpty() {
+    return this.count === 0;
+  }
+
+  /**
+   * @returns {boolean}
+   * @description Returns a flag whether a list has any members
+   */
+  isNotEmpty() {
+    return this.count > 0;
+  }
+
+  /**
+   * @param {any} value - a value to be verified
+   * @returns {boolean}
+   * @description Checks whether a given value is an index and fits
+   *              an Index range within the instance
+   */
+  chkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * @param {string} value - an element ID
+   * @returns {number}
+   * @description Searches an index of an element by its ID
+   */
+  searchIndexByID(value) {
+    const id = valueToIDString(value);
+    let index = -1;
+    if (id !== null && this.hasItems) {
+      index = this.#_items.findIndex((item) => id === item.id);
+    };
+    return index;
+  }
+
+  /**
+   * @param {number} value - an element index
+   * @returns {?TChnAliasItem}
+   * @description Returns an alias element by its index
+   */
+  getItem(value) {
+    return this.chkIndex(value) ? this.#_items[Number(value)] : null;
+  }
+
+  /**
+   * @param {string} value - an element ID
+   * @returns {?TChnAliasItem}
+   * @description Returns an alias element by its ID
+   */
+  getItemByID(value) {
+    return this.getItem(this.searchIndexByID(value));
+  }
+
+  /**
+   * @param {object} obj - an element to be added
+   * @returns {number}
+   * @description Adds an alias element
+   */
+  addItem(obj) {
+    const item = TChnAliasItem.create(obj);
+    let index = -1;
+    if (item !== null) {
+      const id = valueToIDString(item.id);
+      index = this.searchIndexByID(id);
+      if (index === -1) {
+        index = this.count;
+        this.#_items.push(item);
+      } else {
+        this.#_items[index] = item;
+      };
+    };
+    return index;
+  }
+
+  /**
+   * @param {number} value - an element index
+   * @returns {boolean}
+   * @description Tries to delete an element addressed by a given index
+   */
+  delItem(value) {
+    let isSucceed = this.chkIndex(value)
+    if (isSucceed) this.#_items.splice(Number(value), 1);
+    return isSucceed;
+  }
+
+  /**
+   * @param {array} list - a list of an elements
+   * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
+   * @returns {number}
+   * @description Loads a list of a new alias elements
+   */
+  loadItems(list, opt) {
+    const useClear = typeof opt === 'boolean' ? opt : true;
+    let count = 0;
+    if (isArray(list)) {
+      if (list.length > 0 && useClear) this.clear();
+      list.forEach((item) => { if (this.addItem(item) !== -1) count++; });
+    };
+    return count;
+  };
+
+  /**
+   * @returns {void}
+   * @description removes all of the instance members
+   */
+  clear() {
+    this.#_items.length = 0;
+  }
+
+  /**
+   * @param {forEachProcEx} cb - a callback function
+   * @returns {void}
+   * @description Calls given function for each alias element
+   */
+  forEach(cb) {
+    if (typeof cb === 'function') this.#_items.forEach(cb);
+  }
+
+};
+
+// === module exports block ===
+
+module.exports.loadAliasFromFileSync = loadAliasFromFileSync;
+module.exports.saveAliasToFileSync = saveAliasToFileSync;
+
+module.exports.TChnNameRecord = TChnNameRecord;
+module.exports.TChnNamesList = TChnNamesList;
+module.exports.TChnAliasItem = TChnAliasItem;
+module.exports.TChnAliasList = TChnAliasList;