steady-xml

English | 中文

A zero-dependence TypeScript library for the steady conversion and processing of XML data.

Origin

After I convert some XML data to JSON for processing, I expect to intact convert it back to XML data which including interlaced element nodes, CDATA nodes, DOCTYPE nodes, comments and so on.

I looked for some famous XML processing libraries (fast-xml-parser, node-xml2js), but most of them consistently chose a compressed conversion to pursue small space and high performance. Although I found a library (xml-js) that can retain as much information as possible, unfortunately it seems to unmaintained.

This is the origin of this library. The core of this library is to preserve XML information as much as possible during the conversion and processing so that the data can be restored intact. space and performance are not the primary concerns.

Features

This library using a class XmlNode to describe XML nodes and relationships. It can construct XmlNode tree from both XML data or JSON, or generate either XML data or JSON from XmlNode.

The algorithm of XML data parsing is referred to fast-xml-parser to a certain extent, which is an excellent algorithm that provides a guarantee for the speed of parsing.

Currently can be resolved nodes:

• Element (includes attributes)
• Declaration (includes attributes)
• Comment
• DocumentType
• Text
• ProcessingInstruction
• CDATA

Install

1yarn add steady-xml

Shorthand

XML to XmlNode：

1import { parseXmlString } from 'steady-xml'
2
3const rootNode = parseXmlString('<element></element>')

XmlNode to XML：

1import { XmlNode, XmlNodeType } from 'steady-xml'
2
3const rootNode = new XmlNode(XmlNodeType.Root)
4
5rootNode.toXmlString()
6rootNode.toXmlString('\t', '\n')
7rootNode.toXmlString('', '')`${rootNode}`

JSON to XmlNode：

1import { buildFromJson } from 'steady-xml'
2
3const rootNode = buildFromJson({ name: 'element' })

XmlNode to JSON：

1import { XmlNode, XmlNodeType } from 'steady-xml'
2
3const rootNode = new XmlNode(XmlNodeType.Root)
4
5rootNode.toJsObject()
6JSON.stringify(rootNode)

Props

1type TextValue = string | number | boolean | null
2
3function parseXmlString(xmlString: string, props?: Partial<ParseProps>): XmlNode
4
5interface ParseProps {
6  // ignore parse node attributes
7  // default: false
8  ignoreAttributes: boolean
9
10  // should parse node value
11  // default: true
12  parseNodeValue: boolean
13
14  // should trim string values
15  // default: true
16  trimValues: boolean
17
18  // parse node value method
19  // default: v => v
20  valueProcessor: (value: string, type: XmlNodeType, name: string) => TextValue
21
22  // parse attribute values method
23  // default: v => v
24  attributeProcessor: (value: string, name: string, type: XmlNodeType) => TextValue
25}
26
27function buildFromJson<T extends Record<string, any>>(json: T, props?: Partial<BuildProps>): XmlNode
28
29interface BuildProps {
30  // name property key
31  // default: 'name'
32  nameKey: string
33
34  // type property key
35  // default: 'type'
36  typeKey: string
37
38  // value property key
39  // default: 'value'
40  valueKey: string
41
42  // attributes property key
43  // default: 'attributes'
44  attributesKey: string | false
45
46  // children property key
47  // default: 'children'
48  childrenKey: string
49
50  // self closing property key
51  // default: 'selfClosing'
52  selfClosingKey: string | false
53
54  // prefix property key
55  // default: 'prefix'
56  prefixKey: string | false
57
58  // should trim string values
59  // default: true
60  trimValues: boolean
61
62  // explicitly specify whether the json is a root node
63  // if be specified false, will judge according type
64  // if is not a root node, it will as element root node
65  // default: false
66  isRoot: boolean
67
68  // whether name includes prefix
69  // default: false
70  prefixInName: boolean
71
72  // parse node value method
73  // default: v => v
74  valueProcessor: (value: TextValue, type: XmlNodeType, name: string) => TextValue
75
76  // parse attribute values method
77  // default: v => v
78  attributeProcessor: (value: TextValue, name: string, type: XmlNodeType) => TextValue
79}
80
81enum XmlNodeType {
82  // is not a real XML node type, only use as the XML data entry
83  Root = 'Root',
84
85  // <?xml version="1.0"?>
86  Declaration = 'Declaration',
87
88  // <!-- some content -->
89  Comment = 'Comment',
90
91  // <!DOCTYPE Items [<!ENTITY number "123">]>
92  DocumentType = 'DocumentType',
93
94  // <element></element>
95  Element = 'Element',
96
97  // pure text node
98  Text = 'Text',
99
100  // <?pi target="target"?>
101  Instruction = 'Instruction',
102
103  // <![CDATA[<foo></bar>]]>
104  CDATA = 'CDATA'
105}
106
107interface XmlJsObject {
108  name?: string
109  prefix?: string
110  type: XmlNodeType
111  attributes?: Record<string, unknown>
112  value?: any
113  selfClosing?: true
114  children?: XmlJsObject[]
115}
116
117declare class XmlNode {
118  // node name
119  name: string
120
121  // node type
122  type: XmlNodeType
123
124  // parend node
125  parent: XmlNode | null
126
127  // chidl node list
128  children: XmlNode[] | null
129
130  // attribute map
131  attributes: Record<string, unknown>
132
133  // node value
134  value: any
135
136  // is self closing
137  selfClosing: boolean
138
139  // node prefix
140  prefix: string
141
142  constructor(name: string, type: XmlNodeType, parent?: XmlNode | null, value?: any)
143
144  // chain set name
145  setName(value: string): this
146
147  // chain set type
148  setType(value: XmlNodeType): this
149
150  // chain set parent node
151  setParent(value: XmlNode | null): this
152
153  // chain set children list
154  setChildren(value: XmlNode[] | null): this
155
156  // chain set attribute map
157  setAttributes(value: Record<string, unknown>): this
158
159  // chain set value
160  setValue(value: any): this
161
162  // chain set self closing
163  setSelfClosing(value: boolean): this
164
165  // chain set prefix
166  setPrefix(value: string): this
167
168  // chain add attribute
169  addAttribute(name: string, value: unknown): this
170
171  // chain remove attribute
172  removeAttribute(name: string): this
173
174  // chain add child node
175  addChild(childNode: XmlNode): void
176
177  // chain remove child node
178  removeChild(childNode: XmlNode): this
179
180  // generate json data
181  toJsObject(): XmlJsObject
182
183  // generate xml string data
184  toXmlString(indentChar?: string, newLine?: string, indentCount?: number): string
185}

License

MIT License.