xml-toolkit 1.0.60 → 1.1.0

package/README.md

@@ -1,5 +1,6 @@
 ![workflow](https://github.com/do-/node-xml-toolkit/actions/workflows/main.yml/badge.svg)
 ![Jest coverage](./badges/coverage-jest%20coverage.svg)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/do-/node-xml-toolkit)
 
 `node-xml-toolkit` is a pure node.js library for solving diverse XML related application tasks, e. g.:
 * scanning through multi gigabyte long XML files with a limited memory buffer;
@@ -13,16 +14,19 @@ It features both (fast and simple, but greedy) [synchronous](https://github.com/
 npm install xml-toolkit
 ```
 
-# Using
-
-* [Parsing a small file completely](XMLParser)
+# Usage
+* [Parsing a small file completely](XMLParser) (optionally validating)
 
 ```js
 const fs = require ('fs')
-const {XMLParser} = require ('xml-toolkit')
+const {XMLParser, XMLSchemata} = require ('xml-toolkit')
 
 const xml    = fs.readFileSync ('doc.xml')
-const parser = new XMLParser  ({...options})
+// const xs  = new XMLSchemata ('schema.xsd')
+
+const parser = new XMLParser  ({
+// xs,
+})
 
 const document = parser.process (xml)
 
@@ -31,12 +35,15 @@ for (const element of document.detach ().children) {
 }
 ```
 
-* [Reading a Record List](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Reading-a-Record-List), streaming mode
+* [Reading a Record List](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Reading-a-Record-List) (optionally validating)
 
 ```js
-const {XMLReader, XMLNode} = require ('xml-toolkit')
+const {XMLReader, XMLNode, XMLSchemata} = require ('xml-toolkit')
+
+// const xs  = new XMLSchemata ('schema.xsd')
 
 const records = new XMLReader ({
+//xs,
   filterElements : 'Record', 
   map            : XMLNode.toObject ({})
 }).process (xmlSource)
@@ -56,7 +63,7 @@ const records = new XMLReader ({
 // records.on ('data', record => doSomethingWith (record))
 ```
 
-* [Getting a Single Element](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Getting-a-Single-Element), streaming mode
+* [Getting a Single Element](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Getting-a-Single-Element)
 
 ```js
 const {XMLReader, XMLNode} = require ('xml-toolkit')
@@ -67,6 +74,21 @@ const data = await new XMLReader ({
 }).process (xmlSource).findFirst ()
 ```
 
+* [Formatting XML](https://github.com/do-/node-xml-toolkit/wiki/XMLPrinter)
+```js
+const {XMLParser} = require ('xml-toolkit')
+xml = new XMLParser ()
+  .process (fs.readFileSync ('doc.xml'))
+  .toString ({
+//  decl: {encoding: 'UTF-8', standalone: 1},
+    space: '\t', 
+//  attrSpace: 2, 
+//  EOL: '\n',
+//  level: 0, 
+//  encodeLineBreaks: false,
+   })
+```
+
 * [Patching XML](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Patching-XML)
 
 ```js
@@ -80,8 +102,6 @@ let xmlResult = ''; for await (const node of new XMLReader ().process (xmlSource
 * [Serializing an Object According to an XML Schema](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Serializing-an-Object-According-to-an-XML-Schema)
 
 ```js
-const {XMLSchemata} = require ('xml-toolkit')
-
 const data = {ExportDebtRequestsResponse: {	
   "request-data": {
    // ...
@@ -98,14 +118,13 @@ const xml = xs.stringify (data)
     <!-- ... and so on ... -->
 */
 ```
-
-* Invoking a [SOAP 1.1](https://github.com/do-/node-xml-toolkit/wiki/SOAP11) or [SOAP 1.2](https://github.com/do-/node-xml-toolkit/wiki/SOAP12) Web Service
+* Invoking a [SOAP 1.1](SOAP11) Web Service
 
 ```js
 const http = require ('http')
-const {SOAP11, SOAP12} = require ('xml-toolkit')
+const {SOAP11} = require ('xml-toolkit')
 
-const soap = new SOAP11 ('their.wsdl') // or SOAP12
+const soap = new SOAP11 ('their.wsdl')
 
 const {method, headers, body} = soap.http ({RequestElementNameOfTheirs: {amount: '0.01'}})
 
@@ -113,32 +132,6 @@ const rq = http.request (endpointURL, {method, headers})
 rq.write (body)
 ```
 
-* [Implementing](https://github.com/do-/node-xml-toolkit/wiki/Use-Case:-Implement-a-SOAP-Web-Service) a SOAP service
-
-```js
-const {XMLSchemata, SOAP11, SOAP12, SOAPFault} = require ('xml-toolkit')
-
-const SOAP = SOAP11 // or SOAP12
-
-const xs = new XMLSchemata (`myService.wsdl`)
-
-let body, statusCode; try {  
-  body = xs.stringify (myMethod (/*...*/))
-  statusCode = 200
-}
-catch (x) {
-  body = new SOAPFault (x)
-  statusCode = 500
-}
-
-rp.writeHead (statusCode, {
-  'Content-Type': SOAP.contentType,
-})
-
-const xml = SOAP.message (body)
-rp.end (xml)
-```
-
 # Motivation
 
 Unlike Java (with [JAXB](https://www.oracle.com/technical-resources/articles/javase/jaxb.html) and [JAX-WS](https://www.oracle.com/technical-resources/articles/javase/jax-ws-2.html)) and some other software development platforms dating back to late 1990s, the core node.js library doesn't offer any standard tool for dealing with XML.
@@ -154,9 +147,6 @@ Pure js 3rd party modules are abundant, but after some real tasks based research
 
 No W3C specification is 100% implemented here. For instance, DTDs are not supported, so, in theory, any rogue XML file using such bizarre deprecated feature as [Entity Declarations](https://www.w3.org/TR/xml/#sec-entity-decl) may crash the local XML parser.
 
-Though `node-xml-toolkit` has some support for [XMLSchema](https://github.com/do-/node-xml-toolkit/wiki/XMLSchema), it cannot be used for validation. Here, XML Schema is used only as a template for outputting valid XML provided a correct set of input data. That means, each `decimal` will be formatted with proper `fractionDigits`, but no CPU cycle will be spent on checking whether the incoming 10 char string fully conforms to the [`date`](https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/datatypes.html#date) lexical representation or not.
-
-In short, `node-xml-toolkit` may produce incorrect results for some input data, especially for deliberately broken ones.
+The [XMLSchema](https://github.com/do-/node-xml-toolkit/wiki/XMLSchemata) is fairly usable for most real world cases, still some features (like `xs:unique`) are ignored completely, some others may require more test coverage. In general, XML Schema support in `xml-toolkit` should be considered _forever beta_.
 
-There are perfectly reliable external tools for XML validation: for instance, 
-[xmllint](https://linux.die.net/man/1/xmllint) (used in the test suite here) do just fine.
+There are perfectly reliable external tools for XML validation: for instance, [xmllint](https://linux.die.net/man/1/xmllint) (used in the test suite here) do just fine.

package/index.js

@@ -1,11 +1,16 @@
 const {
 	XSSimpleType,
-	XSSimpleTypeFloat,
-	XSSimpleTypeBoolean,
+} = require ('./lib/simple/XSSimpleType')
+
+const {
 	XSSimpleTypeDate,
 	XSSimpleTypeDateTime,
-	XSSimpleTypeQName,
-} = require ('./lib/XSSimpleType')
+} = require ('./lib/simple/XSSimpleTypeDT')
+
+const {
+	XSSimpleTypeFloat,
+	XSSimpleTypeDouble,
+} = require ('./lib/simple/XSSimpleTypeFloatingPoint')
 
 module.exports = {
 	AttributesMap:       require ('./lib/AttributesMap'),	
@@ -20,17 +25,19 @@ module.exports = {
 	XMLNode:             require ('./lib/XMLNode'),
 	XMLLexer:            require ('./lib/XMLLexer'),
 	XMLParser:           require ('./lib/XMLParser'),
-	XMLPrinter:          require ('./lib/XMLPrinter'),
+	XMLPrinter:          require ('./lib/printer/XMLPrinter'),
+	XMLStreamPrinter:    require ('./lib/printer/XMLStreamPrinter'),
 	XMLReader:           require ('./lib/XMLReader'),
 	XMLSchema:           require ('./lib/XMLSchema'),
 	XMLSchemaBuiltIn:    require ('./lib/XMLSchemaBuiltIn'),
 	XMLSchemata:         require ('./lib/XMLSchemata'),
 	XSSimpleType,
 	XSSimpleTypeFloat,
-	XSSimpleTypeBoolean,
+	XSSimpleTypeDouble,
+	XSSimpleTypeBoolean: require ('./lib/simple/XSSimpleTypeBoolean'),
 	XSSimpleTypeDate,
 	XSSimpleTypeDateTime,
-	XSSimpleTypeQName,
+	XSSimpleTypeQName:   require ('./lib/simple/XSSimpleTypeQName'),
 }
 
 module.exports.SOAP = v => {switch (String (v)) {

package/lib/XMLMarshaller.js

@@ -1,6 +1,8 @@
 const assert       = require ('assert')
 const NamespacePrefixesMap = require ('./NamespacePrefixesMap.js')
-const XMLPrinter = require ('./XMLPrinter.js')
+const XMLPrinter = require ('./printer/XMLPrinter.js')
+const XMLStreamPrinter = require ('./printer/XMLStreamPrinter.js')
+const {Readable} = require ('node:stream')
 
 const XSI_TYPE = Symbol.for ('type')
 
@@ -15,10 +17,10 @@ const XMLMarshaller = class {
 		this.schemaElement = this.schema.get (localName); assert (this.schemaElement, 'No schema element found for namespaceURI = ' + namespaceURI + ', localName = ' + localName)
 
 		this.ns = new NamespacePrefixesMap (xs)
-		
+
 		this.isNsDumped = false
-		
-		this.printer = new XMLPrinter (printerOptions)
+
+		this.printer = new ('out' in printerOptions ? XMLStreamPrinter : XMLPrinter) (printerOptions)
 
 	}
 	
@@ -40,28 +42,39 @@ const XMLMarshaller = class {
 
 		try {
 
-			this.appendElement (schemaElement, data, this.ns.QName (o.localName || attributes.name, targetNamespace))
+			const result = this.appendElement (schemaElement, data, this.ns.QName (o.localName || attributes.name, targetNamespace))
+
+			if (result instanceof Promise) {
+
+				result.then (printer.end, printer.destroy)
+
+			}
+			else {
+
+				return printer.text
+
+			}
 
 		}
 		catch (cause) {
 
 			const {targetNamespace, attributes: {name}} = schemaElement
 
-			throw Error (`Cannot stringify ${JSON.stringify (data)} as ${name}#{${targetNamespace}}`, {cause})
+			throw Error (`Cannot stringify ${JSON.stringify (data)} as ${name}#{${targetNamespace}}: ${cause.message}`, {cause})
 
 		}
 
-		return printer.text
-
 	}	
 	
 	appendElement (node, data, qName) {
 
 		this.appendStartTag (node, data, qName)
-		
-		this.appendElementBody (node, data)
-		
-		this.printer.closeElement ()
+
+		const result = this.appendElementBody (node, data), finish = () => this.printer.closeElement ()
+
+		if (!(result instanceof Promise)) return finish ()
+
+		return result.then (finish, this.printer.destroy)
 
 	}
 	
@@ -71,7 +84,7 @@ const XMLMarshaller = class {
 
 		if (!this.isNsDumped) {
 		
-			this.printer.text += this.ns
+			this.printer.write (this.ns.toString ())
 		
 			this.isNsDumped = true
 
@@ -110,13 +123,19 @@ const XMLMarshaller = class {
 		const {attributes: {type}, children} = node
 
 		if (data && data [XSI_TYPE]) {
-			let d = {}; for (let k in data) d [k] = data [k]
-			this.appendContent (this.schema.getType (data [XSI_TYPE]), d)
+
+			const d = {}; for (let k in data) d [k] = data [k]
+
+			return this.appendContent (this.schema.getType (data [XSI_TYPE]), d)
+
 		}
+		else if (type) {
 
-		if (type) return this.appendContent (this.xs.getType (type), data)
+			return this.appendContent (this.xs.getType (type), data)
 
-		for (const i of children) this.appendContent (i, data)
+		}
+
+		return this.appendAllContent (children, data)
 
 	}
 
@@ -142,7 +161,7 @@ const XMLMarshaller = class {
 
 				return this.printer.writeAttribute (
 					this.ns.QName (name, targetNamespace), 
-					this.xs.getAttributeSimpleType (node).stringify (v)
+					this.xs.getAttributeSimpleType (node).stringify (v) // throws
 				)
 
 			case 'extension':
@@ -178,7 +197,7 @@ const XMLMarshaller = class {
 
 				const type = this.xs.getSimpleType (node)
 
-				const xml = type.stringify (data)
+				const xml = type.stringify (data) // throws
 				
 				this.printer.writeCharacters (xml)
 
@@ -192,6 +211,8 @@ const XMLMarshaller = class {
 
 				const qName = this.ns.QName (name, targetNamespace)
 				
+				if (v instanceof Readable) return this.printer.forEach (v, d => this.appendElement (node, d, qName))
+
 				if (!Array.isArray (v)) return this.appendElement (node, v, qName)
 				
 				for (const d of v) this.appendElement (node, d, qName)
@@ -199,17 +220,29 @@ const XMLMarshaller = class {
 				return
 				
 			case 'extension':
-			
-				this.appendContent (this.xs.getType (attributes.base), data)
-				
+
+				return this.appendAllContent ([this.xs.getType (attributes.base), ...children], data)
+
 			default:
 
-				for (const i of children) this.appendContent (i, data)
+				return this.appendAllContent (children, data)
 				
 		}
 
 	}
-		
+
+	appendAllContent (list, data) {
+
+		for (let i = 0; i < list.length; i ++) {
+
+			const result = this.appendContent (list [i], data); if (!(result instanceof Promise)) continue
+
+			return result.then (this.appendAllContent (list.slice (i + 1), data), this.printer.destroy)
+
+		}
+
+	}
+
 }
 
 module.exports = XMLMarshaller

package/lib/XMLNode.js

@@ -1,5 +1,5 @@
 const SAXEvent      = require ('./SAXEvent.js')
-const XMLPrinter    = require ('./XMLPrinter.js')
+const XMLPrinter    = require ('./printer/XMLPrinter.js')
 const NamespacesMap = require ('./NamespacesMap')
 const MoxyLikeJsonEncoder = require ('./MoxyLikeJsonEncoder')
 

package/lib/XMLParser.js

@@ -1,21 +1,40 @@
-const assert      = require ('assert')
-const SAXEvent    = require ('./SAXEvent.js')
-const XMLNode     = require ('./XMLNode.js')
-const XMLIterator = require ('./XMLIterator.js')
+const SAXEvent      = require ('./SAXEvent.js')
+const XMLNode       = require ('./XMLNode.js')
+const XMLIterator   = require ('./XMLIterator.js')
+const XMLValidatior = require ('./validation/XMLValidatior.js')
 
 const XMLParser = class {
 
 	constructor (options = {}) {
-		
-		if (!('stripSpace' in options)) options.stripSpace = true
-		assert (options.stripSpace === true || options.stripSpace === false, 'options.stripSpace must be boolean, not ' + typeof options.stripSpace)
 
-		if (!('useEntities' in options)) options.useEntities = true
-		assert (options.useEntities === true || options.useEntities === false, 'options.useEntities must be boolean, not ' + typeof options.useEntities)
+		if ('xs' in options) {
+
+			const {xs} = options; if (!(xs instanceof Map && xs.constructor.name === 'XMLSchemata')) throw Error (`options.xs must be an XMLSchemata instance, found ${typeof xs} '${xs}'`)
+
+			this.xs = xs
+
+		}
+		else {
+
+			this.xs = null
+
+		}
+
+		for (const k of ['stripSpace', 'useEntities', 'useNamespaces']) {
+
+			if (!(k in options)) options [k] = true
 
-		if (!('useNamespaces' in options)) options.useNamespaces = true
-		assert (options.useNamespaces === true || options.useNamespaces === false, 'options.useNamespaces must be boolean, not ' + typeof options.useNamespaces)
+			switch (options [k]) {
+				case false:
+					if (this.xs !== null && k === 'useNamespaces') throw Error (`With an XMLSchema provided, options.${k} cannot be false`)
+				case true:
+					break
+				default:
+					throw Error (`options.${k} must be boolean, found ${typeof options [k]} '${options [k]}'`)
+			}
 
+		}
+		
 		this.stripSpace    = options.stripSpace
 		this.useEntities   = options.useEntities
 		this.useNamespaces = options.useNamespaces
@@ -46,9 +65,11 @@ const XMLParser = class {
 
 				default:
 
-					if (this.text.length === 0) break
 					if (this.stripSpace) this.text = this.text.trim ()
 					if (this.text.length === 0) break
+					if (this.validator) {
+						this.validator.characters (this.text)
+					}
 					(new XMLNode (this.text, null, SAXEvent.TYPES.CHARACTERS)).parent = this.element
 					this.text = ''
 
@@ -61,14 +82,22 @@ const XMLParser = class {
 					node.parent = this.element
 					if (this.useNamespaces) node.readNamespaces ()
 					this.element = node
-					if (this.document === null) this.document = node
+					if (this.document === null) {
+						this.document = node
+						if (this.xs !== null) this.validator = new XMLValidatior (this.xs, node, () => nodes.pos)
+					}
+					else {
+						if (this.xs !== null) this.validator.startElement (node)
+					}
 					break
 
 				case SAXEvent.TYPES.END_ELEMENT:
 
 					if (this.element === null) throw new Error (`Unbalanced end element tag "${node.text}" occured at position ${nodes.pos}`)
+					node ['_ns_map'] = this.element ['_ns_map']
 					this.element.type = type
 					this.element = this.element.parent
+					if (this.xs !== null) this.validator.endElement (node)
 					break
 
 			}

package/lib/XMLReader.js

@@ -3,6 +3,7 @@ const {Transform} = require ('stream')
 const SAXEvent    = require ('./SAXEvent.js')
 const XMLNode     = require ('./XMLNode.js')
 const XMLLexer    = require ('./XMLLexer.js')
+const XMLValidatior = require ('./validation/XMLValidatior.js')
 
 const OPT_SRC  = Symbol ('_src')
 const OPT_SAX  = Symbol ('_sax')
@@ -54,6 +55,14 @@ const XMLReader = class extends Transform {
 
 		super (options)
 
+		if ('xs' in options) {
+			this.xs = options.xs
+			this.validator = null
+		}
+		else {
+			this.xs = null
+		}
+
 		this.stripSpace    = options.stripSpace
 		this.useEntities   = options.useEntities
 		this.useNamespaces = options.useNamespaces
@@ -133,11 +142,46 @@ const XMLReader = class extends Transform {
 		return this [OPT_SAX] = false
 
 	}
+
+	validate (xmlNode) {
+
+		if (!this.validator) switch (xmlNode.type) {
+
+			case SAXEvent.TYPES.START_ELEMENT:									
+				this.validator = new XMLValidatior (this.xs, xmlNode, () => this.position)
+
+			default:
+				return
+
+		}
+
+		switch (xmlNode.type) {
+
+			case SAXEvent.TYPES.START_ELEMENT : return this.validator.startElement (xmlNode)
+
+			case SAXEvent.TYPES.CHARACTERS    : return this.validator.characters (xmlNode.src)
+
+			case SAXEvent.TYPES.END_ELEMENT   : return this.validator.endElement (xmlNode)
+
+		}
+
+	}
 	
 	publish (xmlNode, type = null) {
 
 		if (type !== null) xmlNode.type = type
 
+		if (this.xs) try {
+
+			this.validate (xmlNode)
+
+		}
+		catch (error) {
+
+			this.destroy (error)
+
+		}
+
 		const {filter} = this; if (filter !== null) {
 
 			if (!filter (xmlNode)) return

package/lib/XMLSchema.js

@@ -70,6 +70,16 @@ const XMLSchema = class extends Map {
 
 	}
 
+	getElement (localName) {
+
+		const el = this.get (localName)
+
+		if (!el || el.localName !== 'element') throw Error (`The element ${localName} is not found in ${this.targetNamespace}`)
+
+		return el
+
+	}
+
 	setSource (node) {
 
 		this.defaultNamespace = node.namespacesMap.default
@@ -94,6 +104,7 @@ const XMLSchema = class extends Map {
 					this [TYPES].set (name, e)
 					break
 				default:
+// console.log ([name, localName, this.targetNamespace])					
 					this.set (name, e)
 			}
 			

package/lib/XMLSchemaBuiltIn.js

@@ -2,7 +2,13 @@ const fs = require ('fs')
 const path = require ('path')
 
 const XMLSchema = require ('./XMLSchema.js')
-const {XSSimpleType} = require ('./XSSimpleType.js')
+const {XSSimpleType} = require ('./simple/XSSimpleType.js')
+const XSSimpleTypeDT = require ('./simple/XSSimpleTypeDT.js')
+const XSSimpleTypeDecimal = require ('./simple/XSSimpleTypeDecimal.js')
+const XSSimpleTypeInteger = require ('./simple/XSSimpleTypeInteger.js')
+const XSSimpleTypeBoolean = require ('./simple/XSSimpleTypeBoolean.js')
+const XSSimpleTypeFloatingPoint = require ('./simple/XSSimpleTypeFloatingPoint.js')
+const XSSimpleTypeQName = require ('./simple/XSSimpleTypeQName.js')
 
 class XMLSchemaBuiltIn extends XMLSchema {
 
@@ -14,15 +20,24 @@ class XMLSchemaBuiltIn extends XMLSchema {
 
 		const doc = parent.parser.process (xml)
 		
-		super (parent, XMLSchema.namespaceURI, doc) 
+		super (parent, XMLSchema.namespaceURI, doc)
+
+		this.byName = {
+			...XSSimpleTypeInteger.byName,
+			...XSSimpleTypeFloatingPoint.byName,
+			...XSSimpleTypeDT.byName,
+			QName   : XSSimpleTypeQName,
+			boolean : XSSimpleTypeBoolean,
+			decimal : XSSimpleTypeDecimal,
+		}
 
 	}
 
-	getSimpleTypeClass (node) {
+	getSimpleTypeClass ({attributes: {name}}) {
 
-		return XSSimpleType.forName (node.attributes.name)
+		return this.byName [name] ?? XSSimpleType
 
-	}
+	}	
 
 }
 

package/lib/XMLSchemaXml.js

@@ -3,7 +3,6 @@ const path = require ('path')
 
 const XMLSchema = require ('./XMLSchema.js')
 const NamespacesMap = require ('./NamespacesMap.js')
-const {XSSimpleType} = require ('./XSSimpleType.js')
 
 class XMLSchemaXml extends XMLSchema {