xml-core

xml-core is a set of classes that make it easier to work with XML within the browser and node.

Showing:

Popularity

Downloads/wk

24.6K

GitHub Stars

16

Maintenance

Last Commit

5mos ago

Contributors

3

Package

Dependencies

3

Size (min+gzip)

30.2KB

License

MIT

Type Definitions

Built-In

Tree-Shakeable

Yes?

Categories

Readme

xml-core

xml-core is a set of classes that make it easier to work with XML within the browser and node.

license CircleCI Coverage Status NPM version

NPM

Introduction

We wanted to be able to validate XAdES in the browser, specifically so we could validate the signature on the EU Trust List.

This lead us to the creation od XMLDSIGjs which allows us to validate XML and XAdESjs which extends it and enables us to validate XAdES signatures.

We use xml-core to make the creation of these libraries easier, we hope you may find it valuable in your own projects also.

Fundementally xml-core provides a way to transform XML to JSON and JSON to XML, which enables you to enforce a schema on the associated XML. The goal of this is to let you work naturally with XML in Javascript.

It is similar to xmljs but has a few differences -

  • Can convert the JSON back to XML,
  • Uses decorators to make enforcing schema in Javascript more natural.

Install

npm install xml-core

Using

ES5

var XmlCore = require("xml-core");

ES2015

import XmlCore from "xml-core";

Decrators

Information about decorators ES2015, TypeScript

XmlElement

Class decorator which allows to describe schema for xml element

Paramteres

NameDescription
localNameSets a local name for xml element. Default value is name of Class
namespaceURISets a namespace URI for xml element. Default value is null
prefixSets a prefix for xml element. Default value is null
parserSets a parser as XmlObject for each child element of XmlCollection. Optional

XmlAttribute

Property decorator which allows to describe schema for attribute of xml element

Paramteres

NameDescription
localNameSets a local name for xml element. Default value is name of Property
namespaceURISets a namespace URI for xml element. Default value is null
prefixSets a prefix for attribute of xml element. Default value is null
defaultValueSets a default value for attribute of xml element. Optional
requiredDetermines if attribute of xml element is required. Default value is false
converterSets a specific converter for attribute of xml element. Default is simple text

XmlChildElement

Property decorator which allows to describe schema for child element of xml element

Paramteres

NameDescription
localNameSets local name for xml element. Default value is name of Class
namespaceURISets namespace URI for xml element. Default value is null
prefixSets prefix for xml element. Default value is null
defaultValueSets a default value for attribute of xml element. Optional
requiredDetermines if child element is required. Default value is false
converterSets a specific converter for child element. Default is simple text
parserSets parser as XmlObject for child element. Optional
minOccursSets a min value for child element occurs. Default value is 0
maxOccursSets a max value for child element occurs. Default value is MAX
noRootDetermines if parser as XmlCollection must return it's children to parent element

XmlContent

Property decorator which allows to describe schema for content of xml element

Paramteres

NameDescription
defaultValueSets a default value for content of xml element. Optional
requiredDetermines if content of xml element is required. Default value is false
converterSets a specific converter for content of xml element. Default is simple text

XmlObject

Base class for XML elements.

LoadXml

Reads XML from string

LoadXml(node: Node | string): void;
static LoadXml(node: Node | string): this;

GetXml

Writes object to XML node

GetXml(): Node | null;

toString

Writes object to string

toString(): string;

Example

Target XML schema

<element name="Signature" type="ds:SignatureType"/>
<complexType name="SignatureType">
  <sequence>
    <element ref="ds:SignedInfo"/>
    <element ref="ds:SignatureValue"/>
    <element ref="ds:KeyInfo" minOccurs="0"/>
    <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/>
  </sequence>
  <attribute name="Id" type="ID" use="optional"/>
</complexType>

TypeScript implementation of XML schema

import { XmlObject, XmlBase64Converter } from "xml-core";

@XmlElement({
    localName: "Signature",
    namespaceURI: "http://www.w3.org/2000/09/xmldsig#",
    prefix: "ds"
})
class Signature extends XmlObject {

    @XmlAttribute({
        localName: XmlSignature.AttributeNames.Id,
        defaultValue: "",
    })
    public Id: string;

    @XmlChildElement({
        parser: SignedInfo,
        required: true,
    })
    public SignedInfo: SignedInfo;

    @XmlChildElement({
        localName: "SignatureValue",
        namespaceURI: "http://www.w3.org/2000/09/xmldsig#",
        prefix: "ds",
        required: true,
        converter: XmlBase64Converter,
        defaultValue: null,
    })
    public SignatureValue: Uint8Array | null;

    @XmlChildElement({
        parser: KeyInfo
    })
    public KeyInfo: KeyInfo;

    @XmlChildElement({
        parser: DataObjects,
        noRoot: true
    })
    public ObjectList: DataObjects;

}

Using

const signature = new Signature();

// Read XML
signature.LoadXml(Signature.Parse('<ds:Signature Id="sigId">...</ds:signature>'));
console.log("Id:", signature.Id); // Id: sigId

// Write XML
signature.Id = "newId";
console.log(signature.toString()); // <ds:Signature Id="sigId">...</ds:signature>

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100