Copying and changing documents
A reader can be piped straight into a writer, with no tree in between. That covers copying a document, extracting part of it, and dropping, changing or adding content on the way through.
The simplest case is one call on the stream writer: copy takes a reader and writes everything the reader reads:
import { StringSink, XMLOutputFactory } from '@exemplarjs/writer';
import { XMLInputFactory } from '@exemplarjs/xml';
const xml = new XMLInputFactory();
const reader = xml.createStreamReader('<catalog><book id="b1"><title>Dune</title></book><stock></stock></catalog>');
const sink = new StringSink();
const writer = new XMLOutputFactory({ indent: ' ' }).createStreamWriter(sink);
writer.copy(reader);
console.log(sink.toString());<?xml version="1.0" encoding="UTF-8"?>
<catalog>
<book id="b1">
<title>Dune</title>
</book>
<stock/>
</catalog>createStreamReader returns a cursor, and copy advances it to the end of the document, writing each event as it is read. The examples below use a factory named xml, created as this one is.
Copy a file or a stream
For a ReadableStream or an async iterable, such as a file stream or a fetch response, create the reader with createAsyncStreamReader, write to a stream, and call copyAsync. Each chunk is parsed and written as it arrives, so the document is never in memory whole:
import { createReadStream, createWriteStream } from 'node:fs';
import { Readable, Writable } from 'node:stream';
import { XMLOutputFactory } from '@exemplarjs/writer';
const input = Readable.toWeb(createReadStream('catalog.xml')) as ReadableStream<Uint8Array>;
const output = Writable.toWeb(createWriteStream('catalog-copy.xml'));
const reader = xml.createAsyncStreamReader(input);
const writer = new XMLOutputFactory({ indent: ' ' }).createStreamWriter(output);
await writer.copyAsync(reader);
await writer.close();copyAsync awaits both ends. It awaits the reader when the next chunk has not arrived yet. It also awaits the destination: when the output is slower than the input, the copy pauses until the destination has accepted what was written, so output does not queue up in memory.
close() resolves when the output stream has accepted everything. Always await it.
Whether to call copy or copyAsync depends only on the reader:
| The reader's source | Created with | Call |
|---|---|---|
| A string or bytes, available whole | createStreamReader(source) | writer.copy(reader) |
| A stream, read as its chunks arrive | createAsyncStreamReader(stream) | await writer.copyAsync(reader) |
Factories and sources lists every source a reader accepts.
What a copy keeps
A copy is the same document, not the same bytes. Elements, attributes, text, comments, processing instructions, CDATA sections and the DOCTYPE are all preserved. The writer serializes them in its own form, so some lexical details of the source are not:
- The XML declaration is generated by the writer, and names the writer's encoding.
- Attribute values are quoted with
", with one space between attributes. - An empty element is written as
<stock/>, as in the first example. - Entity references such as
&shop;are written as their replacement text, because the reader expands them. A reader created withreplaceEntityReferences: falsereports them as references, and the copy keeps them.
The writer's options apply to a copy as to any other output. indent formatted the first example, and Writer options lists the rest.
Copy one element into a document you are writing
copy starts from the reader's current position. At the start of a document it copies the whole document. On a start tag it copies that element with its content, and leaves the reader on the element's end tag. The element is written at the writer's current position, which can be inside a document written with the writer's own methods.
This example merges the books of two catalogs into a new catalog:
import { EventType } from '@exemplarjs/xml';
const spring = '<catalog><book id="b1"><title>Dune</title></book></catalog>';
const autumn = '<catalog><book id="b2"><title>Emma</title></book><book id="b3"><title>Ulysses</title></book></catalog>';
const writer = new XMLOutputFactory({ indent: ' ' }).createStreamWriter(sink);
writer.writeStartDocument();
writer.writeStartElement('catalog');
writer.writeAttribute('year', '2026');
for (const text of [spring, autumn]) {
const reader = xml.createStreamReader(text);
reader.nextTag(); // the source's <catalog>
while (reader.nextTag() === EventType.START_ELEMENT) {
writer.copy(reader); // one <book>, start tag to end tag
}
}
writer.writeEndDocument();<?xml version="1.0" encoding="UTF-8"?>
<catalog year="2026">
<book id="b1">
<title>Dune</title>
</book>
<book id="b2">
<title>Emma</title>
</book>
<book id="b3">
<title>Ulysses</title>
</book>
</catalog>nextTag() advances the reader to the next start tag or end tag. After each copy the reader is on a book's end tag, so the next nextTag() returns either the next book's start tag or the end tag of the source catalog, which ends the loop.
A copied element carries the namespace declarations it depends on, so its names resolve the same way in the new location. One record at a time shows how to select the elements to copy.
Drop content on the way
To change a document during a copy, change what the reader reports. copy writes whatever its reader returns, so the call stays the same.
The most common change is to drop content. createFilteredReader takes a reader and one or more predicates, and the reader then reports an event only if every predicate returns true for it. This copy drops the comments:
import { EventType } from '@exemplarjs/xml';
import { createFilteredReader } from '@exemplarjs/xml/filters';
const text = `<catalog>
<!-- spring list -->
<book id="b1">
<title>Dune</title>
</book>
</catalog>`;
const reader = createFilteredReader(xml.createStreamReader(text), (r) => r.eventType() !== EventType.COMMENT);
const writer = new XMLOutputFactory({ indent: ' ' }).createStreamWriter(sink);
writer.copy(reader);<?xml version="1.0" encoding="UTF-8"?>
<catalog>
<book id="b1">
<title>Dune</title>
</book>
</catalog>Dropping content with filters covers dropping whole elements and combining filters.
Tidy the whitespace
In the output above the comment is gone but its line remains, empty except for the two spaces that indented the comment. The line break and spaces around the comment are text, like any other text in the document, and the copy keeps them. indent does not remove them, because the writer adds whitespace only inside elements that contain no text, and these contain the old layout.
Once the old layout is dropped, the writer applies its own. Add a second filter that drops whitespace-only text:
const reader = createFilteredReader(
xml.createStreamReader(text),
(r) => r.eventType() !== EventType.COMMENT,
(r) => !r.isWhitespace()
);
const writer = new XMLOutputFactory({ indent: ' ' }).createStreamWriter(sink);
writer.copy(reader);<?xml version="1.0" encoding="UTF-8"?>
<catalog>
<book id="b1">
<title>Dune</title>
</book>
</catalog>The same combination, a whitespace filter and indent, re-indents any document, whatever its original layout.
WARNING
Drop whitespace-only text only from data documents, where the whitespace between tags is layout. In mixed content such as <p>A <em>great</em> <b>read</b></p>, the space between </em> and <b> separates two words, and dropping it joins them.
Change or add content on the way
Filters can only drop events. There are three ways to change or add content, and each ends in a writer:
| Task | Use | Connects to the writer with |
|---|---|---|
| Change text or attribute values, rename elements or attributes | A delegate on the reader | writer.copy(reader), as with a filter |
| Add attributes or elements | SAX filters | output.createSAXHandler(destination) |
| Combine several of these, or hold back and reorder content | A generator over event objects | output.createEventWriter(destination) |
copy accepts a delegate in place of the reader it wraps, so the copy is still writer.copy(reader). The other two use a different reading API, and the output factory creates the object that writes their output:
import { SAXParser } from '@exemplarjs/sax';
import { XMLOutputFactory } from '@exemplarjs/writer';
// InStock is your SAX filter, a subclass of XMLFilterImpl.
const writing = new XMLOutputFactory().createSAXHandler(sink);
new SAXParser(xml).parse(source, new InStock(writing));import { XMLOutputFactory } from '@exemplarjs/writer';
// asItems is a generator function of yours: it takes events in and yields the ones to write.
const writer = new XMLOutputFactory().createEventWriter(sink);
writer.add(asItems(xml.createEventReader(source)));The linked pages show each approach in full, including these endings. With no reason to prefer one, start with the reader: filters and delegates need the least code.
Copy a document read without namespaces
Some documents use prefixes such as shop: without declaring them, and a reader rejects them. A reader created with namespaceAware: false accepts them, by treating a colon as an ordinary character in a name. To copy such a document, set the same option on the output factory, so that the writer writes names as given and does not check for declarations:
import { XMLInputFactory } from '@exemplarjs/xml';
const loose = new XMLInputFactory({ namespaceAware: false });
const reader = loose.createStreamReader('<shop:catalog legacy:id="1"><shop:book/></shop:catalog>');
const writer = new XMLOutputFactory({ namespaceAware: false }).createStreamWriter(sink);
writer.copy(reader);
// <?xml version="1.0" encoding="UTF-8"?><shop:catalog legacy:id="1"><shop:book/></shop:catalog>With a default output factory, the writer rejects shop:catalog as a name with a WriterError, code WRITE_NAME. The same option applies to the event writer and the SAX writing handler. Namespaces covers reading without namespace processing.
Next steps
Four worked examples in the exemplar repository are complete programs:
- Change content with a delegate: stacked delegates convert units, copied from a file stream with
copyAsync. - Filter into a new document: filters drop elements and layout, and the writer indents afresh.
- SAX filters into a file: SAX filters change attributes on the way to a writing handler.
- Events into a file: a generator renames elements on the way to an event writer.
Elsewhere in this guide:
- Canonical XML: write a document in canonical form, for signing or comparison.
- Pipelines: how every reader, tree and writer connects, including when the result is a tree instead of a document.