@ygracs/xobj-lib-js 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+#### *v0.3.3*
+
+Release version.
+
+> - update `xObj.md`;
+> - some fixes.
+
 #### *v0.3.2*
 
 Release version.

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.52|
+>|***rev.*:**|0.1.53|
 >|:---|---:|
->|date:|2026-03-03|
+>|date:|2026-06-08|
 
 ## Introduction
 
@@ -13,6 +13,7 @@ This paper describes a functions provided by `xObj.js` module.
 - Base types
     - <a href="#typedef+xml2jsParseOptions">xml2jsParseOptions</a>
     - <a href="#typedef+js2xmlParseOptions">js2xmlParseOptions</a>
+    - <a href="#typedef+INode">INode</a>
 
 - Classes
     - <a href="#TXmlContentParseOptions">TXmlContentParseOptions</a>
@@ -28,6 +29,11 @@ This paper describes a functions provided by `xObj.js` module.
 
 This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function descriptions.
 
+<a name="typedef+INode"></a>
+#### `INode` - object type
+
+This type is an `object` which represents a base element (so called an `XObj-node`). Its child elements addressed by a `key`. Each `key` is defined by a used parser options and must be a `string`.
+
 <a name="typedef+OPT_valtostr"></a>
 #### `OPT_valtostr` - options set
 
@@ -154,7 +160,7 @@ This function returns a value of an object parameter as a string.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `key` | `string` | --- | some key |
 
 ##### ***exceptions***
@@ -173,7 +179,7 @@ This function reads a value of an object parameter and returns it as a `boolean`
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `defValue` | `boolean` | `false` | default value |
 | `key` | `string` | --- | some key |
 
@@ -193,7 +199,7 @@ This function reads a value of an object parameter and returns it as a `number`.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `defValue` | `number` | `0` | default value |
 | `key` | `string` | --- | some key |
 
@@ -215,7 +221,7 @@ This function reads a value of an object parameter and try to convert it to a va
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `key` | `string` | --- | some key |
 
 ##### ***exceptions***
@@ -236,7 +242,7 @@ This function reads a value of an object parameter and returns it as a `string`.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `options` | `string`, `object` | --- | options that defines how a value must be transformed |
 | `key` | `string` | --- | some key |
 
@@ -279,7 +285,7 @@ This function sets object parameter to a given value and if succeed returns `tru
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value to write |
 | `key` | `string` | --- | some key |
 
@@ -299,7 +305,7 @@ This function writes a given `boolean` value of an object parameter.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value to write |
 | `defValue` | `boolean` | `false` | default value |
 | `key` | `string` | --- | some key |
@@ -320,7 +326,7 @@ This function writes a given `number` value of an object parameter.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value to write |
 | `defValue` | `number` | `0` | default value |
 | `key` | `string` | --- | some key |
@@ -341,7 +347,7 @@ This function try to interpret a given value as a valid index value and, if succ
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value to write |
 | `key` | `string` | --- | some key |
 
@@ -361,7 +367,7 @@ This function sets object parameter to a given value and if succeed returns `tru
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value to write |
 | `options` | `string`, `object` | --- | options that defines how a value must be transformed |
 | `key` | `string` | --- | some key |
@@ -405,7 +411,7 @@ This function returns a value of an object attribute. The value is of a `string`
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `key` | `string` | --- | some key |
 
@@ -425,7 +431,7 @@ This function reads a value of an object attribute and returns it as a `boolean`
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `defValue` | `boolean` | `false` | default value |
 | `key` | `string` | --- | some key |
@@ -446,7 +452,7 @@ This function reads a value of an object attribute and returns it as a `number`.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `defValue` | `number` | `0` | default value |
 | `key` | `string` | --- | some key |
@@ -469,7 +475,7 @@ This function reads a value of an object attribute and try to convert it to a va
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `key` | `string` | --- | some key |
 
@@ -491,7 +497,7 @@ This function returns a value of an object attribute. The value is of a `string`
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `options` | `string`, `object` | --- | options that defines how a value must be transformed |
 | `key` | `string` | --- | some key |
@@ -535,7 +541,7 @@ This function sets object attribute to a given value and if succeed returns `tru
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `key` | `string` | --- | some key |
@@ -558,7 +564,7 @@ This function writes a given `boolean` value of an object attribute.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `defValue` | `boolean` | `false` | default value |
@@ -580,7 +586,7 @@ This function writes a given `number` value of an object attribute.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `defValue` | `number` | `0` | default value |
@@ -602,7 +608,7 @@ This function try to interpret a given value as a valid index value and, if succ
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `key` | `string` | --- | some key |
@@ -623,7 +629,7 @@ This function sets object attribute to a given value and if succeed returns `tru
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `options` | `string`, `object` | --- | options that defines how a value must be transformed |
@@ -664,7 +670,7 @@ This is a special function that returns a value of an object parameter as "IT IS
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `key` | `string` | --- | some key |
 
 > NOTE:
@@ -691,7 +697,7 @@ This is a special function that writes a given value of an object parameter as "
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `value` | `any` | --- | some value |
 | `key` | `string` | --- | some key |
 
@@ -722,7 +728,7 @@ This is a special function that returns a value of an object attribute as "IT IS
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `key` | `string` | --- | some key |
 
@@ -751,7 +757,7 @@ This is a special function that writes a given value of an object attribute as "
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `any` | --- | some value |
 | `key` | `string` | --- | some key |
@@ -779,7 +785,7 @@ The function throws a `EvalKeyNameError` exception in case:
 > If a `key` parameter given not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
 
 <a name="getXObjAttributes"></a>
-#### **getXObjAttributes(object\[, key])** => `?object`
+#### **getXObjAttributes(object\[, key])** => `?INode`
 
 This function returns an object which represents a set of the element attributes for a given object or `null` if failed.
 
@@ -787,7 +793,7 @@ This function returns an object which represents a set of the element attributes
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `key` | `string` | --- | some key |
 
 ##### ***exceptions***
@@ -806,7 +812,7 @@ This function tries to check whether or not an attribute with a name given by `a
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `key` | `string` | --- | some key |
 
@@ -832,7 +838,7 @@ This function tries to delete  an attribute with a name given by `attr` paramete
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `key` | `string` | --- | some key |
 
@@ -860,7 +866,7 @@ This function tries to rename an attribute with a name given by `attr` parameter
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `attr` | `string` | --- | some attribute |
 | `value` | `string` | --- | new attribute ID |
 | `key` | `string` | --- | some key |
@@ -890,7 +896,7 @@ This function returns an element from a given object by its name or `null` if th
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 
 ##### ***exceptions***
@@ -937,7 +943,7 @@ This function adds an element given by `name` parameter to a members of the give
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 
 ##### ***result***
@@ -996,7 +1002,7 @@ This function inserts an empty element named by a `name` parameter into a given
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 | `options` | `object` | --- | options |
 
@@ -1063,7 +1069,7 @@ This function deletes an element addressed by `name` parameter from a given obje
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 
 ##### ***result***
@@ -1096,7 +1102,7 @@ This function renames an element addressed by `name` for the given object. If su
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 | `value` | `string` | --- | new element ID |
 
@@ -1124,7 +1130,7 @@ This function tries to clean a given node.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `node` | `object` or `object[]` | --- | some node |
+| `node` | `INode` or `INode[]` | --- | some node or nodes list |
 
 ##### ***exceptions***
 
@@ -1189,7 +1195,7 @@ This function inserts an elements list named by a `name` parameter into a given
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `object` | `object` | --- | some object |
+| `object` | `INode` | --- | some object |
 | `name` | `string` | --- | some child element ID |
 | `options` | `object` | --- | options |
 

package/index.d.ts

@@ -104,6 +104,7 @@ import type {
     RVAL_emodif,
     VCOR_evalkname, RVAL_reason,
     IEvalKeyNameResult,
+    INode,
 } from "./lib/xObj-lib";
 
 export type {
@@ -112,4 +113,5 @@ export type {
     RVAL_emodif,
     VCOR_evalkname, RVAL_reason,
     IEvalKeyNameResult,
+    INode,
 };

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.016-20260530]
+// [v0.1.017-20260606]
 
 // === module init block ===
 
@@ -77,3 +77,5 @@ module.exports.insertXObjEListEx = xObj.insertXObjEListEx;
 module.exports.genXObjENameDescr = xObj.genXObjENameDescr;
 module.exports.insertXObjElements = xObj.insertXObjElements;
 module.exports.insertXObjEChain = xObj.insertXObjEChain;
+
+module.exports.INode = xObj.INode;

package/lib/xObj-attr.d.ts

@@ -1,20 +1,32 @@
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type readXObjAttrOptionAsStr = string;
+export const readXObjAttrOptionAsStr: readXObjAttrOptionAsStr;
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type writeXObjAttrOptionAsStr = string;
+export const writeXObjAttrOptionAsStr: writeXObjAttrOptionAsStr;
 /**
  * Extracts an attributes from a given object by its key.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function getXObjAttributes(obj: object, key?: string): INode | null;
+export function getXObjAttributes(obj: INode, key?: string): INode | null;
 /**
  * Checks whether an attribute is exists.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
-export function checkXObjAttribute(obj: object, attr?: string, key?: string): boolean;
+export function checkXObjAttribute(obj: INode, attr?: string, key?: string): boolean;
 /**
  * Deletes an attribute addressed by a given name.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
-export function deleteXObjAttribute(obj: object, attr?: string, key?: string): boolean;
+export function deleteXObjAttribute(obj: INode, attr?: string, key?: string): boolean;
 /**
  * Renames an attribute addressed by a given name.
  * @since 0.2.0
@@ -23,75 +35,75 @@ export function deleteXObjAttribute(obj: object, attr?: string, key?: string): b
  * @throws {EvalKeyNameError} if `value` param is not valid identifier
  * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
-export function renameXObjAttribute(obj: object, attr?: string, value?: string, key?: string): boolean;
+export function renameXObjAttribute(obj: INode, attr?: string, value?: string, key?: string): boolean;
 /**
  * Extracts an attribute 'AS IS' from a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
-export function readXObjAttrRaw(obj: object, attr?: string, key?: string): any;
+export function readXObjAttrRaw(obj: INode, attr?: string, key?: string): any;
 /**
  * Writes a parameter into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
-export function writeXObjAttrRaw(obj: object, attr: string, value: any, key?: string): boolean;
+export function writeXObjAttrRaw(obj: INode, attr: string, value: any, key?: string): boolean;
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjAttr(obj: object, attr: string, key?: string): string;
+export function readXObjAttr(obj: INode, attr: string, key?: string): string;
 /**
  * Extracts an attribute from a given object and returns it as a boolean.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjAttrAsBool(obj: object, attr: string, defValue?: boolean, key?: string): boolean;
+export function readXObjAttrAsBool(obj: INode, attr: string, defValue?: boolean, key?: string): boolean;
 /**
  * Extracts an attribute from a given object and returns it as a number.
- * @returns {number}
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjAttrAsNum(obj: object, attr: string, defValue?: number, key?: string): number;
+export function readXObjAttrAsNum(obj: INode, attr: string, defValue?: number, key?: string): number;
 /**
  * Extracts an attribute from a given object and returns it as 'index' value.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): number;
+export function readXObjAttrAsIndex(obj: INode, attr: string, key?: string): number;
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-export function readXObjAttrEx(obj: object, attr: string, opt?: object, key?: string): string;
+export function readXObjAttrEx(obj: INode, attr: string, opt?: readXObjAttrOptionAsStr | IValueToStringTransformOptions, key?: string): string;
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjAttr(obj: object, attr: string, value: any, key?: string): boolean;
+export function writeXObjAttr(obj: INode, attr: string, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a boolean and writes it as an attribute
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjAttrAsBool(obj: object, attr: string, value: any, defValue?: boolean, key?: string): boolean;
+export function writeXObjAttrAsBool(obj: INode, attr: string, value: any, defValue?: boolean, key?: string): boolean;
 /**
  * Tries to convert a given value to a number and writes it as an attribute
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjAttrAsNum(obj: object, attr: string, value: any, defValue?: number, key?: string): boolean;
+export function writeXObjAttrAsNum(obj: INode, attr: string, value: any, defValue?: number, key?: string): boolean;
 /**
  * Tries to convert a given value into an 'index' value and writes it
  * as an attribute into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjAttrAsIndex(obj: object, attr: string, value: any, key?: string): boolean;
+export function writeXObjAttrAsIndex(obj: INode, attr: string, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-export function writeXObjAttrEx(obj: object, attr: string, value: any, opt?: object, key?: string): boolean;
+export function writeXObjAttrEx(obj: INode, attr: string, value: any, opt?: writeXObjAttrOptionAsStr | IValueToStringTransformOptions, key?: string): boolean;
 import type { INode } from "./xObj-lib";
+import type { IValueToStringTransformOptions } from "@ygracs/bsfoc-lib-js";

package/lib/xObj-attr.js

@@ -1,4 +1,4 @@
-// [v0.3.138-20260530]
+// [v0.3.140-20260607]
 
 // === module init block ===
 
@@ -44,7 +44,7 @@ const {
 /**
  * Extracts an attributes from a given object by its key.
  * @function getXObjAttributes
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {?INode}
  * @throws {TypeError} if `obj` param is not an object
@@ -71,7 +71,7 @@ module.exports.getXObjAttributes = getXObjAttributes;
 /**
  * Checks whether an attribute is exists.
  * @function checkXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -101,7 +101,7 @@ module.exports.checkXObjAttribute = checkXObjAttribute;
 /**
  * Deletes an attribute addressed by a given name.
  * @function deleteXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -136,7 +136,7 @@ module.exports.deleteXObjAttribute = deleteXObjAttribute;
  * Renames an attribute addressed by a given name.
  * @since 0.2.0
  * @function renameXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} value - new attribute ID
  * @param {string} [key] - some key
@@ -192,7 +192,7 @@ module.exports.renameXObjAttribute = renameXObjAttribute;
 /**
  * Extracts an attribute 'AS IS' from a given object.
  * @function readXObjAttrRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {any}
@@ -222,7 +222,7 @@ module.exports.readXObjAttrRaw = readXObjAttrRaw;
 /**
  * Writes a parameter into a given object.
  * @function writeXObjAttrRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
@@ -272,7 +272,7 @@ module.exports.writeXObjAttrRaw = writeXObjAttrRaw;
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @function readXObjAttr
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {string}
@@ -298,7 +298,7 @@ module.exports.readXObjAttr = readXObjAttr;
 /**
  * Extracts an attribute from a given object and returns it as a boolean.
  * @function readXObjAttrAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
@@ -327,7 +327,7 @@ module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
 /**
  * Extracts an attribute from a given object and returns it as a number.
  * @function readXObjAttrAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
@@ -356,7 +356,7 @@ module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
 /**
  * Extracts an attribute from a given object and returns it as 'index' value.
  * @function readXObjAttrAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {number}
@@ -380,12 +380,24 @@ function readXObjAttrAsIndex(obj, attr, key) {
 };
 module.exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
 
+/**
+ *
+ * @typedef {string} readXObjAttrOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {readXObjAttrOptionAsStr}
+ */
+module.exports.readXObjAttrOptionAsStr = '';
+
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @function readXObjAttrEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
- * @param {object} [opt] - options
+ * @param {readXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {string}
  * @throws {TypeError} if `obj` param is not an object
@@ -405,7 +417,6 @@ function readXObjAttrEx(obj, attr, opt, key) {
       }
     };
   };
-  /** @type {IValueToStringTransformOptions} */
   const _opt = isPlainObject(opt) ? opt : {
     useTrim: true,
     numberToString: true,
@@ -420,7 +431,7 @@ module.exports.readXObjAttrEx = readXObjAttrEx;
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @function writeXObjAttr
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key] - some key
@@ -448,7 +459,7 @@ module.exports.writeXObjAttr = writeXObjAttr;
  * Tries to convert a given value to a boolean and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {boolean} [defValue] - default value
@@ -481,7 +492,7 @@ module.exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
  * Tries to convert a given value to a number and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {number} [defValue] - default value
@@ -514,7 +525,7 @@ module.exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
  * Tries to convert a given value into an 'index' value and writes it
  * as an attribute into a given object.
  * @function writeXObjAttrAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key] - some key
@@ -542,14 +553,26 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
 };
 module.exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
 
+/**
+ *
+ * @typedef {string} writeXObjAttrOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {writeXObjAttrOptionAsStr}
+ */
+module.exports.writeXObjAttrOptionAsStr = '';
+
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
- * @param {object} [opt] - options
+ * @param {writeXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if `obj` param is not an object

package/lib/xObj-lib.d.ts

@@ -196,7 +196,7 @@ export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IE
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function getXObjElement(obj: object, name: string): any | null;
+export function getXObjElement(obj: INode, name: string): any | null;
 /**
  * Adds an element addressed by its key to a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -210,7 +210,7 @@ type addXObjElementParams = Parameters<typeof addXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function addXObjElementEx(obj: object, name: string): INodeModifResult;
+export function addXObjElementEx(obj: INode, name: string): INodeModifResult;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -224,7 +224,7 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjElementEx(obj: object, name: string, opt?: OPT_inselops_L): INodeModifResult;
+export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): INodeModifResult;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -237,19 +237,19 @@ type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function deleteXObjElementEx(obj: object, name: string): INodeModifResult;
+export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
 /**
  * Renames an element addressed by its key.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
-export function renameXObjElement(obj: object, name?: string, value?: string): boolean;
+export function renameXObjElement(obj: INode, name?: string, value?: string): boolean;
 /**
  * Clears a given node
  * @throws {TypeError} if `node`-param is not an object or array
  */
-export function clearXObjNode(node: object | object[]): boolean;
+export function clearXObjNode(node: INode | INode[]): boolean;
 /**
  * Tries to convert a value into an ID.
  */
@@ -267,7 +267,7 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjEListEx(obj: object, name: string, opt?: OPT_inselops_S): INodeModifResult;
+export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResult;
 /**
  * Tries to convert a value into an element name description.
  */

package/lib/xObj-lib.js

@@ -1,15 +1,12 @@
-// [v0.3.138-20260530]
+// [v0.3.140-20260606]
 
 // === module init block ===
 
 const {
   valueToIndex,
-  readAsString, readAsBoolEx, readAsNumberEx,
   isNullOrUndef,
   isInteger,
   isArray, isObject, isPlainObject,
-  // * import types definitions *
-  IValueToStringTransformOptions,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
@@ -17,10 +14,6 @@ const {
   XOBJ_ECODE_TABLE,
 } = require('./xObj-errors');
 
-const {
-  XOBJ_DEF_TNAMES,
-} = require('./xObj-defs');
-
 // === module inner block ===
 
 const {
@@ -32,10 +25,6 @@ const {
   XOBJ_TE_KNES_ECODE,
 } = XOBJ_ECODE_TABLE;
 
-const {
-  XOBJ_DEF_PARAM_TNAME,
-} = XOBJ_DEF_TNAMES;
-
 /**
  * A result of a value check ops.
  * @typedef {Object} RVAL_reason
@@ -268,7 +257,7 @@ module.exports.INode = {};
 /**
  * Extracts an element from a given object by its key.
  * @function getXObjElement
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @returns {?any}
  * @throws {TypeError} if `obj` param is not an object
@@ -364,7 +353,7 @@ module.exports.addXObjElement = addXObjElement;
  * Adds an element addressed by its key to a given object.
  * @since 0.3.0
  * @function addXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
@@ -452,7 +441,7 @@ module.exports.insertXObjElement = insertXObjElement;
  * Inserts an element addressed by its key into a given object.
  * @since 0.2.0
  * @function insertXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {INodeModifResult}
@@ -538,7 +527,7 @@ module.exports.deleteXObjElement = deleteXObjElement;
 /**
  * Deletes an element addressed by its key from a given object.
  * @function deleteXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @returns {INodeModifResult}
  * @throws {TypeError} if `obj` param is not an object
@@ -571,7 +560,7 @@ module.exports.deleteXObjElementEx = deleteXObjElementEx;
 /**
  * Renames an element addressed by its key.
  * @function renameXObjElement
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @param {string} value - new element ID
  * @returns {boolean}
@@ -682,7 +671,7 @@ function insertXObjEList(...args) {
  * Inserts a list elements into a given object.
  * @since 0.2.0
  * @function insertXObjEListEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
  * @returns {INodeModifResult}
@@ -771,7 +760,7 @@ function insertXObjEChain(obj, ...args) {
 
 /**
  * Clears a given node
- * @param {object|object[]} node - some node
+ * @param {INode|INode[]} node - some node
  * @returns {boolean}
  * @throws {TypeError} if `node`-param is not an object or array
  */

package/lib/xObj-param.d.ts

@@ -1,69 +1,83 @@
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type readXObjParamOptionAsStr = string;
+export const readXObjParamOptionAsStr: readXObjParamOptionAsStr;
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type writeXObjParamOptionAsStr = string;
+export const writeXObjParamOptionAsStr: writeXObjParamOptionAsStr;
 /**
  * Extracts a parameter 'AS IS' from a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
-export function readXObjParamRaw(obj: object, key?: string): any;
+export function readXObjParamRaw(obj: INode, key?: string): any;
 /**
  * Writes a parameter 'AS IS' into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
-export function writeXObjParamRaw(obj: object, value: any, key?: string): boolean;
+export function writeXObjParamRaw(obj: INode, value: any, key?: string): boolean;
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjParam(obj: INode, key?: string): string;
 /**
  * Extracts a parameter from a given object and returns it as a boolean.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjParamAsBool(obj: object, defValue?: boolean, key?: string): boolean;
+export function readXObjParamAsBool(obj: INode, defValue?: boolean, key?: string): boolean;
 /**
  * Extracts a parameter from a given object and returns it as a number.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjParamAsNum(obj: object, defValue?: number, key?: string): number;
+export function readXObjParamAsNum(obj: INode, defValue?: number, key?: string): number;
 /**
  * Extracts a parameter from a given object and returns it as 'index' value.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function readXObjParamAsIndex(obj: object, key?: string): number;
+export function readXObjParamAsIndex(obj: INode, key?: string): number;
 /**
  * Extracts a parameter from a given object and returns it as a string.
  * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-export function readXObjParamEx(obj: object, opt?: object, key?: string): string;
+export function readXObjParamEx(obj: INode, opt?: readXObjParamOptionAsStr | IValueToStringTransformOptions, key?: string): string;
+/**
+ * Tries to convert a given value to a string and writes it as a parameter
+ * into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function writeXObjParam(obj: INode, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a boolean and writes it as a parameter
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjParamAsBool(obj: object, value: any, defValue?: boolean, key?: string): boolean;
+export function writeXObjParamAsBool(obj: INode, value: any, defValue?: boolean, key?: string): boolean;
 /**
  * Tries to convert a given value to a number and writes it as a parameter
  * into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjParamAsNum(obj: object, value: any, defValue?: number, key?: string): boolean;
+export function writeXObjParamAsNum(obj: INode, value: any, defValue?: number, key?: string): boolean;
 /**
  * Tries to convert a given value into an 'index' value and writes it
  * as a parameter into a given object.
  * @throws {TypeError} if `obj` param is not an object
  */
-export function writeXObjParamAsIndex(obj: object, value: any, key?: string): boolean;
+export function writeXObjParamAsIndex(obj: INode, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a string and writes it
  * as a parameter into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
-export function writeXObjParamEx(obj: object, value: any, opt?: object, key?: string): boolean;
-/**
- * Extracts a parameter from a given object and returns it as a string.
- * @throws {TypeError} if `obj` param is not an object
- */
-export function readXObjParam(obj: object, key?: string): string;
-/**
- * Tries to convert a given value to a string and writes it as a parameter
- * into a given object.
- * @throws {TypeError} if `obj` param is not an object
- */
-export function writeXObjParam(obj: object, value: any, key?: string): boolean;
+export function writeXObjParamEx(obj: INode, value: any, opt?: writeXObjParamOptionAsStr | IValueToStringTransformOptions, key?: string): boolean;
+import type { INode } from "./xObj-lib";
+import type { IValueToStringTransformOptions } from "@ygracs/bsfoc-lib-js";

package/lib/xObj-param.js

@@ -1,4 +1,4 @@
-// [v0.3.138-20260530]
+// [v0.3.140-20260607]
 
 // === module init block ===
 
@@ -21,6 +21,8 @@ const {
 
 const {
   evalKeyName,
+  // * import types definitions *
+  INode,
 } = require('./xObj-lib');
 
 // === module inner block ===
@@ -40,7 +42,7 @@ const {
 /**
  * Extracts a parameter 'AS IS' from a given object.
  * @function readXObjParamRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {any}
  * @throws {TypeError} if `obj` param is not an object
@@ -65,7 +67,7 @@ module.exports.readXObjParamRaw = readXObjParamRaw;
 /**
  * Writes a parameter 'AS IS' into a given object.
  * @function writeXObjParamRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {boolean}
@@ -101,7 +103,7 @@ module.exports.writeXObjParamRaw = writeXObjParamRaw;
 /**
  * Extracts a parameter from a given object and returns it as a string.
  * @function readXObjParam
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key] - some key
  * @returns {string}
  * @throws {TypeError} if `obj` param is not an object
@@ -126,7 +128,7 @@ module.exports.readXObjParam = readXObjParam;
 /**
  * Extracts a parameter from a given object and returns it as a boolean.
  * @function readXObjParamAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -154,7 +156,7 @@ module.exports.readXObjParamAsBool = readXObjParamAsBool;
 /**
  * Extracts a parameter from a given object and returns it as a number.
  * @function readXObjParamAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
@@ -182,7 +184,7 @@ module.exports.readXObjParamAsNum = readXObjParamAsNum;
 /**
  * Extracts a parameter from a given object and returns it as 'index' value.
  * @function readXObjParamAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key] - some key
  * @returns {number}
  * @throws {TypeError} if `obj` param is not an object
@@ -205,11 +207,23 @@ function readXObjParamAsIndex(obj, key) {
 };
 module.exports.readXObjParamAsIndex = readXObjParamAsIndex;
 
+/**
+ *
+ * @typedef {string} readXObjParamOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {readXObjParamOptionAsStr}
+ */
+module.exports.readXObjParamOptionAsStr = '';
+
 /**
  * Extracts a parameter from a given object and returns it as a string.
  * @function readXObjParamEx
- * @param {object} obj - some object
- * @param {object} [opt] - options
+ * @param {INode} obj - some object
+ * @param {readXObjParamOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {string}
  * @throws {TypeError} if `obj` param is not an object
@@ -229,7 +243,6 @@ function readXObjParamEx(obj, opt, key) {
       }
     };
   };
-  /** @type {IValueToStringTransformOptions} */
   const _opt = isPlainObject(opt) ? opt : {
     useTrim: false,
     numberToString: true,
@@ -244,7 +257,7 @@ module.exports.readXObjParamEx = readXObjParamEx;
  * Tries to convert a given value to a string and writes it as a parameter
  * into a given object.
  * @function writeXObjParam
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -271,7 +284,7 @@ module.exports.writeXObjParam = writeXObjParam;
  * Tries to convert a given value to a boolean and writes it as a parameter
  * into a given object.
  * @function writeXObjParamAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
@@ -303,7 +316,7 @@ module.exports.writeXObjParamAsBool = writeXObjParamAsBool;
  * Tries to convert a given value to a number and writes it as a parameter
  * into a given object.
  * @function writeXObjParamAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
@@ -335,7 +348,7 @@ module.exports.writeXObjParamAsNum = writeXObjParamAsNum;
  * Tries to convert a given value into an 'index' value and writes it
  * as a parameter into a given object.
  * @function writeXObjParamAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -362,13 +375,25 @@ function writeXObjParamAsIndex(obj, value, key) {
 };
 module.exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
 
+/**
+ *
+ * @typedef {string} writeXObjParamOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {writeXObjParamOptionAsStr}
+ */
+module.exports.writeXObjParamOptionAsStr = '';
+
 /**
  * Tries to convert a given value to a string and writes it
  * as a parameter into a given object.
  * @function writeXObjParamEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
- * @param {object} [opt] - options
+ * @param {writeXObjParamOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if `obj` param is not an object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",