@ygracs/chn-alias-list 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+#### *v0.0.9*
+
+Pre-release version.
+
+> - update `chn-alias-list.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.4.0;
+> - update dependency on `@cntwg/file-helper` module to v0.0.4;
+> - (TChnAliasList) add method: `checkIndex`, `tryIndex`;
+> - (TChnAliasList) deprecate method: `chkIndex`;
+> - (TChnAliasList) change method behavior: `loadItems`;
+> - (TChnNamesList) add method: `checkIndex`, `tryIndex`;
+> - (TChnNamesList) deprecate method: `chkIndex`;
+> - (TChnNamesList) change method behavior: `loadItems`;
+> - some fixes.
+
+#### *v0.0.8*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.4;
+> - (TChnNamesList) remove deprecated method: `getName`, `addName`, `delName`, `loadNames`;
+> - some fixes.
+
 #### *v0.0.7*
 
 Pre-release version.

package/doc/chn-alias-list.md

@@ -1,7 +1,7 @@
 
->|***rev.*:**|0.0.8|
+>|***rev.*:**|0.0.10|
 >|:---|---:|
->|date:|2026-01-30|
+>|date:|2026-06-28|
 
 ## Introduction
 
@@ -11,6 +11,7 @@ This paper describes a classes and some helper functions provided by `chn-alias-
 
 - Base types
     - <a href="#typedef+IChannelRecord">IChannelRecord</a>
+    - <a href="#typedef+ILangTextPair">ILangTextPair</a>
     - <a href="#typedef+fsoDescr">fsoDescr</a>
 
 - Classes
@@ -27,6 +28,16 @@ This paper describes a classes and some helper functions provided by `chn-alias-
 
 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+ILangTextPair"></a>
+#### `ILangTextPair` => `[ lang, text ]`
+
+This type describes a record element, an array of two elements that represents a `<lang>`-`<text>` pair. The structure of an array is listed in the table below:
+
+| element name | value type | description |
+|:---|---|:---|
+| `lang` | `string` | a language name |
+| `text` | `any` | a text value |
+
 <a name="typedef+IChannelRecord"></a>
 #### `IChannelRecord` - descriptor
 
@@ -36,7 +47,7 @@ This descriptor is an `object` that contains an info of a channel data.
 |:---|---|---:|:---|
 | `id` | `string` | no | a channel ID |
 | `alias` | `string` | no | a target ID for a channel |
-| `name` | `any[]` | no | a list of a channel names |
+| `name` | `ILangTextPair[]` | no | a list of a channel names |
 | `status` | `string` | no | a channel status |
 
 <a name="typedef+fsoDescr"></a>
@@ -53,45 +64,45 @@ This descriptor is an `object` that describes a status for an operation with som
 | `source` | `string` | yes | path to a file |
 | `content` | `any` | yes | content |
 
-## Module classes
+### Module classes
 
 <a name="TChnNameRecord"></a>
-### **TChnNameRecord**
+#### **TChnNameRecord**
 
 This class implements an interface of the name record
 
 <a name="new_TChnNameRecord_new"></a>
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class. It receives no arguments.
 
-#### class properties
+##### class properties
 
 <a name="TChnNameRecord+lang"></a>
-##### **lang**
+###### **lang**
 
 | value type | read only | description |
 |---|---|:---|
 | `string` | yes | defines a language applied to a name record value |
 
 <a name="TChnNameRecord+text"></a>
-##### **text**
+###### **text**
 
 | value type | read only | description |
 |---|---|:---|
 | `string` | yes | defines a text value of a name record |
 
 <a name="TChnNameRecord+value"></a>
-##### **value**
+###### **value**
 
 | value type | read only | description |
 |---|---|:---|
-| `string[]` | no | defines a value of a name record |
+| `ILangTextPair` | no | defines a value of a name record |
 
-#### class methods
+##### class methods
 
 <a name="TChnNameRecord+setValue"></a>
-##### **setValue(data)** => `boolean`
+###### **setValue(data)** => `boolean`
 
 This method sets the value of a name record.
 
@@ -100,7 +111,7 @@ This method sets the value of a name record.
 | `data` | `any` | --- | a data for a name record to be set |
 
 <a name="TChnNameRecord+toFormatString"></a>
-##### **toFormatString(opt)** => `string`
+###### **toFormatString(opt)** => `string`
 
 Returns a name record value as a formatted string.
 
@@ -109,50 +120,57 @@ Returns a name record value as a formatted string.
 | `opt` | `any` | --- | <*reserved*> |
 
 <a name="TChnNameRecord+reset"></a>
-##### **reset()** => `void`
+###### **reset()** => `void`
 
 Clears the record.
 
 <a name="TChnNamesList"></a>
-### **TChnNamesList**
+#### **TChnNamesList**
 
 This class implements an interface of the name records list.
 
 <a name="new_TChnNamesList_new"></a>
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class. It receives no arguments.
 
-#### class properties
+##### class properties
 
 <a name="TChnNamesList+count"></a>
-##### **count**
+###### **count**
 
 | value type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of a name records |
 
 <a name="TChnNamesList+value"></a>
-##### **value**
+###### **value**
 
 | value type | read only | description |
 |---|---|:---|
-| `TChnNameRecord[]` | yes | contains a list of a name records |
+| `ILangTextPair[]` | yes | contains a list of a name entries |
 
-#### class methods
+##### class methods
 
 <a name="TChnNamesList+isEmpty"></a>
-##### **isEmpty()** => `boolean`
+###### **isEmpty()** => `boolean`
 
 Returns a flag that indicating whether a list is empty or not.
 
 <a name="TChnNamesList+isNotEmpty"></a>
-##### **isNotEmpty()** => `boolean`
+###### **isNotEmpty()** => `boolean`
 
 Returns a flag that indicating whether a list has any members.
 
 <a name="TChnNamesList+chkIndex"></a>
-##### **chkIndex(value)** => `boolean`
+###### **chkIndex(value)** => `boolean`
+
+> WARNING: \[since `v0.0.9`] this method deprecated (*use [`checkIndex`](#TChnNamesList+checkIndex) method instead*).
+
+<a name="TChnNamesList+checkIndex"></a>
+###### **checkIndex(value)** => `boolean`
+
+> since: \[`v0.0.9`]
 
 Checks whether a given value is an index and fits
 an Index range within the instance.
 
@@ -160,8 +178,19 @@ Checks whether a given value is an index and fits
 an Index range within the ins
 |:---|---|---:|:---|
 | `value` | `any` | --- | a value to be verified |
 
+<a name="TChnNamesList+tryIndex"></a>
+###### **tryIndex(value)** => `number`
+
+> since: \[`v0.0.9`]
+
+This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+
 <a name="TChnNamesList+getIndex"></a>
-##### **getIndex(value)** => `number`
+###### **getIndex(value)** => `number`
 
 Searches an index of a given name in the list.
 
@@ -169,13 +198,8 @@ Searches an index of a given name in the list.
 |:---|---|---:|:---|
 | `value` | `string` | --- | a name to be searched |
 
-<a name="TChnNamesList+getName"></a>
-##### **getName(value)** => `?TChnNameRecord`
-
-> \[!] NOTE: `[since v0.0.5]` deprecated. Use `getItem` instead.
-
 <a name="TChnNamesList+getItem"></a>
-##### **getItem(value)** => `?TChnNameRecord`
+###### **getItem(value)** => `?TChnNameRecord`
 
 > since: \[v0.0.5]
 
@@ -185,13 +209,8 @@ Returns a name record addressed by a given index.
 |:---|---|---:|:---|
 | `value` | `number` | --- | an element index in the list |
 
-<a name="TChnNamesList+addName"></a>
-#### **addName(data)** => `boolean`
-
-> \[!] NOTE: `[since v0.0.5]` deprecated. Use `addItem` instead.
-
 <a name="TChnNamesList+addItem"></a>
-#### **addItem(data)** => `boolean`
+###### **addItem(data)** => `boolean`
 
 > since: \[v0.0.5]
 
@@ -201,13 +220,8 @@ Adds a new name record to a list members.
 |:---|---|---:|:---|
 | `data` | `any` | --- | a data for a name record to be added in the list |
 
-<a name="TChnNamesList+delName"></a>
-##### **delName(value)** => `boolean`
-
-> \[!] NOTE: `[since v0.0.5]` deprecated. Use `delItem` instead.
-
 <a name="TChnNamesList+delItem"></a>
-##### **delItem(value)** => `boolean`
+###### **delItem(value)** => `boolean`
 
 > since: \[v0.0.5]
 
@@ -217,13 +231,8 @@ Tries to delete a name record addressed by a given index.
 |:---|---|---:|:---|
 | `value` | `number` | --- | an element index in the list |
 
-<a name="TChnNamesList+loadNames"></a>
-##### **loadNames(list, \[opt])** => `number`
-
-> \[!] NOTE: `[since v0.0.5]` deprecated. Use `loadItems` instead.
-
 <a name="TChnNamesList+loadItems"></a>
-##### **loadItems(list, \[opt])** => `number`
+###### **loadItems(list, \[options])** => `number`
 
 > since: \[v0.0.5]
 
@@ -232,15 +241,27 @@ Loads a list of a new name records.
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `list` | `array` | --- | a list of an elements to load |
-| `opt` | `boolean` | `true` | defines whether to clear the list before load a new one |
+| `options` | `boolean` or `object` | `true` | load options |
+
+###### ***`options` parameter***
+
+The `options` parameter is a `boolean` on an `object`.
+
+If `options` parameter is a `boolean` it treats as a `useClear` option.
+
+\[**since: `v0.0.9`**] If `options` parameter is an `object` it may contains the following set of parameters:
+
+| option name | value type | default value | description |
+|:---|---|---:|:---|
+| `useClear` | `boolean` | `true` | if set to `true`, before the load, the list is cleared |
 
 <a name="TChnNamesList+clear"></a>
-##### **clear()** => `void`
+###### **clear()** => `void`
 
 Removes all of the instance members.
 
 <a name="TChnNamesList+forEach"></a>
-##### **forEach(cb)** => `void`
+###### **forEach(cb)** => `void`
 
 Calls a given function upon each name record in the list.
 
@@ -249,7 +270,7 @@ Calls a given function upon each name record in the list.
 | `cb` | `callback` | --- | a callback function defined by a user |
 
 <a name="TChnNamesList+filter"></a>
-##### **filter(cb)** => `TChnNameRecord[]`
+###### **filter(cb)** => `TChnNameRecord[]`
 
 > since: \[v0.0.5]
 
@@ -260,49 +281,49 @@ Returns an array of a name records picked up by a given function.
 | `cb` | `callback` | --- | a callback function defined by a user |
 
 <a name="TChnAliasItem"></a>
-### **TChnAliasItem**
+#### **TChnAliasItem**
 
 This class implements an interface of the channel item.
 
 <a name="new_TChnAliasItem_new"></a>
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class. It receives no arguments.
 
-#### class properties
+##### class properties
 
 <a name="TChnAliasItem+id"></a>
-##### **id**
+###### **id**
 
 | value type | read only | description |
 |---|---|:---|
 | `string` | no | defines a channel ID |
 
 <a name="TChnAliasItem+alias"></a>
-##### **alias**
+###### **alias**
 
 | value type | read only | description |
 |---|---|:---|
 | `string` | no | defines a channel alias |
 
 <a name="TChnAliasItem+names"></a>
-##### **names**
+###### **names**
 
 | value type | read only | description |
 |---|---|:---|
 | `TChnNamesList` | yes | contains a list of a name records |
 
 <a name="TChnAliasItem+status"></a>
-##### **status**
+###### **status**
 
 | value type | read only | description |
 |---|---|:---|
 | `string` | yes | defines an instance status |
 
-#### class methods
+##### class methods
 
 <a name="TChnAliasItem+setID"></a>
-##### **setID(value)** => `boolean`
+###### **setID(value)** => `boolean`
 
 Sets a channel ID.
 
@@ -311,7 +332,7 @@ Sets a channel ID.
 | `value` | `string` | --- | a channel ID |
 
 <a name="TChnAliasItem+setAlias"></a>
-##### **setAlias(value)** => `boolean`
+###### **setAlias(value)** => `boolean`
 
 Sets a channel alias.
 
@@ -320,39 +341,39 @@ Sets a channel alias.
 | `value` | `string` | --- | a channel alias |
 
 <a name="TChnAliasItem+addName"></a>
-##### **addName(data)** => `boolean`
+###### **addName(data)** => `boolean`
 
 > \[!] NOTE: `[since v0.0.7]` deprecated. Use [`TChnNamesList.addItem`](#TChnNamesList+addItem) instead.
 
 <a name="TChnAliasItem+loadNames"></a>
-##### **loadNames(list, \[opt])** => `number`
+###### **loadNames(list, \[opt])** => `number`
 
 > \[!] NOTE: `[since v0.0.7]` deprecated. Use [`TChnNamesList.loadItems`](#TChnNamesList+loadItems) instead.
 
 <a name="TChnAliasItem+enable"></a>
-##### **enable()** => `void`
+###### **enable()** => `void`
 
 Sets item status to "enabled".
 
 <a name="TChnAliasItem+disable"></a>
-##### **disable()** => `void`
+###### **disable()** => `void`
 
 Sets item status to "disabled".
 
 <a name="TChnAliasItem+up"></a>
-##### **up()** => `void`
+###### **up()** => `void`
 
 Sets item status to "active"/"running".
 
 <a name="TChnAliasItem+down"></a>
-##### **down()** => `void`
+###### **down()** => `void`
 
 Sets item status to "inactive"/"stopped".
 
-#### class methods
+##### class methods
 
 <a name="TChnAliasItem+setStatus"></a>
-##### **setStatus(value)** => `boolean`
+###### **setStatus(value)** => `boolean`
 
 Sets item status.
 
@@ -360,17 +381,17 @@ Sets item status.
 |:---|---|---:|:---|
 | `value` | `string` | --- | a name of predefined status value (a possible value may be: `enabled`, `disabled`, `up` or `down`) |
 
-#### class methods (*special*)
+##### class methods (*special*)
 
 <a name="TChnAliasItem+toJSON"></a>
-##### **toJSON()** => `IChannelRecord`
+###### **toJSON()** => `IChannelRecord`
 
 A special method that provides an interface to an instance representation
 for a `JSON.stringify()`.
 
-#### class methods (*static*)
+##### class methods (*static*)
 
 <a name="TChnAliasItem.create"></a>
-##### **create(obj)** => `?TChnAliasItem`
+###### **create(obj)** => `?TChnAliasItem`
 
 Creates a new alias element.
 
@@ -379,48 +400,65 @@ Creates a new alias element.
 | `obj` | `IChannelRecord` | --- | an initial data |
 
 <a name="TChnAliasList"></a>
-### **TChnAliasList**
+#### **TChnAliasList**
 
 This class implements an interface of the channel items list.
 
 <a name="new_TChnAliasList_new"></a>
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class. It receives no arguments.
 
-#### class properties
+##### class properties
 
 <a name="TChnAliasList+count"></a>
-##### **count**
+###### **count**
 
 | value type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of the elements |
 
-#### class methods
+##### class methods
 
 <a name="TChnAliasList+isEmpty"></a>
-##### **isEmpty()** => `boolean`
+###### **isEmpty()** => `boolean`
 
 Returns a flag that indicating whether a list is empty or not.
 
 <a name="TChnAliasList+isNotEmpty"></a>
-##### **isNotEmpty()** => `boolean`
+###### **isNotEmpty()** => `boolean`
 
 Returns a flag that indicating whether a list has any members.
 
 <a name="TChnAliasList+chkIndex"></a>
-##### **chkIndex(value)** => `boolean`
+###### **chkIndex(value)** => `boolean`
+
+> WARNING: \[since `v0.0.9`] this method deprecated (*use [`checkIndex`](#TChnAliasList+checkIndex) method instead*).
 
-Checks whether a given value is an index and fits
- an Index range within the instance.
+<a name="TChnAliasList+checkIndex"></a>
+###### **checkIndex(value)** => `boolean`
+
+> since: \[`v0.0.9`]
+
+Checks whether a given value is an index and fits an Index range within the instance.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+
+<a name="TChnAliasList+tryIndex"></a>
+###### **tryIndex(value)** => `number`
+
+> since: \[`v0.0.9`]
+
+This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `value` | `any` | --- | a value to be verified |
 
 <a name="TChnAliasList+searchIndexByID"></a>
-##### **searchIndexByID(value)** => `number`
+###### **searchIndexByID(value)** => `number`
 
 Searches an index of an element by its given ID.
 
@@ -429,7 +467,7 @@ Searches an index of an element by its given ID.
 | `value` | `string` | --- | a value of ID to be searched |
 
 <a name="TChnAliasList+getItem"></a>
-##### **getItem(value)** => `?TChnAliasItem`
+###### **getItem(value)** => `?TChnAliasItem`
 
 Returns an alias element by its index.
 
@@ -438,7 +476,7 @@ Returns an alias element by its index.
 | `value` | `number` | --- | an element index |
 
 <a name="TChnAliasList+getItemByID"></a>
-##### **getItemByID(value)** => `?TChnAliasItem`
+###### **getItemByID(value)** => `?TChnAliasItem`
 
 Returns an alias element by its ID.
 
@@ -447,7 +485,7 @@ Returns an alias element by its ID.
 | `value` | `string` | --- | an element ID |
 
 <a name="TChnAliasList+addItem"></a>
-##### **addItem(obj)** => `number`
+###### **addItem(obj)** => `number`
 
 Adds an alias element.
 
@@ -456,7 +494,7 @@ Adds an alias element.
 | `obj` | `IChannelRecord` | --- | an element to be added |
 
 <a name="TChnAliasList+delItem"></a>
-##### **delItem(value)** => `boolean`
+###### **delItem(value)** => `boolean`
 
 Tries to delete an element addressed by a given index.
 
@@ -465,22 +503,34 @@ Tries to delete an element addressed by a given index.
 | `value` | `number` | --- | an element index |
 
 <a name="TChnAliasList+loadItems"></a>
-##### **loadItems(list, \[opt])** => `number`
+###### **loadItems(list, \[options])** => `number`
 
 Loads a list of a new alias elements.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `list` | `IChannelRecord[]` | --- | a list of an elements |
-| `opt` | `boolean` | `true` | a flag that defines whether to clear the list before load a new one |
+| `options` | `boolean` or `object` | `true` | load options |
+
+###### ***`options` parameter***
+
+The `options` parameter is a `boolean` on an `object`.
+
+If `options` parameter is a `boolean` it treats as a `useClear` option.
+
+\[**since: `v0.0.9`**] If `options` parameter is an `object` it may contains the following set of parameters:
+
+| option name | value type | default value | description |
+|:---|---|---:|:---|
+| `useClear` | `boolean` | `true` | if set to `true`, before the load, the list is cleared |
 
 <a name="TChnAliasList+clear"></a>
-##### **clear()** => `void`
+###### **clear()** => `void`
 
 Removes all of the instance members.
 
 <a name="TChnAliasList+forEach"></a>
-##### **forEach(cb)** => `void`
+###### **forEach(cb)** => `void`
 
 Calls given function for each alias element in the list.
 
@@ -489,7 +539,7 @@ Calls given function for each alias element in the list.
 | `cb` | `callback` | --- | a callback function defined by a user |
 
 <a name="TChnAliasList+filter"></a>
-##### **filter(cb)** => `TChnAliasItem[]`
+###### **filter(cb)** => `TChnAliasItem[]`
 
 > since: \[v0.0.5]
 
@@ -499,10 +549,10 @@ Returns an array of a channel items picked up by a given function.
 |:---|---|---:|:---|
 | `cb` | `callback` | --- | a callback function defined by a user |
 
-## Module functions
+### Module functions
 
 <a name="loadAliasFromFileSync"></a>
-#### **loadAliasFromFileSync(src, [opt])** => `object`
+##### **loadAliasFromFileSync(src, [opt])** => `object`
 
 Loads an alias data from a file.
 
@@ -512,7 +562,7 @@ Loads an alias data from a file.
 | `opt` | `any` | --- | <*reserved*> |
 
 <a name="saveAliasToFileSync"></a>
-#### **saveAliasToFileSync(src, content, [opt])** => `fsoDescr`
+##### **saveAliasToFileSync(src, content, [opt])** => `fsoDescr`
 
 Saves an alias data to a file.
 

package/index.d.ts

@@ -1,10 +1,10 @@
-import type { fsoDescr } from '@cntwg/file-helper';
-
-import {
-  TChnNameRecord, TChnNamesList,
-  TChnAliasItem, TChnAliasList,
-  type IChannelRecord,
-} from './lib/chn-alias-list';
+import { TChnNameRecord } from "./lib/chn-names";
+import { TChnNamesList } from "./lib/chn-names";
+import { TChnAliasItem } from "./lib/chn-alias-list";
+import { TChnAliasList } from "./lib/chn-alias-list";
+import type { fsoDescr } from "@cntwg/file-helper";
+import type { ILangTextPair } from "./lib/chn-names";
+import type { IChannelRecord } from "./lib/chn-alias-list";
 
 import {
   loadAliasFromFileSync, saveAliasToFileSync,
@@ -19,6 +19,7 @@ export {
 
 export type {
   fsoDescr,
+  ILangTextPair,
   IChannelRecord,
   RVAL_loadaliasff,
 };