Skip to content

Getting started ​

exemplar is an XML toolkit for JavaScript and TypeScript, built around a conformant XML 1.0 and 1.1 parser. It provides:

  • three streaming APIs for reading: a pull cursor, event objects and SAX;
  • two in-memory trees: a DOM, and an XDM tree queried with XPath 3.1;
  • a streaming writer, and canonical XML;
  • DTD validation, XInclude and XML catalogs.

It runs on Node, Deno, Bun and in browsers, and each part is a separate package.

This page covers installation and two examples: reading a document with the cursor, and querying one with XPath.

Install ​

The two programs on this page need three packages:

bash
npm install @exemplarjs/xml @exemplarjs/xdm @exemplarjs/xpath
bash
pnpm add @exemplarjs/xml @exemplarjs/xdm @exemplarjs/xpath
bash
yarn add @exemplarjs/xml @exemplarjs/xdm @exemplarjs/xpath
bash
bun add @exemplarjs/xml @exemplarjs/xdm @exemplarjs/xpath
bash
deno add npm:@exemplarjs/xml npm:@exemplarjs/xdm npm:@exemplarjs/xpath

The packages are released together under one version number. Install them all at the same version.

What each package is for
PackageWhat it is for
@exemplarjs/xmlParsing: the factory, the cursor, event objects, errors
@exemplarjs/saxThe SAX parser and SAX filters
@exemplarjs/domA mutable DOM tree with the browser's DOM interface
@exemplarjs/xdmThe XDM tree: compact, read-only, built for XPath
@exemplarjs/xpathXPath 3.1 queries
@exemplarjs/writerWriting XML
@exemplarjs/validationValidating a document against its DTD
@exemplarjs/xincludeXInclude: assembling a document from several files
@exemplarjs/catalogXML catalogs: resolving DTDs and other files to local copies
@exemplarjs/canonicalCanonical XML, for comparing and signing documents
@exemplarjs/encodings-cjkDecoding Japanese, Chinese and Korean encodings other than UTF-8

Packages and runtimes lists every import path and what each runtime supports.

Read a document ​

The first program reads a catalog of books and prints each title. Save it as books.mjs and run it with node books.mjs.

ts
import { 
EventType
,
XMLInputFactory
} from '@exemplarjs/xml';
const
source
= `<catalog>
<book id="b1"><title>Dune</title><price>9.99</price></book> <book id="b2"><title>Emma</title><price>7.50</price></book> </catalog>`; const
xml
= new
XMLInputFactory
();
const
reader
=
xml
.
createStreamReader
(
source
);
for (let
type
=
reader
.
next
();
type
!==
EventType
.
END_DOCUMENT
;
type
=
reader
.
next
()) {
if (
type
===
EventType
.
START_ELEMENT
&&
reader
.
localName
() === 'title') {
console
.
log
(
reader
.
elementText
());
} } // Dune // Emma

XMLInputFactory holds the parser configuration and no per-document state, so one instance can be shared across the application. createStreamReader returns the cursor, exemplar's pull parser: next() advances to the next event and returns its type, and accessors such as localName() and elementText() read the current event.

The cursor creates no object per event and does not buffer the document, so its memory use does not grow with the size of the input. Reading with the cursor covers it in full.

TIP

The samples in this guide are TypeScript. Hover over a name in any of them to see its type.

Ask a question with XPath ​

The second program parses the same catalog into an XDM tree and queries it with XPath 3.1. XDM is the XPath data model, and exemplar's XDM tree is a compact, read-only tree designed for XPath evaluation: it holds its nodes in typed arrays in document order and all its text in one string.

ts
import { 
XdmDocumentBuilder
} from '@exemplarjs/xdm';
import {
XPathCompiler
} from '@exemplarjs/xpath';
const
catalog
= new
XdmDocumentBuilder
().
parse
(
source
);
const
compiler
= new
XPathCompiler
();
// The titles of the books that cost less than 9. const
cheap
=
compiler
.
compile
('//book[price < 9]/title');
console
.
log
(
cheap
.
evaluateStrings
(
catalog
));
// [ 'Emma' ] // The number of books. const
count
=
compiler
.
compile
('count(//book)');
console
.
log
(
count
.
evaluateNumber
(
catalog
));
// 2

compile parses the expression once, and the compiled expression can be evaluated any number of times, against any tree. The evaluation method determines the JavaScript type of the result: evaluateStrings returns an array of strings, evaluateNumber a single number.

The tree holds the whole document in memory. For a file too large for that, One record at a time builds a tree per record. Getting started with XPath continues from here.

Next steps ​

The next five pages complete the introduction: choosing a reading API, factories and sources, namespaces, errors and locations, and pipelines, which connect readers to tree builders and writers. Or go directly to a task:

TaskStart with
Read a file, an HTTP response or another sourceFactories and sources
Read a large file without buffering itLarge files and streams, then One record at a time
Query a documentGetting started with XPath
Change a documentPipelines
Write XMLWriting XML
Validate a documentValidating against a DTD
Read untrusted XMLUntrusted input

Released under the Apache License 2.0.