@ygracs/xobj-lib-js 0.0.13

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+#### *v0.0.13*
+
+Pre-release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.2.
+
+#### *v0.0.12*
+
+Pre-release version.
+
+> - some fixes in 'xObj-lib.js' module;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.1.
+
+#### *v0.0.11*
+
+Pre-release version.
+
+> - remove dependency on `@ygracs/xml-js6` module;
+> - fixed exports in `$module/index.js`.
+
+#### *v0.0.10*
+
+Pre-release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.0.
+
+#### *v0.0.1-v0.0.9*
+
+Pre-release version.

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2019-2022 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/README.md

@@ -0,0 +1,9 @@
+|***rev.*:**|0.1.0|
+|:---|---:|
+|***date***:|2022-05-18|
+
+## Introduction
+
+This module provide a helper functions for object manipulation. It was primarily written to work with a XML-parse provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
+
+> Note: for more see `xObj.md` in the project `doc` directory.

package/doc/xObj.md

@@ -0,0 +1,339 @@
+>|***rev.*:**|0.1.10|
+>|:---|---:|
+>|date:|2022-05-23|
+
+## Intoduction
+
+This paper describes a functions provided by `xObj.js` module.
+
+> Note: This module was primarily written to deal with a XML-parse provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
+
+## Content
+
+### Base constants
+
+|name|type|value|
+|:---|---|---:|
+|XOBJ_DEF_PARAM_TNAME|`string`|`__text`|
+|XOBJ_DEF_ATTR_TNAME|`string`|`__attr`|
+|DEF_XML_PARSE_OPTIONS|`object`|---|
+
+#### **DEF\_XML\_PARSE_OPTIONS**
+
+This constant object provided by the module contains a default settings of options for XML-parser module used within.
+
+The settings listed in the table below:
+
+|name|type|value|
+|:---|---|:---|
+|compact|`boolean`|`true`|
+|declarationKey|`string`|`__decl`|
+|attributesKey|`string`|`__attr`|
+|textKey|`string`|`__text`|
+|commentKey|`string`|`__note`|
+|cdataKey|`string`|`__cdata`|
+|nameKey|`string`|`__name`|
+|typeKey|`string`|`__type`|
+|parentKey|`string`|`parent`|
+|elementsKey|`string`|`items`|
+|ignoreDeclaration|`boolean`|`false`|
+|ignoreDocType|`boolean`|`false`|
+|ignoreInstractions|`boolean`|`false`|
+|ignoreText|`boolean`|`false`|
+|ignoreComments|`boolean`|`false`|
+|ignoreCData|`boolean`|`false`|
+|fullTagEmptyElement|`boolean`|`true`|
+|addParent|`boolean`|`false`|
+|trim|`boolean`|`true`|
+|spaces|`number`|`2`|
+
+### Base functions for read and write an object parameter
+
+> Note:
+> If a `key` parameter given to the function is `undefined` or is not a type of `string`, 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 trow a `TypeError` exception.
+
+#### **readXObjParam(object\[, key])**
+
+This function returns a value of an object parameter. The value is of a `string` type.
+
+#### **readXObjParamAsBool(object\[, defValue \[, key]])**
+
+This function reads a value of an object parameter and returns it as a `boolean`.
+
+The `defValue` must be of a `boolean` type, if else the `false` is used.
+
+#### **readXObjParamAsNum(object\[, defValue \[, key])**
+
+This function reads a value of an object parameter and returns it as a `number`.
+
+The `defValue` must be of a `number` type, if else the `0` is used.
+
+#### **readXObjParamAsStr(object\[, defValue \[, key])**
+
+This function reads a value of an object parameter and returns it as a `string`.
+
+The `defValue` must be of a `string` type, if else the empty string is used.
+
+#### **readXObjParamAsIndex(object\[, key])**
+
+This function reads a value of an object parameter and try to convert it to a valid index value. If function failed, `-1` is returned.
+
+> Note: *for use in this case, index is validated as a non-negative integer number.*
+
+#### **writeXObjParam(object, value\[, key])**
+
+This function sets object parameter to a given value and if succeed returns `true`.
+
+#### **writeXObjParamAsBool(object, value\[, defValue\[, key]])**
+
+This function writes a given `boolean` value of an object parameter.
+
+The `defValue` must be of a `boolean` type, if else the `false` is used.
+
+#### **writeXObjParamAsNum(object, value\[, defValue\[, key]])**
+
+This function writes a given `number` value of an object parameter.
+
+The `defValue` must be of a `number` type, if else the `0` is used.
+
+#### **writeXObjParamAsIndex(object, value\[, key])**
+
+This function try to interpret a given value as a valid index value and, if succeed, writes it into an object parameter.
+
+#### **writeXObjParamEx(object, value\[, defValue\[, key]])**
+
+This function sets object parameter to a given value and if succeed returns `true`.
+
+### Base functions for read or write object attributes
+
+> Note:
+> If a `key` parameter given to the function is `undefined` or is not a type of `string`, 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 trow a `TypeError` exception.
+>
+> If an `attr` parameter given to the function is not a 'string' type, the function will trow a `TypeError` exception.
+
+#### **readXObjAttr(object, attr\[, key])**
+
+This function returns a value of an object attribute. The value is of a `string` type.
+
+#### **readXObjAttrAsBool(object, attr\[, defValue\[, key]])**
+
+This function reads a value of an object attribute and returns it as a `boolean`.
+
+The `defValue` must be of a `boolean` type, if else the `false` is used.
+
+#### **readXObjAttrAsNum(object, attr\[, defValue\[, key]])**
+
+This function reads a value of an object attribute and returns it as a `number`.
+
+The `defValue` must be of a `number` type, if else the `0` is used.
+
+#### **readXObjAttrAsStr(object, attr\[, defValue\[, key]])**
+
+This function returns a value of an object attribute. The value is of a `string` type.
+
+The `defValue` must be of a `string` type, if else the empty string is used.
+
+#### **readXObjAttrAsIndex(object, attr\[,  key])**
+
+This function reads a value of an object attribute and try to convert it to a valid index value. If function failed, `-1` is returned.
+
+> Note: *for use in this case, index is validated as a non-negative integer number.*
+
+#### **writeXObjAttr(object, attr, value\[, key])**
+
+This function sets object attribute to a given value and if succeed returns `true`.
+
+>Note: a value must be of a `string` type or can be converted to a string
+>
+
+#### **writeXObjAttrAsBool(object, attr, value\[, defValue\[, key]])**
+
+This function writes a given `boolean` value of an object attribute.
+
+The `defValue` must be of a `boolean` type, if else the `false` is used.
+
+#### **writeXObjAttrAsNum(object, attr, value\[, defValue\[, key]])**
+
+This function writes a given `number` value of an object attribute.
+
+The `defValue` must be of a `number` type, if else the `0` is used.
+
+#### **writeXObjAttrAsIndex(object, attr, value\[, key])**
+
+This function try to interpret a given value as a valid index value and, if succeed, writes it into an object attribute.
+
+#### **writeXObjAttrEx(object, attr, value\[, defValue\[, key]])**
+
+This function sets object attribute to a given value and if succeed returns `true`.
+
+### Special functions for read and write an object parameter
+
+> Note:
+> If a `key` parameter given to the function is `undefined` or is not a type of `string`, 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 trow a `TypeError` exception.
+
+#### **readXObjParamRaw(object\[, key])**
+
+This is a special function that returns a value of an object parameter as "IT IS".
+
+#### **writeXObjParamRaw(object, value\[, key])**
+
+This is a special function that writes a given value of an object parameter as "IT IS".
+
+### Special functions for read or write object attributes
+
+> Note:
+> If a `key` parameter given to the function is `undefined` or is not a type of `string`, 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 trow a `TypeError` exception.
+
+#### **readXObjAttrRaw(object, attr\[, key])**
+
+This is a special function that returns a value of an object attribute as "IT IS".
+
+#### **writeXObjAttrRaw(object, attr, value\[, key])**
+
+This is a special function that writes a given value of an object attribute as "IT IS".
+
+#### **getXObjAttributes(object, name)**
+
+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.
+
+### Other functions
+
+#### **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 trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+#### **insertXObjElement(object, name\[, options])**
+
+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 trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+An `options.force` parameter modifies the functions behavoir as follows:
+- if not given it is set to `false`(default value);
+- when set to `true`, the addressed element will be replaced with an empty element.
+- when set to `false`, if the target element exists and is not a type of an `object`, the function will failed.
+
+An `options.rip_oldies` parameter applied only if `options.force` is `true`. And if set to `false` (default value), it prevents a replacement of an element which exists  and has a type of an `object`.
+
+#### **addXObjElement(object, name)**
+
+This function adds an element given by `name` parameter to a members of the given objectand and returns an `object` that represents a status of the operation.
+
+> the function will trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+The status of an operation contains 2 fields:
+
+- `isSucceed` - `boolean` value;
+- `item` - an item which was added or a `null`.
+
+#### **deleteXObjElement(object, name)**
+
+This function deletes an element addressed by `name` parameter from a given object. If succeed `true` is returned.
+
+> the function will trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+#### **renameXObjElement(object, oldName, newName)**
+
+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 trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `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.
+
+#### **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 trow a `TypeError` exception.
+>
+> For use of `options` parameter see `insertXObjElement`.
+
+#### **insertXObjEList(object, name\[, options])**
+
+This function inserts an elements list named by a `name` parameter into a given object. If succeed the list will be returned or `null` in opposite.
+
+> the function will trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+An `options.force` parameter modifies the functions behavoir as follows:
+- if not given it is set to `false`(default value);
+- when set to `true`, the addresssed element will be replaced with an empty elements list.
+- when set to `false`, if the target element type is an `object`, the function will wrapps it in the list.
+- when set to `false`, if the target element exists and is not a type of an `array` or an `object`, the function will failed.
+
+An `options.rip_oldies` parameter applied only if `options.force` is `true`. And if set to `false` (default value), it prevents a replacement of an element which exists and has a type of an `array`.
+
+#### **insertXObjEChain(object, names_list\[, options])**
+
+This function inserts a chain of the elements listed by `names_list`. If succeed the last inserted element will be returned or `null` if failed.
+
+> If an `object` parameter given to the function is not a plain object, the function will trow a `TypeError` exception.
+>
+> For use of `options` parameter see `insertXObjElement`.
+
+#### **deleteXObjElementEx(object, name)**
+
+This function deletes an element adderssed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
+
+> the function will trow a `TypeError` if:
+> - `object` parameter is not a plain object;
+> - `name` parameter is not a non-empty string.
+
+The status of an operation contains 2 fields:
+
+- `isSucceed` - `boolean` value;
+- `item` - an item which was deleted (only for objects) or a `null`.
+
+### Base class
+
+#### **TXmlContentParseOptions**
+
+This class implements an interface for handling XML-parse options.
+
+##### class constructor
+
+The class constructor creates a new instance of the class. It receives arguments listed below:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object.|
+|`options`|`object`|---|an options settings.|
+
+##### class properties
+
+The table below describes a properties of a `TXmlContentParseOptions` class:
+
+|name|read only|description|
+|:---|---|:---|
+|settings|yes|presents a current options|
+|xml2js|yes|returns an options for an XML-to-JS converter|
+|js2xml|yes|returns an options for an JS-to-XML converter|
+
+##### class methods (*static*)
+
+###### **createNewOptionsSet(obj)**
+
+This method transforms a given object to a set of accepted parser options.

package/index.js

@@ -0,0 +1,14 @@
+// [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');

package/lib/xObj-lib.js

@@ -0,0 +1,548 @@
+// [v0.1.022-20220822]
+
+// === module init block ===
+
+const {
+  valueToIndex, readAsBool, readAsString,
+  readAsBoolEx, readAsNumberEx, isNotEmptyString, isNullOrUndef,
+  isArray, isObject, isPlainObject, readAsListS,
+} = require('@ygracs/bsfoc-lib-js');
+
+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_ANES_EMSG = '<attr_name> must be a non-empty string';
+const XOBJ_TE_KNES_EMSG = '<key_name> must be a non-empty string';
+
+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 getXObjElement(obj, name){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  // TODO: check type of obj[key_name]
+  return obj[key] !== undefined ? obj[key] : null;
+};
+
+function getXObjAttributes(obj, key_name = XOBJ_DEF_ATTR_TNAME){
+  return getXObjElement(obj, readAsString(key_name, XOBJ_DEF_ATTR_TNAME, true));
+};
+
+function insertXObjElement(obj, name, opt){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let force_act = false;
+  let rip_oldies = false;
+  if (typeof opt === 'boolean') {
+    force_act = opt;
+  } else if (isPlainObject(opt)) {
+    force_act = readAsBool(opt.force, false);
+    if (force_act) rip_oldies = readAsBool(opt.rip_oldies, false);
+  };
+  let isACCEPTED = false;
+  if (isNullOrUndef(obj[key])) {
+    obj[key] = {};
+    isACCEPTED = true;
+  } else if (force_act) {
+    if (rip_oldies || !isPlainObject(obj[key])) obj[key] = {};
+    isACCEPTED = true;
+  } else {
+    isACCEPTED = isPlainObject(obj[key]);
+  };
+  return isACCEPTED ? obj[key] : null;
+};
+
+function addXObjElement(obj, name){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let prop = obj[key];
+  let item = {};
+  let result = false;
+  // // TODO:  consider wheter or not do ops if new_key exists
+  if (isNullOrUndef(prop)) {
+    obj[key] = {};
+    prop = obj[key];
+    result = true;
+  } else if (isPlainObject(prop)) {
+    obj[key] = [ prop, item ];
+    prop = item;
+    result = true;
+  } else if (isArray(prop)) {
+    prop.push(item);
+    prop = item;
+    result = true;
+  };
+  return {
+    isSucceed: result,
+    item: result ? prop : null,
+  };
+};
+
+function deleteXObjElement(obj, name){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let result = false;
+  // // TODO: catch errors in strict mode
+  result = delete obj[key];
+  return result;
+};
+
+function deleteXObjElementEx(obj, name){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let prop = obj[key];
+  let result = false;
+  // // TODO: catch errors in strict mode
+  result = delete obj[key];
+  return {
+    isSucceed: result,
+    item: result && isObject(prop) ? prop : null,
+  };
+};
+
+function renameXObjElement(obj, name, newName){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  const newKey = typeof newName === 'string' ? newName.trim() : '';
+  if (newKey === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let prop = obj[key];
+  let result = false;
+  // // TODO:  consider wheter or not do ops if new_key exists
+  if (prop !== undefined) {
+    if (key === newKey) return isObject(prop) ? true : false;
+    // // TODO: catch errors in strict mode
+    result = delete obj[key];
+    if (result) {
+      obj[newKey] = isObject(prop) ? prop : {};
+    };
+  };
+  return result;
+};
+
+function readXObjParamRaw(obj, key_name = XOBJ_DEF_PARAM_TNAME){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  key_name = readAsString(key_name, XOBJ_DEF_PARAM_TNAME, true);
+  return isNotEmptyString(key_name) ? obj[key_name] : undefined;
+};
+
+function writeXObjParamRaw(obj, value, key_name = XOBJ_DEF_PARAM_TNAME){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  key_name = readAsString(key_name, XOBJ_DEF_PARAM_TNAME, true);
+  let isACCEPTED = isNotEmptyString(key_name);
+  if (isACCEPTED) obj[key_name] = value;
+  return isACCEPTED;
+};
+
+function readXObjAttrRaw(obj, attr, key_name = XOBJ_DEF_ATTR_TNAME){
+  const attrName = typeof attr === 'string' ? attr.trim() : '';
+  if (attrName === '') throw new TypeError(XOBJ_TE_ANES_EMSG);
+  obj = getXObjElement(obj, readAsString(key_name, XOBJ_DEF_ATTR_TNAME, true));
+  return isPlainObject(obj) ? obj[attrName] : undefined ;
+};
+
+function writeXObjAttrRaw(obj, attr, value, key_name = XOBJ_DEF_ATTR_TNAME){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const attrName = typeof attr === 'string' ? attr.trim() : '';
+  if (attrName === '') throw new TypeError(XOBJ_TE_ANES_EMSG);
+  key_name = readAsString(key_name, XOBJ_DEF_ATTR_TNAME, true);
+  let isACCEPTED = isNotEmptyString(key_name);
+  if (isACCEPTED) {
+    if (!isPlainObject(obj[key_name])) obj[key_name] = {};
+    obj[key_name][attrName] = value;
+  };
+  return isACCEPTED;
+};
+
+function readXObjParam(obj, defKey){
+  const param = readXObjParamRaw(obj, defKey);
+  return readAsString(param, {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+  });
+};
+
+function readXObjParamAsBool(obj, defValue = false, defKey){
+  const param = readXObjParamRaw(obj, defKey);
+  return readAsBoolEx(param, defValue);
+};
+
+function readXObjParamAsNum(obj, defValue = 0, defKey){
+  const param = readXObjParamRaw(obj, defKey);
+  return readAsNumberEx(param, defValue);
+};
+
+function readXObjParamAsStr(obj, defValue = '', defKey){
+  const param = readXObjParamRaw(obj, defKey);
+  return readAsString(param, defValue, {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+  });
+};
+
+function readXObjParamAsIndex(obj, defKey){
+  return valueToIndex(readXObjParamRaw(obj, defKey));
+};
+
+function writeXObjParam(obj, value, defKey){
+  const _value = readAsString(value, {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+  });
+  return writeXObjParamRaw(obj, _value, defKey);
+};
+
+function writeXObjParamAsBool(obj, value, defValue = false, defKey){
+  const _value = readAsBoolEx(value, defValue).toString();
+  return writeXObjParamRaw(obj, _value, defKey);
+};
+
+function writeXObjParamAsNum(obj, value, defValue = 0, defKey){
+  const _value = readAsNumberEx(value, defValue).toString();
+  return writeXObjParamRaw(obj, _value, defKey);
+};
+
+function writeXObjParamAsIndex(obj, value, defKey){
+  const _value = valueToIndex(value).toString();
+  return writeXObjParamRaw(obj, _value, defKey);
+};
+
+function writeXObjParamEx(obj, value, defValue, defKey){
+  const _defValue = readAsString(defValue, {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+  });
+  const _value = readAsString(value, _defValue, {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+  });
+  return writeXObjParamRaw(obj, _value, defKey);
+};
+
+function readXObjAttr(obj, name, defKey){
+  const param = readXObjAttrRaw(obj, name, defKey);
+  return readAsString(param, {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+  });
+};
+
+function readXObjAttrAsBool(obj, name, defValue = false, defKey){
+  const param = readXObjAttrRaw(obj, name, defKey);
+  return readAsBoolEx(param, defValue);
+};
+
+function readXObjAttrAsNum(obj, name, defValue = 0, defKey){
+  const param = readXObjAttrRaw(obj, name, defKey);
+  return readAsNumberEx(param, defValue);
+};
+
+function readXObjAttrAsStr(obj, name, defValue = '', defKey){
+  const param = readXObjAttrRaw(obj, name, defKey);
+  return readAsString(param, defValue, {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+  });
+};
+
+function readXObjAttrAsIndex(obj, name, defKey){
+  return valueToIndex(readXObjAttrRaw(obj, name, defKey));
+};
+
+function writeXObjAttr(obj, name, value, defKey){
+  const _value = readAsString(value, {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+  });
+  return writeXObjAttrRaw(obj, name, _value, defKey);
+};
+
+function writeXObjAttrAsBool(obj, name, value, defValue = false, defKey){
+  const _value = readAsBoolEx(value, defValue).toString();
+  return  writeXObjAttrRaw(obj, name, _value, defKey);
+};
+
+function writeXObjAttrAsNum(obj, name, value, defValue = 0, defKey){
+  const _value = readAsNumberEx(value, defValue).toString();
+  return writeXObjAttrRaw(obj, name, _value, defKey);
+};
+
+function writeXObjAttrAsIndex(obj, name, value, defKey){
+  const _value = valueToIndex(value).toString();
+  return writeXObjAttrRaw(obj, name, _value, defKey);
+};
+
+function writeXObjAttrEx(obj, name, value, defValue, defKey){
+  const _defValue = readAsString(defValue, {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+  });
+  const _value = readAsString(value, _defValue, {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+  });
+  return writeXObjAttrRaw(obj, name, _value, defKey);
+};
+
+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();
+    };
+  };
+  const key_names = readAsListS({
+    trim: true,
+    keep_empty: false,
+  }, ...args);
+  for (let key_name of key_names) {
+    if (insertXObjElement(obj, key_name, opt) !== null) count++;
+  };
+  return count;
+};
+
+function insertXObjEList(obj, name, opt){
+  if (!isPlainObject(obj)) throw new TypeError(XOBJ_TE_NPOBJ_EMSG);
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key === '') throw new TypeError(XOBJ_TE_KNES_EMSG);
+  let force_act = false;
+  let rip_oldies = false;
+  if (typeof opt === 'boolean') {
+    force_act = opt;
+  } else if (isPlainObject(opt)) {
+    force_act = readAsBool(opt.force, false);
+    if (force_act) rip_oldies = readAsBool(opt.rip_oldies, false);
+  };
+  let isACCEPTED = false;
+  if (isNullOrUndef(obj[key])) {
+    obj[key] = [];
+    isACCEPTED = true;
+  } else if (force_act) {
+    if (rip_oldies || !isArray(obj[key])) obj[key] = [];
+    isACCEPTED = true;
+  } else {
+    isACCEPTED = isArray(obj[key]);
+    if (!isACCEPTED && isPlainObject(obj[key])) {
+      obj[key] = [ obj[key] ];
+      isACCEPTED = true;
+    };
+  };
+  return isACCEPTED ? obj[key] : 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({
+    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);
+    isSUCCEED = isPlainObject(obj);
+    if (!isSUCCEED) break;
+    curObj = obj;
+  };
+  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,
+    };
+  }
+
+}
+
+// === 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.readXObjParamRaw = readXObjParamRaw;
+exports.readXObjParam = readXObjParam;
+exports.readXObjParamAsBool = readXObjParamAsBool;
+exports.readXObjParamAsNum = readXObjParamAsNum;
+exports.readXObjParamAsStr = readXObjParamAsStr;
+exports.readXObjParamAsIndex = readXObjParamAsIndex;
+exports.writeXObjParamRaw = writeXObjParamRaw;
+exports.writeXObjParam = writeXObjParam;
+exports.writeXObjParamAsBool = writeXObjParamAsBool;
+exports.writeXObjParamAsNum = writeXObjParamAsNum;
+exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
+exports.writeXObjParamEx = writeXObjParamEx;
+
+exports.readXObjAttrRaw = readXObjAttrRaw;
+exports.readXObjAttr = readXObjAttr;
+exports.readXObjAttrAsBool = readXObjAttrAsBool;
+exports.readXObjAttrAsNum = readXObjAttrAsNum;
+exports.readXObjAttrAsStr = readXObjAttrAsStr;
+exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
+exports.writeXObjAttrRaw = writeXObjAttrRaw;
+exports.writeXObjAttr = writeXObjAttr;
+exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
+exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
+exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
+exports.writeXObjAttrEx = writeXObjAttrEx;
+
+exports.getXObjAttributes = getXObjAttributes;
+
+exports.getXObjElement = getXObjElement;
+exports.insertXObjElement = insertXObjElement;
+exports.addXObjElement = addXObjElement;
+exports.deleteXObjElement = deleteXObjElement;
+exports.deleteXObjElementEx = deleteXObjElementEx;
+exports.renameXObjElement = renameXObjElement;
+
+exports.insertXObjElements = insertXObjElements;
+exports.insertXObjEList = insertXObjEList;
+exports.insertXObjEChain = insertXObjEChain;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ygracs/xobj-lib-js",
+  "version": "0.0.13",
+  "description": "A helper library to work with xml-js module",
+  "author": "ygracs <cs70th-om@rambler.ru>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/ygracs/xobj-lib-js.git"
+  },
+  "main": "./index.js",
+  "files": [
+    "doc/xObj.md",
+    "lib/xObj-lib.js",
+    "index.js"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test-xobj": "jest xObj",
+    "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"
+  },
+  "dependencies": {
+    "@ygracs/bsfoc-lib-js": "^0.1.2"
+  },
+  "devDependencies": {
+    "jest": "^27.5.1"
+  }
+}