@ygracs/xobj-lib-js 0.3.3 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+#### *v0.4.1*
+
+Release version.
+
+> - update `xObj.md`;
+> - add a new function: `insertXObjNode`;
+> - some fixes.
+
+#### *v0.4.0*
+
+Release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.4.0;
+> - some fixes.
+
 #### *v0.3.3*
 
 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

@@ -1,6 +1,9 @@
 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";
+import { evalXObjEName } from "./lib/xObj-names";
+import { genXObjENameDescr } from "./lib/xObj-names";
 
 export {
     TXmlContentParseOptions,
@@ -8,6 +11,8 @@ export {
     XOBJ_DEF_TNAMES,
 };
 
+export { EvalKeyNameError };
+
 import type {
     xml2jsParseOptions, js2xmlParseOptions,
     OPT_parserOptions,
@@ -18,10 +23,6 @@ export type {
     OPT_parserOptions,
 };
 
-import { EvalKeyNameError } from "./lib/xObj-errors";
-
-export { EvalKeyNameError };
-
 import {
     readXObjAttrRaw,
     readXObjAttr,
@@ -55,12 +56,10 @@ import {
     deleteXObjElement, deleteXObjElementEx,
     renameXObjElement,
     insertXObjEList, insertXObjEListEx,
-    evalXObjEName,
-    evalKeyName,
-    genXObjENameDescr,
     insertXObjElements,
     insertXObjEChain,
     clearXObjNode,
+    insertXObjNode,
 } from "./lib/xObj-lib";
 
 export {
@@ -91,27 +90,26 @@ export {
     renameXObjElement,
     insertXObjEList, insertXObjEListEx,
     evalXObjEName,
-    evalKeyName,
     genXObjENameDescr,
     insertXObjElements,
     insertXObjEChain,
     clearXObjNode,
+    insertXObjNode,
 };
 
 import type {
-    XObjENameDescr, XObjENameDescrConditions,
-    OPT_inselops_L, OPT_inselops_S,
-    RVAL_emodif,
-    VCOR_evalkname, RVAL_reason,
+    IXObjENameDescr, IXObjENameDescrConditions,
     IEvalKeyNameResult,
+} from "./lib/xObj-names";
+
+import type {
+    OPT_inselops_L, OPT_inselops_S,
     INode,
 } from "./lib/xObj-lib";
 
 export type {
-    XObjENameDescr, XObjENameDescrConditions,
+    IXObjENameDescr, IXObjENameDescrConditions,
     OPT_inselops_L, OPT_inselops_S,
-    RVAL_emodif,
-    VCOR_evalkname, RVAL_reason,
     IEvalKeyNameResult,
     INode,
 };

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.017-20260606]
+// [v0.1.020-20260712]
 
 // === module init block ===
 
@@ -12,6 +12,11 @@ const {
   EvalKeyNameError,
 } = require('./lib/xObj-errors');
 
+const {
+  evalXObjEName,
+  genXObjENameDescr,
+} = require('./lib/xObj-names');
+
 const xObjAttr = require('./lib/xObj-attr');
 
 const xObjParam = require('./lib/xObj-param');
@@ -30,6 +35,9 @@ module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;
 
 module.exports.EvalKeyNameError = EvalKeyNameError;
 
+module.exports.evalXObjEName = evalXObjEName;
+module.exports.genXObjENameDescr = genXObjENameDescr;
+
 module.exports.readXObjParamRaw = xObjParam.readXObjParamRaw;
 module.exports.readXObjParam = xObjParam.readXObjParam;
 module.exports.readXObjParamAsBool = xObjParam.readXObjParamAsBool;
@@ -70,12 +78,14 @@ 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;
 
+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.140-20260607]
+// [v0.3.144-20260712]
 
 // === module init block ===
 
@@ -21,7 +21,10 @@ const {
 
 const {
   evalKeyName,
-  getXObjElement, insertXObjElement,
+} = require('./xObj-names');
+
+const {
+  getXObjElement, insertXObjNode,
   // * import types definitions *
   INode,
 } = require('./xObj-lib');
@@ -154,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;
         };
@@ -183,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 });
   };
 };
@@ -240,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

@@ -1,196 +1,102 @@
 /**
- * A result of `evalKeyName` function
+ * A `Node`-element
+ * @since 0.3.2
  */
-export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
-export const IEvalKeyNameResult: IEvalKeyNameResult;
 export type INode = {
     [x: string]: any;
 };
 export const INode: INode;
 /**
- * A result of an xObj modification ops
- */
-export type INodeModifResult = INodeModifResultOnFail | INodeModifResultOnSuccess;
-export const INodeModifResult: INodeModifResult;
-/**
- * Some conditions applied to an element as a result of an element name pattern
- * evaluation ops.
- */
-export type XObjENameDescrConditions = {
-    /**
-     * - element name
-     */
-    name: any;
-    /**
-     * - element type
-     */
-    type: any;
-    /**
-     * - some value
-     */
-    value?: any;
-};
-/**
- * A result of an element name pattern evaluation ops.
+ * A result of an xObj modification ops if failed
  */
-export type XObjENameDescr = {
-    /**
-     * - ops flag
-     */
-    isERR: boolean;
+export type INodeModifResultOnFail = {
     /**
-     * - element name
+     * - flag that indicates whether an ops is succeed or not
      */
-    name: null | number | string;
+    isSucceed: false;
     /**
-     * - some conditions applied to an element
+     * - some element as a result
      */
-    conditions: XObjENameDescrConditions | null;
-};
-/**
- * A list of a `INode`-elements
- */
-export type INodeList = INode[];
-/**
- * An options for an element insertion ops
- */
-export type OPT_inselops_L = {
-    force?: boolean;
-    ripOldies?: boolean;
-    acceptIfList?: boolean;
-};
-/**
- * An options for an element insertion ops
- */
-export type OPT_inselops_S = {
-    force?: boolean;
-    ripOldies?: boolean;
+    item: null;
 };
+export const INodeModifResultOnFail: INodeModifResultOnFail;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type RVAL_reason = {
+export type INodeModifResultOnSuccess_S1 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: INode;
 };
+export const INodeModifResultOnSuccess_S1: INodeModifResultOnSuccess_S1;
 /**
- * An error description of a value check ops on fail.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type IEvalKeyNameReasonOnFail = {
+export type INodeModifResultOnSuccess_S2 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: INode[];
 };
+export const INodeModifResultOnSuccess_S2: INodeModifResultOnSuccess_S2;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
+ * A result of an xObj modification ops if succeed (when child element not returned)
  */
-export type VCOR_evalkname = {
+export type INodeModifResultOnSuccess_S0 = {
     /**
-     * - ops flag
+     * - flag that indicates whether an ops is succeed or not
      */
-    isSucceed: boolean;
+    isSucceed: true;
     /**
-     * - result value or reson if failed
+     * - some element as a result
      */
-    value: string | IEvalKeyNameReasonOnFail;
+    item: null;
 };
+export const INodeModifResultOnSuccess_S0: INodeModifResultOnSuccess_S0;
 /**
- * An options setting for `evalKeyName` function
+ * A list of a `Node`-elements
  */
-export type IEvalKeyNameOptions = {
-    /**
-     * - a flag to accept only a non-empty string values
-     */
-    onlyNES?: boolean;
-};
+export type INodeList = INode[];
 /**
- * A result of `evalKeyName` function if succeed
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type IEvalKeyNameResultOnSuccess = {
-    /**
-     * - ops flag
-     */
-    isSucceed: true;
-    /**
-     * - result value
-     */
-    value: string;
-};
+export type IAddNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1;
 /**
- * A result of `evalKeyName` function if failed
+ * An options for an element insertion ops
  */
-export type IEvalKeyNameResultOnFail = {
-    /**
-     * - ops flag
-     */
-    isSucceed: false;
-    /**
-     * - reason of fail
-     */
-    value: IEvalKeyNameReasonOnFail;
+export type OPT_inselops_L = {
+    force?: boolean;
+    ripOldies?: boolean;
+    acceptIfList?: boolean;
 };
 /**
  * A result of an xObj modification ops
- * @deprecated
- * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
+ * @since 0.4.0
  */
-export type RVAL_emodif = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: boolean;
-    /**
-     * - some element as a result
-     */
-    item: object | object[] | null;
-};
+export type IInsertNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if failed
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type INodeModifResultOnFail = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: false;
-    /**
-     * - some element as a result
-     */
-    item: null;
-};
+export type IDeleteNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S0 | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if succeed
+ * An options for an element insertion ops
  */
-export type INodeModifResultOnSuccess = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: true;
-    /**
-     * - some element as a result
-     */
-    item: object | object[];
+export type OPT_inselops_S = {
+    force?: boolean;
+    ripOldies?: boolean;
 };
 
-/**
- * Tries to convert a value into an ID.
- * @inner
- */
-export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
 /**
  * Extracts an element from a given object by its key.
  * @throws {TypeError} if `obj` param is not an object
@@ -202,7 +108,7 @@ export function getXObjElement(obj: INode, name: string): any | null;
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link addXObjElementEx} for param details
  */
-export function addXObjElement(...args: addXObjElementParams): object | null;
+export function addXObjElement(...args: addXObjElementParams): INode | null;
 type addXObjElementParams = Parameters<typeof addXObjElementEx>;
 /**
  * Adds an element addressed by its key to a given object.
@@ -210,13 +116,13 @@ type addXObjElementParams = Parameters<typeof addXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function addXObjElementEx(obj: INode, name: string): INodeModifResult;
+export function addXObjElementEx(obj: INode, name: string): IAddNodeResult;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
-export function insertXObjElement(...args: insertXObjElementParams): object | null;
+export function insertXObjElement(...args: insertXObjElementParams): INode | INode[] | null;
 type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
@@ -224,7 +130,7 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): INodeModifResult;
+export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): IInsertNodeResult;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -237,7 +143,7 @@ type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
+export function deleteXObjElementEx(obj: INode, name: string): IDeleteNodeResult;
 /**
  * Renames an element addressed by its key.
  * @throws {TypeError} if `obj` param is not an object
@@ -245,21 +151,12 @@ export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
  * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
 export function renameXObjElement(obj: INode, name?: string, value?: string): boolean;
-/**
- * Clears a given node
- * @throws {TypeError} if `node`-param is not an object or array
- */
-export function clearXObjNode(node: INode | INode[]): boolean;
-/**
- * Tries to convert a value into an ID.
- */
-export function evalXObjEName(value: any): null | number | string;
 /**
  * Inserts a list elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see insertXObjEListEx
  */
-export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
+export function insertXObjEList(...args: insertXObjEListParams): INode[] | null;
 type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * Inserts a list elements into a given object.
@@ -267,18 +164,31 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResult;
+export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResultOnFail | INodeModifResultOnSuccess_S2;
 /**
- * Tries to convert a value into an element name description.
+ * Inserts a chain of an elements into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function genXObjENameDescr(value: any): XObjENameDescr;
+export function insertXObjEChain(obj: INode, ...args: insertListOfElementsParams): any | null;
 /**
- * Inserts an elements into a given object.
+ * Clears a given node
+ * @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 insertXObjElements(obj: object, ...args: any[]): number;
+export function insertXObjNode(obj: INode, name: string): INode | null;
 /**
- * Inserts a chain of an elements into a given object.
+ * Inserts an elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function insertXObjEChain(obj: object, ...args: any[]): any | null;
+export function insertXObjElements(obj: INode, ...args: insertListOfElementsParams): number;
+type insertListOfElementsParams = [ ...names: string[], options: OPT_inselops_L];