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

package/CHANGELOG.md

@@ -5,7 +5,11 @@ Release version.
 > - update `xObj.md`;
 > - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
 > - 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 `EvalKeyNameError` class;
+> - add new `compact`-property for `TXmlContentParseOptions`;
 > - some fixes.
 
 #### *v0.2.4*

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.46|
+>|***rev.*:**|0.1.48|
 >|:---|---:|
->|date:|2025-12-14|
+>|date:|2026-02-22|
 
 ## Introduction
 
@@ -10,6 +10,20 @@ This paper describes a functions provided by `xObj.js` module.
 
 ## Content
 
+- Base types
+    - <a href="#typedef+xml2jsParseOptions">xml2jsParseOptions</a>
+    - <a href="#typedef+js2xmlParseOptions">js2xmlParseOptions</a>
+
+- Classes
+    - <a href="#TXmlContentParseOptions">TXmlContentParseOptions</a>
+    - <a href="#EvalKeyNameError">EvalKeyNameError</a>
+
+- Functions
+    - <a href="#func+attribute+read">read element attributes</a>
+    - <a href="#func+attribute+write">write element attributes</a>
+    - <a href="#func+param+read">read element parameter</a>
+    - <a href="#func+param+write">write element parameter</a>
+
 ### Base type definitions
 
 This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function descriptions.
@@ -116,10 +130,8 @@ The settings listed in the table below:
 | `elementsKey` | `string` | `items` ||
 | `ignoreDeclaration` | `boolean` | `false` ||
 | `ignoreDocType` | `boolean` | `false` ||
-| `ignoreInstractions` | `boolean` | `false` | \<*deprecated*> (*use `ignoreInstraction` instead*) |
 | `ignoreInstraction` | `boolean` | `false` ||
 | `ignoreText` | `boolean` | `false` ||
-| `ignoreComments` | `boolean` | `false` | \<*deprecated*> (*use `ignoreComment` instead*) |
 | `ignoreComment` | `boolean` | `false` ||
 | `ignoreCData` | `boolean` | `false` ||
 | `fullTagEmptyElement` | `boolean` | `true` ||
@@ -127,6 +139,7 @@ The settings listed in the table below:
 | `trim` | `boolean` | `true` ||
 | `spaces` | `number` | `2` ||
 
+<a name="func+param+read"></a>
 ### Base functions for read an object parameter value
 
 > Note:
@@ -251,6 +264,7 @@ The function throws a `TypeError` exception in case:
 - code: `ERR_XOBJ_NPOBJ`
   + if `object` parameter is not an `Object` instance.
 
+<a name="func+param+write"></a>
 ### Base functions for write an object parameter value
 
 > Note:
@@ -376,6 +390,7 @@ The function throws a `TypeError` exception in case:
 - code: `ERR_XOBJ_NPOBJ`
   + if `object` parameter is not an `Object` instance.
 
+<a name="func+attribute+read"></a>
 ### Base functions for read an object attributes value
 
 > Note:
@@ -505,6 +520,7 @@ The function throws a `TypeError` exception in case:
 - code: `ERR_XOBJ_NPOBJ`
   + if `object` parameter is not an `Object` instance.
 
+<a name="func+attribute+write"></a>
 ### Base functions for write an object attributes value
 
 > Note:
@@ -1040,6 +1056,26 @@ The function throws a `TypeError` exception in case:
   + if `name` parameter given and is not a type of a `string`;
   + id `value` parameter given and is not a type of a `string`.
 
+<a name="clearXObjNode"></a>
+#### **clearXObjNode(node)** => `boolean`
+
+> since: \[v0.2.x]
+
+This function tries to clean a given node.
+
+##### ***parameters***
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `node` | `object` or `object[]` | --- | some node |
+
+##### ***exceptions***
+
+The function throws a `TypeError` exception in case:
+
+- code: `ERR_XOBJ_NPOBJ`
+  + if `node` parameter is not an `Object` or `Array` instance;
+
 ### Other special functions
 
 <a name="evalXObjEName"></a>
@@ -1214,7 +1250,7 @@ The class constructor receives an arguments listed below:
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `options` | `object` | --- | an options settings |
+| `options` | `object` | --- | some initial options settings |
 
 ##### class properties
 
@@ -1225,6 +1261,15 @@ The class constructor receives an arguments listed below:
 |---|---|:---|
 | `object` | yes | contains a current options |
 
+<a name="TXmlContentParseOptions+compact"></a>
+###### **compact**
+
+> since: \[v0.2.x]
+
+| property type | read only | description |
+|---|---|:---|
+| `boolean` | yes | returns a current value for a `compact`-options |
+
 <a name="TXmlContentParseOptions+xml2js"></a>
 ###### **xml2js**
 
@@ -1232,6 +1277,8 @@ The class constructor receives an arguments listed below:
 |---|---|:---|
 | `xml2jsParseOptions` | yes | returns an options for an XML-to-JS converter |
 
+for more details see [`xml2jsParseOptions`](#typedef+xml2jsParseOptions).
+
 <a name="TXmlContentParseOptions+js2xml"></a>
 ###### **js2xml**
 
@@ -1239,12 +1286,14 @@ The class constructor receives an arguments listed below:
 |---|---|:---|
 | `js2xmlParseOptions` | yes | returns an options for a JS-to-XML converter |
 
+for more details see [`js2xmlParseOptions`](#typedef+js2xmlParseOptions).
+
 <a name="TXmlContentParseOptions+reservedKeys"></a>
 ###### **reservedKeys**
 
 | property type | read only | description |
 |---|---|:---|
-| `Set<string>` | yes | returns a set of the reserved key words those must not be used as an element names  |
+| `Set<string>` | yes | returns a set of the reserved key words those must not be used as an element names |
 
 ##### class methods (*static*)
 
@@ -1252,3 +1301,47 @@ The class constructor receives an arguments listed below:
 ###### **createNewOptionsSet(obj)** => `object`
 
 This method transforms a given object to a set of accepted parser options.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `object` | --- | some initial options settings |
+
+### Special class
+
+<a name="EvalKeyNameError"></a>
+#### **EvalKeyNameError**
+
+> since: \[v0.2.x]
+
+This class extends a functionality of a `TypeError`-object to provide more accurate information when an error happened through a key evaluation.
+
+> NOTE: the class is in a `beta`-stage.
+
+#### class constructor
+
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `msg` | `string` | --- | some user error message |
+| `options` | `any` | --- | user options |
+
+#### class properties
+
+<a name="EvalKeyNameError+name"></a>
+##### **name**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | represents the name for the type of error |
+
+<a name="EvalKeyNameError+code"></a>
+##### **code**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | represents an error code |

package/index.d.ts

@@ -41,6 +41,7 @@ declare const _exports: {
     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;

package/lib/xObj-defs.d.ts

@@ -96,6 +96,10 @@ export class TXmlContentParseOptions {
      * Contains a set of a current settings
      */
     get settings(): OPT_parserOptions;
+    /**
+     * Returns a value of `compact` option
+     */
+    get compact(): boolean;
     /**
      * Contains a set of a settings for converting an 'XML' to 'JS'-object
      */

package/lib/xObj-defs.js

@@ -1,4 +1,4 @@
-// [v0.1.067-20260101]
+// [v0.1.070-20260221]
 
 // === module init block ===
 
@@ -10,10 +10,6 @@ const {
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
 const XOBJ_DEF_PARAM_TNAME = '__text';
 const XOBJ_DEF_ATTR_TNAME = '__attr';
 const XOBJ_DEF_DECL_TNAME = '__decl';
@@ -25,8 +21,6 @@ const XOBJ_DEF_TNAMES = {
   XOBJ_DEF_DECL_TNAME,
   XOBJ_DEF_CDATA_TNAME,
 };
-//module.exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
-//module.exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
 module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;
 
 /**
@@ -68,12 +62,8 @@ const DEF_XML_PARSE_OPTIONS = {
   elementsKey: 'items',
   ignoreDeclaration: false,
   ignoreDocType: false,
-  /** @deprecated */
-  ignoreInstractions: false,
   ignoreInstraction: false,
   ignoreText: false,
-  /** @deprecated */
-  ignoreComments: false,
   ignoreComment: false,
   ignoreCData: false,
   fullTagEmptyElement: true,
@@ -83,14 +73,6 @@ const DEF_XML_PARSE_OPTIONS = {
 };
 module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
 
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
 /**
  * A parser options to convert an 'XML'-string into a 'JS'-object
  * @typedef {Object} xml2jsParseOptions
@@ -161,6 +143,15 @@ class TXmlContentParseOptions {
     return this.#_options;
   }
 
+  /**
+   * Returns a value of `compact` option
+   * @since 0.2.x
+   * @type {boolean}
+   */
+  get compact() {
+    return this.#_options.compact ? true : false;
+  }
+
   /**
    * Contains a set of a settings for converting an 'XML' to 'JS'-object
    * @type {xml2jsParseOptions}

package/lib/xObj-errors.js

@@ -1,4 +1,4 @@
-// [v0.1.003-20251229]
+// [v0.1.004-20260221]
 
 // === module init block ===
 
@@ -41,6 +41,7 @@ const XOBJ_ECODE_TABLE = {
 module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
 
 /**
+ * @since 0.2.x
  * @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

@@ -1,3 +1,4 @@
+import type { EvalKeyNameError } from "./xObj-errors";
 /**
  * A result of a value check ops.
  */
@@ -109,10 +110,15 @@ export type OPT_inselops_S = {
     ripOldies?: boolean;
 };
 
+/**
+ * Clears a given node
+ * @throws {TypeError} if `node`-param is not an object or array
+ */
+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 {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 export function readXObjParamRaw(obj: object, key?: string): any;
 /**
@@ -144,7 +150,7 @@ 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 {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if third param is not valid identifier
  */
 export function writeXObjParamRaw(obj: object, value: any, key?: string): boolean;
 /**
@@ -181,7 +187,7 @@ export function writeXObjParamEx(obj: object, value: any, opt?: object, key?: st
 /**
  * Extracts an attribute 'AS IS' from a given object.
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 export function readXObjAttrRaw(obj: object, attr?: string, key?: string): any;
 /**
@@ -214,7 +220,7 @@ export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): nu
 /**
  * Writes a parameter into a given object.
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 export function writeXObjAttrRaw(obj: object, attr: string, value: any, key?: string): boolean;
 /**
@@ -256,67 +262,68 @@ 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
  */
 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
  */
 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 {TypeError} if second param is not an object
- * @throws {TypeError} if third 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
  */
 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 {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second 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 {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 export function addXObjElement(obj: object, name: string): RVAL_emodif;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if first param is not an object
- * @see insertXObjElementEx
+ * @see {@link insertXObjElementEx} for param details
  */
 export function insertXObjElement(...args: insertXObjElementParams): object | null;
 type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
-//export function insertXObjElement(...args: [obj: object, name: string, opt?: OPT_inselops_L]): object | null;
 /**
  * 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 {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second 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
- * @see deleteXObjElementEx
+ * @see {@link deleteXObjElementEx} for param details
  */
 export function deleteXObjElement(...args: deleteXObjElementParams): boolean;
 type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
-//export function deleteXObjElement(...args: [obj: object, name: string]): boolean;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second 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 {TypeError} if second param is not a string
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {EvalKeyNameError} if third param is not valid identifier
  */
 export function renameXObjElement(obj: object, name?: string, value?: string): boolean;
 /**
@@ -330,12 +337,11 @@ export function evalXObjEName(value: any): null | number | string;
  */
 export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
 type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
-//export function insertXObjEList(...args: [obj: object, name: string, opt?: OPT_inselops_S]): object | object[] | null;
 /**
  * Inserts a list elements into a given object.
  * @since 0.2.0
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 export function insertXObjEListEx(obj: object, name: string, opt?: OPT_inselops_S): RVAL_emodif;
 /**

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.114-20260131]
+// [v0.3.127-20260222]
 
 // === module init block ===
 
@@ -8,6 +8,8 @@ const {
   isNullOrUndef,
   isInteger,
   isArray, isObject, isPlainObject,
+  // * import types definitions *
+  OPT_valtostr,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
@@ -235,7 +237,7 @@ function genXObjENameDescr(value) {
  * @param {string} name - some child element
  * @returns {?any}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function getXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
@@ -293,7 +295,7 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
  * @param {string} name - some child element
  * @returns {RVAL_emodif}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function addXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
@@ -346,7 +348,7 @@ function addXObjElement(obj, name) {
  * @param {OPT_inselops_L} [opt] - options
  * @returns {?object}
  * @throws {TypeError} if first param is not an object
- * @see insertXObjElementEx
+ * @see {@link insertXObjElementEx} for param details
  */
 function insertXObjElement(...args) {
   let item = null;
@@ -375,7 +377,7 @@ function insertXObjElement(...args) {
  * @param {OPT_inselops_L} [opt] - options
  * @returns {RVAL_emodif}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -426,7 +428,7 @@ function insertXObjElementEx(obj, name, opt) {
  * @param {string} name - some child element
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
- * @see deleteXObjElementEx
+ * @see {@link deleteXObjElementEx} for param details
  */
 function deleteXObjElement(...args) {
   let isSucceed = false;
@@ -453,7 +455,7 @@ function deleteXObjElement(...args) {
  * @param {string} name - some child element
  * @returns {RVAL_emodif}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function deleteXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
@@ -486,8 +488,8 @@ function deleteXObjElementEx(obj, name) {
  * @param {string} value - new element ID
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is not a string
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {EvalKeyNameError} if third param is not valid identifier
  */
 function renameXObjElement(obj, name = '', value = '') {
   if (!isPlainObject(obj)) {
@@ -531,6 +533,7 @@ function renameXObjElement(obj, name = '', value = '') {
  * @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
  */
 function checkXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -558,6 +561,7 @@ function checkXObjAttribute(obj, attr = '', key) {
  * @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
  */
 function deleteXObjAttribute(obj, attr = '', key) {
   let _obj = null;
@@ -591,8 +595,9 @@ function deleteXObjAttribute(obj, attr = '', key) {
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is not an object
- * @throws {TypeError} if third 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
  */
 function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
   if (!isPlainObject(obj)) {
@@ -602,37 +607,38 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
     );
   };
   const opt = false;
-  let { isSucceed, value: _key } = evalKeyName(key, opt);
-  if (!isSucceed) {
-    const { code, msg } = _key;
-    throw new EvalKeyNameError(msg, { code });
-  };
-  isSucceed = false;
-  if (_key !== '') {
-    let _obj = obj[_key];
-    if (isPlainObject(_obj)) {
-      const { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
-      if (!isAcceptON) {
-        const { code, msg } = oname;
-        throw new EvalKeyNameError(msg, { code });
-      };
-      const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
-      if (!isAcceptNN) {
-        const { code, msg } = nname;
-        throw new EvalKeyNameError(msg, { code });
-      };
-      if (oname !== '' && oname in _obj && nname !== '') {
-        if (oname !== nname) {
-          _obj = Object.entries(_obj);
-          const index = _obj.findIndex((item) => item[0] === oname);
-          _obj[index][0] = nname;
-          obj[_key] = Object.fromEntries(_obj);
+  const { isSucceed, value: _key } = evalKeyName(key, opt);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (_key !== '') {
+      let _obj = obj[_key];
+      if (isPlainObject(_obj)) {
+        const { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
+        if (!isAcceptON) {
+          const { code, msg } = oname;
+          throw new EvalKeyNameError(msg, { code });
+        };
+        const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+        if (!isAcceptNN) {
+          const { code, msg } = nname;
+          throw new EvalKeyNameError(msg, { code });
+        };
+        if (oname !== '' && oname in _obj && nname !== '') {
+          if (oname !== nname) {
+            _obj = Object.entries(_obj);
+            const index = _obj.findIndex((item) => item[0] === oname);
+            _obj[index][0] = nname;
+            obj[_key] = Object.fromEntries(_obj);
+          };
+          isSucceed = true;
         };
-        isSucceed = true;
       };
     };
+    return isSucceed;
+  } else {
+    const { code, msg } = _key;
+    throw new EvalKeyNameError(msg, { code });
   };
-  return isSucceed;
 };
 
 /**
@@ -642,7 +648,7 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {any}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -667,7 +673,7 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if third param is not valid identifier
  */
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
@@ -676,17 +682,22 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: _key } = evalKeyName(key, false);
-  if (!isSucceed) {
+  const { isSucceed, value: _key } = evalKeyName(key, false);
+  if (isSucceed) {
+    if (
+      _key === ''
+      || value === undefined
+      || isObject(value)
+      || typeof value === 'function'
+    ) {
+      return false;
+    };
+    obj[_key] = value;
+    return true;
+  } else {
     const { code, msg } = _key;
     throw new EvalKeyNameError(msg, { code });
   };
-  if (_key === '' || value === undefined) {
-    isSucceed = false;
-  } else {
-    obj[_key] = value;
-  };
-  return isSucceed;
 };
 
 /**
@@ -697,7 +708,7 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
  * @param {string} [key] - some key
  * @returns {any}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function readXObjAttrRaw(obj, attr = '', key) {
   let _obj = null;
@@ -725,38 +736,44 @@ function readXObjAttrRaw(obj, attr = '', key) {
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
-  let { isSucceed, value: name } = evalKeyName(attr, false);
-  if (!isSucceed) {
-    const { code, msg } = name;
-    throw new EvalKeyNameError(msg, { code });
-  };
-  isSucceed = false;
-  if (name !== '' && value !== undefined) {
-    let _obj = null;
-    try {
-      const opt = { force: true, acceptIfList: true };
-      _obj = insertXObjElement(obj, key, opt);
-    } catch (err) {
-      throw err;
-    };
-    if (isArray(_obj)) {
-      // force a replacement of the old element if it's array
+  const { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (
+      name !== ''
+      && value !== undefined
+      && !isObject(value)
+      && typeof value !== 'function'
+    ) {
+      let _obj = null;
       try {
-        const opt = { force: true, ripOldies: true };
+        const opt = { force: true, acceptIfList: true };
         _obj = insertXObjElement(obj, key, opt);
       } catch (err) {
         throw err;
       };
+      if (isArray(_obj)) {
+        // force a replacement of the old element if it's array
+        try {
+          const opt = { force: true, ripOldies: true };
+          _obj = insertXObjElement(obj, key, opt);
+        } catch (err) {
+          throw err;
+        };
+      };
+      if (_obj !== null) {
+        _obj[name] = value;
+        isSucceed = true;
+      };
     };
-    if (_obj !== null) {
-      _obj[name] = value;
-      isSucceed = true;
-    };
+    return isSucceed;
+  } else {
+    const { code, msg } = name;
+    throw new EvalKeyNameError(msg, { code });
   };
-  return isSucceed;
 };
 
 /**
@@ -791,6 +808,7 @@ function readXObjParam(obj, key) {
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
+ * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjParamAsBool(obj, defValue, key) {
   let result = undefined;
@@ -817,6 +835,7 @@ function readXObjParamAsBool(obj, defValue, key) {
  * @param {string} [key] - some key
  * @returns {number}
  * @throws {TypeError} if first param is not an object
+ * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjParamAsNum(obj, defValue, key) {
   let result = undefined;
@@ -859,14 +878,12 @@ function readXObjParamEx(obj, opt, key) {
       }
     };
   };
-  let _opt = opt;
-  if (!isPlainObject(_opt)) {
-    _opt = {
-      useTrim: false,
-      numberToString: true,
-      boolToString: true,
-      defValue: _opt,
-    };
+  /** @type {OPT_valtostr} */
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
   };
   return readAsString(result, _opt);
 };
@@ -1028,7 +1045,7 @@ function writeXObjParamAsIndex(obj, value, key) {
  */
 function writeXObjParamEx(obj, value, opt, key) {
   let isSucceed = false;
-  if (value !== undefined) {
+  if (value !== undefined && typeof value !== 'function') {
     let _opt = opt;
     if (!isPlainObject(_opt)) {
       const defValue = readAsString(_opt, {
@@ -1094,6 +1111,7 @@ function readXObjAttr(obj, attr, key) {
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if first param is not an object
+ * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjAttrAsBool(obj, attr, defValue, key) {
   let result = undefined;
@@ -1121,6 +1139,7 @@ function readXObjAttrAsBool(obj, attr, defValue, key) {
  * @param {string} [key] - some key
  * @returns {number}
  * @throws {TypeError} if first param is not an object
+ * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
  */
 function readXObjAttrAsNum(obj, attr, defValue, key) {
   let result = undefined;
@@ -1164,14 +1183,12 @@ function readXObjAttrEx(obj, attr, opt, key) {
       }
     };
   };
-  let _opt = opt;
-  if (!isPlainObject(_opt)) {
-    _opt = {
-      useTrim: true,
-      numberToString: true,
-      boolToString: true,
-      defValue: _opt,
-    };
+  /** @type {OPT_valtostr} */
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
   };
   return readAsString(result, _opt);
 };
@@ -1339,7 +1356,7 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
  */
 function writeXObjAttrEx(obj, attr, value, opt, key) {
   let isSucceed = false;
-  if (value !== undefined) {
+  if (value !== undefined && typeof value !== 'function') {
     let _opt = opt;
     if (!isPlainObject(_opt)) {
       const defValue = readAsString(_opt, {
@@ -1443,7 +1460,7 @@ function insertXObjEList(...args) {
  * @param {OPT_inselops_S} [opt] - options
  * @returns {RVAL_emodif}
  * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
+ * @throws {EvalKeyNameError} if second param is not valid identifier
  */
 function insertXObjEListEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
@@ -1524,9 +1541,32 @@ function insertXObjEChain(obj, ...args) {
   return result;
 };
 
-/***
- * (* class definitions *)
+/**
+ * Clears a given node
+ * @param {(object|object[])} node - some node
+ * @returns {boolean}
+ * @throws {TypeError} if `node`-param is not an object or array
  */
+function clearXObjNode(node) {
+  if (isObject(node)) {
+    if (isArray(node)) {
+      node.length = 0;
+      return true;
+    };
+    let isSucceed = false;
+    for (const key in node) {
+      // // TODO: catch errors in strict mode
+      isSucceed = delete node[key];
+    };
+    return isSucceed;
+  } else {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
+  };
+};
+module.exports.clearXObjNode = clearXObjNode;
 
 // === module exports block ===
 

package/package.json

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