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

package/CHANGELOG.md

@@ -4,6 +4,8 @@ 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`;
 > - add a new `EvalKeyNameError` class;
 > - some fixes.
 

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.46|
+>|***rev.*:**|0.1.47|
 >|:---|---:|
->|date:|2025-12-14|
+>|date:|2026-02-14|
 
 ## Introduction
 
@@ -10,6 +10,16 @@ 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
+
 ### 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 +126,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` ||
@@ -1214,7 +1222,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
 
@@ -1232,6 +1240,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 +1249,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 +1264,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/lib/xObj-defs.js

@@ -1,4 +1,4 @@
-// [v0.1.067-20260101]
+// [v0.1.068-20260203]
 
 // === 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

package/lib/xObj-lib.d.ts

@@ -1,3 +1,4 @@
+import type { EvalKeyNameError } from "./xObj-errors";
 /**
  * A result of a value check ops.
  */
@@ -11,6 +12,45 @@ export type RVAL_reason = {
      */
     msg: string;
 };
+/**
+ * An options setting for `evalKeyName` function
+ */
+export type IEvalKeyNameOptions = {
+    /**
+     * - a flag to accept only a non-empty string values
+     */
+    onlyNES?: boolean | undefined;
+};
+/**
+ * A result of `evalKeyName` function if succeed
+ */
+export type IEvalKeyNameResultOnSuccess = {
+    /**
+     * - ops flag
+     */
+    isSucceed: true;
+    /**
+     * - result value
+     */
+    value: string;
+};
+/**
+ * A result of `evalKeyName` function if failed
+ */
+export type IEvalKeyNameResultOnFail = {
+    /**
+     * - ops flag
+     */
+    isSucceed: false;
+    /**
+     * - reason of fail
+     */
+    value: RVAL_reason;
+};
+/**
+ * A result of `evalKeyName` function
+ */
+export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
 /**
  * A result of a value check ops.
  */
@@ -73,7 +113,7 @@ export type OPT_inselops_S = {
 /**
  * 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;
 /**
@@ -105,7 +145,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;
 /**
@@ -142,7 +182,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;
 /**
@@ -175,7 +215,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;
 /**
@@ -217,66 +257,70 @@ 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: [obj: object, name: string, opt?: OPT_inselops_L]): object | null;
+export function insertXObjElement(...args: insertXObjElementParams): object | null;
+type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * 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: [obj: object, name: string]): boolean;
+export function deleteXObjElement(...args: deleteXObjElementParams): boolean;
+type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
 /**
  * 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;
-
 /**
  * Tries to convert a value into an ID.
  */
@@ -286,19 +330,20 @@ export function evalXObjEName(value: any): null | number | string;
  * @throws {TypeError} if first param is not an object
  * @see insertXObjEListEx
  */
-export function insertXObjEList(...args: [obj: object, name: string, opt?: OPT_inselops_S]): object | object[] | null;
+export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
+type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * 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;
 /**
  * Tries to convert a value into an ID.
  * @inner
  */
-export function evalKeyName(value: any, opt?: boolean): VCOR_evalkname;
+export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
 /**
  * Tries to convert a value into an element name description.
  */
@@ -313,4 +358,4 @@ export function insertXObjElements(obj: object, ...args: any[]): number;
  * @throws {TypeError} if first param is not an object
  */
 export function insertXObjEChain(obj: object, ...args: any[]): any | null;
-export {}
+export {}

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.3.111-20251229]
+// [v0.3.120-20260213]
 
 // === module init block ===
 
@@ -42,22 +42,55 @@ const {
  * @property {string} msg - message text
  */
 
+/**
+ * An options setting for `evalKeyName` function
+ * @since 0.2.x
+ * @typedef {Object} IEvalKeyNameOptions
+ * @property {boolean} [onlyNES] - a flag to accept only a non-empty string values
+ */
+
+/**
+ * A result of `evalKeyName` function if succeed
+ * @since 0.2.x
+ * @typedef {Object} IEvalKeyNameResultOnSuccess
+ * @property {true} isSucceed - ops flag
+ * @property {string} value - result value
+ */
+
+/**
+ * A result of `evalKeyName` function if failed
+ * @since 0.2.x
+ * @typedef {Object} IEvalKeyNameResultOnFail
+ * @property {false} isSucceed - ops flag
+ * @property {RVAL_reason} value - reason of fail
+ */
+
+/**
+ * A result of `evalKeyName` function
+ * @since 0.2.x
+ * @typedef {(IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail)} IEvalKeyNameResult
+ */
+
 /**
  * A result of a value check ops.
  * @typedef {Object} VCOR_evalkname
  * @property {boolean} isSucceed - ops flag
  * @property {(string|RVAL_reason)} value - result value or reson if failed
+ * @todo \[from v0.2.x] make obsolete. Use `IEvalKeyNameResult` instead.
  */
 
 /**
  * Tries to convert a value into an ID.
  * @function evalKeyName
  * @param {any} value - key to validate
- * @param {boolean} [opt=true]
- * @returns {VCOR_evalkname}
+ * @param {(boolean|IEvalKeyNameOptions)} [opt=true] - some options
+ * @returns {IEvalKeyNameResult}
  * @inner
  */
 function evalKeyName(value, opt = true) {
+  let {
+    onlyNES,
+  } = isPlainObject(opt) ? opt : { onlyNES: opt };
   if (typeof value !== 'string') {
     return {
       isSucceed: false,
@@ -68,7 +101,7 @@ function evalKeyName(value, opt = true) {
     };
   };
   const key = value.trim();
-  if (opt && key === '') {
+  if (onlyNES && key === '') {
     return {
       isSucceed: false,
       value: {
@@ -202,7 +235,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)) {
@@ -211,7 +244,7 @@ function getXObjElement(obj, name) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: key } = evalKeyName(name);
+  const { isSucceed, value: key } = evalKeyName(name);
   if (isSucceed) {
     // TODO: [?] check type of obj[key_name]
     return obj[key] !== undefined ? obj[key] : null;
@@ -260,7 +293,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)) {
@@ -269,31 +302,32 @@ function addXObjElement(obj, name) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: key } = evalKeyName(name);
-  if (!isSucceed) {
+  const { isSucceed, value: key } = evalKeyName(name);
+  if (isSucceed) {
+    const item = {};
+    let prop = obj[key];
+    let isSucceed = false;
+    // // TODO: [?] consider whether or not do ops if new_key exists
+    if (isNullOrUndef(prop)) {
+      obj[key] = prop = item;
+      isSucceed = true;
+    } else if (isObject(prop)) {
+      if (isArray(prop)) {
+        prop.push(item);
+      } else {
+        obj[key] = [ prop, item ];
+      };
+      prop = item;
+      isSucceed = true;
+    };
+    return {
+      isSucceed,
+      item: isSucceed ? prop : null,
+    };
+  } else {
     const { code, msg } = key;
     throw new EvalKeyNameError(msg, { code });
   };
-  const item = {};
-  let prop = obj[key];
-  isSucceed = false;
-  // // TODO: [?] consider whether or not do ops if new_key exists
-  if (isNullOrUndef(prop)) {
-    obj[key] = prop = item;
-    isSucceed = true;
-  } else if (isObject(prop)) {
-    if (isArray(prop)) {
-      prop.push(item);
-    } else {
-      obj[key] = [ prop, item ];
-    };
-    prop = item;
-    isSucceed = true;
-  };
-  return {
-    isSucceed,
-    item: isSucceed ? prop : null,
-  };
 };
 
 /**
@@ -312,7 +346,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;
@@ -341,7 +375,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)) {
@@ -350,37 +384,38 @@ function insertXObjElementEx(obj, name, opt) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: key } = evalKeyName(name);
-  if (!isSucceed) {
-    const { code, msg } = key;
-    throw new EvalKeyNameError(msg, { code });
-  };
-  const item = {};
-  let prop = obj[key];
-  isSucceed = false;
-  if (isNullOrUndef(prop)) {
-    obj[key] = prop = item;
-    isSucceed = true;
-  } else {
-    /** @type {OPT_inselops_L} */
-    let {
-      force,
-      ripOldies,
-      acceptIfList,
-    } = isPlainObject(opt) ? opt : {};
-    if (typeof force !== 'boolean') force = false;
-    if (typeof ripOldies !== 'boolean') ripOldies = false;
-    if (typeof acceptIfList !== 'boolean') acceptIfList = false;
-    if (force && (ripOldies || !isObject(prop))) {
+  const { isSucceed, value: key } = evalKeyName(name);
+  if (isSucceed) {
+    const item = {};
+    let prop = obj[key];
+    let isSucceed = false;
+    if (isNullOrUndef(prop)) {
       obj[key] = prop = item;
       isSucceed = true;
     } else {
-      isSucceed = isPlainObject(prop) || (isArray(prop) && acceptIfList);
+      /** @type {OPT_inselops_L} */
+      let {
+        force,
+        ripOldies,
+        acceptIfList,
+      } = isPlainObject(opt) ? opt : {};
+      if (typeof force !== 'boolean') force = false;
+      if (typeof ripOldies !== 'boolean') ripOldies = false;
+      if (typeof acceptIfList !== 'boolean') acceptIfList = false;
+      if (force && (ripOldies || !isObject(prop))) {
+        obj[key] = prop = item;
+        isSucceed = true;
+      } else {
+        isSucceed = isPlainObject(prop) || (isArray(prop) && acceptIfList);
+      };
     };
-  };
-  return {
-    isSucceed,
-    item: isSucceed ? prop : null,
+    return {
+      isSucceed,
+      item: isSucceed ? prop : null,
+    };
+  } else {
+    const { code, msg } = key;
+    throw new EvalKeyNameError(msg, { code });
   };
 };
 
@@ -391,7 +426,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;
@@ -418,7 +453,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)) {
@@ -427,19 +462,20 @@ function deleteXObjElementEx(obj, name) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: key } = evalKeyName(name);
-  if (!isSucceed) {
+  const { isSucceed, value: key } = evalKeyName(name);
+  if (isSucceed) {
+    let prop = obj[key];
+    let isSucceed = false;
+    // // TODO: catch errors in strict mode
+    isSucceed = delete obj[key];
+    return {
+      isSucceed,
+      item: isSucceed && isObject(prop) ? prop : null,
+    };
+  } else {
     const { code, msg } = key;
     throw new EvalKeyNameError(msg, { code });
   };
-  let prop = obj[key];
-  isSucceed = false;
-  // // TODO: catch errors in strict mode
-  isSucceed = delete obj[key];
-  return {
-    isSucceed,
-    item: isSucceed && isObject(prop) ? prop : null,
-  };
 };
 
 /**
@@ -450,8 +486,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)) {
@@ -461,12 +497,12 @@ function renameXObjElement(obj, name = '', value = '') {
     );
   };
   const opt = false;
-  let { isSucceed: isAcceptON, value: oname } = evalKeyName(name, opt);
+  const { isSucceed: isAcceptON, value: oname } = evalKeyName(name, opt);
   if (!isAcceptON) {
     const { code, msg } = oname;
     throw new EvalKeyNameError(msg, { code });
   };
-  let { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+  const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
   if (!isAcceptNN) {
     const { code, msg } = nname;
     throw new EvalKeyNameError(msg, { code });
@@ -495,6 +531,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;
@@ -504,7 +541,7 @@ function checkXObjAttribute(obj, attr = '', key) {
     throw err;
   };
   if (_obj === null) return false;
-  let { isSucceed, value: name } = evalKeyName(attr, false);
+  const { isSucceed, value: name } = evalKeyName(attr, false);
   if (isSucceed) {
     if (name === '') return false;
   } else {
@@ -522,6 +559,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;
@@ -531,17 +569,18 @@ function deleteXObjAttribute(obj, attr = '', key) {
     throw err;
   };
   if (_obj === null) return false;
-  let { isSucceed, value: name } = evalKeyName(attr, false);
-  if (!isSucceed) {
+  const { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (name !== '') {
+      // // TODO: catch errors in strict mode
+      isSucceed = delete _obj[name];
+    };
+    return isSucceed;
+  } else {
     const { code, msg } = name;
     throw new EvalKeyNameError(msg, { code });
   };
-  isSucceed = false;
-  if (name !== '') {
-    // // TODO: catch errors in strict mode
-    isSucceed = delete _obj[name];
-  };
-  return isSucceed;
 };
 
 /**
@@ -554,8 +593,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)) {
@@ -565,37 +605,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)) {
-      let { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
-      if (!isAcceptON) {
-        const { code, msg } = oname;
-        throw new EvalKeyNameError(msg, { code });
-      };
-      let { 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;
 };
 
 /**
@@ -605,7 +646,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)) {
@@ -614,7 +655,7 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: _key } = evalKeyName(key, false);
+  const { isSucceed, value: _key } = evalKeyName(key, false);
   if (!isSucceed) {
     const { code, msg } = _key;
     throw new EvalKeyNameError(msg, { code });
@@ -630,7 +671,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)) {
@@ -639,17 +680,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;
 };
 
 /**
@@ -660,7 +706,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;
@@ -670,7 +716,7 @@ function readXObjAttrRaw(obj, attr = '', key) {
     throw err;
   };
   if (_obj !== null) {
-    let { isSucceed, value: name } = evalKeyName(attr, false);
+    const { isSucceed, value: name } = evalKeyName(attr, false);
     if (!isSucceed) {
       const { code, msg } = name;
       throw new EvalKeyNameError(msg, { code });
@@ -688,38 +734,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;
 };
 
 /**
@@ -1406,7 +1458,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)) {
@@ -1415,36 +1467,37 @@ function insertXObjEListEx(obj, name, opt) {
       { code: XOBJ_TE_NPOBJ_ECODE },
     );
   };
-  let { isSucceed, value: key } = evalKeyName(name);
-  if (!isSucceed) {
-    const { code, msg } = key;
-    throw new EvalKeyNameError(msg, { code });
-  };
-  /** @type {OPT_inselops_S} */
-  let {
-    force,
-    ripOldies,
-  } = isPlainObject(opt) ? opt : {};
-  if (typeof force !== 'boolean') force = false;
-  if (typeof ripOldies !== 'boolean') ripOldies = false;
-  let prop = obj[key];
-  isSucceed = false;
-  if (
-    isNullOrUndef(prop)
-    || (force && (ripOldies || !isObject(prop)))
-  ) {
-    obj[key] = prop = [];
-    isSucceed = true;
-  } else {
-    if (isObject(prop)) {
-      if (!isArray(prop)) prop = [ prop ];
-      obj[key] = prop;
+  const { isSucceed, value: key } = evalKeyName(name);
+  if (isSucceed) {
+    /** @type {OPT_inselops_S} */
+    let {
+      force,
+      ripOldies,
+    } = isPlainObject(opt) ? opt : {};
+    if (typeof force !== 'boolean') force = false;
+    if (typeof ripOldies !== 'boolean') ripOldies = false;
+    let prop = obj[key];
+    let isSucceed = false;
+    if (
+      isNullOrUndef(prop)
+      || (force && (ripOldies || !isObject(prop)))
+    ) {
+      obj[key] = prop = [];
       isSucceed = true;
+    } else {
+      if (isObject(prop)) {
+        if (!isArray(prop)) prop = [ prop ];
+        obj[key] = prop;
+        isSucceed = true;
+      };
     };
-  };
-  return {
-    isSucceed,
-    item: isSucceed ? prop  : null,
+    return {
+      isSucceed,
+      item: isSucceed ? prop  : null,
+    };
+  } else {
+    const { code, msg } = key;
+    throw new EvalKeyNameError(msg, { code });
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.2.8-b",
+  "version": "0.2.9-b.1",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -11,7 +11,7 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "doc/xObj.md",
+    "doc/*.md",
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
     "lib/xObj-errors.js",
@@ -31,10 +31,10 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.3.3"
+    "@ygracs/bsfoc-lib-js": "~0.3.3"
   },
   "devDependencies": {
-    "@ygracs/test-helper": "~0.0.1-b",
+    "@ygracs/test-helper": "~0.0.2-b",
     "jest": "^30.2.0",
     "jsdoc-to-markdown": "^9.1.3",
     "minimist": "^1.2.8",