@ygracs/xobj-lib-js 0.0.14-rc1 → 0.0.14-rc3

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+#### *v0.0.14rc3*
+
+Pre-release version.
+
+> - `xObj-lib.md` updated;
+> - some fixes in 'xObj-lib.js' module;
+> - added `genXObjENameDescr` function.
+
+#### *v0.0.14rc2*
+
+Pre-release version.
+
+> - some fixes in 'xObj-lib.js' module;
+> - added some error codes (see details in docs);
+> - added evalXObjEName function;
+> - added deleteXObjAttribute function.
+
 #### *v0.0.14rc1*
 
 Pre-release version.

package/LICENSE

@@ -1,9 +1,9 @@
-The MIT License (MIT)
-
-Copyright (c) 2019-2023 Yuri Grachev
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2019-2023 Yuri Grachev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.16|
+>|***rev.*:**|0.1.22|
 >|:---|---:|
->|date:|2023-02-07|
+>|date:|2023-03-15|
 
 ## Intoduction
 
@@ -52,7 +52,7 @@ The settings listed in the table below:
 > Note:
 > If a `key` parameter given to the function is not a type of `string`, the `TypeError` will be thrown. If that parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
 >
-> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
+> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
 
 #### **readXObjParam(object\[, key])**
 
@@ -113,7 +113,7 @@ This function sets object parameter to a given value and if succeed returns `tru
 >
 > If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
 >
-> If an `attr` parameter given to the function is not a 'string' type, the function will throw a `TypeError` exception.
+> If an `attr` parameter given to the function is not a 'string' type, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
 
 #### **readXObjAttr(object, attr\[, key])**
 
@@ -175,7 +175,7 @@ This function sets object attribute to a given value and if succeed returns `tru
 > Note:
 > If a `key` parameter given to the function is not a type of `string`, the `TypeError` will be thrown. If that parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
 >
-> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
+> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
 
 #### **readXObjParamRaw(object\[, key])**
 
@@ -190,7 +190,7 @@ This is a special function that writes a given value of an object parameter as "
 > Note:
 > If a `key` parameter given to the function is not a type of `string`, the `TypeError` will be thrown. If that parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
 >
-> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
+> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
 
 #### **readXObjAttrRaw(object, attr\[, key])**
 
@@ -200,24 +200,49 @@ This is a special function that returns a value of an object attribute as "IT IS
 
 This is a special function that writes a given value of an object attribute as "IT IS".
 
+### Other functions for deal with an object attributes
+
+> Note:
+> If a `key` parameter given to the function is not a type of `string`, the `TypeError` will be thrown. If that parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+>
+> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
+
 #### **getXObjAttributes(object\[, key])**
 
-This is a special function that returns an object which represents a set of the element attributes for a given object or `null` if failed.
+This function returns an object which represents a set of the element attributes for a given object or `null` if failed.
 
 #### **checkXObjAttribute(object, attr\[, key])**
 
-This is a special function that checks whether or not an attribute with a name given by `attr` parameter exists for the element given by `object` parameter. If attribute exists `true` is returned.
+This function tries to check whether or not an attribute with a name given by `attr` parameter exists for the element given by `object` parameter. If attribute exists `true` is returned.
+
+> Note: If an `attr` parameter is not a type of `string`, the function will throw a `TypeError` exception.
+
+#### **deleteXObjAttribute(object, attr\[, key])**
+
+This function tries to delete  an attribute with a name given by `attr` parameter. If succeed `true` is returned.
 
 > Note: If an `attr` parameter is not a type of `string`, the function will throw a `TypeError` exception.
 
 ### Other functions
 
+#### **evalXObjEName(name)**
+
+This function evaluated a value given by a `name` parameter and return a result. The dependencies of a resulted value returned by the function given in the following table:
+
+|given value|value of result|
+|:---|---|
+|value not given (*or `undefined`*)|value of `undefined`|
+|any empty string|an empty string|
+|value is a positive number or a string that can be converted to a such number|value of a `number`|
+|any other string that can\'t be converted to a number|value of a string|
+|any other cases|value of `null`|
+
 #### **getXObjElement(object, name)**
 
 This function returns an element from a given object by its name or `null` if that element not found.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
 #### **addXObjElement(object, name)**
@@ -225,7 +250,7 @@ This function returns an element from a given object by its name or `null` if th
 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.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
 The status of an operation contains 2 fields:
@@ -238,7 +263,7 @@ The status of an operation contains 2 fields:
 This function inserts an empty element named by a `name` parameter into a given object. If succeed the element will be returned or `null` in opposite.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
 An `options.force` parameter modifies the functions behavior as follows:
@@ -255,7 +280,7 @@ An `options.ripOldies` parameter applied only if `options.force` is `true`. And
 This function deletes an element addressed by `name` parameter from a given object. If succeed `true` is returned.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
 #### **renameXObjElement(object, oldName, newName)**
@@ -263,20 +288,50 @@ This function deletes an element addressed by `name` parameter from a given obje
 This function renames an element with a name `oldName` to a name `newName` for the given object. If succeed `true` is returned.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `oldName` or `newName` parameter is not a non-empty string.
 
 ### 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.
 
+#### **genXObjENameDescr(name)**
+
+This function creates a object that contains description of the value given by a `name` parameter.
+
+A value of the `name` parameter must have some of the following formats:
+
+1. `<name>`;
+2. `<name>[<child>]`;
+3. `<name>[<child>=<value>]`;
+4. `<name>[@<attribute>]`;
+5. `<name>[@<attribute>=<value>]`;
+
+> Note: the `<value>` must be quotted if it contains characters like a spaces or square brackets.
+
+The returned object has following attributes:
+
+|attribute|value type|description|
+|:---|---|---|
+|`isERR`|`boolean`|set to `true` if error happend|
+|`name`|`string`|contains a name of the element|
+|`conditions`|`object`||
+
+The object `conditions` property (*if present*) contains following attributes:
+
+|attribute|value type|description|
+|:---|---|---|
+|`type`|`string`||
+|`name`|||
+|`value`|||
+
 #### **insertXObjElements(object, names_list\[, options])**
 
 This function inserts an elements given by the `names_list` and return quantity of the inserted elements.
 
 > If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
 >
-> For use of `options` parameter see `insertXObjElement`.
+> The `options` parameter if given must be an object. For details see `insertXObjElement`.
 
 #### **insertXObjEList(object, name\[, options])**
 
@@ -302,14 +357,14 @@ This function inserts a chain of the elements listed by `names_list`. If succeed
 
 > If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
 >
-> For use of `options` parameter see `insertXObjElement`.
+> The `options` parameter if given must be an object. For details see `insertXObjElement`.
 
 #### **deleteXObjElementEx(object, name)**
 
 This function deletes an element addressed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
 
 > the function will throw a `TypeError` if:
-> - `object` parameter is not a plain object;
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
 The status of an operation contains 2 fields:

package/index.js

@@ -1,14 +1,11 @@
-// [v0.1.007-20220524]
-
-// === module init block ===
-
-//const xObj = require('./lib/xObj-lib.js');
-
-// === module extra block (helper functions) ===
-
-// === module main block ===
-
-// === module exports block ===
-
-//module.exports.xObj = xObj;
-module.exports = require('./lib/xObj-lib.js');
+// [v0.1.009-20230316]
+
+// === module init block ===
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+// === module exports block ===
+
+module.exports = require('./lib/xObj-lib.js');

package/lib/xObj-lib.js

@@ -1,10 +1,11 @@
-// [v0.1.042-20230207]
+// [v0.1.056-20230316]
 
 // === module init block ===
 
 const {
-  valueToIndex, readAsBool, readAsString,
-  readAsBoolEx, readAsNumberEx, isNotEmptyString, isNullOrUndef,
+  valueToIndex,
+  readAsString, readAsBoolEx, readAsNumberEx,
+  isNullOrUndef,
   isArray, isObject, isPlainObject, readAsListS,
 } = require('@ygracs/bsfoc-lib-js');
 
@@ -12,12 +13,18 @@ const XOBJ_DEF_PARAM_TNAME = '__text';
 const XOBJ_DEF_ATTR_TNAME = '__attr';
 
 const XOBJ_TE_INVARG_EMSG = 'invalid argument';
-const XOBJ_TE_NOBJ_EMSG = XOBJ_TE_INVARG_EMSG + '(an object is expected)';
-const XOBJ_TE_NARR_EMSG = XOBJ_TE_INVARG_EMSG + '(an array is expected)';
-const XOBJ_TE_NSTR_EMSG = XOBJ_TE_INVARG_EMSG + '(a string is expected)';
-const XOBJ_TE_NPOBJ_EMSG = XOBJ_TE_INVARG_EMSG + '(a plain object is expected)';
+const XOBJ_TE_NOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (an object expected)`;
+const XOBJ_TE_NOBJ_ECODE = 'ERR_XOBJ_NOBJ';
+const XOBJ_TE_NARR_EMSG = `${XOBJ_TE_INVARG_EMSG} (an array expected)`;
+const XOBJ_TE_NARR_ECODE = 'ERR_XOBJ_NARR';
+const XOBJ_TE_NSTR_EMSG = `${XOBJ_TE_INVARG_EMSG} (a string expected)`;
+const XOBJ_TE_NSTR_ECODE = 'ERR_XOBJ_NSTR';
+const XOBJ_TE_NPOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (a plain object expected)`;
+const XOBJ_TE_NPOBJ_ECODE = 'ERR_XOBJ_NPOBJ';
 const XOBJ_TE_ANES_EMSG = '<attr_name> must be a non-empty string';
+const XOBJ_TE_ANES_ECODE = 'ERR_XOBJ_INVARG_ATTR';
 const XOBJ_TE_KNES_EMSG = '<key_name> must be a non-empty string';
+const XOBJ_TE_KNES_ECODE = 'ERR_XOBJ_INVARG_KEY';
 
 const DEF_XML_PARSE_OPTIONS = {
   compact: true,
@@ -46,11 +53,102 @@ const DEF_XML_PARSE_OPTIONS = {
 
 // === module main block (function definitions) ===
 
+function evalXObjEName(value){
+  let name = value;
+  if (!isNullOrUndef(name)) {
+    switch (typeof name) {
+      case 'number' : {
+        if (Number.isNaN(name) || name < 0) name = null;
+        break;
+      }
+      case 'string' : {
+        name = name.trim();
+        if (name !== '') {
+          let value = Number(name);
+          if (!Number.isNaN(value)) {
+            name = value < 0 ? null : value;
+          };
+        };
+        break;
+      }
+      default: {
+        name = null;
+        break;
+      }
+    };
+  };
+  return name;
+};
+
+function genXObjENameDescr(value){
+  let result = null;
+  let name = null;
+  let conditions = null;
+  let isERR = false;
+  let tail = null;
+  if (typeof value === 'string') {
+    const re = /^\s*([^\[\]\s]+)?(\s*)(\[.*])?\s*$/;
+    tail = value.match(re);
+    //console.log('CHECK: '+JSON.stringify(tail, null, 2));
+    if (tail) {
+      if (tail[1]) {
+        name = tail[1];
+        if (name) {
+          if (tail[2] === '') {
+            if (tail[3]) {
+              const re = /\[(@{0,1})(?:([^\[=]*?)(?:(?=[=])(=)((?![\"\'])[^\]]*|(?=([\"\']))\5(.*)\5))?)](\s*.*)/;
+              tail = tail[3].match(re);
+              //console.log('CHECK: '+JSON.stringify(tail, null, 2));
+              if (tail) {
+                let name = evalXObjEName(tail[2]);
+                let type = tail[1] === '@' ? 'attribute' : 'child';
+                let value = undefined;
+                if (tail[3] === '=') value = tail[5] ? tail[6] : tail[4];
+                if (tail[7]) isERR = true;
+                conditions = {
+                  name,
+                  type,
+                  value,
+                };
+              };
+            };
+          } else if (tail[3]) {
+            name = null;
+          };
+        };
+      };
+    };
+  } else {
+    name = value;
+  };
+  name = evalXObjEName(name);
+  if (name === null) isERR = true;
+  result = {
+    name,
+    conditions,
+    isERR,
+  };
+  return result;
+};
+
 function getXObjElement(obj, name){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
+  };
   // TODO: [?] check type of obj[key_name]
   return obj[key] !== undefined ? obj[key] : null;
 };
@@ -60,9 +158,9 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
   try {
     result = getXObjElement(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG :
-      case XOBJ_TE_KNES_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
         break;
       }
       default: {
@@ -75,10 +173,23 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
 };
 
 function addXObjElement(obj, name){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
+  };
   const item = {};
   let prop = obj[key];
   let isSUCCEED = false;
@@ -87,14 +198,13 @@ function addXObjElement(obj, name){
     obj[key] = prop = item;
     isSUCCEED = true;
   } else if (isObject(prop)) {
-    isSUCCEED = true;
     if (isArray(prop)) {
       prop.push(item);
-      prop = item;
     } else {
       obj[key] = [ prop, item ];
-      prop = item;
     };
+    prop = item;
+    isSUCCEED = true;
   };
   return {
     isSucceed: isSUCCEED,
@@ -102,30 +212,36 @@ function addXObjElement(obj, name){
   };
 };
 
-function insertXObjElement(obj, name, opt){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+function insertXObjElement(obj, name, opt = {}){
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
-  let _options = opt;
-  if (typeof opt === 'boolean') {
-    _options = { force: _options };
-  } else if (!isPlainObject(_options)) {
-    _options = {};
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
   };
+  const _options = isPlainObject(opt) ? opt : {};
   let { force, rip_oldies, ripOldies } = _options;
   if (typeof force !== 'boolean') force = false;
   if (ripOldies === undefined) ripOldies = rip_oldies;
   if (typeof ripOldies !== 'boolean') ripOldies = false;
-  const item = {};
   let prop = obj[key];
-  let isACCEPTED = false;
-  if (isNullOrUndef(prop)) {
+  let isACCEPTED = (
+    isNullOrUndef(prop)
+    || (force && (ripOldies || !isPlainObject(prop)))
+  );
+  if (isACCEPTED) {
     obj[key] = prop = {};
-    isACCEPTED = true;
-  } else if (force) {
-    if (ripOldies || !isPlainObject(prop)) obj[key] = prop = {};
-    isACCEPTED = true;
   } else {
     isACCEPTED = isPlainObject(prop);
   };
@@ -133,10 +249,23 @@ function insertXObjElement(obj, name, opt){
 };
 
 function deleteXObjElement(obj, name){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
+  };
   let result = false;
   // // TODO: catch errors in strict mode
   result = delete obj[key];
@@ -144,10 +273,23 @@ function deleteXObjElement(obj, name){
 };
 
 function deleteXObjElementEx(obj, name){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
+  };
   let prop = obj[key];
   let result = false;
   // // TODO: catch errors in strict mode
@@ -159,13 +301,24 @@ function deleteXObjElementEx(obj, name){
 };
 
 function renameXObjElement(obj, name, newName){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
-  if (typeof newName !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string' || typeof newName !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
   const newKey = newName.trim();
-  if (newKey === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  if (key === '' || newKey === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
+  };
   const prop = obj[key];
   let result = false;
   if (prop !== undefined) {
@@ -180,8 +333,12 @@ function renameXObjElement(obj, name, newName){
   return result;
 };
 
-function checkXObjAttribute(obj, attr, key){
-  if (typeof attr !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+function checkXObjAttribute(obj, attr = '', key){
+  if (typeof attr !== 'string') {
+    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   let objAttr = null;
   try {
     objAttr = getXObjAttributes(obj, key);
@@ -200,16 +357,55 @@ function checkXObjAttribute(obj, attr, key){
   return result;
 };
 
+function deleteXObjAttribute(obj, attr = '', key){
+  if (typeof attr !== 'string') {
+    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
+  let objAttr = null;
+  try {
+    objAttr = getXObjAttributes(obj, key);
+  } catch (err) {
+    throw err;
+  };
+  const attrName = attr.trim();
+  let result = false;
+  if (objAttr !== null && attrName !== '') {
+    // // TODO: catch errors in strict mode
+    result = delete objAttr[attrName];
+  };
+  return result;
+};
+
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof key !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof key !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const _key = key.trim();
   return _key !== '' ? obj[_key] : undefined;
 };
 
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof key !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof key !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const _key = key.trim();
   let isSUCCEED = false;
   if (_key !== '' && value !== undefined){
@@ -219,8 +415,12 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME){
   return isSUCCEED;
 };
 
-function readXObjAttrRaw(obj, attr, key){
-  if (typeof attr !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+function readXObjAttrRaw(obj, attr = '', key){
+  if (typeof attr !== 'string') {
+    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   let objAttr = null;
   try {
     objAttr = getXObjAttributes(obj, key);
@@ -231,8 +431,12 @@ function readXObjAttrRaw(obj, attr, key){
   if (objAttr !== null && attrName !== '') return objAttr[attrName];
 };
 
-function writeXObjAttrRaw(obj, attr, value, key = XOBJ_DEF_ATTR_TNAME){
-  if (typeof attr !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME){
+  if (typeof attr !== 'string') {
+    let err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const attrName = attr.trim();
   let objAttr = null;
   let isSUCCEED = false;
@@ -240,9 +444,9 @@ function writeXObjAttrRaw(obj, attr, value, key = XOBJ_DEF_ATTR_TNAME){
     try {
       objAttr = insertXObjElement(obj, key, { force: true });
     } catch (err) {
-      switch (err.message) {
-        case XOBJ_TE_NSTR_EMSG :
-        case XOBJ_TE_KNES_EMSG : {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE :
+        case XOBJ_TE_KNES_ECODE : {
           break;
         }
         default: {
@@ -264,8 +468,8 @@ function readXObjParam(obj, key){
   try {
     result = readXObjParamRaw(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -286,8 +490,8 @@ function readXObjParamAsBool(obj, defValue, key){
   try {
     result = readXObjParamRaw(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -304,8 +508,8 @@ function readXObjParamAsNum(obj, defValue, key){
   try {
     result = readXObjParamRaw(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -322,8 +526,8 @@ function readXObjParamAsStr(obj, defValue, key){
   try {
     result = readXObjParamRaw(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -344,8 +548,8 @@ function readXObjParamAsIndex(obj, key){
   try {
     result = readXObjParamRaw(obj, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -365,7 +569,19 @@ function writeXObjParam(obj, value, key){
       numberToString: true,
       boolToString: true,
     });
-    isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    try {
+      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -374,7 +590,19 @@ function writeXObjParamAsBool(obj, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = readAsBoolEx(value, defValue).toString();
-    isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    try {
+      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -383,7 +611,19 @@ function writeXObjParamAsNum(obj, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = readAsNumberEx(value, defValue).toString();
-    isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    try {
+      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -392,7 +632,19 @@ function writeXObjParamAsIndex(obj, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = valueToIndex(value).toString();
-    isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    try {
+      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -410,7 +662,19 @@ function writeXObjParamEx(obj, value, defValue, key){
       numberToString: true,
       boolToString: true,
     });
-    isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    try {
+      isSUCCEED = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -420,8 +684,8 @@ function readXObjAttr(obj, attr, key){
   try {
     result = readXObjAttrRaw(obj, attr, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -442,8 +706,8 @@ function readXObjAttrAsBool(obj, attr, defValue, key){
   try {
     result = readXObjAttrRaw(obj, attr, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -460,8 +724,8 @@ function readXObjAttrAsNum(obj, attr, defValue, key){
   try {
     result = readXObjAttrRaw(obj, attr, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -478,8 +742,8 @@ function readXObjAttrAsStr(obj, attr, defValue, key){
   try {
     result = readXObjAttrRaw(obj, attr, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -500,8 +764,8 @@ function readXObjAttrAsIndex(obj, attr, key){
   try {
     result = readXObjAttrRaw(obj, attr, key);
   } catch (err) {
-    switch (err.message) {
-      case XOBJ_TE_NSTR_EMSG : {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
         break;
       }
       default: {
@@ -521,7 +785,19 @@ function writeXObjAttr(obj, attr, value, key){
       numberToString: true,
       boolToString: true,
     });
-    isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    try {
+      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -530,7 +806,19 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = readAsBoolEx(value, defValue).toString();
-    isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    try {
+      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -539,7 +827,19 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = readAsNumberEx(value, defValue).toString();
-    isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    try {
+      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -548,7 +848,19 @@ function writeXObjAttrAsIndex(obj, attr, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
     const _value = valueToIndex(value).toString();
-    isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    try {
+      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
@@ -566,86 +878,100 @@ function writeXObjAttrEx(obj, attr, value, defValue, key){
       numberToString: true,
       boolToString: true,
     });
-    isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    try {
+      isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+          break;
+        }
+      };
+    };
   };
   return isSUCCEED;
 };
 
 function insertXObjElements(obj, ...args){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  let opt = {};
-  let count = 0;
-  let args_len = args.length;
-  if (args_len > 0) {
-    let pos = args_len-1;
-    if (typeof args[pos] === 'boolean') {
-      opt.force = args.pop();
-    } else if (isPlainObject(args[pos])) {
-      opt = args.pop();
-    };
+  if (!isPlainObject(obj)) {
+    let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
   };
-  const key_names = readAsListS({
+  const len = args.length;
+  const hasOpt = len > 0 && isPlainObject(args[len - 1]);
+  const opt = hasOpt ? args.pop() : {};
+  const names = readAsListS({
     trim: true,
     keep_empty: false,
   }, ...args);
-  for (let key_name of key_names) {
-    if (insertXObjElement(obj, key_name, opt) !== null) count++;
+  let count = 0;
+  for (let key of names) {
+    if (insertXObjElement(obj, key, opt) !== null) count++;
   };
   return count;
 };
 
-function insertXObjEList(obj, name, opt){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  if (typeof name !== 'string') throw new TypeError(XOBJ_TE_NSTR_EMSG);
+function insertXObjEList(obj, name, opt = {}){
+  let err = null;
+  if (!isPlainObject(obj)) {
+    err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  if (typeof name !== 'string') {
+    err = new TypeError(XOBJ_TE_NSTR_EMSG);
+    err.code = XOBJ_TE_NSTR_ECODE;
+    throw err;
+  };
   const key = name.trim();
-  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
-  let _options = opt;
-  if (typeof opt === 'boolean') {
-    _options = { force: _options };
-  } else if (!isPlainObject(_options)) {
-    _options = {};
+  if (key === '') {
+    err = new TypeError(XOBJ_TE_KNES_EMSG);
+    err.code = XOBJ_TE_KNES_ECODE;
+    throw err;
   };
+  const _options = isPlainObject(opt) ? opt : {};
   let { force, rip_oldies, ripOldies } = _options;
   if (typeof force !== 'boolean') force = false;
   if (ripOldies === undefined) ripOldies = rip_oldies;
   if (typeof ripOldies !== 'boolean') ripOldies = false;
-  let isACCEPTED = false;
-  if (isNullOrUndef(obj[key])) {
-    obj[key] = [];
-    isACCEPTED = true;
-  } else if (force) {
-    if (ripOldies || !isArray(obj[key])) obj[key] = [];
-    isACCEPTED = true;
+  let item = obj[key];
+  let isACCEPTED = (
+    isNullOrUndef(item)
+    || (force && (ripOldies || !isArray(item)))
+  );
+  if (isACCEPTED) {
+    obj[key] = item = [];
   } else {
-    isACCEPTED = isArray(obj[key]);
-    if (!isACCEPTED && isPlainObject(obj[key])) {
-      obj[key] = [ obj[key] ];
+    isACCEPTED = isArray(item);
+    if (!isACCEPTED && isPlainObject(item)) {
+      obj[key] = item = [ item ];
       isACCEPTED = true;
     };
   };
-  return isACCEPTED ? obj[key] : null;
+  return isACCEPTED ? item  : null;
 };
 
 function insertXObjEChain(obj, ...args){
-  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
-  let opt = {};
-  let args_len = args.length;
-  if (args_len > 0) {
-    let pos = args_len-1;
-    if (typeof args[pos] === 'boolean') {
-      opt.force = args.pop();
-    } else if (isPlainObject(args[pos])) {
-      opt = args.pop();
-    };
-  };
-  let key_names = readAsListS({
+  if (!isPlainObject(obj)) {
+    let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
+    err.code = XOBJ_TE_NPOBJ_ECODE;
+    throw err;
+  };
+  const len = args.length;
+  const hasOpt = len > 0 && isPlainObject(args[len - 1]);
+  const opt = hasOpt ? args.pop() : {};
+  const names = readAsListS({
     trim: true,
     keep_empty: false,
   }, ...args);
   let curObj = obj;
   let isSUCCEED = false;
-  for (let key_name of key_names) {
-    obj = insertXObjElement(obj, key_name, opt);
+  for (let key of names) {
+    obj = insertXObjElement(obj, key, opt);
     isSUCCEED = isPlainObject(obj);
     if (!isSUCCEED) break;
     curObj = obj;
@@ -754,6 +1080,8 @@ exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
 
 exports.TXmlContentParseOptions = TXmlContentParseOptions;
 
+exports.evalXObjEName = evalXObjEName;
+
 exports.readXObjParamRaw = readXObjParamRaw;
 exports.readXObjParam = readXObjParam;
 exports.readXObjParamAsBool = readXObjParamAsBool;
@@ -782,6 +1110,7 @@ exports.writeXObjAttrEx = writeXObjAttrEx;
 
 exports.getXObjAttributes = getXObjAttributes;
 exports.checkXObjAttribute = checkXObjAttribute;
+exports.deleteXObjAttribute = deleteXObjAttribute;
 
 exports.getXObjElement = getXObjElement;
 exports.insertXObjElement = insertXObjElement;
@@ -793,3 +1122,5 @@ exports.renameXObjElement = renameXObjElement;
 exports.insertXObjElements = insertXObjElements;
 exports.insertXObjEList = insertXObjEList;
 exports.insertXObjEChain = insertXObjEChain;
+
+exports.genXObjENameDescr = genXObjENameDescr;

package/package.json

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