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

package/CHANGELOG.md

@@ -1,12 +1,16 @@
-#### *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: `addXObjElementEx`, `clearXObjNode`;
 > - add a new `EvalKeyNameError` class;
+> - add new `compact`-property for `TXmlContentParseOptions`;
 > - some fixes.
 
 #### *v0.2.4*

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.47|
+>|***rev.*:**|0.1.51|
 >|:---|---:|
->|date:|2026-02-14|
+>|date:|2026-02-28|
 
 ## 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:
@@ -878,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***
@@ -1048,6 +1077,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 +1282,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

@@ -1,78 +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;
-
-    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 {
     /**
@@ -96,6 +96,11 @@ export class TXmlContentParseOptions {
      * Contains a set of a current settings
      */
     get settings(): OPT_parserOptions;
+    /**
+     * Returns a value of `compact` option
+     * @since 0.3.0
+     */
+    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-20260227]
 
 // === module init block ===
 
@@ -143,6 +143,15 @@ class TXmlContentParseOptions {
     return this.#_options;
   }
 
+  /**
+   * Returns a value of `compact` option
+   * @since 0.3.0
+   * @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.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.003-20251229]
+// [v0.1.004-20260227]
 
 // === module init block ===
 
@@ -41,6 +41,7 @@ const XOBJ_ECODE_TABLE = {
 module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
 
 /**
+ * @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