@ygracs/xobj-lib-js 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+#### *v0.4.1*
+
+Release version.
+
+> - update `xObj.md`;
+> - add a new function: `insertXObjNode`;
+> - some fixes.
+
 #### *v0.4.0*
 
 Release version.

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.53|
+>|***rev.*:**|0.1.54|
 >|:---|---:|
->|date:|2026-06-08|
+>|date:|2026-07-12|
 
 ## Introduction
 
@@ -24,6 +24,8 @@ This paper describes a functions provided by `xObj.js` module.
     - <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>
+    - <a href="#func+other">other</a>
+    - <a href="#func+experimental">experimental</a>
 
 ### Base type definitions
 
@@ -885,6 +887,7 @@ The function throws a `EvalKeyNameError` exception in case:
   + if `value` parameter given and is not a type of a `string`;
   + if `key` parameter given and is not a type of a `string`.
 
+<a name="func+other"></a>
 ### Other functions
 
 <a name="getXObjElement"></a>
@@ -1234,6 +1237,7 @@ The function throws a `EvalKeyNameError` exception in case:
 - code: `ERR_XOBJ_INVARG_KEY`
   + if `name` parameter given and is an empty string.
 
+<a name="func+experimental"></a>
 ### Experimental functions
 
 > Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
@@ -1269,6 +1273,34 @@ The object `conditions` property (*if present*) contains following attributes:
 |`name`|`string`||
 |`value`|`any`||
 
+<a name="insertXObjNode"></a>
+#### **insertXObjNode(object, name)** => `null`\|`object`
+
+> since: \[v0.4.1]
+
+This function inserts an empty element named by a `name` parameter into a given object. When element exists but it is not an `object`, such element will be replaced. If succeed the element will be returned or `null` in opposite.
+
+##### ***parameters***
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `INode` | --- | 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;
+
+The function throws a `EvalKeyNameError` exception in case:
+
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+
 <a name="insertXObjElements"></a>
 #### **insertXObjElements(object, name\[...name_N\[, options]])** => `number`
 

package/index.d.ts

@@ -59,6 +59,7 @@ import {
     insertXObjElements,
     insertXObjEChain,
     clearXObjNode,
+    insertXObjNode,
 } from "./lib/xObj-lib";
 
 export {
@@ -93,6 +94,7 @@ export {
     insertXObjElements,
     insertXObjEChain,
     clearXObjNode,
+    insertXObjNode,
 };
 
 import type {

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.019-20260630]
+// [v0.1.020-20260712]
 
 // === module init block ===
 
@@ -84,4 +84,8 @@ module.exports.insertXObjEListEx = xObj.insertXObjEListEx;
 module.exports.insertXObjElements = xObj.insertXObjElements;
 module.exports.insertXObjEChain = xObj.insertXObjEChain;
 
+module.exports.clearXObjNode = xObj.clearXObjNode;
+module.exports.insertXObjNode = xObj.insertXObjNode;
+
+
 module.exports.INode = xObj.INode;

package/lib/xObj-attr.js

@@ -1,4 +1,4 @@
-// [v0.3.141-20260629]
+// [v0.3.144-20260712]
 
 // === module init block ===
 
@@ -24,7 +24,7 @@ const {
 } = require('./xObj-names');
 
 const {
-  getXObjElement, insertXObjElement,
+  getXObjElement, insertXObjNode,
   // * import types definitions *
   INode,
 } = require('./xObj-lib');
@@ -157,28 +157,32 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
     );
   };
   const opt = false;
-  const { isSucceed, value: _key } = evalKeyName(key, opt);
+  const { isSucceed, value: aKey } = 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 (aKey !== '') {
+      const aNode = obj[aKey];
+      if (isPlainObject(aNode)) {
+        const { isSucceed: isAcceptON, value: aname } = evalKeyName(attr, opt);
         if (!isAcceptON) {
-          const { code, msg } = oname;
+          const { code, msg } = aname;
           throw new EvalKeyNameError(msg, { code });
         };
-        const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+        const { isSucceed: isAcceptNN, value: vname } = evalKeyName(value, opt);
         if (!isAcceptNN) {
-          const { code, msg } = nname;
+          const { code, msg } = vname;
           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);
+        if (aname !== '' && aname in aNode && vname !== '') {
+          if (aname !== vname) {
+            const entries = Object.entries(aNode);
+            const ai = entries.findIndex((item) => item[0] === aname);
+            if (vname in aNode) {
+              const vi = entries.findIndex((item) => item[0] === vname);
+              if (ai < vi) entries[vi][1] = entries[ai][1];
+            };
+            entries[ai][0] = vname;
+            obj[aKey] = Object.fromEntries(entries);
           };
           isSucceed = true;
         };
@@ -186,7 +190,7 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
     };
     return isSucceed;
   } else {
-    const { code, msg } = _key;
+    const { code, msg } = aKey;
     throw new EvalKeyNameError(msg, { code });
   };
 };
@@ -243,24 +247,22 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
       && !isObject(value)
       && typeof value !== 'function'
     ) {
-      let _obj = null;
+      let node = null;
       try {
-        const opt = { force: true, acceptIfList: true };
-        _obj = insertXObjElement(obj, key, opt);
+        node = insertXObjNode(obj, key);
       } 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;
+        switch (err.code) {
+          case XOBJ_TE_NSTR_ECODE :
+          case XOBJ_TE_KNES_ECODE : {
+            break;
+          }
+          default: {
+            throw err;
+          }
         };
       };
-      if (_obj !== null) {
-        _obj[name] = value;
+      if (node !== null) {
+        node[name] = value;
         isSucceed = true;
       };
     };

package/lib/xObj-lib.d.ts

@@ -176,6 +176,15 @@ export function insertXObjEChain(obj: INode, ...args: insertListOfElementsParams
  * @throws {TypeError} if `node`-param is not an object or array
  */
 export function clearXObjNode(node: INode | INode[]): boolean;
+/**
+ * Inserts an element addressed by its key into a given object. If it exists
+ * and it is not an `object` a function forces an element replacement.
+ * @since 0.4.1
+ * @experimental
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
+ */
+export function insertXObjNode(obj: INode, name: string): INode | null;
 /**
  * Inserts an elements into a given object.
  * @throws {TypeError} if `obj` param is not an object

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.144-20260704]
+// [v0.3.146-20260712]
 
 // === module init block ===
 
@@ -627,6 +627,38 @@ function clearXObjNode(node) {
 };
 module.exports.clearXObjNode = clearXObjNode;
 
+/**
+ * Inserts an element addressed by its key into a given object. If it exists
+ * and it is not an `object` a function forces an element replacement.
+ * @since 0.4.1
+ * @param {INode} obj - some object
+ * @param {string} name - some child element
+ * @returns {?INode}
+ * @experimental
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
+ */
+function insertXObjNode(obj, name) {
+  if (!isPlainObject(obj)) {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
+  };
+  const { isSucceed, value: key } = evalKeyName(name);
+  if (isSucceed) {
+    /** @type {?INode} */
+    const item = {};
+    let prop = obj[key];
+    if (!isPlainObject(prop)) prop = obj[key] = item;
+    return prop;
+  } else {
+    const { code, msg } = key;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.insertXObjNode = insertXObjNode;
+
 // === module exports block ===
 
 // * experimental *

package/package.json

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