@ygracs/chn-alias-list 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+#### *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.4*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.2.
+
 #### *v0.0.1-0.0.3*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024-2024 Yuri Grachev
+Copyright (c) 2024-2025 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

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.044-20250414]
 
 // === module init block ===
 
@@ -10,7 +10,7 @@ const {
 
 const {
   loadJSONFromFileSync, saveJSONToFileSync,
-} = require('#lib/file-helper.js');
+} = require('@cntwg/file-helper');
 
 // === module extra block (helper functions) ===
 
@@ -215,6 +215,15 @@ class TChnNameRecord {
  * @description 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
  */
@@ -229,6 +238,22 @@ class TChnNamesList {
     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
    * @readonly
@@ -291,21 +316,39 @@ class TChnNamesList {
     return index;
   }
 
+  /**
+   * @deprecated
+   * @see TChnNamesList.getItem
+   * @todo [from v0.0.5] make obsolete
+   */
+  getName(value) {
+    return this.getItem(value);
+  }
+
   /**
    * @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);
+  }
+
   /**
    * @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 !== '';
@@ -313,30 +356,49 @@ class TChnNamesList {
     return isSucceed;
   }
 
+  /**
+   * @deprecated
+   * @see TChnNamesList.delItem
+   * @todo [from v0.0.5] make obsolete
+   */
+  delName(value) {
+    return this.delItem(value);
+  }
+
   /**
    * @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);
+  }
+
   /**
    * @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;
   };
@@ -358,6 +420,16 @@ class TChnNamesList {
     if (typeof cb === 'function') this.#_items.forEach(cb);
   }
 
+  /**
+   * @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) : [];
+  }
+
 };
 
 /**
@@ -454,20 +526,20 @@ class TChnAliasItem {
    * @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);
   }
 
   /**
    * @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);
   }
 
   /**
@@ -475,10 +547,10 @@ class TChnAliasItem {
    * @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);
   }
 
   /**
@@ -605,6 +677,22 @@ class TChnAliasList {
     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 the elements
    * @readonly
@@ -613,15 +701,6 @@ class TChnAliasList {
     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
@@ -657,7 +736,7 @@ class TChnAliasList {
   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;
@@ -746,6 +825,16 @@ class TChnAliasList {
     if (typeof cb === 'function') this.#_items.forEach(cb);
   }
 
+  /**
+   * @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) : [];
+  }
+
 };
 
 // === module exports block ===

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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.1"
+    "@cntwg/file-helper": "^0.0.1",
+    "@ygracs/bsfoc-lib-js": "^0.2.3"
   },
   "devDependencies": {
     "jest": "^29.7.0",
-    "jsdoc-to-markdown": "^9.0.4",
+    "jsdoc-to-markdown": "^9.1.1",
     "minimist": "^1.2.8"
   }
 }

package/lib/file-helper.js

@@ -1,245 +0,0 @@
-// [v0.1.026-20241021]
-
-// === module init block ===
-
-const fs = require('fs');
-
-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 };
-};
-
-/**
- * @function loadFileSync
- * @param {string} src - a path to some file
- * @returns {fsoDescr}
- * @inner
- * @description Loads file by a given path
- */
-function loadFileSync(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:loadFileSync: ${err}`);
-          //throw err;
-        };
-      };
-    };
-  };
-  return data;
-};
-
-/**
- * @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;
-};
-
-// === module main block ===
-
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
-/**
- * @typedef {Object} RVAL_loadjsonff
- * @property {fsoDescr} descr - ops description
- * @property {any} obj - loaded content
- * @description A result of `loadJSONFromFileSync`
- */
-
-/**
- * @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 = loadFileSync(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 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.loadFileSync = loadFileSync;
-module.exports.saveToFileSync = saveToFileSync;
-module.exports.loadJSONFromFileSync = loadJSONFromFileSync;
-module.exports.saveJSONToFileSync = saveJSONToFileSync;