@ygracs/chn-alias-list 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -1,9 +1,24 @@
-#### *v0.0.4*
+#### *v0.0.6*
 
 Pre-release version.
 
-> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.2.
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0.
 
-#### *v0.0.1-0.0.3*
+#### *v0.0.5*
+
+Pre-release version.
+
+> - update `chn-alias-list.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.3;
+> - add dependency on `@cntwg/file-helper` module;
+> - add 'filter'-method to a `TChnNamesList`-class;
+> - change name of a method `getName` into `getItem` for a `TChnNamesList`-class (*old name deprecated*);
+> - change name of a method `addName` into `addItem` for a `TChnNamesList`-class (*old name deprecated*);
+> - change name of a method `delName` into `delItem` for a `TChnNamesList`-class (*old name deprecated*);
+> - change name of a method `loadNames` into `loadItems` for a `TChnNamesList`-class (*old name deprecated*);
+> - add 'filter'-method to a `TChnAliasList`-class;
+> - other fixes.
+
+#### *v0.0.1-0.0.4*
 
 Pre-release version.

package/doc/chn-alias-list.md

@@ -1,7 +1,7 @@
 
->|***rev.*:**|0.0.3|
+>|***rev.*:**|0.0.5|
 >|:---|---:|
->|date:|2024-10-21|
+>|date:|2025-04-14|
 
 ## Introduction
 
@@ -138,6 +138,13 @@ Searches an index of a given name in the list.
 <a name="TChnNamesList+getName"></a>
 ##### **getName(value)** => `?TChnNameRecord`
 
+> \[!] NOTE: `[since v0.0.5]` deprecated. Use `getItem` instead.
+
+<a name="TChnNamesList+getItem"></a>
+##### **getItem(value)** => `?TChnNameRecord`
+
+> since: \[v0.0.5]
+
 Returns a name record addressed by a given index.
 
 | parameter name | value type | default value | description |
@@ -147,6 +154,13 @@ Returns a name record addressed by a given index.
 <a name="TChnNamesList+addName"></a>
 #### **addName(data)** => `boolean`
 
+> \[!] NOTE: `[since v0.0.5]` deprecated. Use `addItem` instead.
+
+<a name="TChnNamesList+addItem"></a>
+#### **addItem(data)** => `boolean`
+
+> since: \[v0.0.5]
+
 Adds a new name record to a list members.
 
 | parameter name | value type | default value | description |
@@ -156,6 +170,13 @@ Adds a new name record to a list members.
 <a name="TChnNamesList+delName"></a>
 ##### **delName(value)** => `boolean`
 
+> \[!] NOTE: `[since v0.0.5]` deprecated. Use `delItem` instead.
+
+<a name="TChnNamesList+delItem"></a>
+##### **delItem(value)** => `boolean`
+
+> since: \[v0.0.5]
+
 Tries to delete a name record addressed by a given index.
 
 | parameter name | value type | default value | description |
@@ -165,6 +186,13 @@ Tries to delete a name record addressed by a given index.
 <a name="TChnNamesList+loadNames"></a>
 ##### **loadNames(list, \[opt])** => `number`
 
+> \[!] NOTE: `[since v0.0.5]` deprecated. Use `loadItems` instead.
+
+<a name="TChnNamesList+loadItems"></a>
+##### **loadItems(list, \[opt])** => `number`
+
+> since: \[v0.0.5]
+
 Loads a list of a new name records.
 
 | parameter name | value type | default value | description |
@@ -180,7 +208,18 @@ Removes all of the instance members.
 <a name="TChnNamesList+forEach"></a>
 ##### **forEach(cb)** => `void`
 
-Calls given function for each name record in the list.
+Calls a given function upon each name record in the list.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `cb` | `callback` | --- | a callback function defined by a user |
+
+<a name="TChnNamesList+filter"></a>
+##### **filter(cb)** => `TChnNameRecord[]`
+
+> since: \[v0.0.5]
+
+Returns an array of a name records picked up by a given function.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
@@ -419,6 +458,17 @@ Calls given function for each alias element in the list.
 |:---|---|---:|:---|
 | `cb` | `callback` | --- | a callback function defined by a user |
 
+<a name="TChnAliasList+filter"></a>
+##### **filter(cb)** => `TChnAliasItem[]`
+
+> since: \[v0.0.5]
+
+Returns an array of a channel items picked up by a given function.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `cb` | `callback` | --- | a callback function defined by a user |
+
 ## Module functions
 
 <a name="loadAliasFromFileSync"></a>

package/lib/chn-alias-list.js

@@ -1,4 +1,4 @@
-// [v0.1.033-20241021]
+// [v0.1.045-20250820]
 
 // === module init block ===
 
@@ -10,17 +10,21 @@ const {
 
 const {
   loadJSONFromFileSync, saveJSONToFileSync,
-} = require('#lib/file-helper.js');
+} = 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,30 +216,56 @@ 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}
+  */
+
 /**
  * @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 = [];
   }
 
+  [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 };
+      },
+    };
+  }
+
   /**
-   * @property {number} - contains a quantity of a name records
+   * Contains a quantity of a name records
+   * @type {number}
    * @readonly
    */
   get count() {
@@ -238,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() {
@@ -250,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);
@@ -277,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 };
@@ -292,20 +328,38 @@ class TChnNamesList {
   }
 
   /**
+   * @deprecated
+   * @see TChnNamesList.getItem
+   * @todo [from v0.0.5] make obsolete
+   */
+  getName(value) {
+    return this.getItem(value);
+  }
+
+  /**
+   * Returns a name record
    * @param {number} value - an element index
    * @returns {?TChnNameRecord}
-   * @description Returns a name record
    */
-  getName(value) {
+  getItem(value) {
     return this.chkIndex(value) ? this.#_items[Number(value)] : null;
   }
 
   /**
+   * @deprecated
+   * @see TChnNamesList.addItem
+   * @todo [from v0.0.5] make obsolete
+   */
+  addName(data) {
+    return this.addItem(data);
+  }
+
+  /**
+   * 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
    */
-  addName(data) {
+  addItem(data) {
     const _data = data instanceof TChnNameRecord ? data.value : data;
     const item = new TChnNameRecord();
     const isSucceed = item.setValue(_data) && item.text !== '';
@@ -314,63 +368,96 @@ class TChnNamesList {
   }
 
   /**
+   * @deprecated
+   * @see TChnNamesList.delItem
+   * @todo [from v0.0.5] make obsolete
+   */
+  delName(value) {
+    return this.delItem(value);
+  }
+
+  /**
+   * 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
    */
-  delName(value) {
+  delItem(value) {
     let isSucceed = this.chkIndex(value)
     if (isSucceed) this.#_items.splice(Number(value), 1);
     return isSucceed;
   }
 
   /**
+   * @deprecated
+   * @see TChnNamesList.loadItems
+   * @todo [from v0.0.5] make obsolete
+   */
+  loadNames(...args) {
+    return this.loadItems(...args);
+  }
+
+  /**
+   * 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
    */
-  loadNames(list, opt) {
+  loadItems(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++; });
+      items.forEach((item) => { if (this.addItem(item)) count++; });
     };
     return count;
   };
 
   /**
+   * 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[]}
+   */
+  filter(cb) {
+    return typeof cb === 'function' ? this.#_items.filter(cb) : [];
+  }
+
 };
 
 /**
  * @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;
 
   /**
@@ -386,7 +473,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel ID
+   * Contains a channel ID
+   * @type {string}
    */
   get id() {
     return this.#_id;
@@ -397,7 +485,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel alias
+   * Contains a channel alias
+   * @type {string}
    */
   get alias() {
     return this.#_alias;
@@ -408,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() {
@@ -416,7 +506,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines an instance status
+   * Contains an instance status
+   * @type {string}
    * @readonly
    */
   get status() {
@@ -426,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);
@@ -438,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);
@@ -450,73 +543,73 @@ class TChnAliasItem {
   }
 
   /**
+   * Returns a name record
    * @param {number} value
    * @returns {?TChnNameRecord}
    * @deprecated
-   * @description Returns a name record
-   * @see TChnNamesList.getName
+   * @see TChnNamesList.getItem
    */
   getName(value) {
-    return this.#_names.getName(value);
+    return this.#_names.getItem(value);
   }
 
   /**
+   * Adds a new name record
    * @param {any} data - a name record
    * @returns {boolean}
-   * @description Adds a new name record
-   * @see TChnNamesList.addName
+   * @see TChnNamesList.addItem
    */
   addName(data) {
-    return this.#_names.addName(data);
+    return this.#_names.addItem(data);
   }
 
   /**
+   * 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.loadNames
+   * @see TChnNamesList.loadItems
    */
   loadNames(...args) {
-    return this.#_names.loadNames(...args);
+    return this.#_names.loadItems(...args);
   }
 
   /**
+   * 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);
@@ -546,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;
@@ -562,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;
@@ -595,54 +687,62 @@ 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 = [];
   }
 
-  /**
-   * @property {number} - contains a quantity of the elements
-   * @readonly
-   */
-  get count() {
-    return this.#_items.length;
+  [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 };
+      },
+    };
   }
 
   /**
-   * @property {boolean} - defines if the instance has any items
+   * Contains a quantity of the elements
+   * @type {number}
    * @readonly
-   * @deprecated
    */
-  get hasItems() {
-    return this.#_items.length > 0;
+  get count() {
+    return this.#_items.length;
   }
 
   /**
+   * 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);
@@ -650,41 +750,42 @@ 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);
     let index = -1;
-    if (id !== null && this.hasItems) {
+    if (id !== null && this.isNotEmpty()) {
       index = this.#_items.findIndex((item) => id === item.id);
     };
     return index;
   }
 
   /**
+   * 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);
@@ -703,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)
@@ -714,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;
@@ -730,22 +831,31 @@ 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[]}
+   */
+  filter(cb) {
+    return typeof cb === 'function' ? this.#_items.filter(cb) : [];
+  }
+
 };
 
 // === module exports block ===

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A small library which provides some helper classes for EPG-tools",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -12,7 +12,6 @@
   "files": [
     "doc/chn-alias-list.md",
     "lib/chn-alias-list.js",
-    "lib/file-helper.js",
     "index.js",
     "CHANGELOG.md"
   ],
@@ -26,11 +25,12 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.2.2"
+    "@cntwg/file-helper": "^0.0.1",
+    "@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"
   }
 }

package/lib/file-helper.js

@@ -1,442 +0,0 @@
-// [v0.1.029-20250218]
-
-// === module init block ===
-
-const fs = require('fs');
-const fse = require('fs').promises;
-
-const {
-  isPlainObject,
-} = require('@ygracs/bsfoc-lib-js');
-
-// === module extra block (helper functions) ===
-
-/**
- * @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} VCOR_evalerrfs
- * @property {boolean} isSucceed - ops flag
- * @property {fsoDescr} descr - description
- * @description A result of an error check ops.
- */
-
-/**
- * @function checkFsError
- * @param {fsoDescr} descr
- * @param {Error} err
- * @returns {VCOR_evalerrfs}
- * @inner
- * @description Checks an error code of a fs ops and sets descr info if succeed
- */
-function checkFsError(descr, err) {
-  let isSucceed = false;
-  if (isPlainObject(err) && isPlainObject(descr)) {
-    switch (err.code) {
-      case 'ENOENT':
-      case 'EISDIR':
-      case 'ENOTDIR':
-      case 'EPERM': {
-        descr.errCode = err.errno;
-        descr.errEvent = err.code;
-        descr.errMsg = `ERR_FILE_${err.code}`;
-        isSucceed = true;
-        break;
-      }
-      default: {}
-    };
-    if (isSucceed) descr.isERR = true;
-  };
-  return { isSucceed, descr };
-};
-
-// === module main block ===
-
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
-/**
- * @function loadFromFileSync
- * @param {string} src - a path to some file
- * @returns {fsoDescr}
- * @inner
- * @description Loads file by a given path
- */
-function loadFromFileSync(src) {
-  /** @type {fsoDescr} */
-  const data = {
-    isERR: false,
-    errCode: 0,
-    errEvent: '',
-    errMsg: '',
-    source: '',
-    content: '',
-  };
-  if (typeof src !== 'string') {
-    if (src !== undefined) {
-      data.isERR = true;
-      data.errEvent = 'ERR_INVARG';
-      data.errMsg = 'The "source" argument must be a string';
-    };
-  } else {
-    const srcPath = src.trim();
-    if (srcPath !== '') {
-      data.source = srcPath;
-      try {
-        data.content = fs.readFileSync(srcPath, 'utf8');
-      } catch (err) {
-        const { isSucceed } = checkFsError(data, err);
-        if (!isSucceed) {
-          // // TODO: [?] consider check others
-          //console.log(`TEST_ERR-MSG:loadFromFileSync: ${err}`);
-          //throw err;
-        };
-      };
-    };
-  };
-  return data;
-};
-
-/**
- * @function loadFromFile
- * @param {string} src - a path to some file
- * @returns {Promise<fsoDescr, Error>}
- * @async
- * @inner
- * @description Loads file by a given path
- */
-function loadFromFile(src) {
-  /**/// main part that return promise as a result
-  return new Promise((resolve, reject) => {
-    /** @type {fsoDescr} */
-    const data = {
-      isERR: false,
-      errCode: 0,
-      errEvent: '',
-      errMsg: '',
-      source: '',
-      content: '',
-    };
-    if (typeof src !== 'string') {
-      if (src !== undefined) {
-        data.isERR = true;
-        data.errEvent = 'ERR_INVARG';
-        data.errMsg = 'The "source" argument must be a string';
-      };
-      resolve(data);
-    } else {
-      const srcPath = src.trim();
-      if (srcPath === '') resolve(data);
-      data.source = srcPath;
-      fse.readFile(srcPath, 'utf8').then(result => {
-        data.content = result;
-        resolve(data);
-      }).catch(err => {
-        let { isSucceed } = checkFsError(data, err);
-        if (isSucceed) {
-          data.content = '';
-          resolve(data);
-        } else {
-          //console.log('CHECK: loadFromFile() => Error => '+err);
-          //console.log('CHECK: loadFromFile() => Error => '+err.code);
-          reject(err);
-        };
-      });
-    };
-  });
-};
-
-/**
- * @function saveToFileSync
- * @param {string} src - a path to some file
- * @param {string} content - some file content
- * @param {any} [opt] - <reserved>
- * @returns {fsoDescr}
- * @inner
- * @description Saves a content to a file
- */
-function saveToFileSync(src, content = '', opt) {
-  /** @type {fsoDescr} */
-  const data = {
-    isERR: false,
-    errCode: 0,
-    errEvent: '',
-    errMsg: '',
-    source: '',
-    content: '',
-  };
-  if (typeof src !== 'string') {
-    data.isERR = true;
-    data.errEvent = src === undefined ? 'ERR_NOSRC' : 'ERR_INVARG';
-    data.errMsg = 'The "source" argument must be a string';
-  } else if (typeof content === 'string') {
-    const srcPath = src.trim();
-    if (srcPath === '') {
-      data.isERR = true;
-      data.errEvent = 'ERR_NOSRC';
-      data.errMsg = 'No "source" path given';
-    } else {
-      data.source = srcPath;
-      try {
-        fs.writeFileSync(srcPath, content, 'utf8');
-      } catch (err) {
-        const { isSucceed } = checkFsError(data, err);
-        if (!isSucceed) {
-          // // TODO: [?] consider check others
-          //console.log(`TEST_ERR-MSG:saveToFileSync: ${err}`);
-          //throw err;
-        };
-      };
-    };
-  } else {
-    data.isERR = true;
-    data.errEvent = 'ERR_INVARG';
-    data.errMsg = 'The "content" argument must be a string';
-  };
-  return data;
-};
-
-/**
- * @function saveToFile
- * @param {string} src - a path to some file
- * @param {string} content - some file content
- * @param {any} [opt] - <reserved>
- * @returns {Promise<fsoDescr, Error>}
- * @async
- * @inner
- * @description Saves a content to a file
- */
-function saveToFile(src, content = '', opt) {
-  /**/// main part that return promise as a result
-  return new Promise((resolve, reject) => {
-    /** @type {fsoDescr} */
-    const data = {
-      isERR: false,
-      errCode: 0,
-      errEvent: '',
-      errMsg: '',
-      source: '',
-      content: '',
-    };
-    if (typeof src !== 'string') {
-      data.isERR = true;
-      data.errEvent = src === undefined ? 'ERR_NOSRC' : 'ERR_INVARG';
-      data.errMsg = 'The "source" argument must be a string';
-      resolve(data);
-    }  else if (typeof content === 'string') {
-      const srcPath = src.trim();
-      if (srcPath === '') {
-        data.isERR = true;
-        data.errEvent = 'ERR_NOSRC';
-        data.errMsg = 'No "source" path given';
-        resolve(data);
-      } else {
-        data.source = srcPath;
-        fse.writeFile(srcPath, content, 'utf8').then(result => {
-          resolve(data);
-        }).catch(err => {
-          const { isSucceed } = checkFsError(data, err);
-          if (isSucceed) resolve(data);
-          // // TODO: [?] consider check others
-          //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err);
-          //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err.code);
-          reject(err);
-        });
-      };
-    } else {
-      data.isERR = true;
-      data.errEvent = 'ERR_INVARG';
-      data.errMsg = 'The "content" argument must be a string';
-      resolve(data);
-    };
-  });
-};
-
-/**
- * @typedef {Object} RVAL_loadjsonff
- * @property {fsoDescr} descr - ops description
- * @property {any} obj - loaded content
- * @description A result of `loadJSONFromFileSync`
- */
-
-/**
- * @function loadJSONFromFile
- * @param {string} src - a path to some file
- * @param {any} [opt] - <reserved>
- * @returns {Promise<RVAL_loadjsonff, Error>}
- * @async
- * @inner
- * @description Loads a JSON-object from a file
- */
-function loadJSONFromFile(src, opt) {
-  /**/// main part that return promise as a result
-  return new Promise((resolve, reject) => {
-    loadFromFile(src).then(data => {
-      let obj = null;
-      if (!data.isERR) {
-        if (data.content !== '') {
-          try {
-            obj = JSON.parse(data.content);
-            // if succeed clear <data.content>
-            data.content = '';
-          } catch (err) {
-            data.isERR = true;
-            //console.log(`TEST_ERR-CODE: [${err.code}](${err.errno})`);
-            //console.log(`TEST_ERR-MSG: ${err}`);
-            if (err instanceof SyntaxError) {
-              data.errEvent = 'ERR_JSON_BADDATA';
-              data.errMsg = err.message;
-            } else {
-              data.errEvent = 'ERR_JSON_UNKNOWN';
-            };
-          };
-        };
-      };
-      resolve({ descr: data, obj });
-    }).catch(err => {
-      //console.log('CHECK: TXEpgContentProvider.loadFromFile() => Error => '+err);
-      //console.log('CHECK: TXEpgContentProvider.loadFromFile() => Error => '+err.code);
-      reject(err);
-    });
-  });
-};
-
-/**
- * @function loadJSONFromFileSync
- * @param {string} src - a path to some file
- * @param {any} [opt] - <reserved>
- * @returns {RVAL_loadjsonff}
- * @inner
- * @description Loads a JSON-object from a file
- */
-function loadJSONFromFileSync(src, opt) {
-  const data = loadFromFileSync(src);
-  let obj = null;
-  if (!data.isERR) {
-    if (data.content !== '') {
-      try {
-        obj = JSON.parse(data.content);
-        // if succeed clear <data.content>
-        data.content = '';
-      } catch (err) {
-        data.isERR = true;
-        //console.log(`TEST_ERR-CODE: [${err.code}](${err.errno})`);
-        //console.log(`TEST_ERR-MSG: ${err}`);
-        if (err instanceof SyntaxError) {
-          data.errEvent = 'ERR_JSON_BADDATA';
-          data.errMsg = err.message;
-        } else {
-          data.errEvent = 'ERR_JSON_UNKNOWN';
-        };
-      };
-    };
-  };
-  return { descr: data, obj };
-};
-
-/**
- * @function saveJSONToFile
- * @param {string} src - a path to some file
- * @param {object} obj - some content
- * @param {any} [opt] - <reserved>
- * @returns {Promise<fsoDescr, Error>}
- * @throws {Error}
- * @async
- * @inner
- * @description Saves a JSON-object to a file
- */
-function saveJSONToFile(src, obj, opt) {
-  /**/// main part that return promise as a result
-  return new Promise((resolve, reject) => {
-    /** @type {fsoDescr} */
-    let data = {
-      isERR: false,
-      errCode: 0,
-      errEvent: '',
-      errMsg: '',
-      source: '',
-      content: '',
-    };
-    (new Promise((resolve, reject) => {
-      data.content = JSON.stringify(obj, null, 2);
-      resolve(true);
-    })).then(result => {
-      saveToFile(src, data.content, null).then(data => {
-        resolve(data);
-      }).catch(err => {
-        // // TODO: [?] consider check others
-        //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err);
-        //console.log('CHECK: TXEpgContentProvider.saveToFile() => Error => '+err.code);
-        reject(err);
-      });
-    }).catch(err => {
-      data.isERR = true;
-      //console.log(`TEST_ERR-CODE: [${err.code}](${err.errno})`);
-      //console.log(`TEST_ERR-MSG: ${err}`);
-      data.errEvent = 'ERR_JSON_UNKNOWN';
-      resolve(data);
-    });
-  });
-};
-
-/**
- * @function saveJSONToFileSync
- * @param {string} src - a path to some file
- * @param {object} obj - some content
- * @param {any} [opt] - <reserved>
- * @returns {fsoDescr}
- * @inner
- * @description Saves a JSON-object to a file
- */
-function saveJSONToFileSync(src, obj, opt) {
-  /** @type {fsoDescr} */
-  let data = {
-    isERR: false,
-    errCode: 0,
-    errEvent: '',
-    errMsg: '',
-    source: '',
-    content: '',
-  };
-  try {
-    data.content = JSON.stringify(obj, null, 2);
-  } catch (err) {
-    data.isERR = true;
-    //console.log(`TEST_ERR-CODE: [${err.code}](${err.errno})`);
-    //console.log(`TEST_ERR-MSG: ${err}`);
-    data.errEvent = 'ERR_JSON_UNKNOWN';
-  };
-  if (!data.isERR) {
-    data = saveToFileSync(src, data.content, opt);
-  };
-  return data;
-};
-
-/***
- * (* class definitions *)
- */
-
-// === module exports block ===
-
-module.exports.checkFsError = checkFsError;
-module.exports.loadFromFile = loadFromFile;
-module.exports.loadFromFileSync = loadFromFileSync;
-module.exports.saveToFile = saveToFile;
-module.exports.saveToFileSync = saveToFileSync;
-module.exports.loadJSONFromFile = loadJSONFromFile;
-module.exports.loadJSONFromFileSync = loadJSONFromFileSync;
-module.exports.saveJSONToFile = saveJSONToFile;
-module.exports.saveJSONToFileSync = saveJSONToFileSync;