@ygracs/xobj-lib-js 0.2.4 → 0.2.6-b

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.105-20250719]
+// [v0.3.111-20251229]
 
 // === module init block ===
 
@@ -10,6 +10,15 @@ const {
   isArray, isObject, isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  EvalKeyNameError,
+  XOBJ_ECODE_TABLE,
+} = require('./xObj-errors');
+
+const {
+  XOBJ_DEF_TNAMES,
+} = require('./xObj-defs');
+
 const {
   XOBJ_TE_NSTR_EMSG,
   XOBJ_TE_NSTR_ECODE,
@@ -17,9 +26,14 @@ const {
   XOBJ_TE_NPOBJ_ECODE,
   XOBJ_TE_KNES_EMSG,
   XOBJ_TE_KNES_ECODE,
-} = require('#lib/xObj-defs.js').XOBJ_ECODE_TABLE;
+} = XOBJ_ECODE_TABLE;
+
+const {
+  XOBJ_DEF_PARAM_TNAME,
+  XOBJ_DEF_ATTR_TNAME,
+} = XOBJ_DEF_TNAMES;
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 /**
  * A result of a value check ops.
@@ -75,9 +89,6 @@ function evalKeyName(value, opt = true) {
  * (* constant definitions *)
  */
 
-const XOBJ_DEF_PARAM_TNAME = '__text';
-const XOBJ_DEF_ATTR_TNAME = '__attr';
-
 /***
  * (* function definitions *)
  */
@@ -119,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;
@@ -187,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 });
 };
 
 /**
@@ -246,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];
@@ -328,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];
@@ -406,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;
@@ -440,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 !== '') {
@@ -497,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;
 };
@@ -524,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 !== '') {
@@ -551,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 !== '') {
@@ -570,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) {
@@ -606,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;
 };
@@ -632,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;
@@ -672,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];
   };
@@ -695,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) {
@@ -776,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;
@@ -1348,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;
@@ -1412,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 {
@@ -1462,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;
@@ -1494,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;
@@ -1540,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.4",
+  "version": "0.2.6-b",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -9,28 +9,35 @@
     "url": "git+https://gitlab.com/ygracs/xobj-lib-js.git"
   },
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/xObj.md",
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
+    "lib/xObj-errors.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.3.0"
+    "@ygracs/bsfoc-lib-js": "^0.3.1-b"
   },
   "devDependencies": {
-    "jest": "^30.0.5",
-    "jsdoc-to-markdown": "^9.1.2",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "~0.0.1-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }