@ygracs/xobj-lib-js 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+#### *v0.1.2*
+
+Release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
+> - move some definitions from `xObj-lib.js` module into `xObj-defs.js`;
+> - fix behavior for function: `evalXObjEName`.
+
+#### *v0.1.1*
+
+Release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.0.
+
 #### *v0.1.0*
 
 Release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2023 Yuri Grachev
+Copyright (c) 2019-2024 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:
 

package/index.js

@@ -1,11 +1,18 @@
-// [v0.1.010-20230730]
+// [v0.1.012-20240624]
 
 // === module init block ===
 
+const {
+  TXmlContentParseOptions,
+  DEF_XML_PARSE_OPTIONS,
+} = require('./lib/xObj-defs');
+
 // === module extra block (helper functions) ===
 
 // === module main block ===
 
 // === module exports block ===
 
-module.exports = require('./lib/xObj-lib.js');
+module.exports = require('./lib/xObj-lib');
+module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
+module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;

package/lib/xObj-defs.js

@@ -0,0 +1,166 @@
+// [v0.1.060-20240623]
+
+// === module init block ===
+
+const {
+  //valueToIndex,
+  //readAsString, readAsBoolEx, readAsNumberEx,
+  //isNullOrUndef,
+  //isArray, isObject,
+  isPlainObject, //readAsListS,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+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 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,
+  declarationKey: '__decl',
+  attributesKey: XOBJ_DEF_ATTR_TNAME,
+  textKey: XOBJ_DEF_PARAM_TNAME,
+  commentKey: '__note',
+  cdataKey: '__cdata',
+  nameKey: '__name',
+  typeKey: '__type',
+  parentKey: 'parent',
+  elementsKey: 'items',
+  ignoreDeclaration: false,
+  ignoreDocType: false,
+  ignoreInstractions: false,
+  ignoreText: false,
+  ignoreComments: false,
+  ignoreCData: false,
+  fullTagEmptyElement: true,
+  addParent: false,
+  trim: true,
+  spaces: 2,
+};
+
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+class TXmlContentParseOptions {
+  #_options = null;
+
+  constructor(param){
+    this.#_options = TXmlContentParseOptions.createNewOptionsSet(param);
+  }
+
+  get settings(){ return this.#_options }
+
+  get xml2js(){
+    let _settings = this.#_options;
+    return {
+      compact: _settings.compact,
+      declarationKey: _settings.declarationKey,
+      attributesKey: _settings.attributesKey,
+      textKey: _settings.textKey,
+      commentKey: _settings.commentKey,
+      cdataKey: _settings.cdataKey,
+      nameKey: _settings.nameKey,
+      typeKey: _settings.typeKey,
+      parentKey: _settings.parentKey,
+      elementsKey: _settings.elementsKey,
+      ignoreDeclaration: _settings.ignoreDeclaration,
+      ignoreDocType: _settings.ignoreDocType,
+      ignoreInstraction: _settings.ignoreInstractions,
+      ignoreText: _settings.ignoreText,
+      ignoreComment: _settings.ignoreComments,
+      ignoreCData: _settings.ignoreCData,
+      addParent: _settings.addParent,
+      trim: _settings.trim,
+    };
+  }
+
+  get js2xml(){
+    let _settings = this.#_options;
+    return {
+      compact: _settings.compact,
+      declarationKey: _settings.declarationKey,
+      attributesKey: _settings.attributesKey,
+      textKey: _settings.textKey,
+      commentKey: _settings.commentKey,
+      cdataKey: _settings.cdataKey,
+      nameKey: _settings.nameKey,
+      typeKey: _settings.typeKey,
+      parentKey: _settings.parentKey,
+      elementsKey: _settings.elementsKey,
+      ignoreDeclaration: _settings.ignoreDeclaration,
+      ignoreDocType: _settings.ignoreDocType,
+      ignoreInstraction: _settings.ignoreInstractions,
+      ignoreText: _settings.ignoreText,
+      ignoreComment: _settings.ignoreComments,
+      ignoreCData: _settings.ignoreCData,
+      fullTagEmptyElement: _settings.fullTagEmptyElement,
+      spaces: _settings.spaces,
+    };
+  }
+
+  static createNewOptionsSet(opt){
+    if (opt instanceof TXmlContentParseOptions) {
+      opt = opt.settings;
+    } else if (isPlainObject(opt)) {
+      opt = isPlainObject(opt.settings) ? opt.settings : opt;
+    } else {
+      opt = DEF_XML_PARSE_OPTIONS;
+    };
+    return {
+      compact: opt.compact,
+      declarationKey: opt.declarationKey,
+      attributesKey: opt.attributesKey,
+      textKey: opt.textKey,
+      commentKey: opt.commentKey,
+      cdataKey: opt.cdataKey,
+      nameKey: opt.nameKey,
+      typeKey: opt.typeKey,
+      parentKey: opt.parentKey,
+      elementsKey: opt.elementsKey,
+      ignoreDeclaration: opt.ignoreDeclaration,
+      ignoreDocType: opt.ignoreDocType,
+      ignoreInstractions: opt.ignoreInstractions,
+      ignoreText: opt.ignoreText,
+      ignoreComments: opt.ignoreComments,
+      ignoreCData: opt.ignoreCData,
+      fullTagEmptyElement: opt.fullTagEmptyElement,
+      addParent: opt.addParent,
+      trim: opt.trim,
+      spaces: opt.spaces,
+    };
+  }
+
+}
+
+// === 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.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
+
+module.exports.TXmlContentParseOptions = TXmlContentParseOptions;

package/lib/xObj-lib.js

@@ -1,14 +1,24 @@
-// [v0.1.058-20230730]
+// [v0.1.063-20240624]
 
 // === module init block ===
 
 const {
-  valueToIndex,
+  valueToIndex, valueToIDString,
   readAsString, readAsBoolEx, readAsNumberEx,
   isNullOrUndef,
-  isArray, isObject, isPlainObject, readAsListS,
+  isInteger,
+  isArray, isObject, isPlainObject,
+  readAsListS,
 } = require('@ygracs/bsfoc-lib-js');
 
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
 const XOBJ_DEF_PARAM_TNAME = '__text';
 const XOBJ_DEF_ATTR_TNAME = '__attr';
 
@@ -26,56 +36,37 @@ 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,
-  declarationKey: '__decl',
-  attributesKey: XOBJ_DEF_ATTR_TNAME,
-  textKey: XOBJ_DEF_PARAM_TNAME,
-  commentKey: '__note',
-  cdataKey: '__cdata',
-  nameKey: '__name',
-  typeKey: '__type',
-  parentKey: 'parent',
-  elementsKey: 'items',
-  ignoreDeclaration: false,
-  ignoreDocType: false,
-  ignoreInstractions: false,
-  ignoreText: false,
-  ignoreComments: false,
-  ignoreCData: false,
-  fullTagEmptyElement: true,
-  addParent: false,
-  trim: true,
-  spaces: 2,
-};
-
-// === module extra block (helper functions) ===
-
-// === module main block (function definitions) ===
+/***
+ * (* function definitions *)
+ */
 
 function evalXObjEName(value){
+  //return valueToIDString(value); // // TODO: [?]
   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;
-          };
+  switch (typeof name) {
+    case 'number' : {
+      if (valueToIndex(name) === -1) name = null;
+      break;
+    }
+    case 'string' : {
+      name = name.trim();
+      if (name !== '') {
+        let value = Number(name);
+        if (!Number.isNaN(value)) {
+          name = (
+            value < 0 || !isInteger(value)
+            ? null
+            : value
+          );
         };
-        break;
-      }
-      default: {
+      } else {
         name = null;
-        break;
-      }
-    };
+      };
+      break;
+    }
+    default: {
+      name = null;
+    }
   };
   return name;
 };
@@ -131,6 +122,14 @@ function genXObjENameDescr(value){
   return result;
 };
 
+/**
+ * @function getXObjElement
+ * @param {object}
+ * @param {ID_STRING}
+ * @returns {?object}
+ * @throws {TypeError}
+ * @description Extracts an element from a given object by its key.
+ */
 function getXObjElement(obj, name){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -153,6 +152,14 @@ function getXObjElement(obj, name){
   return obj[key] !== undefined ? obj[key] : null;
 };
 
+/**
+ * @function getXObjAttributes
+ * @param {object}
+ * @param {ID_STRING} [key]
+ * @returns {?object}
+ * @throws {TypeError}
+ * @description Extracts an attributes from a given object by its key.
+ */
 function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
   let result = null;
   try {
@@ -172,6 +179,14 @@ function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME){
   return isPlainObject(result) ? result : null;
 };
 
+/**
+ * @function addXObjElement
+ * @param {object}
+ * @param {ID_STRING}
+ * @returns {?object}
+ * @throws {TypeError}
+ * @description Adds an element addressed by its key to a given object.
+ */
 function addXObjElement(obj, name){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -212,6 +227,17 @@ function addXObjElement(obj, name){
   };
 };
 
+/**
+ * @function insertXObjElement
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {object} [opt]
+ * @param {bool} [opt.force=false]
+ * @param {bool} [opt.ripOldies=false]
+ * @returns {?object}
+ * @throws {TypeError}
+ * @description Inserts an element addressed by its key into a given object.
+ */
 function insertXObjElement(obj, name, opt){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -247,6 +273,14 @@ function insertXObjElement(obj, name, opt){
   return isACCEPTED ? prop : null;
 };
 
+/**
+ * @function deleteXObjElement
+ * @param {object}
+ * @param {ID_STRING}
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Deletes an element addressed by its key from a given object.
+ */
 function deleteXObjElement(obj, name){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -271,6 +305,14 @@ function deleteXObjElement(obj, name){
   return result;
 };
 
+/**
+ * @function deleteXObjElementEx
+ * @param {object}
+ * @param {ID_STRING}
+ * @returns {object}
+ * @throws {TypeError}
+ * @description Deletes an element addressed by its key from a given object.
+ */
 function deleteXObjElementEx(obj, name){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -299,6 +341,15 @@ function deleteXObjElementEx(obj, name){
   };
 };
 
+/**
+ * @function renameXObjElement
+ * @param {object}
+ * @param {ID_STRING} - old key
+ * @param {ID_STRING} - new key
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Renames an element addressed by its key.
+ */
 function renameXObjElement(obj, name, newName){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -332,6 +383,15 @@ function renameXObjElement(obj, name, newName){
   return result;
 };
 
+/**
+ * @function checkXObjAttribute
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Checks wheter an attribute is exists.
+ */
 function checkXObjAttribute(obj, attr = '', key){
   if (typeof attr !== 'string') {
     let err = new TypeError(XOBJ_TE_NSTR_EMSG);
@@ -356,6 +416,15 @@ function checkXObjAttribute(obj, attr = '', key){
   return result;
 };
 
+/**
+ * @function deleteXObjAttribute
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Deletes an attribute addressed by a given key.
+ */
 function deleteXObjAttribute(obj, attr = '', key){
   if (typeof attr !== 'string') {
     let err = new TypeError(XOBJ_TE_NSTR_EMSG);
@@ -377,6 +446,14 @@ function deleteXObjAttribute(obj, attr = '', key){
   return result;
 };
 
+/**
+ * @function readXObjParamRaw
+ * @param {object}
+ * @param {ID_STRING} [key]
+ * @returns {any}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -393,6 +470,15 @@ function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME){
   return _key !== '' ? obj[_key] : undefined;
 };
 
+/**
+ * @function writeXObjParamRaw
+ * @param {object}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -414,6 +500,15 @@ function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME){
   return isSUCCEED;
 };
 
+/**
+ * @function readXObjAttrRaw
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {ID_STRING} [key]
+ * @returns {any}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttrRaw(obj, attr = '', key){
   if (typeof attr !== 'string') {
     let err = new TypeError(XOBJ_TE_NSTR_EMSG);
@@ -430,6 +525,16 @@ function readXObjAttrRaw(obj, attr = '', key){
   if (objAttr !== null && attrName !== '') return objAttr[attrName];
 };
 
+/**
+ * @function writeXObjAttrRaw
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME){
   if (typeof attr !== 'string') {
     let err = new TypeError(XOBJ_TE_NSTR_EMSG);
@@ -462,6 +567,14 @@ function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME){
   return isSUCCEED;
 };
 
+/**
+ * @function readXObjParam
+ * @param {object}
+ * @param {ID_STRING} [key]
+ * @returns {string}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParam(obj, key){
   let result = undefined;
   try {
@@ -484,6 +597,15 @@ function readXObjParam(obj, key){
   });
 };
 
+/**
+ * @function readXObjParam
+ * @param {object}
+ * @param {bool}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParamAsBool(obj, defValue, key){
   let result = undefined;
   try {
@@ -502,6 +624,15 @@ function readXObjParamAsBool(obj, defValue, key){
   return readAsBoolEx(result, defValue);
 };
 
+/**
+ * @function readXObjParam
+ * @param {object}
+ * @param {number}
+ * @param {ID_STRING} [key]
+ * @returns {number}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParamAsNum(obj, defValue, key){
   let result = undefined;
   try {
@@ -520,6 +651,15 @@ function readXObjParamAsNum(obj, defValue, key){
   return readAsNumberEx(result, defValue);
 };
 
+/**
+ * @function readXObjParam
+ * @param {object}
+ * @param {string}
+ * @param {ID_STRING} [key]
+ * @returns {string}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParamAsStr(obj, defValue, key){
   let result = undefined;
   try {
@@ -535,13 +675,22 @@ function readXObjParamAsStr(obj, defValue, key){
       }
     };
   };
-  return readAsString(result, defValue, {
+  return readAsString(result, {
     useTrim: false,
     numberToString: true,
     boolToString: true,
+    defValue,
   });
 };
 
+/**
+ * @function readXObjParam
+ * @param {object}
+ * @param {ID_STRING} [key]
+ * @returns {index}
+ * @throws {TypeError}
+ * @description Extracts a parameter from a given object.
+ */
 function readXObjParamAsIndex(obj, key){
   let result = undefined;
   try {
@@ -560,6 +709,15 @@ function readXObjParamAsIndex(obj, key){
   return valueToIndex(result);
 };
 
+/**
+ * @function writeXObjParam
+ * @param {object}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParam(obj, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -585,6 +743,16 @@ function writeXObjParam(obj, value, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjParamAsBool
+ * @param {object}
+ * @param {any}
+ * @param {bool}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParamAsBool(obj, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -606,6 +774,16 @@ function writeXObjParamAsBool(obj, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjParamAsNum
+ * @param {object}
+ * @param {any}
+ * @param {number}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParamAsNum(obj, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -627,6 +805,15 @@ function writeXObjParamAsNum(obj, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjParamAsIndex
+ * @param {object}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParamAsIndex(obj, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -648,6 +835,16 @@ function writeXObjParamAsIndex(obj, value, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjParamEx
+ * @param {object}
+ * @param {any}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjParamEx(obj, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -656,10 +853,11 @@ function writeXObjParamEx(obj, value, defValue, key){
       numberToString: true,
       boolToString: true,
     });
-    const _value = readAsString(value, _defValue, {
+    const _value = readAsString(value, {
       useTrim: false,
       numberToString: true,
       boolToString: true,
+      defValue: _defValue,
     });
     try {
       isSUCCEED = writeXObjParamRaw(obj, _value, key);
@@ -678,6 +876,15 @@ function writeXObjParamEx(obj, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function readXObjAttr
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {ID_STRING} [key]
+ * @returns {string}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttr(obj, attr, key){
   let result = undefined;
   try {
@@ -700,6 +907,16 @@ function readXObjAttr(obj, attr, key){
   });
 };
 
+/**
+ * @function readXObjAttrAsBool
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {bool}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttrAsBool(obj, attr, defValue, key){
   let result = undefined;
   try {
@@ -718,6 +935,16 @@ function readXObjAttrAsBool(obj, attr, defValue, key){
   return readAsBoolEx(result, defValue);
 };
 
+/**
+ * @function readXObjAttrAsNum
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {number}
+ * @param {ID_STRING} [key]
+ * @returns {number}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttrAsNum(obj, attr, defValue, key){
   let result = undefined;
   try {
@@ -736,6 +963,16 @@ function readXObjAttrAsNum(obj, attr, defValue, key){
   return readAsNumberEx(result, defValue);
 };
 
+/**
+ * @function readXObjAttrAsStr
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {string}
+ * @param {ID_STRING} [key]
+ * @returns {string}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttrAsStr(obj, attr, defValue, key){
   let result = undefined;
   try {
@@ -751,13 +988,23 @@ function readXObjAttrAsStr(obj, attr, defValue, key){
       }
     };
   };
-  return readAsString(result, defValue, {
+  return readAsString(result, {
     useTrim: true,
     numberToString: true,
     boolToString: true,
+    defValue,
   });
 };
 
+/**
+ * @function readXObjAttrAsIndex
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {ID_STRING} [key]
+ * @returns {index}
+ * @throws {TypeError}
+ * @description Extracts an attribute from a given object.
+ */
 function readXObjAttrAsIndex(obj, attr, key){
   let result = undefined;
   try {
@@ -776,6 +1023,16 @@ function readXObjAttrAsIndex(obj, attr, key){
   return valueToIndex(result);
 };
 
+/**
+ * @function writeXObjAttr
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttr(obj, attr, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -801,6 +1058,17 @@ function writeXObjAttr(obj, attr, value, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjAttrAsBool
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {bool}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttrAsBool(obj, attr, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -822,6 +1090,17 @@ function writeXObjAttrAsBool(obj, attr, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjAttrAsNum
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {number}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttrAsNum(obj, attr, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -843,6 +1122,16 @@ function writeXObjAttrAsNum(obj, attr, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjAttrAsIndex
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttrAsIndex(obj, attr, value, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -864,6 +1153,17 @@ function writeXObjAttrAsIndex(obj, attr, value, key){
   return isSUCCEED;
 };
 
+/**
+ * @function writeXObjAttrEx
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {any}
+ * @param {any}
+ * @param {ID_STRING} [key]
+ * @returns {bool}
+ * @throws {TypeError}
+ * @description Writes a parameter into a given object.
+ */
 function writeXObjAttrEx(obj, attr, value, defValue, key){
   let isSUCCEED = false;
   if (value !== undefined) {
@@ -872,10 +1172,11 @@ function writeXObjAttrEx(obj, attr, value, defValue, key){
       numberToString: true,
       boolToString: true,
     });
-    const _value = readAsString(value, _defValue, {
+    const _value = readAsString(value, {
       useTrim: true,
       numberToString: true,
       boolToString: true,
+      defValue: _defValue,
     });
     try {
       isSUCCEED = writeXObjAttrRaw(obj, attr, _value, key);
@@ -894,6 +1195,15 @@ function writeXObjAttrEx(obj, attr, value, defValue, key){
   return isSUCCEED;
 };
 
+/**
+ * @function insertXObjElements
+ * @param {object}
+ * @param {...ID_STRING} args - list of a keys
+ * @param {object} [opt]
+ * @returns {number}
+ * @throws {TypeError}
+ * @description Inserts an elements into a given object.
+ */
 function insertXObjElements(obj, ...args){
   if (!isPlainObject(obj)) {
     let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
@@ -914,6 +1224,17 @@ function insertXObjElements(obj, ...args){
   return count;
 };
 
+/**
+ * @function insertXObjEList
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {object} [opt]
+ * @param {bool} [opt.force=false]
+ * @param {bool} [opt.ripOldies=false]
+ * @returns {?any}
+ * @throws {TypeError}
+ * @description Inserts a list elements into a given object.
+ */
 function insertXObjEList(obj, name, opt){
   let err = null;
   if (!isPlainObject(obj)) {
@@ -953,6 +1274,16 @@ function insertXObjEList(obj, name, opt){
   return isACCEPTED ? item  : null;
 };
 
+/**
+ * @function insertXObjEChain
+ * @param {object}
+ * @param {ID_STRING}
+ * @param {...ID_STRING} args - a list of keys
+ * @param {object} [opt]
+ * @returns {?any}
+ * @throws {TypeError}
+ * @description Inserts a chain of an elements into a given object.
+ */
 function insertXObjEChain(obj, ...args){
   if (!isPlainObject(obj)) {
     let err = new TypeError(XOBJ_TE_NPOBJ_EMSG);
@@ -977,106 +1308,14 @@ function insertXObjEChain(obj, ...args){
   return isSUCCEED ? curObj : null;
 };
 
-// === module main block (class definitions) ===
-
-class TXmlContentParseOptions {
-  #_options = null;
-
-  constructor(param){
-    this.#_options = TXmlContentParseOptions.createNewOptionsSet(param);
-  }
-
-  get settings(){ return this.#_options }
-
-  get xml2js(){
-    let _settings = this.#_options;
-    return {
-      compact: _settings.compact,
-      declarationKey: _settings.declarationKey,
-      attributesKey: _settings.attributesKey,
-      textKey: _settings.textKey,
-      commentKey: _settings.commentKey,
-      cdataKey: _settings.cdataKey,
-      nameKey: _settings.nameKey,
-      typeKey: _settings.typeKey,
-      parentKey: _settings.parentKey,
-      elementsKey: _settings.elementsKey,
-      ignoreDeclaration: _settings.ignoreDeclaration,
-      ignoreDocType: _settings.ignoreDocType,
-      ignoreInstraction: _settings.ignoreInstractions,
-      ignoreText: _settings.ignoreText,
-      ignoreComment: _settings.ignoreComments,
-      ignoreCData: _settings.ignoreCData,
-      addParent: _settings.addParent,
-      trim: _settings.trim,
-    };
-  }
-
-  get js2xml(){
-    let _settings = this.#_options;
-    return {
-      compact: _settings.compact,
-      declarationKey: _settings.declarationKey,
-      attributesKey: _settings.attributesKey,
-      textKey: _settings.textKey,
-      commentKey: _settings.commentKey,
-      cdataKey: _settings.cdataKey,
-      nameKey: _settings.nameKey,
-      typeKey: _settings.typeKey,
-      parentKey: _settings.parentKey,
-      elementsKey: _settings.elementsKey,
-      ignoreDeclaration: _settings.ignoreDeclaration,
-      ignoreDocType: _settings.ignoreDocType,
-      ignoreInstraction: _settings.ignoreInstractions,
-      ignoreText: _settings.ignoreText,
-      ignoreComment: _settings.ignoreComments,
-      ignoreCData: _settings.ignoreCData,
-      fullTagEmptyElement: _settings.fullTagEmptyElement,
-      spaces: _settings.spaces,
-    };
-  }
-
-  static createNewOptionsSet(opt){
-    if (opt instanceof TXmlContentParseOptions) {
-      opt = opt.settings;
-    } else if (isPlainObject(opt)) {
-      opt = isPlainObject(opt.settings) ? opt.settings : opt;
-    } else {
-      opt = DEF_XML_PARSE_OPTIONS;
-    };
-    return {
-      compact: opt.compact,
-      declarationKey: opt.declarationKey,
-      attributesKey: opt.attributesKey,
-      textKey: opt.textKey,
-      commentKey: opt.commentKey,
-      cdataKey: opt.cdataKey,
-      nameKey: opt.nameKey,
-      typeKey: opt.typeKey,
-      parentKey: opt.parentKey,
-      elementsKey: opt.elementsKey,
-      ignoreDeclaration: opt.ignoreDeclaration,
-      ignoreDocType: opt.ignoreDocType,
-      ignoreInstractions: opt.ignoreInstractions,
-      ignoreText: opt.ignoreText,
-      ignoreComments: opt.ignoreComments,
-      ignoreCData: opt.ignoreCData,
-      fullTagEmptyElement: opt.fullTagEmptyElement,
-      addParent: opt.addParent,
-      trim: opt.trim,
-      spaces: opt.spaces,
-    };
-  }
-
-}
+/***
+ * (* class definitions *)
+ */
 
 // === module exports block ===
 
 exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
 exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
-exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
-
-exports.TXmlContentParseOptions = TXmlContentParseOptions;
 
 exports.evalXObjEName = evalXObjEName;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -12,6 +12,7 @@
   "files": [
     "doc/xObj.md",
     "lib/xObj-lib.js",
+    "lib/xObj-defs.js",
     "index.js",
     "CHANGELOG.md"
   ],
@@ -21,16 +22,20 @@
     "test-xobj:c1": "jest xObj-lib.1",
     "test-xobj:c2": "jest xObj-lib.2",
     "test-xobj:c3": "jest xObj-lib.3",
-    "test-xobj:c4": "jest xObj-lib.4"
+    "test-xobj:c4": "jest xObj-lib.4",
+    "build-doc-md": "jsdoc2md",
+    "build-doc-html": "jsdoc"
   },
   "imports": {
-    "#lib/*": "./lib/*"
+    "#lib/*": "./lib/*",
+    "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.1.4"
+    "@ygracs/bsfoc-lib-js": "^0.2.1"
   },
   "devDependencies": {
-    "jest": "^29.6.1",
+    "jest": "^29.7.0",
+    "jsdoc-to-markdown": "^8.0.1",
     "minimist": "^1.2.8"
   }
 }