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

package/CHANGELOG.md

@@ -6,7 +6,10 @@ Release version.
 > - 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.47|
+>|***rev.*:**|0.1.48|
 >|:---|---:|
->|date:|2026-02-14|
+>|date:|2026-02-22|
 
 ## Introduction
 
@@ -19,6 +19,10 @@ This paper describes a functions provided by `xObj.js` module.
     - <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
 
@@ -135,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:
@@ -259,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:
@@ -384,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:
@@ -513,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:
@@ -1048,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>
@@ -1233,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**
 

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.068-20260203]
+// [v0.1.070-20260221]
 
 // === module init block ===
 
@@ -143,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

@@ -110,6 +110,11 @@ 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

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.120-20260213]
+// [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 {
@@ -806,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;
@@ -832,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;
@@ -874,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);
 };
@@ -1043,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, {
@@ -1109,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;
@@ -1136,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;
@@ -1179,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);
 };
@@ -1354,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, {
@@ -1539,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.1",
+  "version": "0.2.9-b.2",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",