@ygracs/chn-alias-list 0.0.7 → 0.0.9

package/lib/chn-names.js

@@ -0,0 +1,392 @@
+// [v0.1.059-20260628]
+
+// === module init block ===
+
+const {
+  isArray, isPlainObject,
+  valueToArray, valueToIndex, valueToIDString,
+  readAsString,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+/**
+ * An array of two elements that represents a `<lang>`-`<text>` pair
+ * @typedef {string[]} ILangTextPair
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {ILangTextPair}
+ */
+module.exports.ILangTextPair = [];
+
+/**
+ * Converts a <Lang, Text> key-pair to a string
+ * @function convertLangTextValueToString
+ * @param {ILangTextPair} data - contains a data to be printed
+ * @param {object} [opt]
+ * @returns {string}
+ * @inner
+ */
+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 ===
+
+/**
+ * @classdesc This class implements an interface of the name record
+ */
+class TChnNameRecord {
+  /** @type {string} */
+  #_lang;
+  /** @type {string} */
+  #_value;
+
+  /**
+   * Creates an instance of the name record
+   */
+  constructor() {
+    this.reset();
+  }
+
+  /**
+   * Contains a language
+   * @type {string}
+   * @readonly
+   */
+  get lang() {
+    return this.#_lang;
+  }
+
+  /**
+   * Contains a value of the record
+   * @type {string}
+   * @readonly
+   */
+  get text() {
+    return this.#_value;
+  }
+
+  /**
+   * Contains a value of the record
+   * @type {ILangTextPair}
+   */
+  get value() {
+    return [ this.#_lang, this.#_value ];
+  }
+
+  set value(data) {
+    this.setValue(data);
+  }
+
+  /**
+   * Sets the record value
+   * @param {any} data - a value of the record
+   * @returns {boolean}
+   */
+  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;
+  }
+
+  /**
+   * Returns value as a formated string
+   * @param {any} opt - <reserved>
+   * @returns {string}
+   */
+  toFormatString(opt) {
+    return convertLangTextValueToString(this.value, opt);
+  }
+
+  /**
+   * Clears the record
+   * @returns {void}
+   */
+  reset() {
+    this.#_lang = '';
+    this.#_value = '';
+  }
+
+};
+module.exports.TChnNameRecord = TChnNameRecord;
+
+/**
+ * A settings for the list load ops
+ * @typedef {Object} ILoadListItemsOptions
+ * @property {boolean} [useClear=true] - indicates whether to clear the list
+ *     before load
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {ILoadListItemsOptions}
+ */
+module.exports.ILoadListItemsOptions = {};
+
+/**
+ * A user defined procedure to process an array elements
+ * @callback forEachProcEx
+ * @param {any} item - some element
+ * @param {number} [index] - element index
+ * @param {any[]} [arr]
+ * @returns {void}
+ */
+
+ /**
+  * A user defined procedure to process an array elements
+  * @callback cbArrECheck
+  * @param {any} item - some element
+  * @param {number} [index] - element index
+  * @param {any[]} [arr] - array a callback was called upon
+  * @returns {any}
+  */
+
+/**
+ * @classdesc This class implements an interface of the name records list
+ */
+class TChnNamesList {
+  /** @type {TChnNameRecord[]} */
+  #_items;
+
+  /**
+   * Creates an instance of the name records list
+   */
+  constructor() {
+    this.#_items = [];
+  }
+
+  [Symbol.iterator]() {
+    let index = 0;
+    return {
+      next: () => {
+        if (index < this.count) {
+          return { done: false, value: this.getItem(index++) };
+        } else {
+          return { done: true };
+        };
+      },
+      return() {
+        return { done: true };
+      },
+    };
+  }
+
+  /**
+   * Contains a quantity of a name records
+   * @type {number}
+   * @readonly
+   */
+  get count() {
+    return this.#_items.length;
+  }
+
+  /**
+   * Contains a list of a name entries
+   * @type {ILangTextPair[]}
+   * @readonly
+   */
+  get value() {
+    /** @type {ILangTextPair[]} */
+    const result = [];
+    this.#_items.forEach((item, i) => {
+      result.push(item.value);
+    });
+    return result;
+  }
+
+  /**
+   * Returns a flag whether a list is empty or not
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.count === 0;
+  }
+
+  /**
+   * Returns a flag whether a list has any members
+   * @returns {boolean}
+   */
+  isNotEmpty() {
+    return this.count > 0;
+  }
+
+  /**
+   * Checks whether a given value is an index and fits an index range
+   * within the instance
+   * @param {any} value - a value to be verified
+   * @returns {boolean}
+   * @deprecated
+   * @todo \[since v0.0.9] deprecated. Use {@link checkIndex} instead.
+   */
+  chkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * Checks whether a given value is an index and fits an index range
+   * within the instance
+   * @since 0.0.9
+   * @param {any} value - a value to be verified
+   * @returns {boolean}
+   */
+  checkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * Returns an index in case a given value is a valid index value and not exceeds
+   * an index range within the instance. If failed a `-1` returned
+   * @param {any} value - value to evaluate
+   * @returns {number}
+   * @since 0.0.9
+   */
+  tryIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count ? index : -1;
+  }
+
+  /**
+   * Searches an index of a given name
+   * @param {string} value - a name
+   * @returns {number}
+   */
+  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;
+  }
+
+  /**
+   * Returns a name record
+   * @since 0.0.5
+   * @param {number} value - an element index
+   * @returns {?TChnNameRecord}
+   */
+  getItem(value) {
+    const i = this.tryIndex(value);
+    return i === -1 ? null: this.#_items[i];
+  }
+
+  /**
+   * Adds a new name record to a list members
+   * @since 0.0.5
+   * @param {any} data - a value of a name record
+   * @returns {boolean}
+   */
+  addItem(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;
+  }
+
+  /**
+   * Tries to delete a name record addressed by a given index
+   * @since 0.0.5
+   * @param {number} value - an element index
+   * @returns {boolean}
+   */
+  delItem(value) {
+    const i = this.tryIndex(value);
+    let isSucceed = i !== -1;
+    if (isSucceed) this.#_items.splice(i, 1);
+    return isSucceed;
+  }
+
+  /**
+   * Defines whether to clear the list before load
+   * @typedef {boolean} loadListItemsOption
+   */
+  /**
+   * Loads a new name records
+   * @since 0.0.5
+   * @param {any} list - an element or a list of an elements
+   * @param {loadListItemsOption|ILoadListItemsOptions} [opt] - load options
+   * @returns {number}
+   */
+  loadItems(list, opt) {
+    let {
+      useClear = true,
+    } = isPlainObject(opt) ? opt : { useClear: opt };
+    if (typeof useClear !== 'boolean') useClear = true;
+    const items = valueToArray(list);
+    let count = 0;
+    if (items.length) {
+      if (useClear) this.clear();
+      items.forEach((item) => { if (this.addItem(item)) count++; });
+    };
+    return count;
+  };
+
+  /**
+   * Removes all of the instance members
+   * @returns {void}
+   */
+  clear() {
+    this.#_items.length = 0;
+  }
+
+  /**
+   * Calls given function for each name record
+   * @param {forEachProcEx} cb - a callback function
+   * @returns {void}
+   */
+  forEach(cb) {
+    if (typeof cb === 'function') this.#_items.forEach(cb);
+  }
+
+  /**
+   * Returns an array of a  name records picked up by a given function
+   * @param {cbArrECheck} cb - a callback function
+   * @returns {TChnNameRecord[]}
+   */
+  filter(cb) {
+    return typeof cb === 'function' ? this.#_items.filter(cb) : [];
+  }
+
+};
+module.exports.TChnNamesList = TChnNamesList;

package/lib/file-helper-ext.js

@@ -1,4 +1,4 @@
-// [v0.1.049-20260130]
+// [v0.1.050-20260308]
 
 // === module init block ===
 
@@ -21,14 +21,6 @@ const {
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
 /**
  * A result of `loadAliasFromFile...`
  * @typedef {Object} RVAL_loadaliasff
@@ -58,6 +50,7 @@ function loadAliasFromFileSync(src, opt) {
   };
   return { descr, result };
 };
+module.exports.loadAliasFromFileSync = loadAliasFromFileSync;
 
 /**
  * Saves an alias to a file
@@ -91,12 +84,4 @@ function saveAliasToFileSync(src, content, opt) {
   };
   return data;
 };
-
-/***
- * (* class definitions *)
- */
-
-// === module exports block ===
-
-module.exports.loadAliasFromFileSync = loadAliasFromFileSync;
 module.exports.saveAliasToFileSync = saveAliasToFileSync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A small library which provides some helper classes for EPG-tools",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -12,6 +12,7 @@
   "types": "./index.d.ts",
   "files": [
     "doc/*.md",
+    "lib/chn-names.js",
     "lib/chn-alias-list.js",
     "lib/file-helper-ext.js",
     "lib/*.d.ts",
@@ -30,12 +31,12 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/file-helper": "^0.0.3",
-    "@ygracs/bsfoc-lib-js": "~0.3.3"
+    "@cntwg/file-helper": "~0.0.4",
+    "@ygracs/bsfoc-lib-js": "~0.4.0"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
+    "jest": "^30.4.2",
     "jsdoc-to-markdown": "^9.1.3",
     "minimist": "^1.2.8",
     "typescript": "~5.9.3"