@ygracs/xobj-lib-js 0.2.5-b → 0.2.7-b

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.106-20251213]
+// [v0.3.111-20251229]
 
 // === module init block ===
 
@@ -11,7 +11,11 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
+  EvalKeyNameError,
   XOBJ_ECODE_TABLE,
+} = require('./xObj-errors');
+
+const {
   XOBJ_DEF_TNAMES,
 } = require('./xObj-defs');
 
@@ -126,11 +130,19 @@ function evalXObjEName(value) {
   return name;
 };
 
+/**
+ * A result of an element name pattern evaluation ops.
+ * @typedef {Object} XObjENameDescr
+ * @property {boolean} isERR - ops flag
+ * @property {(null|number|string)} name - element name
+ * @property {?object} conditions - some conditions applied to an element
+ */
+
 /**
  * Tries to convert a value into an element name description.
  * @function genXObjENameDescr
- * @param {any} value
- * @returns {object}
+ * @param {any} value - element name pattern
+ * @returns {XObjENameDescr}
  */
 function genXObjENameDescr(value) {
   let result = null;
@@ -194,19 +206,18 @@ function genXObjENameDescr(value) {
  */
 function getXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: key } = evalKeyName(name);
-  if (!isSucceed) {
-    const { code, msg } = key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+  if (isSucceed) {
+    // TODO: [?] check type of obj[key_name]
+    return obj[key] !== undefined ? obj[key] : null;
   };
-  // TODO: [?] check type of obj[key_name]
-  return obj[key] !== undefined ? obj[key] : null;
+  const { code, msg } = key;
+  throw new EvalKeyNameError(msg, { code });
 };
 
 /**
@@ -253,16 +264,15 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
  */
 function addXObjElement(obj, name) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: key } = evalKeyName(name);
   if (!isSucceed) {
     const { code, msg } = key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   const item = {};
   let prop = obj[key];
@@ -335,16 +345,15 @@ function insertXObjElement(...args) {
  */
 function insertXObjElementEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: key } = evalKeyName(name);
   if (!isSucceed) {
     const { code, msg } = key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   const item = {};
   let prop = obj[key];
@@ -413,16 +422,15 @@ function deleteXObjElement(...args) {
  */
 function deleteXObjElementEx(obj, name) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: key } = evalKeyName(name);
   if (!isSucceed) {
     const { code, msg } = key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   let prop = obj[key];
   isSucceed = false;
@@ -447,24 +455,21 @@ function deleteXObjElementEx(obj, name) {
  */
 function renameXObjElement(obj, name = '', value = '') {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   const opt = false;
   let { isSucceed: isAcceptON, value: oname } = evalKeyName(name, opt);
   if (!isAcceptON) {
     const { code, msg } = oname;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   let { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
   if (!isAcceptNN) {
     const { code, msg } = nname;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   let isSucceed = false;
   if (oname !== '' && oname in obj && nname !== '') {
@@ -504,9 +509,7 @@ function checkXObjAttribute(obj, attr = '', key) {
     if (name === '') return false;
   } else {
     const { code, msg } = name;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   return _obj[name] !== undefined;
 };
@@ -531,9 +534,7 @@ function deleteXObjAttribute(obj, attr = '', key) {
   let { isSucceed, value: name } = evalKeyName(attr, false);
   if (!isSucceed) {
     const { code, msg } = name;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   isSucceed = false;
   if (name !== '') {
@@ -558,17 +559,16 @@ function deleteXObjAttribute(obj, attr = '', key) {
  */
 function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   const opt = false;
   let { isSucceed, value: _key } = evalKeyName(key, opt);
   if (!isSucceed) {
     const { code, msg } = _key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   isSucceed = false;
   if (_key !== '') {
@@ -577,16 +577,12 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
       let { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
       if (!isAcceptON) {
         const { code, msg } = oname;
-        const err = new TypeError(msg);
-        err.code = code;
-        throw err;
+        throw new EvalKeyNameError(msg, { code });
       };
       let { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
       if (!isAcceptNN) {
         const { code, msg } = nname;
-        const err = new TypeError(msg);
-        err.code = code;
-        throw err;
+        throw new EvalKeyNameError(msg, { code });
       };
       if (oname !== '' && oname in _obj && nname !== '') {
         if (oname !== nname) {
@@ -613,16 +609,15 @@ function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNA
  */
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: _key } = evalKeyName(key, false);
   if (!isSucceed) {
     const { code, msg } = _key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   return _key !== '' ? obj[_key] : undefined;
 };
@@ -639,16 +634,15 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
  */
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: _key } = evalKeyName(key, false);
   if (!isSucceed) {
     const { code, msg } = _key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   if (_key === '' || value === undefined) {
     isSucceed = false;
@@ -679,9 +673,7 @@ function readXObjAttrRaw(obj, attr = '', key) {
     let { isSucceed, value: name } = evalKeyName(attr, false);
     if (!isSucceed) {
       const { code, msg } = name;
-      const err = new TypeError(msg);
-      err.code = code;
-      throw err;
+      throw new EvalKeyNameError(msg, { code });
     };
     if (name !== '') return _obj[name];
   };
@@ -702,9 +694,7 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
   let { isSucceed, value: name } = evalKeyName(attr, false);
   if (!isSucceed) {
     const { code, msg } = name;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   isSucceed = false;
   if (name !== '' && value !== undefined) {
@@ -783,13 +773,13 @@ function readXObjParamAsBool(obj, defValue, key) {
 };
 
 /**
+ * Extracts a parameter from a given object and returns it as a number.
  * @function readXObjParamAsNum
  * @param {object} obj - some object
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
  * @throws {TypeError} if first param is not an object
- * Extracts a parameter from a given object and returns it as a number.
  */
 function readXObjParamAsNum(obj, defValue, key) {
   let result = undefined;
@@ -1355,9 +1345,10 @@ function writeXObjAttrEx(obj, attr, value, opt, key) {
  */
 function insertXObjElements(obj, ...args) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let count = 0;
   let len = args.length;
@@ -1419,16 +1410,15 @@ function insertXObjEList(...args) {
  */
 function insertXObjEListEx(obj, name, opt) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let { isSucceed, value: key } = evalKeyName(name);
   if (!isSucceed) {
     const { code, msg } = key;
-    const err = new TypeError(msg);
-    err.code = code;
-    throw err;
+    throw new EvalKeyNameError(msg, { code });
   };
   /** @type {OPT_inselops_S} */
   let {
@@ -1469,9 +1459,10 @@ function insertXObjEListEx(obj, name, opt) {
  */
 function insertXObjEChain(obj, ...args) {
   if (!isPlainObject(obj)) {
-    const err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
-    err.code = XOBJ_TE_NPOBJ_ECODE;
-    throw err;
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
   };
   let result = null;
   let len = args.length;
@@ -1501,9 +1492,6 @@ function insertXObjEChain(obj, ...args) {
 
 // === module exports block ===
 
-module.exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
-module.exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
-
 module.exports.readXObjParamRaw = readXObjParamRaw;
 module.exports.readXObjParam = readXObjParam;
 module.exports.readXObjParamAsBool = readXObjParamAsBool;
@@ -1547,12 +1535,10 @@ module.exports.evalXObjEName = evalXObjEName;
 module.exports.insertXObjEList = insertXObjEList;
 module.exports.insertXObjEListEx = insertXObjEListEx;
 
-/* inner */
+// * inner *
 module.exports.evalKeyName = evalKeyName;
 
-/* experimental */
+// * experimental *
 module.exports.genXObjENameDescr = genXObjENameDescr;
-/* experimental */
 module.exports.insertXObjElements = insertXObjElements;
-/* experimental */
 module.exports.insertXObjEChain = insertXObjEChain;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.2.5-b",
+  "version": "0.2.7-b",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -14,6 +14,7 @@
     "doc/xObj.md",
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
+    "lib/xObj-errors.js",
     "lib/*.d.ts",
     "index.js",
     "index.d.ts",
@@ -30,7 +31,7 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.3.1-b"
+    "@ygracs/bsfoc-lib-js": "^0.3.2-b"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.1-b",