@cntwg/xml-lib-js 0.0.23 → 0.0.25

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+#### *v0.0.25*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.0;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.1.
+
+#### *v0.0.24*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.4;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.0;
+> - some fixes in `xmldoc-lib.js` module.
+
 #### *v0.0.23*
 
 Pre-release version.

package/README.md

@@ -1,11 +1,21 @@
-|***rev.*:**|0.1.2|
+|***rev.*:**|0.1.4|
 |:---|---:|
-|***date***:|2022-09-06|
+|***date***:|2023-09-19|
 
 ## Introduction
 
 This module provide a base functionality for handling an XML-documents.
 
+## Use cases
+
+### Installation
+
+`npm install @cntwg/xml-lib-js`
+
+## Description
+
+This module contains the following components:
+
 ### 1. xObj-manipulator
 
 xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` module](https://gitlab.com/ygracs/xobj-lib-js)).
@@ -16,8 +26,6 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 
 	+ `XML_DEF_ROOT_ETAG_NAME`;
 	+ `XML_DEF_PARSE_OPTIONS`;
-	+ `DEF_XML_ROOT_ETAG_NAME` (*will deprecate*);
-	+ `DEF_XML_PARSE_OPTIONS` (*will deprecate*).
 
 - classes:
 

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.20|
+>|***rev.*:**|0.1.22|
 >|:---|---:|
->|date:|2023-03-01|
+>|date:|2023-09-19|
 
 ## Introduction
 
@@ -8,7 +8,7 @@ This paper describes a constants and an object classes provided by `xmldoc-lib.j
 
 ## Module constants
 
-### **DEF\_XML\_PARSE_OPTIONS** or **XML\_DEF\_PARSE_OPTIONS**
+### **XML\_DEF\_PARSE_OPTIONS**
 
 This constant object provided by the module contains a default settings of options for XML-parser module used within.
 
@@ -37,12 +37,10 @@ The settings listed in the table below:
 |`trim`|`boolean`|`true`|
 |`spaces`|`number`|`2`|
 
-### **DEF\_XML\_ROOT\_ETAG_NAME** or **XML\_DEF\_ROOT\_ETAG_NAME**
+### **XML\_DEF\_ROOT\_ETAG_NAME**
 
 This constant defines a default value for naming the root element for XML-document. Its value is `root`.
 
-> WARNING: The constant `DEF\_XML\_ROOT\_ETAG_NAME` will be deprecated. Use `XML\_DEF\_ROOT\_ETAG_NAME` instead.
-
 ## Module classes
 
 ### **TXmlContentParseOptions**
@@ -80,26 +78,32 @@ This class implements a proxy interface for handling attributes of an element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object that holds an attributes|
 |`options`|`object`|---|an options settings|
 
+> NOTE: if `object` parameter is not a plain object the `TypeError` thrown.
+
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
 |:---|---|---:|:---|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (*see description for `XML_DEF_PARSE_OPTIONS`*)|
 
-> NOTE: if `object` parameter is not a plain object the `TypeError` thrown.
-
 #### class properties
 
-|name|read only|description|
-|:---|---|:---|
-|`entries`|yes|returns array of entries for all existing attributes|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|`entries`|`array`|yes|returns an array of entries for all existing attributes|
 
 
 #### class methods
@@ -130,13 +134,19 @@ This class implements a proxy interface for an element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object|
 |`options`|`object`|---|an options settings|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -146,11 +156,11 @@ The `options` structure is listed below:
 
 #### class properties
 
-|property name|read only|description|
-|:---|---|:---|
-|`attributes`|yes|returns an attributes of the element|
-|`name`|yes|returns a tag name of the element|
-|`textValue`|no|represents a value of the element|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|`attributes`|`TXmlAttributesMapper`|yes|returns an attributes of the element|
+|`name`||yes|\<*reserved*>|
+|`textValue`|`string`|no|represents a value of the element|
 
 #### class methods
 
@@ -235,13 +245,19 @@ This class implements a proxy interface for a list of elements.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object of an array type.|
 |`options`|`object`|---|an options settings.|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -253,7 +269,7 @@ The `options` structure is listed below:
 #### class properties
 
 |property name|property type|read only|description|
-|:---|---|:---|
+|:---|---|---|:---|
 |`count`|`number`|yes|returns a quantity of the elements|
 |`size`|`number`|yes|returns a quantity of the elements|
 |`maxIndex`|`index`|yes|returns a last possible index of the elements|
@@ -305,6 +321,12 @@ This method deletes an element addressed by `index`. If succeed `true` is return
 
 This method loaded a list of elements listed by `items` and returns a quantity of a successfully added elements.
 
+The `options` structure is listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`useClear`|`boolean`|`true`|if `true` the method deletes all the previous content before load the list|
+
 #### class methods (*special*)
 
 ##### **_getItemRaw(name)**
@@ -329,13 +351,19 @@ This class implements a proxy interface for a document declaration element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|`object`|---|a host object for the document content.|
 |`options`|`object`|---|an options settings.|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -345,7 +373,7 @@ The `options` structure is listed below:
 #### class properties
 
 |property name|property type|read only|description|
-|:---|---|:---|
+|:---|---|---|:---|
 |`version`|`string`|no|returns a version of a XML|
 |`encoding`|`string`|no|returns an encodings used by a document|
 
@@ -353,21 +381,27 @@ The `options` structure is listed below:
 
 ##### **init()**
 
-This method initializes element with a default values.
+This method initializes an element with a default values.
 
 ### **TXmlContentRootElement**
 
-This class extends functionality of a `TXmlElementController` class.
+This class extends a functionality of a `TXmlElementController` class.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|`object`|---|a host object for the document content|
 |`options`|`object`|---|an options settings|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -380,9 +414,9 @@ The `options` structure is listed below:
 
 #### class properties
 
-|name|read only|description|
-|:---|---|:---|
-|tagName|no||
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|tagName|`string`|no||
 
 #### class methods (*static*)
 
@@ -400,7 +434,13 @@ This class implements a proxy interface for manipulate a content of a document.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an `options` parameter as its argument.
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives an `options` parameter as its argument.
+
+##### `options` parameter
 
 The `options` structure is listed below:
 
@@ -414,9 +454,9 @@ The `options` structure is listed below:
 
 #### class properties
 
-|property name|read only|description|
-|:---|---|:---|
-|rootElement|yes|returns a document root element|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|rootElement||yes|returns a document root element|
 
 #### class methods
 
@@ -428,12 +468,6 @@ This method clears a document content.
 
 This method returns a document content as a string.
 
-##### **saveToFile(src)**
-
-This method saves a document content into a file addressed by `src`.
-
-> This is `async` method.
-
 ##### **saveToFileSync(src)**
 
 This method saves a document content into a file addressed by `src`.
@@ -442,13 +476,17 @@ This method saves a document content into a file addressed by `src`.
 
 This method loads a document content from a string given by `str`.
 
-##### **loadFromFile(src)**
+##### **loadFromFileSync(src)**
 
 This method loads a document content from a file addressed by `src`.
 
-> This is `async` method.
+#### class methods (*async*)
 
-##### **loadFromFileSync(src)**
+##### **saveToFile(src)**
+
+This method saves a document content into a file addressed by `src`.
+
+##### **loadFromFile(src)**
 
 This method loads a document content from a file addressed by `src`.
 
@@ -461,3 +499,5 @@ This method returns a document content as a string in the JSON-format.
 ##### **_bindContent(obj\[, options])**
 
 This method binds a given object as a document content.
+
+For `options` parameter details see the class constructor description.

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.009-20230316]
+// [v0.1.011-20230919]
 
 // === module init block ===
 
@@ -13,11 +13,6 @@ const xmldoc = require('./lib/xmldoc-lib.js');
 
 exports.xObj = xObj;
 
-// will deprecate
-exports.DEF_XML_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
-// will deprecate
-exports.DEF_XML_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
-
 exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
 exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
 

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.066-20230317]
+// [v0.1.069-20230926]
 
 // === module init block ===
 
@@ -584,11 +584,12 @@ class TXmlElementsListController {
   }
 
   loadItems(items, opt){
-    let act_as_new = true;
-    if (isPlainObject(opt)) {
-      act_as_new = readAsBool(opt.load_as_new, act_as_new);
-    };
-    if (act_as_new) this.clear();
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      useClear,
+    } = _options;
+    if (typeof useClear !== 'boolean') useClear = true;
+    if (useClear) this.clear();
     let count = this.count;
     valueToArray(items).forEach((item) => { this.addItem(item); });
     return this.count - count;
@@ -609,11 +610,11 @@ class TXmlContentDeclaration {
     // load options
     let _options = isPlainObject(opt) ? opt : {};
     // set parser options
-    let { parseOptions: parseOptions } = _options;
+    let { parseOptions } = _options;
     if (!isPlainObject(parseOptions)) {
       _options.parseOptions = parseOptions = {};
     };
-    let { settings: settings } = parseOptions;
+    let { settings } = parseOptions;
     if (!isPlainObject(settings)) parseOptions.settings = settings = {};
     let { declarationKey } = settings;
     if (
@@ -757,7 +758,7 @@ class TXmlContentRootElement extends TXmlElementController {
   }
 
   set tagName(value){
-    value = readAsString(value, '', true);
+    value = readAsString(value, true);
     this.#_options.rootETagName = isNotEmptyString(
       value
     ) ? value : XML_DEF_ROOT_ETAG_NAME;
@@ -841,12 +842,10 @@ class TXmlContentContainer {
 
   saveToXMLString(){
     let result = '';
-    //let isERR = false;
     try {
       result = xmlParser.js2xml(this.#_content, this.#_parseOptions.js2xml);
     } catch (err) {
       //console.log('CHECK: TXmlContentContainer.saveToXMLString() => Error => '+err);
-      //isERR = true;
       throw err;
     };
     return result;
@@ -884,8 +883,8 @@ class TXmlContentContainer {
               break;
             }
             default: {
-              console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
-              console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
+              //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err);
+              //console.log('CHECK: TXmlContentContainer.saveToFile() => Error => '+err.code);
               reject(err);
               break;
             }
@@ -921,8 +920,8 @@ class TXmlContentContainer {
             break;
           }
           default: {
-            console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
-            console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
+            //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err);
+            //console.log('CHECK: TXmlContentContainer.saveToFileSync() => Error => '+err.code);
             throw err;
             break;
           }
@@ -992,8 +991,8 @@ class TXmlContentContainer {
               break;
             }
             default: {
-              console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err);
-              console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err.code);
+              //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err);
+              //console.log('CHECK: TXmlContentContainer.loadFromFile() => Error => '+err.code);
               reject(err);
               break;
             }
@@ -1040,8 +1039,8 @@ class TXmlContentContainer {
             break;
           }
           default: {
-            console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err);
-            console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err.code);
+            //console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err);
+            //console.log('CHECK: TXmlContentContainer.loadFromFileSync() => Error => '+err.code);
             throw err;
             break;
           }
@@ -1059,9 +1058,6 @@ class TXmlContentContainer {
 
 // === module exports block ===
 
-//exports.DEF_XML_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS; // will deprecate
-//exports.DEF_XML_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME; // will deprecate
-
 exports.XML_DEF_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS;
 exports.XML_DEF_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -32,12 +32,12 @@
     "#lib/*": "./lib/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.1.3",
+    "@ygracs/bsfoc-lib-js": "^0.2.0",
     "@ygracs/xml-js6": "^0.0.3-b",
-    "@ygracs/xobj-lib-js": "^0.0.14-rc4"
+    "@ygracs/xobj-lib-js": "^0.1.1"
   },
   "devDependencies": {
-    "jest": "^29.6.1",
+    "jest": "^29.7.0",
     "minimist": "^1.2.8"
   }
 }