@ygracs/xobj-lib-js 0.0.13 → 0.0.14-rc2

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+#### *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.
+
+> - `xObj-lib.md` updated;
+> - some fixes in 'xObj-lib.js' module;
+> - changed behavior for `getXObjAttributes` (*see details in docs*);
+> - changed behavior for `readXObjParamRaw` and its siblings (*see details in docs*);
+> - changed behavior for `writeXObjParamRaw` and its siblings (*see details in docs*);
+> - changed behavior for `readXObjAttrRaw` and its siblings (*see details in docs*);
+> - changed behavior for `writeXObjAttrRaw` and its siblings (*see details in docs*);
+> - changed `options` parameter for `insertXObjElement` (*see details in docs*);
+> - changed `options` parameter for `insertXObjEList` (*see details in docs*);
+> - added `checkXObjAttribute` function.
+
 #### *v0.0.13*
 
 Pre-release version.

package/LICENSE

@@ -1,9 +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.
+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.10|
+>|***rev.*:**|0.1.20|
 >|:---|---:|
->|date:|2022-05-23|
+>|date:|2023-02-27|
 
 ## Intoduction
 
@@ -50,9 +50,9 @@ The settings listed in the table below:
 ### 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 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 trow 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])**
 
@@ -109,11 +109,11 @@ This function sets object parameter to a given value and if succeed returns `tru
 ### 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 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 trow a `TypeError` exception.
+> 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 trow 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])**
 
@@ -173,9 +173,9 @@ This function sets object attribute to a given value and if succeed returns `tru
 ### 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 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 trow 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])**
 
@@ -188,9 +188,9 @@ This is a special function that writes a given value of an object parameter as "
 ### 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 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 trow 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,62 +200,95 @@ 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".
 
-#### **getXObjAttributes(object, name)**
+### Other functions for deal with an object attributes
 
-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.
+> 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 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 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 trow a `TypeError` if:
-> - `object` parameter is not a plain object;
+> the function will throw a `TypeError` if:
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `name` parameter is not a non-empty string.
 
-#### **insertXObjElement(object, name\[, options])**
+#### **addXObjElement(object, name)**
 
-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.
+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 trow a `TypeError` if:
-> - `object` parameter is not a plain object;
+> the function will throw a `TypeError` if:
+> - `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 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.
+The status of an operation contains 2 fields:
 
-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`.
+- `isSucceed` - `boolean` value;
+- `item` - an item which was added or a `null`.
 
-#### **addXObjElement(object, name)**
+#### **insertXObjElement(object, name\[, options])**
 
-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.
+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;
+> the function will throw a `TypeError` if:
+> - `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:
+An `options.force` parameter modifies the functions behavior 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.
 
-- `isSucceed` - `boolean` value;
-- `item` - an item which was added or a `null`.
+An `options.ripOldies` 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`.
+
+> NOTE: An `options.rip_oldies` will deprecate. Use `options.ripOldies` instead.
 
 #### **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;
+> the function will throw a `TypeError` if:
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `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;
+> the function will throw a `TypeError` if:
+> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
 > - `oldName` or `newName` parameter is not a non-empty string.
 
 ### Experimental functions
@@ -266,46 +299,48 @@ This function renames an element with a name `oldName` to a name `newName` for t
 
 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.
+> 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])**
 
 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:
+> the function will throw 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.
+An `options.force` parameter modifies the functions behavior 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 elements list.
+- when set to `false`, if the target element type is an `object`, the function will wraps 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`.
+An `options.ripOldies` 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`.
+
+> NOTE: An `options.rip_oldies` will deprecate. Use `options.ripOldies` instead.
 
 #### **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.
+> 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 adderssed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
+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 trow a `TypeError` if:
-> - `object` parameter is not a plain object;
+> the function will throw a `TypeError` if:
+> - `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:
 
 - `isSucceed` - `boolean` value;
-- `item` - an item which was deleted (only for objects) or a `null`.
+- `item` - an item which was deleted (*only for objects*) or a `null`.
 
 ### Base class
 

package/index.js

@@ -1,14 +1,11 @@
-// [v0.1.007-20220524]
+// [v0.1.008-20230227]
 
 // === 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');