xml-toolkit 1.0.61 → 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'),	
@@ -28,10 +33,11 @@ module.exports = {
 	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

@@ -60,7 +60,7 @@ const XMLMarshaller = class {
 
 			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})
 
 		}
 

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 {
 

package/lib/XMLSchemata.js

@@ -8,7 +8,8 @@ const XMLSchemaXml = require ('./XMLSchemaXml.js')
 const XMLSchemaBuiltIn = require ('./XMLSchemaBuiltIn.js')
 const XMLMarshaller = require ('./XMLMarshaller.js')
 
-const {XSSimpleType} = require ('./XSSimpleType.js')
+const XSAnyType = require ('./XSAnyType.js')
+const {XSSimpleType} = require ('./simple/XSSimpleType.js')
 
 const IDX = Symbol ('_index')
 
@@ -32,6 +33,12 @@ const XMLSchemata = class extends Map {
 		this.addFile (fn)
 
 	}
+
+	getDebugQName (localName, namespaceURI) {
+
+		return namespaceURI ? `{${namespaceURI}}${localName}` : localName
+
+	}
 	
 	register (name, targetNamespace) {
 	
@@ -51,10 +58,20 @@ const XMLSchemata = class extends Map {
 
 		if (node.localName === 'simpleType' && !node._xsSimpleType) node._xsSimpleType = new (schema.getSimpleTypeClass (node)) (this)
 
+		if (!('targetNamespace' in node)) node.targetNamespace = namespaceURI
+
 		return node
 
 	}
 
+	getAnyType (node) {
+
+		if ('_xsAnyType' in node) return node._xsAnyType
+
+		return node._xsAnyType = new XSAnyType (this, node)
+
+	}
+
 	getSimpleType (node) {
 
 		if ('_xsSimpleType' in node) return node._xsSimpleType
@@ -65,15 +82,65 @@ const XMLSchemata = class extends Map {
 
 	getSimpleTypeClass (node) {
 		
-		if (node) for (const {localName, namespaceURI, attributes: {base}, children} of node.children)
-				
-			if (localName === 'restriction' && namespaceURI === XMLSchema.namespaceURI)
+		if (node) for (const {localName, attributes: {base}, children} of node.children) switch (localName) {
+
+			case 'restriction': return this.getType (base)._xsSimpleType.restrict (children)
+
+			case 'union': return class {
+
+				constructor (xs) {
+
+					this.xs = xs
+
+					this.nodes = children
+
+				}
+
+				stringify (v) {
+
+					const messages = []; for (const node of this.nodes) {
+
+						try {
+
+							return this.xs.getSimpleType (node).stringify (v)
+
+						}
+						catch (err) {
+
+							messages.push (err.message)
+
+						}
 
-				return this.getType (base)._xsSimpleType.restrict (children.map (
+					}
+						
+					throw Error (messages.join ('; '))
 
-					({localName, attributes: {value}}) => ({name: localName, value})
+				}
 
-				))
+				validateScalar (v) {
+
+					const messages = []; for (const node of this.nodes) {
+
+						try {
+
+							return this.xs.getSimpleType (node).validateScalar (v)
+
+						}
+						catch (err) {
+
+							messages.push (err.message)
+
+						}
+
+					}
+
+					throw Error (messages.join ('; '))
+
+				}
+
+			}
+
+		}
 
 		return XSSimpleType
 
@@ -98,10 +165,26 @@ const XMLSchemata = class extends Map {
 	getByReference (ref) {
 
 		const [localName, namespaceURI] = ref
-		
-		const s = this.get (namespaceURI); if (s == null) throw new Error ('Unknown namespace: ' + namespaceURI)
-				
-		return s.get (localName)
+						
+		return this.getSchema (namespaceURI).get (localName)
+
+	}
+
+	getSchema (namespaceURI) {
+
+		if (!this.has (namespaceURI)) throw new Error ('Unknown namespace: ' + namespaceURI)
+
+		return this.get (namespaceURI)
+
+	}
+
+	getTypeDefinition (node) {
+
+		// while (node.attributes.ref) node = this.getByReference (node.attributes.ref)
+
+		if (node.attributes.type) return this.getType (node.attributes.type)
+
+		return node.children.find (i => i.localName.endsWith ('Type'))
 
 	}
 

package/lib/XSAnyType.js

@@ -0,0 +1,98 @@
+const Occurable = require ('./validation/Occurable')
+
+module.exports = class {
+
+	#isAnyAttributeAllowed = false
+	#isExtended = false
+	#parent = null
+
+	get isAnyAttributeAllowed () {
+
+		return this.#isAnyAttributeAllowed
+
+	}
+
+	constructor (xs, node) {
+
+		this.xs = xs
+		this.node = node
+
+		this.attributes = new Map ()
+		this.elements   = []
+
+		this.scan (node)
+
+		if (this.#parent === null) return
+
+		if (this.#isExtended) this.extend (); else this.restrict ()
+
+	}
+
+	extend () {
+
+		this.attributes = new Map ([
+			...this.#parent.attributes,
+			...this.attributes
+		])
+
+		this.elements = this.#parent.elements.concat (this.elements)
+
+		this.content = new Occurable ([this.#parent.content, this.content])
+
+	}
+
+	restrict () {
+
+		this.attributes = new Map ([
+			...this.#parent.attributes,
+			...this.attributes
+		])
+
+	}
+
+	asSimpleType () {
+
+		return this.xs.getSimpleType (this.node)
+
+	}
+
+	get debugQName () {
+
+		const {xs, node} = this
+
+		return xs.getDebugQName (node.attributes.name, node.targetNamespace)
+
+	}
+
+	scan (node) {
+
+		while (node.attributes.ref) node = this.xs.getByReference (node.attributes.ref)
+
+		switch (node.localName) {
+
+			case 'anyAttribute': return this.#isAnyAttributeAllowed = true
+
+			case 'attribute': return this.attributes.set (node.attributes.name, node)
+
+			case 'any':
+			case 'element':
+				return this.elements.push (node)
+
+			case 'all':
+			case 'choice':
+			case 'sequence':
+				this.content ??= new Occurable (node, this.xs)
+				break
+
+			case 'extension': 
+				this.#isExtended = true
+			case 'restriction': 
+				this.#parent = this.xs.getAnyType (this.xs.getType (node.attributes.base))
+
+		}
+
+		for (const child of node.children) this.scan (child)
+
+	}
+
+}