@ygracs/xobj-lib-js 0.2.9-b.2 → 0.3.0-beta.0

package/CHANGELOG.md

@@ -1,13 +1,14 @@
-#### *v0.2.x*
+#### *v0.3.x*
 
 Release version.
 
 > - update `xObj.md`;
 > - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+> - change behavior for function: `addXObjElement` on handling exceptions;
 > - change behavior for function: `evalKeyName` on handling `opt` parameter;
 > - change behavior for function: `writeXObjParamRaw`, `writeXObjAttrRaw`;
 > - improve behavior for function: `writeXObjParam`, `writeXObjParamEx`, `writeXObjAttr`, `writeXObjAttrEx`;
-> - add a new function: `clearXObjNode`;
+> - add a new function: `addXObjElementEx`, `clearXObjNode`;
 > - add a new `EvalKeyNameError` class;
 > - add new `compact`-property for `TXmlContentParseOptions`;
 > - some fixes.

package/README.md

@@ -1,15 +1,15 @@
-|***rev.*:**|0.1.2|
+|***rev.*:**|0.1.3|
 |:---|---:|
-|***date***:|2024-09-15|
+|***date***:|2026-02-28|
 
 ## Introduction
 
-This module provide a helper functions for object manipulation. It was primarily written to work with a XML-parse provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
+This module provide a helper functions for object manipulation. It was primarily written to work with a XML-parser provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
 
-> Note: for more see `xObj.md` in the project `doc` directory.
+> Note: for more see `xObj.md` in the package `doc` directory or in a package [*repo*](https://gitlab.com/ygracs/xobj-lib-js).
 
-> Notes on upgrade to `v0.2.0`
-> > The `v0.2.0` is not fully compatible with a previous one due to some breaking changes. For more details read the docs for a functions used in your project.
+> Notes on upgrade to `v0.3.0`
+> > The `v0.3.0` is not fully compatible with a previous one due to some breaking changes. For more details read the docs for a functions used in your project.
 
 ## Use cases
 

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.48|
+>|***rev.*:**|0.1.51|
 >|:---|---:|
->|date:|2026-02-22|
+>|date:|2026-02-28|
 
 ## Introduction
 
@@ -886,6 +886,27 @@ The function throws a `TypeError` exception in case:
 <a name="addXObjElement"></a>
 #### **addXObjElement(object, name)** => `object`
 
+This function adds an element given by `name` parameter to a members of the given object.  If succeed the element will be returned or `null` in opposite.
+
+##### ***parameters***
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+
+##### ***exceptions***
+
+The function throws a `TypeError` exception in case:
+
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+
+<a name="addXObjElementEx"></a>
+#### **addXObjElementEx(object, name)** => `object`
+
+> since: \[v0.2.0]
+
 This function adds an element given by `name` parameter to a members of the given object and returns an `object` that represents a status of the operation.
 
 ##### ***parameters***

package/index.d.ts

@@ -1,79 +1,107 @@
-declare const _exports: {
-    readXObjParamRaw: typeof import("./lib/xObj-lib").readXObjParamRaw;
-    readXObjParam: typeof import("./lib/xObj-lib").readXObjParam;
-    readXObjParamAsBool: typeof import("./lib/xObj-lib").readXObjParamAsBool;
-    readXObjParamAsNum: typeof import("./lib/xObj-lib").readXObjParamAsNum;
-    readXObjParamEx: typeof import("./lib/xObj-lib").readXObjParamEx;
-    readXObjParamAsIndex: typeof import("./lib/xObj-lib").readXObjParamAsIndex;
-    writeXObjParamRaw: typeof import("./lib/xObj-lib").writeXObjParamRaw;
-    writeXObjParam: typeof import("./lib/xObj-lib").writeXObjParam;
-    writeXObjParamAsBool: typeof import("./lib/xObj-lib").writeXObjParamAsBool;
-    writeXObjParamAsNum: typeof import("./lib/xObj-lib").writeXObjParamAsNum;
-    writeXObjParamAsIndex: typeof import("./lib/xObj-lib").writeXObjParamAsIndex;
-    writeXObjParamEx: typeof import("./lib/xObj-lib").writeXObjParamEx;
-    readXObjAttrRaw: typeof import("./lib/xObj-lib").readXObjAttrRaw;
-    readXObjAttr: typeof import("./lib/xObj-lib").readXObjAttr;
-    readXObjAttrAsBool: typeof import("./lib/xObj-lib").readXObjAttrAsBool;
-    readXObjAttrAsNum: typeof import("./lib/xObj-lib").readXObjAttrAsNum;
-    readXObjAttrEx: typeof import("./lib/xObj-lib").readXObjAttrEx;
-    readXObjAttrAsIndex: typeof import("./lib/xObj-lib").readXObjAttrAsIndex;
-    writeXObjAttrRaw: typeof import("./lib/xObj-lib").writeXObjAttrRaw;
-    writeXObjAttr: typeof import("./lib/xObj-lib").writeXObjAttr;
-    writeXObjAttrAsBool: typeof import("./lib/xObj-lib").writeXObjAttrAsBool;
-    writeXObjAttrAsNum: typeof import("./lib/xObj-lib").writeXObjAttrAsNum;
-    writeXObjAttrAsIndex: typeof import("./lib/xObj-lib").writeXObjAttrAsIndex;
-    writeXObjAttrEx: typeof import("./lib/xObj-lib").writeXObjAttrEx;
-    getXObjAttributes: typeof import("./lib/xObj-lib").getXObjAttributes;
-    checkXObjAttribute: typeof import("./lib/xObj-lib").checkXObjAttribute;
-    deleteXObjAttribute: typeof import("./lib/xObj-lib").deleteXObjAttribute;
-    renameXObjAttribute: typeof import("./lib/xObj-lib").renameXObjAttribute;
-    getXObjElement: typeof import("./lib/xObj-lib").getXObjElement;
-    addXObjElement: typeof import("./lib/xObj-lib").addXObjElement;
-    insertXObjElement: typeof import("./lib/xObj-lib").insertXObjElement;
-    insertXObjElementEx: typeof import("./lib/xObj-lib").insertXObjElementEx;
-    deleteXObjElement: typeof import("./lib/xObj-lib").deleteXObjElement;
-    deleteXObjElementEx: typeof import("./lib/xObj-lib").deleteXObjElementEx;
-    renameXObjElement: typeof import("./lib/xObj-lib").renameXObjElement;
-    evalXObjEName: typeof import("./lib/xObj-lib").evalXObjEName;
-    insertXObjEList: typeof import("./lib/xObj-lib").insertXObjEList;
-    insertXObjEListEx: typeof import("./lib/xObj-lib").insertXObjEListEx;
-    evalKeyName: typeof import("./lib/xObj-lib").evalKeyName;
-    genXObjENameDescr: typeof import("./lib/xObj-lib").genXObjENameDescr;
-    insertXObjElements: typeof import("./lib/xObj-lib").insertXObjElements;
-    insertXObjEChain: typeof import("./lib/xObj-lib").insertXObjEChain;
-    clearXObjNode: typeof import("./lib/xObj-lib").clearXObjNode;
-
-    TXmlContentParseOptions: typeof TXmlContentParseOptions; // [?] class declaration
-    DEF_XML_PARSE_OPTIONS: typeof DEF_XML_PARSE_OPTIONS;
-    XOBJ_DEF_TNAMES: typeof XOBJ_DEF_TNAMES;
-
-    EvalKeyNameError: typeof EvalKeyNameError; // [?] class declaration
-
-    xml2jsParseOptions: xml2jsParseOptions;
-    js2xmlParseOptions: js2xmlParseOptions;
-    OPT_parserOptions: OPT_parserOptions;
-
-    XObjENameDescr: XObjENameDescr;
-    OPT_inselops_L: OPT_inselops_L;
-    OPT_inselops_S: OPT_inselops_S;
-    RVAL_reason: RVAL_reason;
-    RVAL_emodif: RVAL_emodif;
-    VCOR_evalkname: VCOR_evalkname;
-};
-export = _exports;
 import { TXmlContentParseOptions } from "./lib/xObj-defs";
 import { DEF_XML_PARSE_OPTIONS } from "./lib/xObj-defs";
 import { XOBJ_DEF_TNAMES } from "./lib/xObj-defs";
-import { EvalKeyNameError } from "./lib/xObj-errors";
+
+export {
+    TXmlContentParseOptions,
+    DEF_XML_PARSE_OPTIONS,
+    XOBJ_DEF_TNAMES,
+};
 
 import type {
   xml2jsParseOptions, js2xmlParseOptions,
   OPT_parserOptions,
 } from "./lib/xObj-defs";
 
+export type {
+    xml2jsParseOptions, js2xmlParseOptions,
+    OPT_parserOptions,
+};
+
+import { EvalKeyNameError } from "./lib/xObj-errors";
+
+export { EvalKeyNameError };
+
+import {
+    readXObjParamRaw,
+    readXObjParam,
+    readXObjParamEx,
+    readXObjParamAsBool, readXObjParamAsNum, readXObjParamAsIndex,
+    writeXObjParamRaw,
+    writeXObjParam,
+    writeXObjParamEx,
+    writeXObjParamAsBool, writeXObjParamAsNum, writeXObjParamAsIndex,
+    readXObjAttrRaw,
+    readXObjAttr,
+    readXObjAttrEx,
+    readXObjAttrAsBool, readXObjAttrAsNum, readXObjAttrAsIndex,
+    writeXObjAttrRaw,
+    writeXObjAttr,
+    writeXObjAttrEx,
+    writeXObjAttrAsBool, writeXObjAttrAsNum, writeXObjAttrAsIndex,
+    getXObjAttributes,
+    checkXObjAttribute,
+    deleteXObjAttribute,
+    renameXObjAttribute,
+    getXObjElement,
+    addXObjElement, addXObjElementEx,
+    insertXObjElement, insertXObjElementEx,
+    deleteXObjElement, deleteXObjElementEx,
+    renameXObjElement,
+    insertXObjEList, insertXObjEListEx,
+    evalXObjEName,
+    evalKeyName,
+    genXObjENameDescr,
+    insertXObjElements,
+    insertXObjEChain,
+    clearXObjNode,
+} from "./lib/xObj-lib";
+
+export {
+    readXObjParamRaw,
+    readXObjParam,
+    readXObjParamEx,
+    readXObjParamAsBool, readXObjParamAsNum, readXObjParamAsIndex,
+    writeXObjParamRaw,
+    writeXObjParam,
+    writeXObjParamEx,
+    writeXObjParamAsBool, writeXObjParamAsNum, writeXObjParamAsIndex,
+    readXObjAttrRaw,
+    readXObjAttr,
+    readXObjAttrEx,
+    readXObjAttrAsBool, readXObjAttrAsNum, readXObjAttrAsIndex,
+    writeXObjAttrRaw,
+    writeXObjAttr,
+    writeXObjAttrEx,
+    writeXObjAttrAsBool, writeXObjAttrAsNum, writeXObjAttrAsIndex,
+    getXObjAttributes,
+    checkXObjAttribute,
+    deleteXObjAttribute,
+    renameXObjAttribute,
+    getXObjElement,
+    addXObjElement, addXObjElementEx,
+    insertXObjElement, insertXObjElementEx,
+    deleteXObjElement, deleteXObjElementEx,
+    renameXObjElement,
+    insertXObjEList, insertXObjEListEx,
+    evalXObjEName,
+    evalKeyName,
+    genXObjENameDescr,
+    insertXObjElements,
+    insertXObjEChain,
+    clearXObjNode,
+};
+
 import type {
   XObjENameDescr,
   OPT_inselops_L, OPT_inselops_S,
   RVAL_reason, RVAL_emodif,
   VCOR_evalkname,
 } from "./lib/xObj-lib";
+
+export type {
+    XObjENameDescr,
+    OPT_inselops_L, OPT_inselops_S,
+    RVAL_reason, RVAL_emodif,
+    VCOR_evalkname,
+};

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.014-20251228]
+// [v0.1.015-20260227]
 
 // === module init block ===
 
@@ -12,16 +12,66 @@ const {
   EvalKeyNameError,
 } = require('./lib/xObj-errors');
 
+const xObj = require('./lib/xObj-lib');
+
 // === module inner block ===
 
 // === module main block ===
 
 // === module exports block ===
 
-module.exports = require('./lib/xObj-lib');
+//module.exports = require('./lib/xObj-lib');
 
 module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
 module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
 module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;
 
 module.exports.EvalKeyNameError = EvalKeyNameError;
+
+module.exports.readXObjParamRaw = xObj.readXObjParamRaw;
+module.exports.readXObjParam = xObj.readXObjParam;
+module.exports.readXObjParamAsBool = xObj.readXObjParamAsBool;
+module.exports.readXObjParamAsNum = xObj.readXObjParamAsNum;
+module.exports.readXObjParamEx = xObj.readXObjParamEx;
+module.exports.readXObjParamAsIndex = xObj.readXObjParamAsIndex;
+module.exports.writeXObjParamRaw = xObj.writeXObjParamRaw;
+module.exports.writeXObjParam = xObj.writeXObjParam;
+module.exports.writeXObjParamAsBool = xObj.writeXObjParamAsBool;
+module.exports.writeXObjParamAsNum = xObj.writeXObjParamAsNum;
+module.exports.writeXObjParamAsIndex = xObj.writeXObjParamAsIndex;
+module.exports.writeXObjParamEx = xObj.writeXObjParamEx;
+
+module.exports.readXObjAttrRaw = xObj.readXObjAttrRaw;
+module.exports.readXObjAttr = xObj.readXObjAttr;
+module.exports.readXObjAttrAsBool = xObj.readXObjAttrAsBool;
+module.exports.readXObjAttrAsNum = xObj.readXObjAttrAsNum;
+module.exports.readXObjAttrEx = xObj.readXObjAttrEx;
+module.exports.readXObjAttrAsIndex = xObj.readXObjAttrAsIndex;
+module.exports.writeXObjAttrRaw = xObj.writeXObjAttrRaw;
+module.exports.writeXObjAttr = xObj.writeXObjAttr;
+module.exports.writeXObjAttrAsBool = xObj.writeXObjAttrAsBool;
+module.exports.writeXObjAttrAsNum = xObj.writeXObjAttrAsNum;
+module.exports.writeXObjAttrAsIndex = xObj.writeXObjAttrAsIndex;
+module.exports.writeXObjAttrEx = xObj.writeXObjAttrEx;
+
+module.exports.getXObjAttributes = xObj.getXObjAttributes;
+module.exports.checkXObjAttribute = xObj.checkXObjAttribute;
+module.exports.deleteXObjAttribute = xObj.deleteXObjAttribute;
+module.exports.renameXObjAttribute = xObj.renameXObjAttribute;
+
+module.exports.getXObjElement = xObj.getXObjElement;
+module.exports.addXObjElement = xObj.addXObjElement;
+module.exports.addXObjElementEx = xObj.addXObjElementEx;
+module.exports.insertXObjElement = xObj.insertXObjElement;
+module.exports.insertXObjElementEx = xObj.insertXObjElementEx;
+module.exports.deleteXObjElement = xObj.deleteXObjElement;
+module.exports.deleteXObjElementEx = xObj.deleteXObjElementEx;
+module.exports.renameXObjElement = xObj.renameXObjElement;
+
+module.exports.evalXObjEName = xObj.evalXObjEName;
+module.exports.insertXObjEList = xObj.insertXObjEList;
+module.exports.insertXObjEListEx = xObj.insertXObjEListEx;
+
+module.exports.genXObjENameDescr = xObj.genXObjENameDescr;
+module.exports.insertXObjElements = xObj.insertXObjElements;
+module.exports.insertXObjEChain = xObj.insertXObjEChain;

package/lib/xObj-defs.d.ts

@@ -80,8 +80,8 @@ export namespace XOBJ_DEF_TNAMES {
 export const DEF_XML_PARSE_OPTIONS: OPT_parserOptions;
 
 /**
- * @classdesc Implements a container that provide a functionality to work
- *    with options for an XML-parser
+ * Implements a container that provide a functionality to work
+ * with options for an XML-parser
  */
 export class TXmlContentParseOptions {
     /**
@@ -98,6 +98,7 @@ export class TXmlContentParseOptions {
     get settings(): OPT_parserOptions;
     /**
      * Returns a value of `compact` option
+     * @since 0.3.0
      */
     get compact(): boolean;
     /**

package/lib/xObj-defs.js

@@ -1,4 +1,4 @@
-// [v0.1.070-20260221]
+// [v0.1.070-20260227]
 
 // === module init block ===
 
@@ -145,7 +145,7 @@ class TXmlContentParseOptions {
 
   /**
    * Returns a value of `compact` option
-   * @since 0.2.x
+   * @since 0.3.0
    * @type {boolean}
    */
   get compact() {

package/lib/xObj-errors.d.ts

@@ -13,8 +13,9 @@ export namespace XOBJ_ECODE_TABLE {
     export { XOBJ_TE_KNES_ECODE };
 }
 /**
- * @classdesc Extends a base `TypeError` object to provide some information
- *            on the errors thrown when a key name evaluation failed
+ * Extends a base `TypeError` object to provide some information
+ * on the errors thrown when a key name evaluation failed
+ * @since 0.3.0
  */
 export class EvalKeyNameError extends TypeError {
     /**

package/lib/xObj-errors.js

@@ -1,4 +1,4 @@
-// [v0.1.004-20260221]
+// [v0.1.004-20260227]
 
 // === module init block ===
 
@@ -41,7 +41,7 @@ const XOBJ_ECODE_TABLE = {
 module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
 
 /**
- * @since 0.2.x
+ * @since 0.3.0
  * @augments TypeError
  * @classdesc Extends a base `TypeError` object to provide some information
  *            on the errors thrown when a key name evaluation failed

package/lib/xObj-lib.d.ts

@@ -110,6 +110,13 @@ export type OPT_inselops_S = {
     ripOldies?: boolean;
 };
 
+/**
+ * Adds an element addressed by its key to a given object.
+ * @since 0.3.0
+ * @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): RVAL_emodif;
 /**
  * Clears a given node
  * @throws {TypeError} if `node`-param is not an object or array
@@ -117,184 +124,185 @@ export type OPT_inselops_S = {
 export function clearXObjNode(node: object | object[]): boolean;
 /**
  * Extracts a parameter 'AS IS' from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Extracts a parameter from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParam(obj: object, key?: string): string;
 /**
  * Extracts a parameter from a given object and returns it as a boolean.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsBool(obj: object, defValue?: boolean, key?: string): boolean;
 /**
  * Extracts a parameter from a given object and returns it as a number.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsNum(obj: object, defValue?: number, key?: string): number;
 /**
  * Extracts a parameter from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
+ * @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;
 /**
  * Extracts a parameter from a given object and returns it as 'index' value.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsIndex(obj: object, key?: string): number;
 /**
  * Writes a parameter 'AS IS' into a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @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;
 /**
  * Tries to convert a given value to a string and writes it as a parameter
  * into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParam(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsBool(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsNum(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsIndex(obj: object, 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 first param is not an 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 an attribute 'AS IS' from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Extracts an attribute from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttr(obj: object, attr: string, key?: string): string;
 /**
  * Extracts an attribute from a given object and returns it as a boolean.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsBool(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsNum(obj: object, attr: string, defValue?: number, key?: string): number;
 /**
  * Extracts an attribute from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
+ * @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;
 /**
  * Extracts an attribute from a given object and returns it as 'index' value.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): number;
 /**
  * Writes a parameter into a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttr(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsBool(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsNum(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsIndex(obj: object, 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 first param is not an 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;
 /**
  * Extracts an attributes from a given object by its key.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function getXObjAttributes(obj: object, key?: string): object | null;
 /**
  * Checks whether an attribute is exists.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Deletes an attribute addressed by a given name.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Renames an attribute addressed by a given name.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
- * @throws {EvalKeyNameError} if forth param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ * @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;
 /**
  * Extracts an element from a given object by its key.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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;
 /**
  * Adds an element addressed by its key to a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @see {@link addXObjElementEx} for param details
  */
-export function addXObjElement(obj: object, name: string): RVAL_emodif;
+export function addXObjElement(...args: addXObjElementParams): object | null;
+type addXObjElementParams = Parameters<typeof addXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
 export function insertXObjElement(...args: insertXObjElementParams): object | null;
@@ -302,28 +310,28 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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): RVAL_emodif;
 /**
  * Deletes an element addressed by its key from a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link deleteXObjElementEx} for param details
  */
 export function deleteXObjElement(...args: deleteXObjElementParams): boolean;
 type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
 /**
  * Deletes an element addressed by its key from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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): RVAL_emodif;
 /**
  * Renames an element addressed by its key.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @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;
 /**
@@ -332,7 +340,7 @@ export function renameXObjElement(obj: object, name?: string, value?: string): b
 export function evalXObjEName(value: any): null | number | string;
 /**
  * Inserts a list elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see insertXObjEListEx
  */
 export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
@@ -340,8 +348,8 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * Inserts a list elements into a given object.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @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): RVAL_emodif;
 /**
@@ -355,12 +363,12 @@ export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IE
 export function genXObjENameDescr(value: any): XObjENameDescr;
 /**
  * Inserts an elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function insertXObjElements(obj: object, ...args: any[]): number;
 /**
  * Inserts a chain of an elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function insertXObjEChain(obj: object, ...args: any[]): any | null;
 export {}

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.127-20260222]
+// [v0.3.131-20260228]
 
 // === module init block ===
 
@@ -46,14 +46,14 @@ const {
 
 /**
  * An options setting for `evalKeyName` function
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameOptions
  * @property {boolean} [onlyNES] - a flag to accept only a non-empty string values
  */
 
 /**
  * A result of `evalKeyName` function if succeed
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameResultOnSuccess
  * @property {true} isSucceed - ops flag
  * @property {string} value - result value
@@ -61,7 +61,7 @@ const {
 
 /**
  * A result of `evalKeyName` function if failed
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {Object} IEvalKeyNameResultOnFail
  * @property {false} isSucceed - ops flag
  * @property {RVAL_reason} value - reason of fail
@@ -69,7 +69,7 @@ const {
 
 /**
  * A result of `evalKeyName` function
- * @since 0.2.x
+ * @since 0.3.0
  * @typedef {(IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail)} IEvalKeyNameResult
  */
 
@@ -78,7 +78,7 @@ const {
  * @typedef {Object} VCOR_evalkname
  * @property {boolean} isSucceed - ops flag
  * @property {(string|RVAL_reason)} value - result value or reson if failed
- * @todo \[from v0.2.x] make obsolete. Use `IEvalKeyNameResult` instead.
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
  */
 
 /**
@@ -178,6 +178,7 @@ function evalXObjEName(value) {
  * @function genXObjENameDescr
  * @param {any} value - element name pattern
  * @returns {XObjENameDescr}
+ * @experimental
  */
 function genXObjENameDescr(value) {
   let result = null;
@@ -236,8 +237,8 @@ function genXObjENameDescr(value) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {?any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function getXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
@@ -261,7 +262,7 @@ function getXObjElement(obj, name) {
  * @param {object} obj - some object
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {?object}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
   let result = null;
@@ -293,11 +294,39 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
  * @function addXObjElement
  * @param {object} obj - some object
  * @param {string} name - some child element
+ * @returns {?object}
+ * @throws {TypeError} if `obj` param is not an object
+ * @see {@link addXObjElementEx} for param details
+ */
+function addXObjElement(...args) {
+  let item = null;
+  try {
+    ({ item } = addXObjElementEx(...args));
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return item;
+};
+
+/**
+ * Adds an element addressed by its key to a given object.
+ * @since 0.3.0
+ * @function addXObjElementEx
+ * @param {object} obj - some object
+ * @param {string} name - some child element
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-function addXObjElement(obj, name) {
+function addXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
     throw new EvalKeyNameError(
       XOBJ_TE_NPOBJ_EMSG,
@@ -331,6 +360,7 @@ function addXObjElement(obj, name) {
     throw new EvalKeyNameError(msg, { code });
   };
 };
+module.exports.addXObjElementEx = addXObjElementEx;
 
 /**
  * An options for an element insertion ops
@@ -347,7 +377,7 @@ function addXObjElement(obj, name) {
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
 function insertXObjElement(...args) {
@@ -376,8 +406,8 @@ function insertXObjElement(...args) {
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -427,7 +457,7 @@ function insertXObjElementEx(obj, name, opt) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link deleteXObjElementEx} for param details
  */
 function deleteXObjElement(...args) {
@@ -454,8 +484,8 @@ function deleteXObjElement(...args) {
  * @param {object} obj - some object
  * @param {string} name - some child element
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 function deleteXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
@@ -487,9 +517,9 @@ function deleteXObjElementEx(obj, name) {
  * @param {string} name - some child element
  * @param {string} value - new element ID
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @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
  */
 function renameXObjElement(obj, name = '', value = '') {
   if (!isPlainObject(obj)) {
@@ -532,8 +562,8 @@ function renameXObjElement(obj, name = '', value = '') {
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 function checkXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -560,8 +590,8 @@ function checkXObjAttribute(obj, attr = '', key) {
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 function deleteXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -594,10 +624,10 @@ function deleteXObjAttribute(obj, attr = '', key) {
  * @param {string} value - new attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
- * @throws {EvalKeyNameError} if forth param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ * @throws {EvalKeyNameError} if `value` param is not valid identifier
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
 function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
   if (!isPlainObject(obj)) {
@@ -647,8 +677,8 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
  * @param {object} obj - some object
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -672,8 +702,8 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
  */
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -707,8 +737,8 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {any}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 function readXObjAttrRaw(obj, attr = '', key) {
   let _obj = null;
@@ -735,8 +765,8 @@ function readXObjAttrRaw(obj, attr = '', key) {
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
   const { isSucceed, value: name } = evalKeyName(attr, false);
@@ -782,7 +812,7 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
  * @param {object} obj - some object
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjParam(obj, key) {
   const opt = {
@@ -807,7 +837,7 @@ function readXObjParam(obj, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjParamAsBool(obj, defValue, key) {
@@ -834,7 +864,7 @@ function readXObjParamAsBool(obj, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjParamAsNum(obj, defValue, key) {
@@ -861,7 +891,7 @@ function readXObjParamAsNum(obj, defValue, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
 function readXObjParamEx(obj, opt, key) {
@@ -894,7 +924,7 @@ function readXObjParamEx(obj, opt, key) {
  * @param {object} obj - some object
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjParamAsIndex(obj, key) {
   let result = undefined;
@@ -921,7 +951,7 @@ function readXObjParamAsIndex(obj, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParam(obj, value, key) {
   let isSucceed = false;
@@ -948,7 +978,7 @@ function writeXObjParam(obj, value, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsBool(obj, value, defValue, key) {
   let isSucceed = false;
@@ -979,7 +1009,7 @@ function writeXObjParamAsBool(obj, value, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsNum(obj, value, defValue, key) {
   let isSucceed = false;
@@ -1009,7 +1039,7 @@ function writeXObjParamAsNum(obj, value, defValue, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjParamAsIndex(obj, value, key) {
   let isSucceed = false;
@@ -1040,7 +1070,7 @@ function writeXObjParamAsIndex(obj, value, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
 function writeXObjParamEx(obj, value, opt, key) {
@@ -1084,7 +1114,7 @@ function writeXObjParamEx(obj, value, opt, key) {
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjAttr(obj, attr, key) {
   const opt = {
@@ -1110,7 +1140,7 @@ function readXObjAttr(obj, attr, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjAttrAsBool(obj, attr, defValue, key) {
@@ -1138,7 +1168,7 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjAttrAsNum(obj, attr, defValue, key) {
@@ -1166,7 +1196,7 @@ function readXObjAttrAsNum(obj, attr, defValue, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {string}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
 function readXObjAttrEx(obj, attr, opt, key) {
@@ -1200,7 +1230,7 @@ function readXObjAttrEx(obj, attr, opt, key) {
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function readXObjAttrAsIndex(obj, attr, key) {
   let result = undefined;
@@ -1228,7 +1258,7 @@ function readXObjAttrAsIndex(obj, attr, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttr(obj, attr, value, key) {
   let isSucceed = false;
@@ -1256,7 +1286,7 @@ function writeXObjAttr(obj, attr, value, key) {
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
   let isSucceed = false;
@@ -1288,7 +1318,7 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
   let isSucceed = false;
@@ -1319,7 +1349,7 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function writeXObjAttrAsIndex(obj, attr, value, key) {
   let isSucceed = false;
@@ -1351,7 +1381,7 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
  * @param {object} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
 function writeXObjAttrEx(obj, attr, value, opt, key) {
@@ -1395,7 +1425,8 @@ function writeXObjAttrEx(obj, attr, value, opt, key) {
  * @param {...string} name - some child element name
  * @param {OPT_inselops_L} [opt]
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
 function insertXObjElements(obj, ...args) {
   if (!isPlainObject(obj)) {
@@ -1431,7 +1462,7 @@ function insertXObjElements(obj, ...args) {
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
  * @returns {?(object|object[])}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 function insertXObjEList(...args) {
   let item = null;
@@ -1459,8 +1490,8 @@ function insertXObjEList(...args) {
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
  * @returns {RVAL_emodif}
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `nmae` param is not valid identifier
  */
 function insertXObjEListEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -1510,7 +1541,8 @@ function insertXObjEListEx(obj, name, opt) {
  * @param {...string} name - some child element name
  * @param {object} [opt] - options
  * @returns {?any}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
 function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {

package/package.json

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