@ygracs/chn-alias-list 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+#### *v0.0.6*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0.
+
 #### *v0.0.5*
 
 Pre-release version.
@@ -13,12 +19,6 @@ Pre-release version.
 > - add 'filter'-method to a `TChnAliasList`-class;
 > - other fixes.
 
-#### *v0.0.4*
-
-Pre-release version.
-
-> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.2.
-
-#### *v0.0.1-0.0.3*
+#### *v0.0.1-0.0.4*
 
 Pre-release version.

package/lib/chn-alias-list.js

@@ -1,4 +1,4 @@
-// [v0.1.044-20250414]
+// [v0.1.045-20250820]
 
 // === module init block ===
 
@@ -12,15 +12,19 @@ const {
   loadJSONFromFileSync, saveJSONToFileSync,
 } = require('@cntwg/file-helper');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
+
+/***
+ * (* helper function definitions *)
+ */
 
 /**
+ * Converts a <Lang, Text> key-pair to a string
  * @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 = [ '', '' ];
@@ -46,29 +50,30 @@ function convertLangTextValueToString(data, opt) {
  */
 
 /**
+ * An 'FS'-ops descriptor.
  * @typedef {Object} fsoDescr
  * @property {boolean} isERR - flag
- * @property {number|undefined} errCode - error code
+ * @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
- * @description A fs ops description.
+ * @property {string} [errMsg] - event message
+ * @property {string} [source] - path to file
+ * @property {any} [content] - file content
  */
 
 /**
+ * A result of `loadAliasFromFile...`
  * @typedef {Object} RVAL_loadaliasff
  * @property {fsoDescr} descr - ops description
  * @property {(null|TChnAliasItem|TChnAliasList)} result - loaded content
- * @description A result of `loadAliasFromFile...`
  */
 
 /**
+ * Loads an alias from a file
  * @function loadAliasFromFileSync
  * @param {string} src - a path to some file
  * @param {any} [opt] - <reserved>
  * @returns {RVAL_loadaliasff}
- * @description Loads an alias from a file
+ * @see {@link loadJSONFromFileSync} for details of an `opt` param
  */
 function loadAliasFromFileSync(src, opt) {
   let { descr, obj } = loadJSONFromFileSync(src, opt);
@@ -86,12 +91,13 @@ function loadAliasFromFileSync(src, opt) {
 };
 
 /**
+ * Saves an alias to a file
  * @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
+ * @see {@link saveJSONToFileSync} for details of an `opt` param
  */
 function saveAliasToFileSync(src, content, opt) {
   const obj = isArray(content) ? content : null;
@@ -109,20 +115,21 @@ function saveAliasToFileSync(src, content, opt) {
  * @classdesc This class implements an interface of the name record
  */
 class TChnNameRecord {
-  /** @property {string} */
+  /** @type {string} */
   #_lang;
-  /** @property {string} */
+  /** @type {string} */
   #_value;
 
   /**
-   * @description Creates an instance of the name record
+   * Creates an instance of the name record
    */
   constructor() {
     this.reset();
   }
 
   /**
-   * @property {string} - defines a language
+   * Contains a language
+   * @type {string}
    * @readonly
    */
   get lang() {
@@ -130,7 +137,8 @@ class TChnNameRecord {
   }
 
   /**
-   * @property {string} - defines a value of the record
+   * Contains a value of the record
+   * @type {string}
    * @readonly
    */
   get text() {
@@ -138,7 +146,8 @@ class TChnNameRecord {
   }
 
   /**
-   * @property {array} - a value of the record
+   * Contains a value of the record
+   * @type {string[]}
    */
   get value() {
     return [ this.#_lang, this.#_value ];
@@ -149,9 +158,9 @@ class TChnNameRecord {
   }
 
   /**
+   * Sets the record value
    * @param {any} data - a value of the record
    * @returns {boolean}
-   * @description Sets the record value
    */
   setValue(data) {
     let _data = data;
@@ -187,17 +196,17 @@ class TChnNameRecord {
   }
 
   /**
+   * Returns value as a formated string
    * @param {any} opt - <reserved>
    * @returns {string}
-   * @description Returns value as a formated string
    */
   toFormatString(opt) {
     return convertLangTextValueToString(this.value, opt);
   }
 
   /**
+   * Clears the record
    * @returns {void}
-   * @description Clears the record
    */
   reset() {
     this.#_lang = '';
@@ -207,32 +216,32 @@ class TChnNameRecord {
 };
 
 /**
+ * A user defined procedure to process an array elements
  * @callback forEachProcEx
- * @param {any} item
- * @param {number} [index]
+ * @param {any} item - some element
+ * @param {number} [index] - element index
  * @param {any[]} [arr]
  * @returns {void}
- * @description user defined procedure to process an array elements
  */
 
  /**
+  * 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}
-  * @description user defined procedure to process an array elements
   */
 
 /**
  * @classdesc This class implements an interface of the name records list
  */
 class TChnNamesList {
-  /** @property {TChnNameRecord[]} */
+  /** @type {TChnNameRecord[]} */
   #_items;
 
   /**
-   * @description Creates an instance of the name records list
+   * Creates an instance of the name records list
    */
   constructor() {
     this.#_items = [];
@@ -255,7 +264,8 @@ class TChnNamesList {
   }
 
   /**
-   * @property {number} - contains a quantity of a name records
+   * Contains a quantity of a name records
+   * @type {number}
    * @readonly
    */
   get count() {
@@ -263,7 +273,8 @@ class TChnNamesList {
   }
 
   /**
-   * @property {TChnNameRecord[]} - contains a list of a name records
+   * Contains a list of a name records
+   * @type {TChnNameRecord[]}
    * @readonly
    */
   get value() {
@@ -275,26 +286,26 @@ class TChnNamesList {
   }
 
   /**
+   * Returns a flag whether a list is empty or not
    * @returns {boolean}
-   * @description Returns a flag whether a list is empty or not
    */
   isEmpty() {
     return this.count === 0;
   }
 
   /**
+   * Returns a flag whether a list has any members
    * @returns {boolean}
-   * @description Returns a flag whether a list has any members
    */
   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}
-   * @description Checks whether a given value is an index and fits
-   *              an Index range within the instance
    */
   chkIndex(value) {
     const index = valueToIndex(value);
@@ -302,9 +313,9 @@ class TChnNamesList {
   }
 
   /**
+   * Searches an index of a given name
    * @param {string} value - a name
    * @returns {number}
-   * @description Searches an index of a given name
    */
   getIndex(value) {
     const opt = { numberToString: true };
@@ -326,9 +337,9 @@ class TChnNamesList {
   }
 
   /**
+   * Returns a name record
    * @param {number} value - an element index
    * @returns {?TChnNameRecord}
-   * @description Returns a name record
    */
   getItem(value) {
     return this.chkIndex(value) ? this.#_items[Number(value)] : null;
@@ -344,9 +355,9 @@ class TChnNamesList {
   }
 
   /**
+   * Adds a new name record to a list members
    * @param {any} data - a value of a name record
    * @returns {boolean}
-   * @description Adds a new name record to a list members
    */
   addItem(data) {
     const _data = data instanceof TChnNameRecord ? data.value : data;
@@ -366,9 +377,9 @@ class TChnNamesList {
   }
 
   /**
+   * Tries to delete a name record addressed by a given index
    * @param {number} value - an element index
    * @returns {boolean}
-   * @description Tries to delete a name record addressed by a given index
    */
   delItem(value) {
     let isSucceed = this.chkIndex(value)
@@ -376,7 +387,6 @@ class TChnNamesList {
     return isSucceed;
   }
 
-  //
   /**
    * @deprecated
    * @see TChnNamesList.loadItems
@@ -387,10 +397,10 @@ class TChnNamesList {
   }
 
   /**
+   * Loads a new name records
    * @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
    */
   loadItems(list, opt) {
     const useClear = typeof opt === 'boolean' ? opt : true;
@@ -404,27 +414,26 @@ class TChnNamesList {
   };
 
   /**
+   * Removes all of the instance members
    * @returns {void}
-   * @description Removes all of the instance members
    */
   clear() {
     this.#_items.length = 0;
   }
 
   /**
+   * Calls given function for each name record
    * @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);
   }
 
   /**
+   * Returns an array of a  name records picked up by a given function
    * @param {cbArrECheck} cb - a callback function
    * @returns {TChnNameRecord[]}
-   * @description Returns an array of a  name records picked up
-   *              by a given function
    */
   filter(cb) {
     return typeof cb === 'function' ? this.#_items.filter(cb) : [];
@@ -436,13 +445,19 @@ class TChnNamesList {
  * @classdesc This class implements an interface of the channel item
  */
 class TChnAliasItem {
-  /** @property {string} */
+  /** @type {string} */
   #_id = '';
-  /** @property {string} */
+  /** @type {string} */
   #_alias = '';
-  /** @property {TChnNamesList} */
+  /** @type {TChnNamesList} */
   #_names;
-  /** @property {object} */
+  /**
+   * A channel status
+   * @typedef {Object} chnStat
+   * @property {boolean} isEnabled
+   * @property {boolean} isActive
+   */
+  /** @type {chnStat} */
   #_status;
 
   /**
@@ -458,7 +473,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel ID
+   * Contains a channel ID
+   * @type {string}
    */
   get id() {
     return this.#_id;
@@ -469,7 +485,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel alias
+   * Contains a channel alias
+   * @type {string}
    */
   get alias() {
     return this.#_alias;
@@ -480,7 +497,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {TChnNamesList} - contains a list of a name records
+   * Contains a list of a name records
+   * @type {TChnNamesList}
    * @readonly
    */
   get names() {
@@ -488,7 +506,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines an instance status
+   * Contains an instance status
+   * @type {string}
    * @readonly
    */
   get status() {
@@ -498,9 +517,10 @@ class TChnAliasItem {
   }
 
   /**
+   * Sets a channel ID
    * @param {string} value - a channel ID
    * @returns {boolean}
-   * @description Sets a channel ID
+   * @see valueToIDString
    */
   setID(value) {
     const id = valueToIDString(value);
@@ -510,9 +530,10 @@ class TChnAliasItem {
   }
 
   /**
+   * Sets a channel alias
    * @param {string} value - a channel alias
    * @returns {boolean}
-   * @description Sets a channel alias
+   * @see valueToIDString
    */
   setAlias(value) {
     const alias = valueToIDString(value);
@@ -522,10 +543,10 @@ class TChnAliasItem {
   }
 
   /**
+   * Returns a name record
    * @param {number} value
    * @returns {?TChnNameRecord}
    * @deprecated
-   * @description Returns a name record
    * @see TChnNamesList.getItem
    */
   getName(value) {
@@ -533,9 +554,9 @@ class TChnAliasItem {
   }
 
   /**
+   * Adds a new name record
    * @param {any} data - a name record
    * @returns {boolean}
-   * @description Adds a new name record
    * @see TChnNamesList.addItem
    */
   addName(data) {
@@ -543,10 +564,10 @@ class TChnAliasItem {
   }
 
   /**
+   * Loads a list of a new name records
    * @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.loadItems
    */
   loadNames(...args) {
@@ -554,41 +575,41 @@ class TChnAliasItem {
   }
 
   /**
+   * Sets item status to enabled
    * @returns {void}
-   * @description Sets item status to enabled
    */
   enable() {
     this.#_status.isEnabled = true;
   }
 
   /**
+   * Sets item status to disabled
    * @returns {void}
-   * @description Sets item status to disabled
    */
   disable() {
     this.#_status.isEnabled = false;
   }
 
   /**
+   * Sets item status to active/running
    * @returns {void}
-   * @description Sets item status to active/running
    */
   up() {
     this.#_status.isActive = true;
   }
 
   /**
+   * Sets item status to inactive/stopped
    * @returns {void}
-   * @description Sets item status to inactive/stopped
    */
   down() {
     this.#_status.isActive = false;
   }
 
   /**
+   * Sets item status
    * @param {string} value - a status value
    * @returns {boolean}
-   * @description Sets item status
    */
   setStatus(value) {
     const status = readAsString(value);
@@ -618,10 +639,9 @@ class TChnAliasItem {
   }
 
   /**
+   * Provides an interface to an instance representation for JSON.stringify()
    * @returns {Object}
    * @protected
-   * @description Provides an interface to an instance representation
-   *              for JSON.stringify()
    */
   toJSON() {
     const { id, alias, names, status } = this;
@@ -634,10 +654,10 @@ class TChnAliasItem {
   }
 
   /**
+   * Creates a new alias element
    * @param {object} obj - an init data
    * @returns {?TChnAliasItem}
    * @static
-   * @description Creates a new alias element
    */
   static create(obj) {
     let result = null;
@@ -667,11 +687,11 @@ class TChnAliasItem {
  * @classdesc This class implements an interface of the channel items list
  */
 class TChnAliasList {
-  /** @property {TChnAliasItem[]} */
+  /** @type {TChnAliasItem[]} */
   #_items;
 
   /**
-   * @description Creates an instance of the channel items list
+   * Creates an instance of the channel items list
    */
   constructor() {
     this.#_items = [];
@@ -694,7 +714,8 @@ class TChnAliasList {
   }
 
   /**
-   * @property {number} - contains a quantity of the elements
+   * Contains a quantity of the elements
+   * @type {number}
    * @readonly
    */
   get count() {
@@ -702,26 +723,26 @@ class TChnAliasList {
   }
 
   /**
+   * Returns a flag whether a list is empty or not
    * @returns {boolean}
-   * @description Returns a flag whether a list is empty or not
    */
   isEmpty() {
     return this.count === 0;
   }
 
   /**
+   * Returns a flag whether a list has any members
    * @returns {boolean}
-   * @description Returns a flag whether a list has any members
    */
   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}
-   * @description Checks whether a given value is an index and fits
-   *              an Index range within the instance
    */
   chkIndex(value) {
     const index = valueToIndex(value);
@@ -729,9 +750,10 @@ class TChnAliasList {
   }
 
   /**
+   * Searches an index of an element by its ID
    * @param {string} value - an element ID
    * @returns {number}
-   * @description Searches an index of an element by its ID
+   * @see valueToIDString
    */
   searchIndexByID(value) {
     const id = valueToIDString(value);
@@ -743,27 +765,27 @@ class TChnAliasList {
   }
 
   /**
+   * Returns an alias element by its 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;
   }
 
   /**
+   * Returns an alias element by its ID
    * @param {string} value - an element ID
    * @returns {?TChnAliasItem}
-   * @description Returns an alias element by its ID
    */
   getItemByID(value) {
     return this.getItem(this.searchIndexByID(value));
   }
 
   /**
+   * Adds an alias element
    * @param {object} obj - an element to be added
    * @returns {number}
-   * @description Adds an alias element
    */
   addItem(obj) {
     const item = TChnAliasItem.create(obj);
@@ -782,9 +804,9 @@ class TChnAliasList {
   }
 
   /**
+   * Tries to delete an element addressed by a given 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)
@@ -793,10 +815,10 @@ class TChnAliasList {
   }
 
   /**
+   * Loads a list of a new alias elements
    * @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;
@@ -809,27 +831,26 @@ class TChnAliasList {
   };
 
   /**
+   * Removes all of the instance members
    * @returns {void}
-   * @description removes all of the instance members
    */
   clear() {
     this.#_items.length = 0;
   }
 
   /**
+   * Calls given function for each alias element
    * @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);
   }
 
   /**
+   * Returns an array of a  name records picked up by a given function
    * @param {cbArrECheck} cb - a callback function
    * @returns {TChnAliasItem[]}
-   * @description Returns an array of a  name records picked up
-   *              by a given function
    */
   filter(cb) {
     return typeof cb === 'function' ? this.#_items.filter(cb) : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "A small library which provides some helper classes for EPG-tools",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -26,11 +26,11 @@
   },
   "dependencies": {
     "@cntwg/file-helper": "^0.0.1",
-    "@ygracs/bsfoc-lib-js": "^0.2.3"
+    "@ygracs/bsfoc-lib-js": "^0.3.0"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "jsdoc-to-markdown": "^9.1.1",
+    "jest": "^30.0.5",
+    "jsdoc-to-markdown": "^9.1.2",
     "minimist": "^1.2.8"
   }
 }