@ygracs/chn-alias-list 0.0.8 → 0.0.9

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

@@ -13,12 +13,13 @@ export type IChannelRecord = {
     /**
      * - list of a channel names
      */
-    name: any[];
+    name: ILangTextPair[];
     /**
      * - channel status
      */
     status: string;
 };
+export const IChannelRecord: IChannelRecord;
 /**
  * A user defined procedure to process an array elements
  */
@@ -27,115 +28,9 @@ 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;
+import { ILangTextPair } from "./chn-names";
 
-/**
- * @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;
-    /**
-     * Returns a name record
-     * @since 0.0.5
-     */
-    getItem(value: number): TChnNameRecord | null;
-    /**
-     * Adds a new name record to a list members
-     * @since 0.0.5
-     */
-    addItem(data: any): boolean;
-    /**
-     * Tries to delete a name record addressed by a given index
-     * @since 0.0.5
-     */
-    delItem(value: number): boolean;
-    /**
-     * 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;
-}
-
+type loadItemsParams = Parameters<TChnNamesList["loadItems"]>;
 /**
  * @classdesc This class implements an interface of the channel item
  */
@@ -192,7 +87,7 @@ export class TChnAliasItem {
      * @see TChnNamesList.loadItems
      * @todo [from v0.0.7] deprecated. Use `TChnNamesList.loadItems` instead.
      */
-    loadNames(...args: [list: any, opt?: boolean]): number;
+    loadNames(...args: loadItemsParams): number;
     /**
      * Sets item status to enabled
      */
@@ -239,8 +134,22 @@ export class TChnAliasList {
     /**
      * Checks whether a given value is an index and fits an index range
      * within the instance
+     * @deprecated
+     * @todo \[since v0.0.9] deprecated. Use {@link checkIndex} instead.
      */
     chkIndex(value: any): boolean;
+    /**
+     * Checks whether a given value is an index and fits an index range
+     * within the instance
+     * @since 0.0.9
+     */
+    checkIndex(value: any): boolean;
+    /**
+     * Returns an index in case a given value is a valid index value and not exceeds
+     * an index range within the instance. If failed a `-1` returned
+     * @since 0.0.9
+     */
+    tryIndex(value: any): number;
     /**
      * Searches an index of an element by its ID
      * @see valueToIDString
@@ -265,7 +174,7 @@ export class TChnAliasList {
     /**
      * Loads a list of a new alias elements
      */
-    loadItems(list: IChannelRecord[], opt?: boolean): number;
+    loadItems(list: IChannelRecord[], opt?: boolean | ILoadListItemsOptions): number;
     /**
      * Removes all of the instance members
      */
@@ -292,3 +201,6 @@ export class TChnAliasList {
     };
     #private;
 }
+import { TChnNamesList } from "./chn-names";
+import { TChnNameRecord } from "./chn-names";
+import { ILoadListItemsOptions } from "./chn-names";

package/lib/chn-alias-list.js

@@ -1,35 +1,21 @@
-// [v0.1.053-20260308]
+// [v0.1.058-20260628]
 
 // === module init block ===
 
 const {
   isArray, isPlainObject,
-  valueToArray, valueToIndex, valueToIDString,
+  valueToIndex, valueToIDString,
   readAsString,
 } = require('@ygracs/bsfoc-lib-js');
 
-// === module inner block ===
+const {
+  TChnNameRecord, TChnNamesList,
+  // * import types definitions *
+  ILangTextPair,
+  ILoadListItemsOptions,
+} = require('./chn-names');
 
-/**
- * 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
- */
-function convertLangTextValueToString(data, opt) {
-  let name = [ '', '' ];
-  let result = '';
-  if (isArray(data)) name = data;
-  let [ lang, text ] = name;
-  if (lang === '') {
-    result = text;
-  } else if (text !== '') {
-    result = `(${lang}): ${text}`;
-  };
-  return result;
-};
+// === module inner block ===
 
 // === module main block ===
 
@@ -38,114 +24,19 @@ function convertLangTextValueToString(data, opt) {
  * @typedef {Object} IChannelRecord
  * @property {string} id - channel ID
  * @property {string} alias - target ID
- * @property {any[]} name - list of a channel names
+ * @property {ILangTextPair[]} name - list of a channel names
  * @property {string} status - channel status
  */
-
 /**
- * @classdesc This class implements an interface of the name record
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IChannelRecord}
  */
-class TChnNameRecord {
-  /** @type {string} */
-  #_lang;
-  /** @type {string} */
-  #_value;
-
-  /**
-   * Creates an instance of the name record
-   */
-  constructor() {
-    this.reset();
-  }
-
-  /**
-   * Contains a language
-   * @type {string}
-   * @readonly
-   */
-  get lang() {
-    return this.#_lang;
-  }
-
-  /**
-   * Contains a value of the record
-   * @type {string}
-   * @readonly
-   */
-  get text() {
-    return this.#_value;
-  }
-
-  /**
-   * Contains a value of the record
-   * @type {string[]}
-   */
-  get value() {
-    return [ this.#_lang, this.#_value ];
-  }
-
-  set value(data) {
-    this.setValue(data);
-  }
-
-  /**
-   * Sets the record value
-   * @param {any} data - a value of the record
-   * @returns {boolean}
-   */
-  setValue(data) {
-    let _data = data;
-    let isSucceed = false;
-    if (_data !== undefined) {
-      if (isPlainObject(_data)) {
-        let { lang, text } = _data;
-        _data = [ lang, text ];
-      } else {
-        _data = valueToArray(_data);
-      };
-      switch (_data.length) {
-        case 0: {
-          break;
-        }
-        case 1: {
-          _data = [ '', _data[0] ];
-        }
-        default: {
-          let [ lang, value = null ] = _data;
-          if (value !== null && typeof value !== 'boolean') {
-            value = readAsString(value, { numberToString: true });
-            lang = value !== '' ? valueToIDString(lang) : null;
-            if (lang === null) lang = '';
-            this.#_lang = lang;
-            this.#_value = value;
-            isSucceed = true;
-          };
-        }
-      };
-    };
-    return isSucceed;
-  }
-
-  /**
-   * Returns value as a formated string
-   * @param {any} opt - <reserved>
-   * @returns {string}
-   */
-  toFormatString(opt) {
-    return convertLangTextValueToString(this.value, opt);
-  }
-
-  /**
-   * Clears the record
-   * @returns {void}
-   */
-  reset() {
-    this.#_lang = '';
-    this.#_value = '';
-  }
-
+module.exports.IChannelRecord = {
+  id: '',
+  alias: '',
+  name: [],
+  status: '',
 };
-module.exports.TChnNameRecord = TChnNameRecord;
 
 /**
  * A user defined procedure to process an array elements
@@ -165,183 +56,6 @@ module.exports.TChnNameRecord = TChnNameRecord;
   * @returns {any}
   */
 
-/**
- * @classdesc This class implements an interface of the name records list
- */
-class TChnNamesList {
-  /** @type {TChnNameRecord[]} */
-  #_items;
-
-  /**
-   * Creates an instance of the name records list
-   */
-  constructor() {
-    this.#_items = [];
-  }
-
-  [Symbol.iterator]() {
-    let index = 0;
-    return {
-      next: () => {
-        if (index < this.count) {
-          return { done: false, value: this.getItem(index++) };
-        } else {
-          return { done: true };
-        };
-      },
-      return() {
-        return { done: true };
-      },
-    };
-  }
-
-  /**
-   * Contains a quantity of a name records
-   * @type {number}
-   * @readonly
-   */
-  get count() {
-    return this.#_items.length;
-  }
-
-  /**
-   * Contains a list of a name records
-   * @type {TChnNameRecord[]}
-   * @readonly
-   */
-  get value() {
-    const result = [];
-    this.#_items.forEach((item, i) => {
-      result.push(item.value);
-    });
-    return result;
-  }
-
-  /**
-   * Returns a flag whether a list is empty or not
-   * @returns {boolean}
-   */
-  isEmpty() {
-    return this.count === 0;
-  }
-
-  /**
-   * Returns a flag whether a list has any members
-   * @returns {boolean}
-   */
-  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}
-   */
-  chkIndex(value) {
-    const index = valueToIndex(value);
-    return index !== -1 && index < this.count;
-  }
-
-  /**
-   * Searches an index of a given name
-   * @param {string} value - a name
-   * @returns {number}
-   */
-  getIndex(value) {
-    const opt = { numberToString: true };
-    const name = readAsString(value, opt);
-    let index = -1;
-    if (name !== '') {
-      index = this.#_items.findIndex((item) => name === item.text);
-    };
-    return index;
-  }
-
-  /**
-   * Returns a name record
-   * @since 0.0.5
-   * @param {number} value - an element index
-   * @returns {?TChnNameRecord}
-   */
-  getItem(value) {
-    return this.chkIndex(value) ? this.#_items[Number(value)] : null;
-  }
-
-  /**
-   * Adds a new name record to a list members
-   * @since 0.0.5
-   * @param {any} data - a value of a name record
-   * @returns {boolean}
-   */
-  addItem(data) {
-    const _data = data instanceof TChnNameRecord ? data.value : data;
-    const item = new TChnNameRecord();
-    const isSucceed = item.setValue(_data) && item.text !== '';
-    if (isSucceed) this.#_items.push(item);
-    return isSucceed;
-  }
-
-  /**
-   * Tries to delete a name record addressed by a given index
-   * @since 0.0.5
-   * @param {number} value - an element index
-   * @returns {boolean}
-   */
-  delItem(value) {
-    let isSucceed = this.chkIndex(value)
-    if (isSucceed) this.#_items.splice(Number(value), 1);
-    return isSucceed;
-  }
-
-  /**
-   * 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}
-   */
-  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.addItem(item)) count++; });
-    };
-    return count;
-  };
-
-  /**
-   * Removes all of the instance members
-   * @returns {void}
-   */
-  clear() {
-    this.#_items.length = 0;
-  }
-
-  /**
-   * Calls given function for each name record
-   * @param {forEachProcEx} cb - a callback function
-   * @returns {void}
-   */
-  forEach(cb) {
-    if (typeof cb === 'function') this.#_items.forEach(cb);
-  }
-
-  /**
-   * Returns an array of a  name records picked up by a given function
-   * @param {cbArrECheck} cb - a callback function
-   * @returns {TChnNameRecord[]}
-   */
-  filter(cb) {
-    return typeof cb === 'function' ? this.#_items.filter(cb) : [];
-  }
-
-};
-module.exports.TChnNamesList = TChnNamesList;
-
 /**
  * @classdesc This class implements an interface of the channel item
  */
@@ -469,9 +183,15 @@ class TChnAliasItem {
 
   /**
    * Loads a list of a new name records
-   * @param {array} list - a list of an elements
+   * @callback loadItemsFn
+   * @param {any} list - a list of an elements
    * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
    * @returns {number}
+   * @see TChnNamesList.loadItems
+   */
+  /**
+   * Loads a list of a new name records
+   * @type {loadItemsFn}
    * @deprecated
    * @see TChnNamesList.loadItems
    * @todo [from v0.0.7] deprecated. Use `TChnNamesList.loadItems` instead.
@@ -650,12 +370,38 @@ class TChnAliasList {
    * within the instance
    * @param {any} value - a value to be verified
    * @returns {boolean}
+   * @deprecated
+   * @todo \[since v0.0.9] deprecated. Use {@link checkIndex} instead.
    */
   chkIndex(value) {
     const index = valueToIndex(value);
     return index !== -1 && index < this.count;
   }
 
+  /**
+   * Checks whether a given value is an index and fits an index range
+   * within the instance
+   * @since 0.0.9
+   * @param {any} value - a value to be verified
+   * @returns {boolean}
+   */
+  checkIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count;
+  }
+
+  /**
+   * Returns an index in case a given value is a valid index value and not exceeds
+   * an index range within the instance. If failed a `-1` returned
+   * @since 0.0.9
+   * @param {any} value - value to evaluate
+   * @returns {number}
+   */
+  tryIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count ? index : -1;
+  }
+
   /**
    * Searches an index of an element by its ID
    * @param {string} value - an element ID
@@ -677,7 +423,8 @@ class TChnAliasList {
    * @returns {?TChnAliasItem}
    */
   getItem(value) {
-    return this.chkIndex(value) ? this.#_items[Number(value)] : null;
+    const i = this.tryIndex(value);
+    return i === -1 ? null : this.#_items[i];
   }
 
   /**
@@ -716,19 +463,27 @@ class TChnAliasList {
    * @returns {boolean}
    */
   delItem(value) {
-    let isSucceed = this.chkIndex(value)
-    if (isSucceed) this.#_items.splice(Number(value), 1);
+    const i = this.tryIndex(value);
+    let isSucceed = i !== -1;
+    if (isSucceed) this.#_items.splice(i, 1);
     return isSucceed;
   }
 
+  /**
+   * Defines whether to clear the list before load
+   * @typedef {boolean} loadListItemsOption
+   */
   /**
    * Loads a list of a new alias elements
    * @param {IChannelRecord[]} list - a list of an elements
-   * @param {boolean} [opt=true] - defines whether to clear the list before load a new one
+   * @param {loadListItemsOption|ILoadListItemsOptions} [opt] - load options
    * @returns {number}
    */
   loadItems(list, opt) {
-    const useClear = typeof opt === 'boolean' ? opt : true;
+    let {
+      useClear = true,
+    } = isPlainObject(opt) ? opt : { useClear: opt };
+    if (typeof useClear !== 'boolean') useClear = true;
     let count = 0;
     if (isArray(list)) {
       if (list.length > 0 && useClear) this.clear();