Repository files navigation

Utility to stream HTML content into a live document.

npm install writable-dom

This module allows you to write a stream of raw HTML chunks into an existing element in the DOM.Each chunk of HTML is handled in a way that is similar to how browsers process and display it.

Specifically blocking assets, including stylesheets and scripts, prevent adding newly parsed nodes to the target element.This means that there are no flashes of unstyled content, and that scripts execution order follows the same rules as normal.

On top of that this module will look ahead for additional assets to preload while it is blocked.

The following examples fetch an HTML stream and place the content into a#root container element.

importWritableDOMStreamfrom"writable-dom";constres=awaitfetch("http://ebay.com");constmyEl=document.getElementById("root");awaitres.body.pipeThrough(newTextDecoderStream()).pipeTo(newWritableDOMStream(myEl));

The presented example relies on theWritableStreams API.

An alternative API is also available to use in case legacy browsers not implementingWritableStreams need to be supported.

The following is a version of the previous example implemented using the alternative API.

importwritableDOMfrom"writable-dom";constres=awaitfetch("https://ebay.com");constdecoder=newTextDecoder();constreader=res.body.getReader();constmyEl=document.getElementById("root");// create a writable object to stream data into.constwritable=writableDOM(myEl);try{while(true){const{ value, done}=awaitreader.read();if(done){// wait for blocking assets to finish.awaitwritable.close();break;}// write partial chunks of html.writable.write(decoder.decode(value));}}catch(err){// ensure the writable dom stops if there is an error.writable.abort(err);}

The module exposes a single default constructor function, once imported it can be used via one of the two following APIs.

importwritableDOMStreamfrom"writable-dom";newWritableDOMStream(target:ParentNode,previousSibling?:ChildNode|null):WritableStream

By instantiating a new object via thenew keyword on the constructor function, the generated object will be of typeWritableStream<string>, which you can for example combine with your original stream via thepipeTo method.

You can also providepreviousSibling to have all written HTML be placedafter that node.

importwritableDOMfrom"writable-dom";writableDOM(target:ParentNode,previousSibling?:ChildNode|null):Writable

Calling the function directly creates a newWritable object which you can use to manually write HTML into thetarget element.

Again, you can also providepreviousSibling to have all written HTML be placedafter that node.

AWritable object provides the following methods:

• write(html: string): void
  Writes a partial chunk of HTML content into thetarget element.

• close(): Promise<void>
  Indicates that no additional HTML is going to be written.Returns a promise that will resolve when all blocking assets have loaded and the content is being displayed in the document.You should not callwrite after callingclose.

• abort(err: Error): voidPrevents any additional HTML from being written into the document and aborts any blocking assets.You should not callwrite after callingabort.

This project adheres to theeBay Code of Conduct. By participating in this project you agree to abide by its terms.