@ygracs/chn-alias-list 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+#### *v0.0.7*
+
+Pre-release version.
+
+> - update `chn-alias-list.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+> - update dependency on `@cntwg/file-helper` module to v0.0.3;
+> - improve behavior of `saveAliasToFileSync` on handling `content` param;
+> - deprecate methods: `addName` and `loadNames` of a `TChnAliasItem`-class;
+> - other fixes.
+
 #### *v0.0.6*
 
 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/doc/chn-alias-list.md

@@ -1,7 +1,7 @@
 
->|***rev.*:**|0.0.5|
+>|***rev.*:**|0.0.8|
 >|:---|---:|
->|date:|2025-04-14|
+>|date:|2026-01-30|
 
 ## Introduction
 
@@ -9,6 +9,10 @@ This paper describes a classes and some helper functions provided by `chn-alias-
 
 ## Content
 
+- Base types
+    - <a href="#typedef+IChannelRecord">IChannelRecord</a>
+    - <a href="#typedef+fsoDescr">fsoDescr</a>
+
 - Classes
     - <a href="#TChnNameRecord">TChnNameRecord</a>
     - <a href="#TChnNamesList">TChnNamesList</a>
@@ -19,6 +23,36 @@ This paper describes a classes and some helper functions provided by `chn-alias-
     - <a href="#loadAliasFromFileSync">loadAliasFromFileSync</a>
     - <a href="#saveAliasToFileSync">saveAliasToFileSync</a>
 
+### Base type definitions
+
+This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function or a class method descriptions.
+
+<a name="typedef+IChannelRecord"></a>
+#### `IChannelRecord` - descriptor
+
+This descriptor is an `object` that contains an info of a channel data.
+
+| property name | value type | optional | description |
+|:---|---|---:|:---|
+| `id` | `string` | no | a channel ID |
+| `alias` | `string` | no | a target ID for a channel |
+| `name` | `any[]` | no | a list of a channel names |
+| `status` | `string` | no | a channel status |
+
+<a name="typedef+fsoDescr"></a>
+#### `fsoDescr` - descriptor
+
+This descriptor is an `object` that describes a status for an operation with some FS-object (*e.g. object such as a file*).
+
+| property name | value type | optional | description |
+|:---|---|---:|:---|
+| `isERR` | `boolean` | no | a flag which indicates whether an error was happen |
+| `errCode` | `number` | yes | an error code |
+| `errEvent` | `string` | no | an error event identifier |
+| `errMsg` | `string` | yes | an error message |
+| `source` | `string` | yes | path to a file |
+| `content` | `any` | yes | content |
+
 ## Module classes
 
 <a name="TChnNameRecord"></a>
@@ -52,7 +86,7 @@ The class constructor creates a new instance of the class. It receives no argume
 
 | value type | read only | description |
 |---|---|:---|
-| `array` | no | defines a value of a name record |
+| `string[]` | no | defines a value of a name record |
 
 #### class methods
 
@@ -103,7 +137,7 @@ The class constructor creates a new instance of the class. It receives no argume
 
 | value type | read only | description |
 |---|---|:---|
-| `array` | yes | contains a list of a name records |
+| `TChnNameRecord[]` | yes | contains a list of a name records |
 
 #### class methods
 
@@ -288,16 +322,12 @@ Sets a channel alias.
 <a name="TChnAliasItem+addName"></a>
 ##### **addName(data)** => `boolean`
 
-Adds a new name record.
-
-> **See**: [TChnNamesList.addName](#TChnNamesList+addName)
+> \[!] NOTE: `[since v0.0.7]` deprecated. Use [`TChnNamesList.addItem`](#TChnNamesList+addItem) instead.
 
 <a name="TChnAliasItem+loadNames"></a>
 ##### **loadNames(list, \[opt])** => `number`
 
-Loads a list of a new name records.
-
-> **See**: [TChnNamesList.loadNames](#TChnNamesList+loadNames)
+> \[!] NOTE: `[since v0.0.7]` deprecated. Use [`TChnNamesList.loadItems`](#TChnNamesList+loadItems) instead.
 
 <a name="TChnAliasItem+enable"></a>
 ##### **enable()** => `void`
@@ -333,7 +363,7 @@ Sets item status.
 #### class methods (*special*)
 
 <a name="TChnAliasItem+toJSON"></a>
-##### **toJSON()**
+##### **toJSON()** => `IChannelRecord`
 
 A special method that provides an interface to an instance representation
 for a `JSON.stringify()`.
 
@@ -346,7 +376,7 @@ Creates a new alias element.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `obj` | `object` | --- | an initial data |
+| `obj` | `IChannelRecord` | --- | an initial data |
 
 <a name="TChnAliasList"></a>
 ### **TChnAliasList**
@@ -423,7 +453,7 @@ Adds an alias element.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `obj` | `object` | --- | an element to be added |
+| `obj` | `IChannelRecord` | --- | an element to be added |
 
 <a name="TChnAliasList+delItem"></a>
 ##### **delItem(value)** => `boolean`
@@ -441,7 +471,7 @@ Loads a list of a new alias elements.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `list` | `array` | --- | a list of an elements |
+| `list` | `IChannelRecord[]` | --- | a list of an elements |
 | `opt` | `boolean` | `true` | a flag that defines whether to clear the list before load a new one |
 
 <a name="TChnAliasList+clear"></a>
@@ -474,7 +504,7 @@ Returns an array of a channel items picked up by a given function.
 <a name="loadAliasFromFileSync"></a>
 #### **loadAliasFromFileSync(src, [opt])** => `object`
 
-Loads an alias from a file.
+Loads an alias data from a file.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
@@ -482,12 +512,12 @@ Loads an alias from a file.
 | `opt` | `any` | --- | <*reserved*> |
 
 <a name="saveAliasToFileSync"></a>
-#### **saveAliasToFileSync(src, content, [opt])** => `object`
+#### **saveAliasToFileSync(src, content, [opt])** => `fsoDescr`
 
-Saves an alias to a file
+Saves an alias data to a file.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `src` | `string` | --- | a path to some file |
-| `content` | `array` | --- | a content to save |
+| `content` | `object` or `object[]` | --- | a content to save |
 | `opt` | `any` | --- | <*reserved*> |

package/index.d.ts

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

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,318 @@
+/**
+ * Defines an object for storing a channel data
+ */
+export type IChannelRecord = {
+    /**
+     * - channel ID
+     */
+    id: string;
+    /**
+     * - target ID
+     */
+    alias: string;
+    /**
+     * - list of a channel names
+     */
+    name: any[];
+    /**
+     * - channel status
+     */
+    status: string;
+};
+/**
+ * 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: IChannelRecord): 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
+     * @todo [from v0.0.6] make obsolete
+     */
+    getName(value: number): TChnNameRecord | null;
+    /**
+     * Adds a new name record
+     * @deprecated
+     * @see TChnNamesList.addItem
+     * @todo [from v0.0.7] deprecated. Use `TChnNamesList.addItem` instead.
+     */
+    addName(data: any): boolean;
+    /**
+     * Loads a list of a new name records
+     * @deprecated
+     * @see TChnNamesList.loadItems
+     * @todo [from v0.0.7] deprecated. Use `TChnNamesList.loadItems` instead.
+     */
+    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(): IChannelRecord;
+    #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: IChannelRecord): 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: IChannelRecord[], 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.045-20250820]
+// [v0.1.050-20260130]
 
 // === module init block ===
 
@@ -8,10 +8,6 @@ const {
   readAsString,
 } = require('@ygracs/bsfoc-lib-js');
 
-const {
-  loadJSONFromFileSync, saveJSONToFileSync,
-} = require('@cntwg/file-helper');
-
 // === module inner block ===
 
 /***
@@ -45,67 +41,18 @@ function convertLangTextValueToString(data, opt) {
  * (* constant definitions *)
  */
 
-/***
- * (* function definitions *)
- */
-
-/**
- * An 'FS'-ops descriptor.
- * @typedef {Object} fsoDescr
- * @property {boolean} isERR - flag
- * @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
- */
-
-/**
- * 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
+ * Defines an object for storing a channel data
+ * @typedef {Object} IChannelRecord
+ * @property {string} id - channel ID
+ * @property {string} alias - target ID
+ * @property {any[]} name - list of a channel names
+ * @property {string} status - channel status
  */
-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 definitions *)
  */
-function saveAliasToFileSync(src, content, opt) {
-  const obj = isArray(content) ? content : null;
-  let result = null;
-  //===
-  result = saveJSONToFileSync(src, obj, opt);
-  return result;
-};
 
 /***
  * (* class definitions *)
@@ -338,6 +285,7 @@ class TChnNamesList {
 
   /**
    * Returns a name record
+   * @since 0.0.5
    * @param {number} value - an element index
    * @returns {?TChnNameRecord}
    */
@@ -356,6 +304,7 @@ 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}
    */
@@ -378,6 +327,7 @@ 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}
    */
@@ -398,6 +348,7 @@ 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}
@@ -548,6 +499,7 @@ class TChnAliasItem {
    * @returns {?TChnNameRecord}
    * @deprecated
    * @see TChnNamesList.getItem
+   * @todo [from v0.0.6] make obsolete
    */
   getName(value) {
     return this.#_names.getItem(value);
@@ -557,7 +509,9 @@ class TChnAliasItem {
    * Adds a new name record
    * @param {any} data - a name record
    * @returns {boolean}
+   * @deprecated
    * @see TChnNamesList.addItem
+   * @todo [from v0.0.7] deprecated. Use `TChnNamesList.addItem` instead.
    */
   addName(data) {
     return this.#_names.addItem(data);
@@ -568,7 +522,9 @@ class TChnAliasItem {
    * @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}
+   * @deprecated
    * @see TChnNamesList.loadItems
+   * @todo [from v0.0.7] deprecated. Use `TChnNamesList.loadItems` instead.
    */
   loadNames(...args) {
     return this.#_names.loadItems(...args);
@@ -640,7 +596,7 @@ class TChnAliasItem {
 
   /**
    * Provides an interface to an instance representation for JSON.stringify()
-   * @returns {Object}
+   * @returns {IChannelRecord}
    * @protected
    */
   toJSON() {
@@ -655,7 +611,7 @@ class TChnAliasItem {
 
   /**
    * Creates a new alias element
-   * @param {object} obj - an init data
+   * @param {IChannelRecord} obj - an init data
    * @returns {?TChnAliasItem}
    * @static
    */
@@ -784,7 +740,7 @@ class TChnAliasList {
 
   /**
    * Adds an alias element
-   * @param {object} obj - an element to be added
+   * @param {IChannelRecord} obj - an element to be added
    * @returns {number}
    */
   addItem(obj) {
@@ -792,7 +748,7 @@ class TChnAliasList {
     let index = -1;
     if (item !== null) {
       const id = valueToIDString(item.id);
-      index = this.searchIndexByID(id);
+      if (id != null) index = this.searchIndexByID(id);
       if (index === -1) {
         index = this.count;
         this.#_items.push(item);
@@ -816,7 +772,7 @@ class TChnAliasList {
 
   /**
    * Loads a list of a new alias elements
-   * @param {array} list - a list of an elements
+   * @param {IChannelRecord[]} list - a list of an elements
    * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
    * @returns {number}
    */
@@ -860,9 +816,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: object | object[], 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,102 @@
+// [v0.1.049-20260130]
+
+// === module init block ===
+
+const {
+  isArray, isObject,
+} = 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 {(object|object[])} content - content
+ * @param {any} [opt] - <reserved>
+ * @returns {fsoDescr}
+ * @see {@link saveJSONToFileSync} for details of an `opt` param
+ */
+function saveAliasToFileSync(src, content, opt) {
+  /** @type {fsoDescr} */
+  let data = {
+    isERR: false,
+    errCode: 0,
+    errEvent: '',
+    errMsg: '',
+    source: '',
+    content: '',
+  };
+  if (isArray(content) || isObject(content)) {
+    //const obj = isArray(content) ? content : null;
+    //===
+    data = saveJSONToFileSync(src, content, opt);
+  } else {
+    if (content !== undefined) {
+      // // TODO: define `errCode` and `errMsg`
+      data.isERR = true;
+      data.errEvent = 'ERR_BAD_CONTENT';
+    };
+  };
+  return data;
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+module.exports.loadAliasFromFileSync = loadAliasFromFileSync;
+module.exports.saveAliasToFileSync = saveAliasToFileSync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "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",
+    "doc/*.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.3.0"
+    "@cntwg/file-helper": "^0.0.3",
+    "@ygracs/bsfoc-lib-js": "~0.3.3"
   },
   "devDependencies": {
-    "jest": "^30.0.5",
-    "jsdoc-to-markdown": "^9.1.2",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "~0.0.2-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }