@ygracs/chn-alias-list 0.0.5 → 0.0.7-b

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+#### *v0.0.x*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+> - update dependency on `@cntwg/file-helper` module to v0.0.3;
+
+#### *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 +26,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/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024-2025 Yuri Grachev
+Copyright (c) 2024-2026 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/index.d.ts

@@ -0,0 +1,17 @@
+import {
+  TChnNameRecord, TChnNamesList,
+  TChnAliasItem, TChnAliasList,
+} from './lib/chn-alias-list';
+
+import {
+  loadAliasFromFileSync, saveAliasToFileSync,
+} from './lib/file-helper-ext';
+
+export {
+  TChnNameRecord, TChnNamesList,
+  TChnAliasItem, TChnAliasList,
+  loadAliasFromFileSync, saveAliasToFileSync,
+};
+
+import type { fsoDescr } from '@cntwg/file-helper';
+export type { fsoDescr };

package/index.js

@@ -1,13 +1,30 @@
-// [v0.0.001-20240620]
+// [v0.1.003-20260120]
 
 // === module init block ===
 
-const lib = require('#lib/chn-alias-list.js');
+const lib = require('./lib/chn-alias-list');
 
-// === module extra block (helper functions) ===
+const fileHelper = require('./lib/file-helper-ext');
+
+const {
+  // * import types definitions *
+  fsoDescr,
+} = require('@cntwg/file-helper');
+
+// === module inner block ===
 
 // === module main block ===
 
 // === module exports block ===
 
-module.exports = lib;
+module.exports.TChnNameRecord = lib.TChnNameRecord;
+module.exports.TChnNamesList = lib.TChnNamesList;
+module.exports.TChnAliasItem = lib.TChnAliasItem;
+module.exports.TChnAliasList = lib.TChnAliasList;
+
+module.exports.loadAliasFromFileSync = fileHelper.loadAliasFromFileSync;
+module.exports.saveAliasToFileSync = fileHelper.saveAliasToFileSync;
+
+// * export types definitions *
+// @ts-ignore
+module.exports.fsoDescr = fsoDescr;

package/lib/chn-alias-list.d.ts

@@ -0,0 +1,292 @@
+/**
+ * A user defined procedure to process an array elements
+ */
+export type forEachProcEx = (item: any, index?: number, arr?: any[]) => void;
+/**
+ * A user defined procedure to process an array elements
+ */
+export type cbArrECheck = (item: any, index?: number, arr?: any[]) => any;
+
+/**
+ * @classdesc This class implements an interface of the name record
+ */
+export class TChnNameRecord {
+    /**
+     * Contains a language
+     */
+    get lang(): string;
+    /**
+     * Contains a value of the record
+     */
+    get text(): string;
+    /**
+     * Contains a value of the record
+     */
+    get value(): string[];
+    set value(data: string[]);
+    /**
+     * Sets the record value
+     */
+    setValue(data: any): boolean;
+    /**
+     * Returns value as a formated string
+     */
+    toFormatString(opt: any): string;
+    /**
+     * Clears the record
+     */
+    reset(): void;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of the name records list
+ */
+export class TChnNamesList {
+    /**
+     * Contains a quantity of a name records
+     */
+    get count(): number;
+    /**
+     * Contains a list of a name records
+     */
+    get value(): TChnNameRecord[];
+    /**
+     * Returns a flag whether a list is empty or not
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns a flag whether a list has any members
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks whether a given value is an index and fits an index range
+     * within the instance
+     */
+    chkIndex(value: any): boolean;
+    /**
+     * Searches an index of a given name
+     */
+    getIndex(value: string): number;
+    /**
+     * @deprecated
+     * @see TChnNamesList.getItem
+     * @todo [from v0.0.5] make obsolete
+     */
+    getName(value: any): TChnNameRecord;
+    /**
+     * Returns a name record
+     * @since 0.0.5
+     */
+    getItem(value: number): TChnNameRecord | null;
+    /**
+     * @deprecated
+     * @see TChnNamesList.addItem
+     * @todo [from v0.0.5] make obsolete
+     */
+    addName(data: any): boolean;
+    /**
+     * Adds a new name record to a list members
+     * @since 0.0.5
+     */
+    addItem(data: any): boolean;
+    /**
+     * @deprecated
+     * @see TChnNamesList.delItem
+     * @todo [from v0.0.5] make obsolete
+     */
+    delName(value: any): boolean;
+    /**
+     * Tries to delete a name record addressed by a given index
+     * @since 0.0.5
+     */
+    delItem(value: number): boolean;
+    /**
+     * @deprecated
+     * @see TChnNamesList.loadItems
+     * @todo [from v0.0.5] make obsolete
+     */
+    loadNames(...args: any[]): number;
+    /**
+     * Loads a new name records
+     * @since 0.0.5
+     */
+    loadItems(list: any, opt?: boolean): number;
+    /**
+     * Removes all of the instance members
+     */
+    clear(): void;
+    /**
+     * Calls given function for each name record
+     */
+    forEach(cb: forEachProcEx): void;
+    /**
+     * Returns an array of a  name records picked up by a given function
+     */
+    filter(cb: cbArrECheck): TChnNameRecord[];
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: TChnNameRecord | null;
+        } | {
+            done: boolean;
+            value?: undefined;
+        };
+        return(): {
+            done: boolean;
+        };
+    };
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of the channel item
+ */
+export class TChnAliasItem {
+    /**
+     * Creates a new alias element
+     */
+    static create(obj: object): TChnAliasItem | null;
+    /**
+     * Contains a channel ID
+     */
+    get id(): string;
+    set id(value: string);
+    /**
+     * Contains a channel alias
+     */
+    get alias(): string;
+    set alias(value: string);
+    /**
+     * Contains a list of a name records
+     */
+    get names(): TChnNamesList;
+    /**
+     * Contains an instance status
+     */
+    get status(): string;
+    /**
+     * Sets a channel ID
+     * @see valueToIDString
+     */
+    setID(value: string): boolean;
+    /**
+     * Sets a channel alias
+     * @see valueToIDString
+     */
+    setAlias(value: string): boolean;
+    /**
+     * Returns a name record
+     * @deprecated
+     * @see TChnNamesList.getItem
+     */
+    getName(value: number): TChnNameRecord | null;
+    /**
+     * Adds a new name record
+     * @see TChnNamesList.addItem
+     */
+    addName(data: any): boolean;
+    /**
+     * Loads a list of a new name records
+     * @see TChnNamesList.loadItems
+     */
+    loadNames(...args: [list: any, opt?: boolean]): number;
+    /**
+     * Sets item status to enabled
+     */
+    enable(): void;
+    /**
+     * Sets item status to disabled
+     */
+    disable(): void;
+    /**
+     * Sets item status to active/running
+     */
+    up(): void;
+    /**
+     * Sets item status to inactive/stopped
+     */
+    down(): void;
+    /**
+     * Sets item status
+     */
+    setStatus(value: string): boolean;
+    /**
+     * Provides an interface to an instance representation for JSON.stringify()
+     */
+    protected toJSON(): any;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an interface of the channel items list
+ */
+export class TChnAliasList {
+    /**
+     * Contains a quantity of the elements
+     */
+    get count(): number;
+    /**
+     * Returns a flag whether a list is empty or not
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns a flag whether a list has any members
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks whether a given value is an index and fits an index range
+     * within the instance
+     */
+    chkIndex(value: any): boolean;
+    /**
+     * Searches an index of an element by its ID
+     * @see valueToIDString
+     */
+    searchIndexByID(value: string): number;
+    /**
+     * Returns an alias element by its index
+     */
+    getItem(value: number): TChnAliasItem | null;
+    /**
+     * Returns an alias element by its ID
+     */
+    getItemByID(value: string): TChnAliasItem | null;
+    /**
+     * Adds an alias element
+     */
+    addItem(obj: object): number;
+    /**
+     * Tries to delete an element addressed by a given index
+     */
+    delItem(value: number): boolean;
+    /**
+     * Loads a list of a new alias elements
+     */
+    loadItems(list: any[], opt?: boolean): number;
+    /**
+     * Removes all of the instance members
+     */
+    clear(): void;
+    /**
+     * Calls given function for each alias element
+     */
+    forEach(cb: forEachProcEx): void;
+    /**
+     * Returns an array of a  name records picked up by a given function
+     */
+    filter(cb: cbArrECheck): TChnAliasItem[];
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: TChnAliasItem | null;
+        } | {
+            done: boolean;
+            value?: undefined;
+        };
+        return(): {
+            done: boolean;
+        };
+    };
+    #private;
+}

package/lib/chn-alias-list.js

@@ -1,4 +1,4 @@
-// [v0.1.044-20250414]
+// [v0.1.047-20260120]
 
 // === module init block ===
 
@@ -8,19 +8,19 @@ const {
   readAsString,
 } = require('@ygracs/bsfoc-lib-js');
 
-const {
-  loadJSONFromFileSync, saveJSONToFileSync,
-} = require('@cntwg/file-helper');
+// === module inner block ===
 
-// === module extra block (helper functions) ===
+/***
+ * (* 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 = [ '', '' ];
@@ -45,62 +45,6 @@ function convertLangTextValueToString(data, opt) {
  * (* 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 *)
  */
@@ -109,20 +53,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 +75,8 @@ class TChnNameRecord {
   }
 
   /**
-   * @property {string} - defines a value of the record
+   * Contains a value of the record
+   * @type {string}
    * @readonly
    */
   get text() {
@@ -138,7 +84,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 +96,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 +134,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 +154,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 +202,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 +211,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 +224,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 +251,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 +275,10 @@ class TChnNamesList {
   }
 
   /**
+   * Returns a name record
+   * @since 0.0.5
    * @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 +294,10 @@ class TChnNamesList {
   }
 
   /**
+   * Adds a new name record to a list members
+   * @since 0.0.5
    * @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 +317,10 @@ class TChnNamesList {
   }
 
   /**
+   * Tries to delete a name record addressed by a given index
+   * @since 0.0.5
    * @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 +328,6 @@ class TChnNamesList {
     return isSucceed;
   }
 
-  //
   /**
    * @deprecated
    * @see TChnNamesList.loadItems
@@ -387,10 +338,11 @@ class TChnNamesList {
   }
 
   /**
+   * Loads a new name records
+   * @since 0.0.5
    * @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 +356,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 +387,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 +415,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel ID
+   * Contains a channel ID
+   * @type {string}
    */
   get id() {
     return this.#_id;
@@ -469,7 +427,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines a channel alias
+   * Contains a channel alias
+   * @type {string}
    */
   get alias() {
     return this.#_alias;
@@ -480,7 +439,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 +448,8 @@ class TChnAliasItem {
   }
 
   /**
-   * @property {string} - defines an instance status
+   * Contains an instance status
+   * @type {string}
    * @readonly
    */
   get status() {
@@ -498,9 +459,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 +472,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 +485,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 +496,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 +506,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 +517,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 +581,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 +596,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 +629,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 +656,8 @@ class TChnAliasList {
   }
 
   /**
-   * @property {number} - contains a quantity of the elements
+   * Contains a quantity of the elements
+   * @type {number}
    * @readonly
    */
   get count() {
@@ -702,26 +665,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 +692,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 +707,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 +746,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 +757,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 +773,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) : [];
@@ -839,9 +802,6 @@ class TChnAliasList {
 
 // === module exports block ===
 
-module.exports.loadAliasFromFileSync = loadAliasFromFileSync;
-module.exports.saveAliasToFileSync = saveAliasToFileSync;
-
 module.exports.TChnNameRecord = TChnNameRecord;
 module.exports.TChnNamesList = TChnNamesList;
 module.exports.TChnAliasItem = TChnAliasItem;

package/lib/file-helper-ext.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A result of `loadAliasFromFile...`
+ */
+export type RVAL_loadaliasff = {
+    /**
+     * - ops description
+     */
+    descr: fsoDescr;
+    /**
+     * - loaded content
+     */
+    result: null | TChnAliasItem | TChnAliasList;
+};
+
+/**
+ * Loads an alias from a file
+ * @see {@link loadJSONFromFileSync} for details of an `opt` param
+ */
+export function loadAliasFromFileSync(src: string, opt?: any): RVAL_loadaliasff;
+/**
+ * Saves an alias to a file
+ * @see {@link saveJSONToFileSync} for details of an `opt` param
+ */
+export function saveAliasToFileSync(src: string, content: any[], opt?: any): fsoDescr;
+
+import type { fsoDescr } from '@cntwg/file-helper';
+import { TChnAliasItem } from "./chn-alias-list";
+import { TChnAliasList } from "./chn-alias-list";

package/lib/file-helper-ext.js

@@ -0,0 +1,86 @@
+// [v0.1.047-20260120]
+
+// === module init block ===
+
+const {
+  isArray,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  loadJSONFromFileSync, saveJSONToFileSync,
+  // * import types definitions *
+  /** @see fsoDescr from `@cntwg/file-helper` */
+  fsoDescr,
+} = require('@cntwg/file-helper');
+
+const {
+  TChnAliasItem, TChnAliasList,
+} = require('./chn-alias-list');
+
+// === module inner block ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * A result of `loadAliasFromFile...`
+ * @typedef {Object} RVAL_loadaliasff
+ * @property {fsoDescr} descr - ops description
+ * @property {(null|TChnAliasItem|TChnAliasList)} result - loaded content
+ */
+
+/**
+ * Loads an alias from a file
+ * @function loadAliasFromFileSync
+ * @param {string} src - a path to some file
+ * @param {any} [opt] - <reserved>
+ * @returns {RVAL_loadaliasff}
+ * @see {@link loadJSONFromFileSync} for details of an `opt` param
+ */
+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 };
+};
+
+/**
+ * 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}
+ * @see {@link saveJSONToFileSync} for details of an `opt` param
+ */
+function saveAliasToFileSync(src, content, opt) {
+  const obj = isArray(content) ? content : null;
+  let result = null;
+  //===
+  result = saveJSONToFileSync(src, obj, opt);
+  return result;
+};
+
+/***
+ * (* 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.5",
+  "version": "0.0.7-b",
   "description": "A small library which provides some helper classes for EPG-tools",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -9,28 +9,35 @@
     "url": "git+https://gitlab.com/ygracs/chn-alias-list.git"
   },
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/chn-alias-list.md",
     "lib/chn-alias-list.js",
+    "lib/file-helper-ext.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/file-helper": "^0.0.1",
-    "@ygracs/bsfoc-lib-js": "^0.2.3"
+    "@cntwg/file-helper": "^0.0.3",
+    "@ygracs/bsfoc-lib-js": "~0.3.3"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "jsdoc-to-markdown": "^9.1.1",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "~0.0.1-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }