Skip to content

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:

ts
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
<?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:

ts
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 sourceCreated withCall
A string or bytes, available wholecreateStreamReader(source)writer.copy(reader)
A stream, read as its chunks arrivecreateAsyncStreamReader(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 with replaceEntityReferences: false reports 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:

ts
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
<?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:

ts
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
<?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:

ts
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
<?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:

TaskUseConnects to the writer with
Change text or attribute values, rename elements or attributesA delegate on the readerwriter.copy(reader), as with a filter
Add attributes or elementsSAX filtersoutput.createSAXHandler(destination)
Combine several of these, or hold back and reorder contentA generator over event objectsoutput.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:

ts
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
));
ts
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:

ts
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:

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.

Released under the Apache License 2.0.