@ygracs/chn-alias-list 0.0.8 → 0.0.9

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;
+}

package/lib/chn-names.js

@@ -0,0 +1,392 @@
+// [v0.1.059-20260628]
+
+// === module init block ===
+
+const {
+  isArray, isPlainObject,
+  valueToArray, valueToIndex, valueToIDString,
+  readAsString,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+/**
+ * An array of two elements that represents a `<lang>`-`<text>` pair
+ * @typedef {string[]} ILangTextPair
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {ILangTextPair}
+ */
+module.exports.ILangTextPair = [];
+
+/**
+ * Converts a <Lang, Text> key-pair to a string
+ * @function convertLangTextValueToString
+ * @param {ILangTextPair} 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 main block ===
+
+/**
+ * @classdesc This class implements an interface of the name record
+ */
+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 {ILangTextPair}
+   */
+  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.TChnNameRecord = TChnNameRecord;
+
+/**
+ * A settings for the list load ops
+ * @typedef {Object} ILoadListItemsOptions
+ * @property {boolean} [useClear=true] - indicates whether to clear the list
+ *     before load
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {ILoadListItemsOptions}
+ */
+module.exports.ILoadListItemsOptions = {};
+
+/**
+ * A user defined procedure to process an array elements
+ * @callback forEachProcEx
+ * @param {any} item - some element
+ * @param {number} [index] - element index
+ * @param {any[]} [arr]
+ * @returns {void}
+ */
+
+ /**
+  * 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}
+  */
+
+/**
+ * @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 entries
+   * @type {ILangTextPair[]}
+   * @readonly
+   */
+  get value() {
+    /** @type {ILangTextPair[]} */
+    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}
+   * @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
+   * @param {any} value - value to evaluate
+   * @returns {number}
+   * @since 0.0.9
+   */
+  tryIndex(value) {
+    const index = valueToIndex(value);
+    return index !== -1 && index < this.count ? index : -1;
+  }
+
+  /**
+   * 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) {
+    const i = this.tryIndex(value);
+    return i === -1 ? null: this.#_items[i];
+  }
+
+  /**
+   * 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) {
+    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 new name records
+   * @since 0.0.5
+   * @param {any} list - an element or a list of an elements
+   * @param {loadListItemsOption|ILoadListItemsOptions} [opt] - load options
+   * @returns {number}
+   */
+  loadItems(list, opt) {
+    let {
+      useClear = true,
+    } = isPlainObject(opt) ? opt : { useClear: opt };
+    if (typeof useClear !== 'boolean') useClear = 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/chn-alias-list",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "A small library which provides some helper classes for EPG-tools",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -12,6 +12,7 @@
   "types": "./index.d.ts",
   "files": [
     "doc/*.md",
+    "lib/chn-names.js",
     "lib/chn-alias-list.js",
     "lib/file-helper-ext.js",
     "lib/*.d.ts",
@@ -30,12 +31,12 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/file-helper": "^0.0.3",
-    "@ygracs/bsfoc-lib-js": "~0.3.4"
+    "@cntwg/file-helper": "~0.0.4",
+    "@ygracs/bsfoc-lib-js": "~0.4.0"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
+    "jest": "^30.4.2",
     "jsdoc-to-markdown": "^9.1.3",
     "minimist": "^1.2.8",
     "typescript": "~5.9.3"