@ygracs/chn-alias-list 0.0.7 → 0.0.9

package/lib/chn-alias-list.js

@@ -1,165 +1,41 @@
-// [v0.1.050-20260130]
+// [v0.1.058-20260628]
 
 // === module init block ===
 
 const {
   isArray, isPlainObject,
-  valueToArray, valueToIndex, valueToIDString,
+  valueToIndex, valueToIDString,
   readAsString,
 } = require('@ygracs/bsfoc-lib-js');
 
-// === module inner block ===
-
-/***
- * (* helper function definitions *)
- */
+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 ===
 
-/***
- * (* constant definitions *)
- */
-
 /**
  * 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 {ILangTextPair[]} name - list of a channel names
  * @property {string} status - channel status
  */
-
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
 /**
- * @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: '',
 };
 
 /**
@@ -180,218 +56,6 @@ class 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;
-  }
-
-  /**
-   * @deprecated
-   * @see TChnNamesList.getItem
-   * @todo [from v0.0.5] make obsolete
-   */
-  getName(value) {
-    return this.getItem(value);
-  }
-
-  /**
-   * 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;
-  }
-
-  /**
-   * @deprecated
-   * @see TChnNamesList.addItem
-   * @todo [from v0.0.5] make obsolete
-   */
-  addName(data) {
-    return this.addItem(data);
-  }
-
-  /**
-   * 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;
-  }
-
-  /**
-   * @deprecated
-   * @see TChnNamesList.delItem
-   * @todo [from v0.0.5] make obsolete
-   */
-  delName(value) {
-    return this.delItem(value);
-  }
-
-  /**
-   * 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;
-  }
-
-  /**
-   * @deprecated
-   * @see TChnNamesList.loadItems
-   * @todo [from v0.0.5] make obsolete
-   */
-  loadNames(...args) {
-    return this.loadItems(...args);
-  }
-
-  /**
-   * 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) : [];
-  }
-
-};
-
 /**
  * @classdesc This class implements an interface of the channel item
  */
@@ -519,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.
@@ -624,7 +294,7 @@ class TChnAliasItem {
         let { alias, name, status } = obj;
         if (obj instanceof TChnAliasItem) name = obj.names.value;
         item.setAlias(alias);
-        item.loadNames(name);
+        item.names.loadItems(name);
         if (typeof isDisabled === 'boolean') {
           // // TODO: process "status"
           if (isDisabled) item.disable();
@@ -638,6 +308,7 @@ class TChnAliasItem {
   }
 
 };
+module.exports.TChnAliasItem = TChnAliasItem;
 
 /**
  * @classdesc This class implements an interface of the channel items list
@@ -699,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
@@ -726,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];
   }
 
   /**
@@ -765,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();
@@ -813,10 +519,4 @@ class TChnAliasList {
   }
 
 };
-
-// === module exports block ===
-
-module.exports.TChnNameRecord = TChnNameRecord;
-module.exports.TChnNamesList = TChnNamesList;
-module.exports.TChnAliasItem = TChnAliasItem;
 module.exports.TChnAliasList = TChnAliasList;

package/lib/chn-names.d.ts

@@ -0,0 +1,146 @@
+/**
+ * An array of two elements that represents a `<lang>`-`<text>` pair
+ */
+export type ILangTextPair = string[];
+export const ILangTextPair: ILangTextPair;
+/**
+ * A settings for the list load ops
+ */
+export type ILoadListItemsOptions = {
+    /**
+     * - indicates whether to clear the list
+     * before load
+     */
+    useClear?: boolean;
+};
+export const ILoadListItemsOptions: ILoadListItemsOptions;
+/**
+ * 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(): ILangTextPair;
+    set value(data: ILangTextPair);
+    /**
+     * 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 entries
+     */
+    get value(): ILangTextPair[];
+    /**
+     * 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
+     * @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 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 | ILoadListItemsOptions): 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;
+}