Home

Damn Simple XML Serializer (2.x)

DSX2 is in the oven right now (2015-06-08). I'm working on unit test migration and debugging. The library is straigthened and packs a lot of cool features. Follow me on twitter @jpgravel to stay informed.

Damns Simple XML Serializer (1.x)

In any text within this documentation, "DSX" or "dsx" stands for Damn Simple XML Serializer.

The DSX project follows Semantic Versioning 2.0 notation. My contact information and links to my other projects can be found at formix.org.

Current development branch

Introduction

Damn Simple XML Serializer (DSX) is an XML serialization library meant to simplify programmer's life. To use this module, install it using npm install damn-simple-xml and then do require("damn-simple-xml") to obtain the serializer constructor.

DSX behavior is similar to that of .NET serialization (XmlSerializer). As of today, we already support a declarative way to specify attribute fields and array items. Moreover, there is currently a way to obtain interleaved text within a set of given node with the _text auto property. The 1.0.0 release now supports a fully declarative way to deserialize inline text like the XmlTextAttribute class does in .NET.

The version 0.6 included many breaking changes compared to the version 0.5 of the library. We did that to get back in-line with actual NodeJS existing standards and to ease declaration of field attributes and array items. We are truly sorry for impacts on your project but since this is my first node open source project, I wanted to get inline with most obvious generally accepted standards like (err, callback) asynchronous function calls as soon as possible. Breaking changes are in-line with Semantic Versioning 2.0 specifications for product version 0.x but its always a mess for the good coder who wants to stay on top.

The version 1.0 contains two breaking changes compared to version 0.6. First, when serializing or deserializing, former DSXS versions needed/received a "root" object having the following interface: {root:"", data:{}}. Now this "root" object has the following interface: {name:"", data:{}} which made DSXS' code clearer and more consistent. The second breaking change is behavioral. The serialize callback prototype is now function(err, xmlpart, level) where xmlpart is a partial XML string that have to be concatenated to a master XML or can be sent directly to any other stream. When the level parameter reaches 0, it means that the serializer work is over. Consult the Behavior section of serializer.serialize(root, callback) function for more details. According to Semantic Versioning 2.0 specifications, no breaking changes will be introduced in version 1.0.

Just like in .NET serialization, a DSX serializer is declared for a particular type of object. Since Javascript is not typed and don't have attribute / annotation mechanism, we use the constructor to inform the serializer of what needs to be serialized as attribute, which fields are to be dumped directly as text in the parent node, what are the name of arrays and array items. See this example:

var Serializer = require("damn-simple-xml");
var serializer = new Serializer(
  arrays: {
    "organization.employees": "employee"
  },
  attributes: {
    "organization.employees.employee": ["id", "number"]
  },
  texts: {
    "organization.employees.employee": "notes"
  }
);

In the preceding example, the serializer constructor makes it tightly binded to the "organization" structure and will fall back to the default behavior for any other object not having the correct structure. Note that behavior declaration must be fully qualified, which means that the targeted field have to be named from the XML root stand point up to the field.

DSXS default behavior is to dump every object's fields as XML elements and any field named _text as in-line text within the current XML element.