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

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+#### *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.

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.045-20250820]
+// [v0.1.047-20260120]
 
 // === module init block ===
 
@@ -8,10 +8,6 @@ const {
   readAsString,
 } = require('@ygracs/bsfoc-lib-js');
 
-const {
-  loadJSONFromFileSync, saveJSONToFileSync,
-} = require('@cntwg/file-helper');
-
 // === module inner block ===
 
 /***
@@ -49,64 +45,6 @@ function convertLangTextValueToString(data, opt) {
  * (* 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
- */
-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 *)
  */
@@ -338,6 +276,7 @@ class TChnNamesList {
 
   /**
    * Returns a name record
+   * @since 0.0.5
    * @param {number} value - an element index
    * @returns {?TChnNameRecord}
    */
@@ -356,6 +295,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 +318,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 +339,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}
@@ -860,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.6",
+  "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.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.1-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }