Connections drop, proxies buffer responses, and mobile networks switch from WiFi to cellular mid-stream. If your streaming code doesn't plan for this, the user sees a response that just stops, with no error and no recovery.

In this article, you'll use an open source TypeScript library called Ore as a practical example of how to build a streaming client that handles real-world network conditions: automatic retries, the official Server-Sent Events (SSE) parsing spec, and clean integration with React and React Server Components.

By the end, you'll understand how async generators, the Fetch API, and the SSE spec fit together to build something far more reliable than a basic fetch and response.body.getReader() loop.

Table of Contents

1. Prerequisites

2. What You Will Learn

3. What Is Server-Sent Events?

4. Why Build a Custom Streaming Client?

5. How to Stream Raw Chunks with an Async Generator

6. How to Parse Server-Sent Events by Hand

7. How to Implement Reconnection with Last-Event-ID

8. How to Handle Retries with Backoff

9. How to Use This with React

10. How to Use This with React Server Components

11. Conclusion

Prerequisites

To follow along, you should have:

• A working understanding of TypeScript

• Familiarity with fetch, ReadableStream, and async/await

• Basic knowledge of React (for the React-specific sections)

What You Will Learn

• How to stream raw text or bytes from a fetch response using async generators

• How to parse the Server-Sent Events spec by hand, field by field

• How to implement automatic reconnection with Last-Event-ID so you don't lose events

• How to handle retries with exponential backoff

• How to integrate a streaming client with React state and React Server Components

What Is Server-Sent Events?

Server-Sent Events (SSE) is a web standard for one-way streaming from server to client over a single HTTP connection. Unlike WebSockets, it's plain HTTP, which means it works through existing infrastructure like load balancers and proxies without special configuration.

An SSE response looks like this on the wire:

event: update
id: 42
data: {"status": "processing"}

event: update
id: 43
data: {"status": "complete"}

Each event is separated by a blank line. The data field carries the payload, event names the event type, and id lets the client track its position in the stream for reconnection.

The browser has a built-in EventSource API for this, but it has real limitations: no custom headers, no POST requests, and inconsistent reconnection behavior across browsers. For anything beyond the simplest case, you often need to parse the stream yourself.

Why Build a Custom Streaming Client?

Many streaming use cases, like AI chat responses, don't use the SSE spec at all. They're just raw chunks of text arriving over time. Other cases, like live notifications, genuinely benefit from the structure SSE provides: named events, IDs for resumption, and a server-controlled retry interval.

Ore handles both with two separate functions:

• stream() for raw text or byte streaming, with no assumptions about format

• streamSSE() for spec-compliant SSE parsing

Both are async generators, so consuming either looks the same from the call site:

for await (const chunk of stream("https://api.example.com/chat")) {
  console.log(chunk);
}

How to Stream Raw Chunks with an Async Generator

The simplest case is streaming raw text. This is useful for AI responses or log tails where there's no event structure, just a sequence of bytes arriving over time.

Here's the core of stream():

export async function* stream(
  url: string,
  options?: StreamOptions
): AsyncGenerator<string | Uint8Array, void, unknown> {
  const { headers, retries = 3, signal, decode = true } = options || {};

  let retryCount = 0;

  while (retryCount <= retries) {
    try {
      const response = await fetch(url, { method: "GET", headers, signal });

      if (!response.body) {
        throw new Error("Response body is null");
      }

      const reader = response.body.getReader();
      const decoder = new TextDecoder();

      try {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          yield decode ? decoder.decode(value, { stream: true }) : value;
        }
      } finally {
        reader.releaseLock();
      }

      return;
    } catch (error: any) {
      if (signal?.aborted) throw error;
      retryCount++;
      if (retryCount > retries) {
        throw new Error(`Max retries exceeded. Last error: ${error.message}`);
      }
      await new Promise((r) => setTimeout(r, 1000 * retryCount));
    }
  }
}

A few design decisions are worth calling out.

The function is an async generator (async function*), so the caller can use for await...of instead of managing a reader and a loop manually. That's the difference between exposing a raw ReadableStream and exposing something pleasant to consume.

The finally block always releases the reader lock, even if the loop exits early through a break or an exception. Forgetting this is a common source of stream leaks.

The retry loop only catches errors from the fetch call and the read loop. If the AbortSignal was the cause of the failure, it rethrows immediately rather than retrying, since retrying a deliberate cancellation makes no sense.

How to Parse Server-Sent Events by Hand

The SSE spec is a simple text format, but parsing it correctly means handling several edge cases: events split across multiple data lines, comment lines starting with a colon, fields with no value, and incomplete lines at the end of a chunk.

Here's the core state machine inside streamSSE():

let buffer = "";
let currentEvent: Partial<SSEEvent> = { data: "", event: null, id: null };
let hasData = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split(/\r\n|\r|\n/);
  buffer = lines.pop() || ""; // keep the last incomplete line for the next chunk

  for (const line of lines) {
    if (line === "") {
      if (hasData) {
        const event: SSEEvent = {
          id: currentEvent.id ?? lastEventId,
          event: currentEvent.event ?? null,
          data: currentEvent.data!.endsWith("\n")
            ? currentEvent.data!.slice(0, -1)
            : currentEvent.data!,
          retry: currentEvent.retry,
        };
        if (event.id) lastEventId = event.id;
        yield event;
        currentEvent = { data: "", event: null, id: null };
        hasData = false;
      }
      continue;
    }

    if (line.startsWith(":")) continue; // comment line, ignore

    const colonIndex = line.indexOf(":");
    const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
    let valueStr = colonIndex === -1 ? "" : line.slice(colonIndex + 1);
    if (valueStr.startsWith(" ")) valueStr = valueStr.slice(1);

    switch (field) {
      case "data":
        currentEvent.data += valueStr + "\n";
        hasData = true;
        break;
      case "event":
        currentEvent.event = valueStr;
        break;
      case "id":
        if (valueStr.indexOf("\0") === -1) currentEvent.id = valueStr;
        break;
      case "retry":
        const retry = parseInt(valueStr, 10);
        if (!isNaN(retry)) retryInterval = retry;
        break;
    }
  }
}

A network chunk doesn't respect line boundaries. A single read() call might end mid-line, so the last, possibly incomplete line is held back in buffer and prepended to the next chunk rather than processed early. This is the part of SSE parsing that's easy to get wrong if you reach for a naïve response.text() and a string split.

The blank line is what ends an event. SSE events don't have a fixed-length header. The spec says a blank line marks the boundary, so the parser only yields an event once it has seen one.

The id field is rejected outright if it contains a null byte, per the spec. That's a small detail that almost no hand-rolled implementation gets right on the first try.

How to Implement Reconnection with Last-Event-ID

This is the part of SSE that gives it a real advantage over a plain fetch stream: built-in support for resuming after a disconnect without losing your place.

let lastEventId: string | null = null;

while (retryCount <= retries) {
  const headers = { ...customHeaders };
  if (lastEventId) {
    (headers as any)["Last-Event-ID"] = lastEventId;
  }

  const response = await fetch(url, { method: "GET", headers, signal });
  // ... read and parse events, updating lastEventId as they arrive
}

Every time an event with an id field arrives, lastEventId is updated. If the connection drops and the client reconnects, it sends Last-Event-ID in the request headers. A well-behaved server can use that header to resume the stream from the right point instead of replaying everything or skipping ahead.

This only works if the server actually honors the header, so it's a contract between client and server, not something the client can guarantee alone. But having the client track and send it correctly is the necessary half of that contract.

How to Handle Retries with Backoff

Both stream() and streamSSE() retry on failure, but they do it slightly differently based on what failed.

stream() uses a simple linear backoff tied to the retry count:

await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));

streamSSE() respects the server-specified retry field from the SSE spec when one is provided, falling back to a default otherwise:

let retryInterval = 1000;
// ... updated from the "retry" field if the server sends one
await new Promise((r) => setTimeout(r, retryInterval));

Letting the server influence the retry interval matters in practice. A server under load can tell clients to back off longer, which is exactly the kind of cooperative behavior the SSE spec was designed to support.

In both functions, an aborted AbortSignal always short-circuits the retry loop. Treating a deliberate cancellation as a retryable failure is a common bug, and the fix is just checking signal?.aborted before deciding to retry.

How to Use This with React

Because both functions are async generators, integrating with React state is a matter of looping and calling setState per chunk:

function ChatComponent() {
  const [messages, setMessages] = useState("");

  useEffect(() => {
    const controller = new AbortController();

    (async () => {
      try {
        for await (const chunk of stream("/api/chat", { signal: controller.signal })) {
          setMessages((prev) => prev + chunk);
        }
      } catch (err: any) {
        if (err.name !== "AbortError") console.error(err);
      }
    })();

    return () => controller.abort();
  }, []);

  return <div>{messages}</div>;
}

The cleanup function calling controller.abort() is doing real work here. Without it, navigating away from the component while a stream is still active leaves the fetch running in the background, updating state on an unmounted component.

How to Use This with React Server Components

Because the generator yields values one at a time, you can also drive a recursive Suspense boundary directly from the async iterator, streaming HTML to the client as each chunk arrives:

async function StreamViewer({ iterator }: { iterator: AsyncIterator<string> }) {
  const { value, done } = await iterator.next();
  if (done) return null;

  return (
    <span>
      {value}
      <Suspense>
        <StreamViewer iterator={iterator} />
      </Suspense>
    </span>
  );
}

export default function Page() {
  const dataStream = stream("https://api.example.com/stream");
  const iterator = dataStream[Symbol.asyncIterator]();

  return (
    <Suspense fallback="Loading...">
      <StreamViewer iterator={iterator} />
    </Suspense>
  );
}

Each recursive call awaits the next chunk and renders a nested Suspense boundary for the rest. React streams each piece of HTML to the client as it resolves, rather than waiting for the entire response.

Conclusion

A reliable streaming client needs to handle more than the success path. Connections drop, chunks arrive split across line boundaries, and cancellation needs to be distinguished from failure.

Ore's approach to this is built from a small set of ideas:

• Expose streams as async generators so consumers can use for await...of

• Parse SSE by hand, field by field, respecting the spec's blank-line event boundaries and buffering incomplete lines across chunks

• Track Last-Event-ID so reconnection can resume rather than restart

• Treat retries and cancellation as separate concerns

• Stay framework-agnostic at the core, with thin integration points for React and React Server Components

That combination is what separates a streaming client that works in a demo from one that holds up against real network conditions. You can explore the full source code at github.com/glamboyosa/ore.

But traditional HTML streaming has a strict rule. The HTML comes in the order of the document. If the browser gets the header first, then the sidebar, and finally the main content, it parses those chunks in that order. If a slow database query blocks a chunk of the page early on, the next chunk often has to wait until it's ready on the server.

JavaScript frameworks have been solving this problem for years. Server-rendering frameworks handle shell, suspense boundaries, loading state, and late content streaming. Some frameworks use inline script to patch the existing DOM. Libraries like HTMX allow developers to update parts of a page with server-generated HTML.

But these solutions require JavaScript somewhere. Declarative Partial Updates raise a different question. What if HTML had its own way of saying,

When this content comes in, put it there?

That's the idea behind Chrome's declarative partial updates proposal.

In this article, you'll learn what problems declarative partial updates aim to solve, how the proposed placeholder syntax works, how out-of-order HTML streaming differs from normal streaming, how the related JavaScript HTML insertion APIs fit in, and why it should be considered an experimental feature of the browser rather than production-ready HTML.

Table of Contents

• What Problem Declarative Partial Updates Try to Solve

• How Traditional HTML Streaming Works

• Why Frameworks Already Work Around This Problem

• What Declarative Partial Updates Add to HTML

• How Marker Placeholders Work

• How Start and End Range Placeholders Work

• How Multiple Updates Work

• How Interleaved Updates Work

• How This Compares to React, HTMX, Astro, and PHP

• How the JavaScript HTML Insertion APIs Fit In

• How to Build a Small Node.js Streaming Demo

• Browser Support and Current Status

• Security, Sanitization, and Sharp Edges

• What This Means for Web Developers

• Conclusion

What Problem Declarative Partial Updates Try to Solve

Consider a product page. The server already knows the page title, navigation, footer, and product details. But the recommendations section requires a slow database query. With traditional server-rendered HTML, you have two common options:

• First, the server waits until everything is ready, then sends a full HTML response. This keeps the code simple, but the user waits a long time before seeing anything useful.

• Second, the server streams the HTML in stages. It sends the top of the page first, then sends the rest as it's ready. This seems to improve performance, because the browser starts rendering before the full response is finished.

But streaming alone doesn't completely solve this problem. The browser still parses the HTML sequentially. If there's a slow recommendation block at the beginning of the document, the content after that block will wait behind it, unless you restructure the document, add JavaScript, or use a framework abstraction.

WICG Patching Explainer describes two limitations of traditional HTML streaming:

1. HTML content is streamed in DOM order.

2. After the initial document parsing step, streaming is no longer as active as before.

Declarative partial update attempts to relax the first limitation. It allows the server to first send a placeholder and then send the actual content in the response. The browser applies that next content over the previous placeholder. This patch doesn't require any custom client-side DOM patching code.

In the above diagram, the server sends HTML chunks in sequence. The browser can render early chunks before the response ends, but the rendered order still follows the response order.

How Traditional HTML Streaming Works

Before studying the proposal, you need to understand its basic structure. A server sends an HTTP response body. That body contains HTML. The browser reads the response as soon as it arrives. It doesn't need to wait for the entire response body to parse the first tags.

Here's a tiny Node.js example:

import http from "node:http";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const server = http.createServer(async (req, res) => {
    res.writeHead(200, {
        "Content-Type": "text/html; charset=utf-8",
    });

    res.write(`
    <!doctype html>
    <html>
      <head>
        <title>Normal HTML Streaming</title>
      </head>
      <body>
        <h1>Normal HTML Streaming</h1>
        <p>This part arrives first.</p>
  `);

    await sleep(2000);

    res.write(`
        <p>This part arrives after two seconds.</p>
  `);

    await sleep(2000);

    res.end(`
        <p>This part arrives after four seconds.</p>
      </body>
    </html>
  `);
});

server.listen(3000, () => {
    console.log("Server running at http://localhost:3000");
});

This example creates a small HTTP server using Node's built-in http module. When you visit the page, the server sends a response in three separate HTML chunks.

The first res.write() immediately sends the document shell, title, and first paragraph. Then sleep(2000) pauses the server for two seconds before the next res.write() sends another paragraph. After another pause, res.end() sends the last paragraph and closes the HTML document.

The browser starts rendering the first chunk before the entire response is complete, then adds subsequent paragraphs as more HTML arrives.

This demonstrates that simple HTML streaming works, but the content is displayed in the same order that the server sends it.

Now open this page in a browser.

http://localhost:3000

You'll see the first part of the page before the entire response is complete. As the server sends more chunks, the browser continues to load.

This behavior is old and functional. But notice its structure. The server writes the first paragraph, then the second paragraph, and then the third paragraph. The browser receives them in the same order. It also places them in the DOM in the same order.

Traditional streaming lets you send previous content first. But it doesn't give you a native way to say that this next chunk will be inside a previous placeholder. Declarative partial updates target that missing part.

Why Frameworks Already Work Around This Problem

Modern frameworks already create experiences where parts of a page are rendered as they're ready. React server components and suspense-based server rendering are common examples. A framework can first send a shell, show a fallback, and then stream the full content later.

But the browser doesn't understand a React boundary as native HTML. The framework has to encode its own protocol. As the WICG patching explainer notes, React uses inline <script> tags to stream content out of order and modify the already parsed DOM.

This works because JavaScript has full DOM access. But it also means that the browser isn't applying the update as normal HTML. A framework runtime or framework-generated script participates in this patching.

HTMX solves a related class of problems in another way. It allows you to request server-rendered HTML and swap parts of the page. This model is practical and popular, but it still relies on a JavaScript library.

Astro popularized the islands architecture, where independently interactive parts of a page are essentially contained within a static HTML document. Chrome's article on Declarative Partial Updates mentions the island architecture as a use case for this proposal.

Declarative Partial Updates doesn't replace those tools. It proposes a low-level browser primitive. Frameworks can later adopt this primitive. Server-rendered apps can also use it directly in simpler cases.

The key change is this: instead of sending JavaScript that finds a DOM node and modifies it, the server sends HTML that declares where the node is located.

What Declarative Partial Updates Add to HTML

Chrome's proposal has two main parts:

• The first part is HTML placeholders and out-of-order streaming using the <template> patch.

• The second part is a new set of JavaScript methods for inserting and streaming HTML into existing documents.

Chrome's announcement states that these APIs are ready for developers to test starting in Chrome 148 using the Experimental Web Platform Features flag. This status is important. It's not currently a stable cross-browser HTML. It's an active proposal and implementation test.

For the declarative streaming part, the proposal uses two HTML concepts:

1. Processing instruction placeholders.

2. The <template> element with the for attribute.

A simplified example looks like this:

<div><?marker name="profile-card"></div>

<template for="profile-card">
    <article>
        <h2>Ada Lovelace</h2>
        <p>Mathematician and early computing pioneer.</p>
    </article>
</template>

The placeholder marks a location. The template contains the content. When the browser parses the template, it finds the matching placeholder and applies the template content there. After parsing, the final DOM behaves like this:

<div>
    <article>
        <h2>Ada Lovelace</h2>
        <p>Mathematician and early computing pioneer.</p>
    </article>
</div>

The server sent the placeholder first and the actual content later. The browser combined them declaratively. That's the basic idea. The HTML gets a native patching instruction without any custom scripts.

In the diagram above, the browser receives and parses the placeholders first. Subsequent templates target those placeholders, so the rendered page updates specific areas without appending all the late HTML at the bottom.

How Marker Placeholders Work

The simplest placeholder is <?marker>. A marker refers to a place in a document where HTML code will appear later. Here's a small example from the proposed model:

<section>
    <h2>Team</h2>

    <ul>
        <?marker name="team-members">
    </ul>
</section>

<template for="team-members">
    <li>Ada Lovelace</li>
</template>

The name attribute of the marker connects it to the for attribute of the template. When the browser parses the template, it finds the marker named team-members and inserts the template content at the location of that marker.

The final DOM behaves like this:

<section>
    <h2>Team</h2>

    <ul>
        <li>Ada Lovelace</li>
    </ul>
</section>

While this may seem simple, timing is important. The placeholder can come at the beginning of the response. The template can come later. This means that the browser can render a working shell first, then patch that specific location when the server sends the delayed content.

This is different from normal streaming, where the next HTML document is displayed later in the order. A marker specifies a target for the next HTML.

Why Processing Instructions Matter

The placeholder syntax may look unusual if you mostly write HTML.

<?marker name="profile">

This is similar to the XML Processing Instruction syntax. MDN explains that processing instructions exist in the DOM, but are currently treated as comments in HTML documents. The Declarative Partial Updates proposal gives browser-level meaning to selected processing instructions for HTML patching. This is why this feature requires browser support.

In current stable HTML, writing <?marker name="profile"> doesn't create a patch point in all browsers. Without support, it treats content as ignored markup or comments. So you should consider this syntax as a recommended behavior, not as established HTML behavior.

How Start and End Range Placeholders Work

A single marker gives you an insertion point. But many UI updates need to replace a whole region.

For example, a page might show a loading message first:

<section>
    <h2>Recommendations</h2>

    <?start name="recommendations">
    <p>Loading recommendations...</p>
    <?end>
</section>

Later, the server sends the real content:

<template for="recommendations">
    <ul>
        <li>Advanced CSS Layouts</li>
        <li>Modern HTML APIs</li>
        <li>Web Performance Basics</li>
    </ul>
</template>

The browser replaces the range between <?start> and <?end> with the template content.

The final DOM behaves like this:

<section>
    <h2>Recommendations</h2>

    <ul>
        <li>Advanced CSS Layouts</li>
        <li>Modern HTML APIs</li>
        <li>Web Performance Basics</li>
    </ul>
</section>

This is near a loading boundary. The document starts with the necessary fallback content. The server finishes the slow work later. When the appropriate template arrives, the browser replaces the fallback.

The <?end> processing directive in the explainer is optional, but it makes the examples easier to understand. Use it when teaching or testing the feature.

Marker Versus Range

Use markers to add content at a specific location. Use a start and end range to replace temporary content.

That means, add something here:

<ul>
    <?marker name="new-item">
</ul>

This says, replace this whole loading region later:

<div>
    <?start name="profile">
    <p>Loading profile...</p>
    <?end>
</div>

The second method is more suitable for real interfaces, as users see meaningful fallback content while they wait.

How Multiple Updates Work

A placeholder doesn't have to be just an update. A server can send a patch, leave another marker, and then send another patch later. This is important for lists, feeds, notifications, logs, comments, and search results.

Here's a simplified example:

<ul>
    <?marker name="messages">
</ul>

<template for="messages">
    <li>First message</li>
    <?marker name="messages">
</template>

<template for="messages">
    <li>Second message</li>
    <?marker name="messages">
</template>

<template for="messages">
    <li>Third message</li>
</template>

The final DOM behaves like this:

<ul>
    <li>First message</li>
    <li>Second message</li>
    <li>Third message</li>
</ul>

Each patch adds content and creates the next outlet. This model is suitable for streaming data, where the server finds the results over time.

Think of a search page. The server finds the first result quickly. The second result requires another service call. The third result requires a database lookup.

Traditional HTML streaming places each result where it appears in the response. Declarative patching allows each result to target a known outlet in the document. This doesn't mean that every list should use this feature. It means that HTML will have a native primitive for this pattern.

How Interleaved Updates Work

The most interesting part is interleaving.

Suppose a page has three regions:

1. A profile card.

2. A recommendations panel.

3. A notification list.

Each region requires different server management. The profile card is ready after one second. Notifications are ready after two seconds. Recommendations are ready after four seconds. In simple streaming, the order of your documents determines what the user sees first.

With declarative patching, the server sends placeholders early:

<main>
    <section>
        <h2>Profile</h2>
        <?start name="profile">
        <p>Loading profile...</p>
        <?end>
    </section>

    <section>
        <h2>Recommendations</h2>
        <?start name="recommendations">
        <p>Loading recommendations...</p>
        <?end>
    </section>

    <section>
        <h2>Notifications</h2>
        <?start name="notifications">
        <p>Loading notifications...</p>
        <?end>
    </section>
</main>

Then the server sends templates in readiness order, not visual order:

<template for="profile">
    <p>Ada Lovelace</p>
</template>

<template for="notifications">
    <ul>
        <li>You have one new message.</li>
    </ul>
</template>

<template for="recommendations">
    <ul>
        <li>Modern HTML APIs</li>
        <li>Streaming Web Apps</li>
    </ul>
</template>

The browser patches each target region. The user gets the profile first, the notification second, and the recommendations third, although in the main document structure the recommendations appear before the notifications.

This is why 'out-of-order streaming' is the key. The HTML response comes in as a stream. But the rendered update doesn't have to follow the same visual order as the response chunks.

The WICG Explainer describes interleaved patching across different outlets. This is one of the strongest reasons this proposal matters. It gives browser-native HTML a behavior developers usually associate with framework-level streaming.

How This Compares to React, HTMX, Astro, and PHP

This feature will allow for comparisons. These comparisons can help you understand the main idea, but can also be confusing if you go too deep.

React

React server rendering already supports streaming UI and fallback state. But the rendering model is React's own. When React needs to patch late-added content to an already parsed document, it uses framework-generated directives and JavaScript.

Declarative Partial Updates bring a low-level part of this concept to HTML. It doesn't replace React's component model, state model, event handling, reconciliation, or ecosystem.

HTMX

HTMX allows you to request HTML from the server and replace it on the page. It's conceptually close, because it treats HTML as the main response format. But HTMX is a JavaScript library.

The goal of declarative partial updates is to make some HTML patching behavior a feature of the browser itself. HTMX still handles many interaction patterns beyond this proposal.

Astro

Astro popularized island-based rendering. A page can consist of mostly static HTML and isolated interactive regions. Chrome cites island architecture as a use case, because independent regions of a page are often rendered at different times.

Declarative partial updates can help servers serve island HTML as each region is rendered.

PHP

Its syntax may remind you of PHP, as server-side code and HTML have been used together for decades. But this proposal is not PHP inside the browser.

PHP runs on the server. Declarative partial updates are the browser's parsing behavior for streamed HTML. A useful workflow comparison can be made with it.

It makes it easier to stream server-generated HTML to specific locations on the page without having to send a separate JavaScript patch for each update.

How the JavaScript HTML Insertion APIs Fit In

Declarative placeholders solve part of the problem. They help the browser patch the streamed HTML to a previous location in the same document.

But not every update comes as part of the original HTML response. Many apps fetch HTML after the page has loaded.

For example, a page might fetch:

• A comments section

• A cart summary

• A profile dropdown

• A notification panel

• A search result preview

Today, JavaScript has several ways to insert HTML into a document:

element.innerHTML = "<p>Hello</p>";
element.outerHTML = "<section>Hello</section>";
element.insertAdjacentHTML("beforeend", "<p>Hello</p>");

These APIs work, but they don't behave the same way.

• Some replace content.

• Some insert beside content.

• Some parse in a specific context.

• Some interact with sanitization and security rules differently.

Chrome's declarative partial updates work also includes a revamped set of HTML insertion and streaming APIs, aiming to create a more explicit naming convention for common insertion patterns.

Here's the basic idea:

The names tell you where the HTML goes. That's the main improvement.

Instead of remembering how innerHTML, outerHTML, insertAdjacentHTML, and createContextualFragment() differ, the method name describes the action.

Static Insertion

A static method accepts a complete HTML string.

const card = document.querySelector("#profile-card");

card.setHTML(`
  <article>
    <h2>Ada Lovelace</h2>
    <p>Mathematician and early computing pioneer.</p>
  </article>
`);

setHTML() parses the string, sanitizes it, and inserts the result into the element.

MDN describes setHTML() as an XSS-safe way to parse and sanitize an HTML string before including it in the DOM. This is safer than assigning untrusted HTML to innerHTML.

Streaming Insertion

The streaming method doesn't require the entire HTML string to begin with. It creates a writable stream. Then JavaScript writes fragments to that stream.

A simplified example looks like this:

const output = document.querySelector("#output");
const writer = output.streamHTMLUnsafe().getWriter();

await writer.write("<p>First streamed chunk</p>");
await writer.write("<p>Second streamed chunk</p>");
await writer.close();

This model is important because streaming is one of the strengths of HTML. The browser doesn't always have to wait for a complete response before inserting meaningful markup.

Chrome also shows this pattern with fetch():

const output = document.querySelector("#output");
const response = await fetch("/comments");

response.body
    .pipeThrough(new TextDecoderStream())
    .pipeTo(output.streamHTMLUnsafe());

Here, the response body streams from the network. TextDecoderStream converts bytes into text. The result pipes into the element's HTML stream.

Why the Unsafe Name Matters

Some methods have Unsafe versions.

For example:

setHTMLUnsafe();
streamHTMLUnsafe();
appendHTMLUnsafe();
streamAppendHTMLUnsafe();

The name is intentional. MDN warns that setHTMLUnsafe() parses the input as HTML and writes the result to the DOM. If you don't pass a sanitizer, no sanitizer is used.

Use the safe versions for untrusted content. Consider the unsafe versions as a low-level tool, especially in cases where you have full control over the HTML source or pass an appropriate sanitizer.

For the demo in this article, keep the user input away from the HTML string. The goal is to teach streaming behavior, not unsafe HTML insertion.

In the diagram above, declarative patching begins within the streamed document. JavaScript streaming insertion begins after the script code selects an element and pipes a streamed response into it.

How to Build a Small Node.js Streaming Demo

Now let's build a small demo.

You will create one Node.js server with three routes:

The demo uses Node's built-in http module.

• No Express.

• No frontend framework.

• No build step.

That keeps the focus on HTML streaming.

Create the Project

Create a new folder:

mkdir html-partial-updates-demo
cd html-partial-updates-demo

Create a package.json file:

{
    "name": "html-partial-updates-demo",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        "dev": "node server.js"
    }
}

Create a server.js file:

import http from "node:http";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const server = http.createServer(async (req, res) => {
    if (req.url === "/normal-stream") {
        return normalStream(req, res);
    }

    if (req.url === "/partial-updates-demo") {
        return partialUpdatesDemo(req, res);
    }

    if (req.url === "/stream-html-api-demo" || req.url === "/comments-stream") {
        return streamHtmlApiDemo(req, res);
    }

    res.writeHead(200, {
        "Content-Type": "text/html; charset=utf-8",
    });

    res.end(`
    <!doctype html>
    <html>
      <head>
        <title>HTML Partial Updates Demo</title>
      </head>
      <body>
        <h1>HTML Partial Updates Demo</h1>

        <ul>
          <li><a href="/normal-stream">Normal HTML streaming</a></li>
          <li><a href="/partial-updates-demo">Declarative partial updates demo</a></li>
          <li><a href="/stream-html-api-demo">Streaming HTML API demo</a></li>
        </ul>
      </body>
    </html>
  `);
});

async function normalStream(req, res) {
    res.writeHead(200, {
        "Content-Type": "text/html; charset=utf-8",
    });

    res.write(`
    <!doctype html>
    <html>
      <head>
        <title>Normal HTML Streaming</title>
      </head>
      <body>
        <h1>Normal HTML Streaming</h1>

        <p>This paragraph arrives immediately.</p>
  `);

    await sleep(1500);

    res.write(`
        <p>This paragraph arrives after 1.5 seconds.</p>
  `);

    await sleep(1500);

    res.end(`
        <p>This paragraph arrives after 3 seconds.</p>

        <p>
          <a href="/">Back to home</a>
        </p>
      </body>
    </html>
  `);
}

async function partialUpdatesDemo(req, res) {
    res.writeHead(200, {
        "Content-Type": "text/html; charset=utf-8",
    });

    res.write(`
    <!doctype html>
    <html>
      <head>
        <title>Declarative Partial Updates Demo</title>
        <style>
          body {
            font-family: system-ui, sans-serif;
            max-width: 760px;
            margin: 40px auto;
            line-height: 1.5;
          }

          section {
            border: 1px solid #ddd;
            border-radius: 12px;
            padding: 16px;
            margin-bottom: 16px;
          }

          .loading {
            color: #666;
          }
        </style>
      </head>
      <body>
        <h1>Declarative Partial Updates Demo</h1>

        <p>
          This page sends placeholders first. Then the server sends
          matching templates when each piece of content is ready.
        </p>

        <section>
          <h2>Profile</h2>
          <?start name="profile">
            <p class="loading">Loading profile...</p>
          <?end>
        </section>

        <section>
          <h2>Recommendations</h2>
          <?start name="recommendations">
            <p class="loading">Loading recommendations...</p>
          <?end>
        </section>

        <section>
          <h2>Notifications</h2>
          <?start name="notifications">
            <p class="loading">Loading notifications...</p>
          <?end>
        </section>
  `);

    await sleep(1000);

    res.write(`
        <template for="profile">
          <p><strong>Ada Lovelace</strong></p>
          <p>Mathematician and early computing pioneer.</p>
        </template>
  `);

    await sleep(1000);

    res.write(`
        <template for="notifications">
          <ul>
            <li>You have one new message.</li>
            <li>Your weekly report is ready.</li>
          </ul>
        </template>
  `);

    await sleep(2000);

    res.end(`
        <template for="recommendations">
          <ul>
            <li>Modern HTML APIs</li>
            <li>Streaming Web Apps</li>
            <li>Web Performance Basics</li>
          </ul>
        </template>

        <p>
          <a href="/">Back to home</a>
        </p>
      </body>
    </html>
  `);
}

async function streamHtmlApiDemo(req, res) {
    if (req.url === "/comments-stream") {
        res.writeHead(200, {
            "Content-Type": "text/html; charset=utf-8",
        });

        res.write(`<article><p>First streamed comment.</p></article>`);

        await sleep(1000);

        res.write(`<article><p>Second streamed comment.</p></article>`);

        await sleep(1000);

        return res.end(`<article><p>Third streamed comment.</p></article>`);
    }

    res.writeHead(200, {
        "Content-Type": "text/html; charset=utf-8",
    });

    res.end(`
    <!doctype html>
    <html>
      <head>
        <title>Streaming HTML API Demo</title>
      </head>
      <body>
        <h1>Streaming HTML API Demo</h1>

        <button id="load-comments">Load comments</button>

        <section id="comments"></section>

        <p>
          <a href="/">Back to home</a>
        </p>

        <script>
          const button = document.querySelector("#load-comments")
          const comments = document.querySelector("#comments")

          button.addEventListener("click", async () => {
            const response = await fetch("/comments-stream")

            response.body
              .pipeThrough(new TextDecoderStream())
              .pipeTo(comments.streamHTMLUnsafe())
          })
        </script>
      </body>
    </html>
  `);
}

server.listen(3000, () => {
    console.log("Server running at http://localhost:3000");
});

This file creates the main demo server. It imports Node's built-in http module, then defines a small sleep() helper for delayed streaming, and then creates an HTTP server with three planned routes.

When the request URL matches /normal-stream, /partial-updates-demo, or /stream-html-api-demo, the server passes the request to the corresponding function. If the user visits the root page, the server returns a simple HTML page with links to the three demos.

Finally, server.listen(3000) starts the server on port 3000, so you can open the demo in your browser at http://localhost:3000.

Run the server:

npm run dev

Then open in browser:

http://localhost:3000

You now have three demos.

Test the Normal Streaming Route

Open this route:

http://localhost:3000/normal-stream

Watch the browser.

• The first paragraph appears early.

• The second paragraph appears later.

• The third paragraph appears last.

This is useful, but it's still in-order streaming. The browser renders in the same order the server sends.

Test the Declarative Partial Updates Route

Open this route:

http://localhost:3000/partial-updates-demo

In a browser that supports the experimental feature, the page first shows three loading regions.

• After one second, the profile region updates.

• After another second, the notifications region updates.

• After two more seconds, the recommendations region updates.

Notice the order. The recommendation section appears before the notification in the document. But the server sends the notification template before the recommendation template.

That's the point. The document structure and streaming order no longer need to be the same. The browser uses the for attribute on each <template> to find the matching processing instruction placeholder.

This example demonstrates the basic idea behind out-of-order HTML streaming.

Test the Streaming HTML API Route

Open this route:

http://localhost:3000/stream-html-api-demo

Click the button.

• The browser fetches /comments-stream.

• The server sends comment HTML in chunks.

• The client pipes the streamed response body into the #comments element.

This isn't the same as declarative placeholder patching. Here, JavaScript starts the request and chooses the target element.

The new API improves how JavaScript inserts streamed HTML. The placeholder syntax improves how HTML itself declares later patches during document streaming. Keep those two ideas separate. They're related, but they solve different parts of the partial update story.

Browser Support and Current Status

Declarative Partial Updates are experimental. Chrome says these APIs are ready for developer testing from Chrome 148 through the experimental web platform features flag.

That means you should read this proposal as active platform work, not as stable production HTML.

To test native behavior in Chrome, enable this flag:

chrome://flags/#enable-experimental-web-platform-features

Then restart the browser. The Blink developer thread describes the feature as a way to stream HTML content out of order and update an existing document with a stream of encoded patches.

The proposal also has a WICG explainer and a WHATWG HTML pull request.

That tells you where the proposal sits:

1. It has a real implementation path in Chrome.

2. It has an explainer in WICG.

3. It has standardization discussion in WHATWG.

4. It's not a finished cross-browser standard yet.

So Declarative Partial Updates are a proposed set of browser APIs for native HTML patching and streaming. Chrome has made them available for developer testing behind a flag.

Security, Sanitization, and Sharp Edges

Partial updates may sound simple. But there are always security risks when adding HTML to a document.

HTML isn't just plain text. It can contain links, forms, event handlers, scripts, custom elements, and other elements that are parsed by the browser. So the source of the HTML is important.

If your server streams trusted HTML generated by your own template, the type of risk is different from the type of risk of adding HTML sent from a user's comments, profile, or chat message.

Template Scope

Chrome's article mentions an important restriction for <template for>. A template only updates processing instructions within the same parent element. Adding <template for> directly to the <body> gives it access to the whole document, including the <head>. That behavior is powerful, so you should understand the scope before designing around it.

The main point is simple: Don't assume a late template should patch any placeholder anywhere without rules. The patch target is scoped for security and predictability.

Dynamic Insertion Has Different Behavior

There's another sharp edge. If you insert a chunk of HTML dynamically using an API like setHTML() or innerHTML, the browser parses that HTML inside an intermediate fragment first.

That means declarative patching applies inside that parsed fragment. It doesn't automatically search the whole existing document and update old placeholders outside the fragment. This distinction matters because document streaming and dynamic HTML insertion aren't the same process.

Safe and Unsafe HTML APIs

The JavaScript insertion APIs also separate safer and lower-level methods.

• setHTML() sanitizes the input before inserting it.

• setHTMLUnsafe() is lower level.

MDN says setHTML() should almost always be preferred where supported because it always removes XSS-unsafe HTML entities.

So the rules are simple:

• Use safe APIs for untrusted content.

• Treat unsafe APIs as advanced tools for trusted HTML or carefully sanitized HTML.

• Never stream user-controlled HTML into the DOM without a sanitization strategy.

What This Means for Web Developers

Declarative Partial Updates matter because they move a common framework pattern closer to the web platform. For years, developers have built partial update systems with JavaScript:

• Fetch HTML.

• Find a DOM node.

• Replace its content.

• Keep loading states in sync.

• Avoid breaking event handlers.

• Handle errors.

• Handle security.

Frameworks and libraries improve this workflow. But the browser still lacks a small native language for saying: This late HTML belongs in that earlier placeholder. Declarative Partial Updates provide that language.

This doesn't mean JavaScript disappears. You still need JavaScript for interactivity, state, event handling, client-side data flows, and many app behaviors. This also doesn't mean frameworks disappear. React, HTMX, Astro, and similar tools solve larger problems than DOM patching.

The more realistic outcome is this:

• Frameworks and server-rendered tools may eventually use these primitives internally.

• Smaller server-rendered apps may use them directly for simple loading regions.

• Browsers may gain a cleaner, lower-level mechanism for streaming HTML into exact locations. That's the important part.

The proposal doesn't make HTML a full app framework. It gives HTML a better streaming patch primitive.

When This Feature Would Help

Declarative Partial Updates fit pages where the server knows the layout early but some sections finish later.

Good examples include:

• Product pages with slow recommendation blocks.

• Dashboards with independent data cards.

• Search pages where results arrive from multiple services.

• Documentation sites with heavy navigation or menus.

• Profile pages with separate activity, stats, and notification regions.

• Server-rendered apps that want loading states without client-side patch scripts.

The most suitable is server-generated HTML. If your app already renders everything on the client, this proposal won't change your architecture much.

If your app emphasizes fast first renders, progressive streaming, low JavaScript overhead, and server-rendered UIs, this proposal becomes even more attractive.

When You Should Avoid It Today

You should avoid production reliance on Declarative Partial Updates today.

Use it for:

• Learning.

• Local demos.

• Browser experiments.

• Framework research.

• Progressive enhancement experiments.

Don't use this as the only path for important production UIs yet. Browser support isn't yet widespread enough. The recommendation may still change. Tooling isn't mature yet. Most users won't leave the experimental flag enabled. If you're experimenting with it, create a fallback.

For example, placeholders should still make sense on the server-rendered page even if they're not patched natively. Or, you should use a small JavaScript fallback in your app until browser support improves.

Conclusion

HTML streaming is old. Out-of-order HTML patching is the new idea. Traditional streaming lets the browser render chunks as they arrive, but the document still follows the order of the response.

Declarative Partial Updates propose a native way to place late HTML into earlier placeholders.

The core syntax is small:

<?marker name="target">

<template for="target">
    <p>Late content</p>
</template>

For loading regions, the syntax uses a range:

<?start name="target">
<p>Loading...</p>
<?end>

<template for="target">
    <p>Real content</p>
</template>

This gives HTML a browser-native patching model. It also opens the door for less custom JavaScript in some server-rendered streaming interfaces. But this is still experimental. The best way to think about Declarative Partial Updates is not HTML replaces frameworks.

A better way is this: HTML is gaining a low-level primitive that frameworks and server-rendered apps have needed for years.

If the proposal moves forward, web developers may get a cleaner way to build fast, progressively rendered pages where the server streams content as soon as each part is ready.

Final Words

If you found the information here valuable, feel free to share it with others who might benefit from it.

I’d really appreciate your thoughts – mention me on X @sumit_analyzen or on Facebook @sumit.analyzen, watch my coding tutorials, or simply connect with me on LinkedIn.

You can also checkout my official website www.sumitsaha.me for more details about me.

Sources

• Declarative Partial Updates, Chrome for Developers

• WICG Declarative Partial Updates Repository

• WICG Patching Explainer

• Blink Dev, Ready for Developer Testing, Declarative Document Patching

• Chrome Platform Status, Declarative Document Patching

• WHATWG HTML Pull Request for Template Patching

• MDN, ProcessingInstruction

• MDN, HTML Template Element

• MDN, Element.setHTML

• MDN, Element.setHTMLUnsafe

• MDN, HTML Sanitizer API

In this article, I'll discuss how we reached young audiences by combining robotics with e-sports.

What on Earth?

Ever heard of anything like it before? Me neither. The robot was created as part of Futurice’s project with Yle, the national broadcast company of Finland.

Yle produces content for TV, radio, and the web. It has a broad reach of older audiences, but has had trouble reaching younger ones. The goal of this project was to use new technology to reach young audiences — specifically teenagers.

Yle’s content has traditionally been non-participatory: the performers perform, and the audience watches. However, younger audiences generally view content that is more participatory, such as YouTube videos or streams.

We wanted to create participatory content — the performer should interact with their audience. Yle’s journalists specialized in teenage audiences pointed out that gaming and e-sports are popular content. We realized that gaming was the perfect context for this: the audience could play together with the performer. We wanted to explore what an entertainer, or even influencer of the future could look like. So why not create a streaming robot gamer?

Yle’s journalists and Futurice’s roboticists coming up with the idea of a robot gamer

First drafts

What Was This Robot Like?

We chose two games for the robot to play: Flappy Bird and Minecraft.

Flappy Bird was a cult game that had a brief period of extreme popularity in 2014. We chose Flappy Bird because the mechanisms of the game are simple, and allowed for the game to be played with machine learning. We wanted to try a neuroevolution algorithm, which evolved new birds into the game based on which birds did best in the previous generation. This way we could see how the audience reacted when a computer was playing the game.

We chose Minecraft for its communal features, which allow interaction between players. Players can co-operate or fight each other, trade with each other, and chat with each other. They can “grief” each other — i.e. be a nuisance. Players can also mine materials, and turn them into items, or even build cities. They can store precious things, farm the land, herd animals, and fight monsters.

Minecraft also has a material called redstone, which players can use to build logic. Effectively, players can build an entire computer inside of Minecraft. Poetic, eh?

For playing Minecraft, we decided that a human should control the robot. The game is complicated, and having authentic interactions with other players would require a human on the other end.

Flappy Bird and the robot

Our team of Yle’s journalists and Futurice roboticists defined some clear advantages for using a robot in this context:

• A robot is tireless — it can play forever, and provide content 24/7. It’s an ideal streamer.
• A robot can be gender neutral. Gamers and gaming audiences are typically male, but a gender neutral robot could potentially attract more diverse audiences.
• A robot can reflect gamers’ behaviour, stirring emotions. Gaming culture is often aggressive. The robot could be aggressive in turn, making gamers reflect on their own behaviour.
• A robot can interact within the game and chat simultaneously. Humans are limited to one output, a robot can have several.

Testing our streaming equipment and having problems with interference from the robot’s face screen.

We decided on a six hour gaming session, alternating between Minecraft and Flappy Bird. To nail down the user experience for the session, we defined guidelines for our design of the robot:

• Experimental user experience — the user should be able to explore within the interaction with the robot.
• Streamers are usually strong characters. The robot is a character with a strong personality.
• The robot can cause “WTF?” reactions in players. We wanted the experience to be memorable, rather than bland.
• The culture and space of online gaming is unique, and should be designed for.

Based on these guidelines, we created the character IQ_201. IQ_201 is based on aggressive online gamers that are convinced of their own superior intelligence (see this meme about having an IQ over 200). The robot would be rude and reactive, meant to get a reaction out of adolescents interacting with it.

Before implementation, the team also wanted to take into account some ethical considerations:

• Transparency about how the robot is operated is needed. If this robot was going to be put into production, users should be able to find information on how it works.
• The robot should treat all the players the same. This was also part of the decision to make the robot appear gender neutral. And due to the sometimes angry, hateful, even racist or sexist culture of gaming, we needed to design the robot’s personality carefully. It could be out-there, even rude, but never hateful. We didn’t want any heated gaming moments.
• The robot should be rude, but not too over-the-top.
• The chat needed to be moderated. As stated, gaming culture can be toxic. We wanted to keep a careful eye on both the Minecraft and Twitch chats, to ensure no shenanigans would go on.

To fulfill all these requirements, we selected the Furhat robot. The Furhat robot had a relatively easy-to-use teleoperation interface, which allowed for the user to input text to be turned into the robot’s speech, as well as perform gestures at the click of a button.

Flowers and Violence

We had a 6 hour stream, starting at 2pm and ending at 8pm. We alternated between games: 2-3pm was Flappy Bird, 3-5pm Minecraft, 5-6pm Flappy Bird, then 6-8pm Minecraft again. This schedule allowed the robot operators playing Minecraft to have a much-needed break in the middle.

Our robot

In the beginning, a few people joined. Gradually, we gained more and more people. We reached our peak at 4:20 — 49 simultaneous viewers on Twitch. Overall, we had 431 unique viewers. In Minecraft, there were around 30 active players. Considering how minimal our advertising was (one forum post and a few tweets), we were pleasantly surprised by the turnout.

The Minecraft sessions were directed by two robot operators (myself and another Minja). The other Minja played Minecraft, and I operated the robot’s voice and gestures. A third person was answering messages on chat.

Minecraft was overwhelming. The robot’s provocative character provoked teenagers into repeatedly killing it. After fleeing to the mountains to be with the llamas a couple of times and being killed yet again, we modified the robot’s behaviour to be more friendly. We wanted to create more constructive interactions.

Two Minjas as robot operators

Toward the end of the second Minecraft stream, teenagers were cooperating with the robot. They protected it from the few aggressive players that were left, and gave it gifts such as flowers. Some even complimented the robot directly, to make it happy. The players started following the robot, agreeing to cooperate when it initiated building a lighthouse. They also built a house, and captured and named a llama: IQ_201 Junior.

There were two clear factions in the game: some were intent to kill the robot throughout the entire game, and some protected it throughout. Some became more comfortable with the robot as the stream went on, switching sides. Either way, the robot aroused strong emotions. Teenagers sought out genuine interaction with it. No-one ignored the robot, or was bored.

Discussions about how the robot worked were had throughout the stream. No-one asked the robot itself though, maybe out of respect or fear of annoying it. Discussions focused on whether the robot was “real”, i.e. whether it was truly automatic, or a human was operating it. Was it typing with actual physical hands? Or had it “hacked into” the game and was playing via code?

“I Will Miss You Robot!”

16 people responded to our survey afterward. 80% of players were under 18, most were 13 to 15-year-olds. 80% of players interacted with the robot. This was extremely positive, we succeeded in making a robot that was compelling to users. 75% of players rated the robot as 3 or above, out of 5.

Viewers over time

We collected comments from the players from the survey, as well as the Minecraft game chat. They are translated from Finnish, and reflect some of the thoughts our players had on the robot.

The critical first:

“It was pretty fun and cool. But it somehow felt like a set-up.” [Referring to the robot possibly having a human operator]

A lot of players were wondering how the robot actually worked. This comment brings us back to the ethical consideration we talked about earlier: transparency about how the robot was operated.

Though we intended to be transparent at first, we decided to not inform users of the robot’s teleoperated nature for this first pilot. We made this choice because we wanted to keep the “suspension of disbelief” of the user active, meaning that we wanted the participants to play along with the fact they were talking to a “real robot” (an autonomous robot) (Duffy & Zawieska, 2012).

The negative response we received regarding the unclarity on the robot’s functioning made it clear to us that if this pilot were extended, it is highly important to be more transparent. It is possible to hold suspension of disbelief and be honest of the robot’s operation simultaneously (we do all know that television shows are not reality, after all).

“The robot was a bit simple in certain things, and sometimes talked meanly to people, and was condescending. This was a bit anxiety inducing… Was this intentional?”

Some players felt that the robot’s rude behaviour crossed the boundary into condescending. They wished that the robot would be more considerate in the future. This indicates that even a robot can hurt feelings. In future versions, making IQ_201 more empathic, and less focused on the superiority of robots over humans, could have positive results.

“The robot looked a bit blue in the face, and its voice was a bit weird.”

Two teenagers did not enjoy the robot’s appearance and voice. One remarked especially about its blue face, asking why we did not make it “normal colored”.

This may have been due to the robot falling into the “uncanny valley” for these players. Uncanny valley is a theory developed by robotics researcher Masahiro Mori (Mori et al., 2012). His theory posits that as the appearance of a robot approaches human-likeness, there is a dip when the appearance gets very close. Zombies and corpses fall into this valley.

To get rid of this effect with our robot, it could be wise to alter the robot’s appearance and voice in future solutions.

The Uncanny Valley by Masahiro Mori. Wikimedia commons.

And then the positive:

“It was really interesting gaming with the robot. :) Hopefully in the future we can have this type of event again. :)”

The majority of the teenagers enjoyed playing with the robot, and watching the stream. Their feedback complimented the robot’s sense of humour, and its playing skills. A continuation of the pilot would surely find an interested audience.

[to the robot] “Some people have trouble with new things. In this case, these players are having trouble with a robot, since you’re new.”

This player consoled the robot in-game, as other players were giving it a hard time by continuously killing it. This comment was moving: the player felt bad for the robot, and thought the robot might feel bad as well, attempting to change that. This is a clear empathic response toward the robot.

[to the robot] “I will miss you robot!”

A few players gave the robot heartfelt goodbyes when it left Minecraft. These players found the robot approachable, and even formed an emotional bond with it. This means we succeeded in creating a compelling character, even during what was only a 6 hour stream.

For future builds of the robot, the players should be informed how the robot operates. This could help them calibrate an appropriate level of emotional bond to the robot.

Are Robotic Influencers Our Future?

Players took an active interest in the robot. They approached it, interacted with it, and formed opinions on it. The robot also provoked emotional reactions — both positive and negative. Some participants really loved the robot and wished for more interaction in the future, and some were heavily critical.

This indicates that robot influencers have the capacity to affect our emotions — whether this capacity will ever reach the level of human entertainers, I do not know. Whether that is desirable, I also do not know.

What positively surprised me was that the young user base of the robot were media literate: they critically examined the robot’s mode of operation. The players had a good idea of what is possible with AI today, and what is not. They were not easily duped.

This makes me hopeful for our future, whether it contains robotic entertainers or not. When viewers remain critical, they can understand that robots are machines with no actual emotional capacity, even if viewers do choose to suspend disbelief.

Interacting with the robot can be though of as a form of parasocial interaction for the viewer — where the viewer may feel that their relationship with the robot is close — even though it is not truly reciprocal. This in itself is not necessarily harmful, as long as we are honest about what the relationship truly is. We should understand that robots are putting on a performance to elicit emotions in us — like human entertainers do

A video about the project.

First published on Towards Data Science.

Duffy, B. R., & Zawieska, K. (2012, September). Suspension of disbelief in social robotics. In 2012 IEEE RO-MAN: The 21st IEEE International Symposium on Robot and Human Interactive Communication (pp. 484–489). IEEE.

Mori, M., MacDorman, K. F., & Kageki, N. (2012). The uncanny valley: The original essay by Masahiro Mori. IEEE Spectrum, 98–100.

Leveraging Neo4j Streams — Part 3

This article is the third part of the Leveraging Neo4j Streams series (Part 1 is here, Part 2 is here). In it, I’ll show you how to bring Neo4j into your Apache Kafka flow by using the streams procedures available with Neo4j Streams.

In order to show how to integrate them, simplify the integration, and let you test the whole project by hand, I’ll use Apache Zeppelin, a notebook runner that simply allows you to natively interact with Neo4j.

What is a Neo4j Stored Procedure?

Starting from Neo4j 3.x, the concept of user-defined procedures and functions was introduced. These are custom implementations of certain functionalities and/or business rules that can’t be (easily) expressed in Cypher itself.

Neo4j provides a number of built-in procedures. The APOC library adds another 450 to cover all kinds of uses from data integration to graph refactorings.

What are the streams procedures?

The Neo4j Streams project comes out with two procedures:

• streams.publish: allows custom message streaming from Neo4j to the configured environment by using the underlying configured Producer
• streams.consume: allows consuming messages from a given topic.

Set-Up the Environment

Going to the following Github repo, you’ll find everything necessary in order to replicate what I’m presenting in this article. What you will need to start is Docker, and then you can simply spin-up the stack by entering into the directory and from the Terminal execute the following command:

$ docker-compose up

This will start-up the whole environment that comprises:

• Neo4j + Neo4j Streams module + APOC procedures
• Apache Kafka
• Apache Spark (which is not necessary in this article, but it’s used in the previous two)
• Apache Zeppelin

By going into Apache Zeppelin @ http://localhost:8080 you’ll find in directory Medium/Part 3 one notebook called “Streams Procedures” which is the subject of this article.

streams.publish

This procedure allows custom message streaming from Neo4j to the configured environment by using the underlying configured Producer.

It takes two variables as input and returns nothing (as it sends its payload asynchronously to the stream):

• topic, type String: where the data will be published
• payload, type Object: what you want to stream.

Example:

CALL streams.publish('my-topic', 'Hello World from Neo4j!')

The message retrieved from the Consumer is the following:

{"payload": "Hello world from Neo4j!"}

You can send any kind of data in the payload: nodes, relationships, paths, lists, maps, scalar values and nested versions thereof.

In case of nodes and/or relationships, if the topic is defined in the patterns provided by the Change Data Capture (CDC) configuration, their properties will be filtered according to the configuration.

Following is a simple video that shows the procedure in action:

The streams.publish procedure in action

streams.consume

This procedure allows for consuming messages from a given topic.

It takes two variables as input:

• topic, type String: where you want to consume the data
• config, _type Map: the configuration parameters

and returns a list of collected events.

The config params are:

• timeout, type Long: it’s the value passed to Kafka [Consumer#poll](https://kafka.apache.org/10/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html#poll-long-) method (milliseconds). Default 1000.
• from, type String: it’s the Kafka configuration parameter auto.offset.reset

Use:

CALL streams.consume('my-topic', {<config>}) YIELD event RETURN event

Example: Imagine you have a producer that publishes events like this:

{"name": "Andrea", "surname": "Santurbano"}

We can create user nodes in this way:

CALL streams.consume('my-topic', {<config>}) YIELD eventCREATE (p:Person{firstName: event.data.name, lastName: event.data.surname})

Following is a simple video that shows the procedure in action:

The stream.consume procedure in action

So this is the end of the “Leveraging Neo4j Streams” series, I hope you enjoyed it!

If you have already tested the Neo4j-Streams module or tested it via this notebook, please fill out our feedback survey.

If you run into any issues or have thoughts about improving our work, please raise a GitHub issue.

In this article, we’ll show how to create a Just-In-Time Data Warehouse by using Neo4j and the Neo4j Streams module with Apache Spark’s Structured Streaming Apis and Apache Kafka.

In order to show how to integrate them, simplify the integration, and let you test the whole project by hand, I’ll use Apache Zeppelin a notebook runner that simply allows to natively interact with Neo4j.

The final result: how a kafka event streamed by Neo4j gets collected by Apache Spark

Leveraging Neo4j Streams

The Neo4j Streams project is composed of three main pillars:

• The Change Data Capture (the subject of this first article) that allows us to stream database changes over Kafka topics
• The Sink that allows consuming data streams from the Kafka topic
• A set of procedures that allows us to Produce/Consume data to/from Kafka Topics

What is a Change Data Capture?

It’s a system that automatically captures changes from a source system (a Database, for instance) and automatically provides these changes to downstream systems for a variety of use cases.

CDC typically forms part of an ETL pipeline. This is an important component for ensuring Data Warehouses (DWH) are kept up to date with any record changes.

Also traditionally CDC applications used to work off of transaction logs, thereby allowing us to replicate databases without having much of a performance impact on its operation.

How does the Neo4j Streams CDC module deal with database changes?

Every transaction inside Neo4j gets captured and transformed in order to stream an atomic element of the transaction.

Let’s suppose we have a simple creation of two nodes and one relationship between them:

CREATE (andrea:Person{name:"Andrea"})-[knows:KNOWS{since:2014}]->(michael:Person{name:"Michael"})

The CDC module will transform this transaction into 3 events (2 node creation, 1 relationship creation).

The Event structure was inspired by the Debezium format and has the following general structure:

{  "meta": { /* transaction meta-data */ },  "payload": { /* the data related to the transaction */    "before": { /* the data before the transaction */},    "after": { /* the data after the transaction */}  }}

Node source (andrea):

{  "meta": {    "timestamp": 1532597182604,    "username": "neo4j",    "tx_id": 1,    "tx_event_id": 0,    "tx_events_count": 3,    "operation": "created",    "source": {      "hostname": "neo4j.mycompany.com"    }  },  "payload": {    "id": "1004",    "type": "node",    "after": {      "labels": ["Person"],      "properties": {        "name": "Andrea"      }    }  }}

Node target (michael):

{  "meta": {    "timestamp": 1532597182604,    "username": "neo4j",    "tx_id": 1,    "tx_event_id": 1,    "tx_events_count": 3,    "operation": "created",    "source": {      "hostname": "neo4j.mycompany.com"    }  },  "payload": {    "id": "1006",    "type": "node",    "after": {      "labels": ["Person"],      "properties": {        "name": "Michael"      }    }  }}

Relationship knows:

{  "meta": {    "timestamp": 1532597182604,    "username": "neo4j",    "tx_id": 1,    "tx_event_id": 2,    "tx_events_count": 3,    "operation": "created",    "source": {      "hostname": "neo4j.mycompany.com"    }  },  "payload": {    "id": "1007",    "type": "relationship",    "label": "KNOWS",    "start": {      "labels": ["Person"],      "id": "1005"    },    "end": {      "labels": ["Person"],      "id": "106"    },    "after": {      "properties": {        "since": 2014      }    }  }}

By default, all the data will be streamed on the neo4j topic. The CDC module allows controlling which nodes are sent to Kafka, and which of their properties you want to send to the topic:

streams.source.topic.nodes.<TOPIC_NAME>=<PATTERN>

With the following example:

streams.source.topic.nodes.products=Product{name, code}

The CDC module will send to the products topic all the nodes that have the label Product. It then sends, to that topic, only the changes about name and code properties. Please go the official documentation for a full description on how label filtering works.

For a more in-depth description of the Neo4j Streams project and how/why we at LARUS and Neo4j built it, check out this article that provides an in-depth description.

Beyond the traditional Data Warehouse

A traditional DWH requires data teams to constantly build multiple costly and time-consuming Extract Transform Load (ETL) pipelines to ultimately derive business insights.

One of the biggest pain points is that, due to its rigid architecture that’s difficult to change, Enterprise Data Warehouses are inherently rigid. That’s because:

• they are based on the Schema-On-Write architecture: first, you define your schema, then you write your data, then you read your data and it comes back in the schema you defined up-front
• they are based on (expensive) batched/scheduled jobs

This results in having to build costly and time-consuming ETL pipelines to access and manipulate the data. And as new data types and sources are introduced, the need to augment your ETL pipelines exacerbates the problem.

Thanks to the combination of the stream data processing with the Neo4j Streams CDC module and the Schema-On-Read approach provided by Apache Spark, we can overcome this rigidity and build a new kind of (flexible) DWH.

A paradigm shift: Just-In-Time Data Warehouse

A JIT-DWH solution is designed to easily handle a wider variety of data from different sources and starts from a different approach about how to deal with and manage data: Schema-On-Read.

Schema-On-Read

Schema-On-Read follows a different sequence: it just loads the data as-is and applies your own lens to the data when you read it back out. With this kind of approach, you can present data in a schema that is adapted best to the queries being issued. You’re not stuck with a one-size-fits-all schema. With schema-on-read, you can present the data back in a schema that is most relevant to the task at hand.

Set-Up the Environment

Going to the following Github repo you’ll find everything you need in order to replicate what I’m presenting in this article. What you will need to start is Docker. Then you can simply spin-up the stack by entering into the directory and from the Terminal, executing the following command:

$ docker-compose up

This will start-up the whole environment that comprises:

• Neo4j + Neo4j Streams module + APOC procedures
• Apache Kafka
• Apache Spark
• Apache Zeppelin

The whole architecture based on Docker containers

By going into Apache Zeppelin @ http://localhost:8080 you’ll find in the directory Medium/Part 1 two notebooks:

• Create a Just-In-Time Data Warehouse: in this notebook, we will build the JIT-DWH
• Query The JIT-DWH: in this notebook, we will perform some queries over the JIT-DWH

The Use-Case:

We’ll create a fake social network like dataset. This will activate the CDC module of Neo4j Stream, and via Apache Spark we’ll intercept this event and persist them on the File System as JSON.

Then we’ll demonstrate how new fields added in our nodes will be automatically added to our JIT-DWL without the modification of the ETL pipeline, thanks to the Schema-On-Read approach.

We’ll execute the following steps:

1. Create the fake data set
2. Build our data pipeline that intercepts the Kafka events published by the Neo4j Streams CDC module
3. Make the first query over our JIT-DWH on Spark
4. Add a new field in our graph model
5. Show how the new field is automatically exposed in real time thanks to the Neo4j Streams CDC module (without the need for changes over our ETL pipeline thanks to the Schema-On-Read approach).

Notebook 1: Create a Just-In-Time Data Warehouse

We’ll create a fake social network by using the APOC apoc.periodic.repeat procedure that executes this query every 15 seconds:

WITH ["M", "F", ""] AS genderUNWIND range(1, 10) AS idCREATE (p:Person {id: apoc.create.uuid(), name: "Name-" +  apoc.text.random(10), age: round(rand() * 100), index: id, gender: gender[toInteger(size(gender) * rand())]})WITH collect(p) AS peopleUNWIND people AS p1UNWIND range(1, 3) AS friendWITH p1, people[(p1.index + friend) % size(people)] AS p2CREATE (p1)-[:KNOWS{years: round(rand() * 10), engaged: (rand() > 0.5)}]->(p2)

If you need more details about the APOC project, please follow this link.

So the resulting graph model is quite straightforward:

The Graph Model

Let’s create an index over the Person node:

%neo4jCREATE INDEX ON :Person(id)

Now let’s set the Background Job in Neo4j:

%neo4jCALL apoc.periodic.repeat('create-fake-social-data', 'WITH ["M", "F", "X"] AS gender UNWIND range(1, 10) AS id CREATE (p:Person {id: apoc.create.uuid(), name: "Name-" +  apoc.text.random(10), age: round(rand() * 100), index: id, gender: gender[toInteger(size(gender) * rand())]}) WITH collect(p) AS people UNWIND people AS p1 UNWIND range(1, 3) AS friend WITH p1, people[(p1.index + friend) % size(people)] AS p2 CREATE (p1)-[:KNOWS{years: round(rand() * 10), engaged: (rand() > 0.5)}]->(p2)', 15) YIELD nameRETURN name AS created

This background query brings the Neo4j-Streams CDC module to stream related events over the “neo4j” Kafka topic (the default topic of the CDC).

Now let’s create a Structured Streaming Dataset that consumes the data from the “neo4j” topic:

val kafkaStreamingDF = (spark    .readStream    .format("kafka")    .option("kafka.bootstrap.servers", "broker:9093")    .option("startingoffsets", "earliest")    .option("subscribe", "neo4j")    .load())

The kafkaStreamingDF Dataframe is basically a ProducerRecord representation. And in fact its schema is:

root|-- key: binary (nullable = true)|-- value: binary (nullable = true)|-- topic: string (nullable = true)|-- partition: integer (nullable = true)|-- offset: long (nullable = true)|-- timestamp: timestamp (nullable = true)|-- timestampType: integer (nullable = true)

Now let’s create the Structure of the data streamed by the CDC using the Spark APIs in order to read the streamed data:

val cdcMetaSchema = (new StructType()    .add("timestamp", LongType)    .add("username", StringType)    .add("operation", StringType)    .add("source", MapType(StringType, StringType, true)))    val cdcPayloadSchemaBeforeAfter = (new StructType()    .add("labels", ArrayType(StringType, false))    .add("properties", MapType(StringType, StringType, true)))    val cdcPayloadSchema = (new StructType()    .add("id", StringType)    .add("type", StringType)    .add("label", StringType)    .add("start", MapType(StringType, StringType, true))    .add("end", MapType(StringType, StringType, true))    .add("before", cdcPayloadSchemaBeforeAfter)    .add("after", cdcPayloadSchemaBeforeAfter))    val cdcSchema = (new StructType()    .add("meta", cdcMetaSchema)    .add("payload", cdcPayloadSchema))

The cdcSchema is suitable for both node and relationships events.

What we need now is to extract only the CDC event from the Dataframe, so let’s perform a simple transformation query over Spark:

val cdcDataFrame = (kafkaStreamingDF    .selectExpr("CAST(value AS STRING) AS VALUE")    .select(from_json('VALUE, cdcSchema) as 'JSON))

The cdcDataFrame contains just one column JSON which is the data streamed from the Neo4j-Streams CDC module.

Let’s perform a simple ETL query in order to extract fields of interest:

val dataWarehouseDataFrame = (cdcDataFrame    .where("json.payload.type = 'node' and (array_contains(nvl(json.payload.after.labels, json.payload.before.labels), 'Person'))")    .selectExpr("json.payload.id AS neo_id", "CAST(json.meta.timestamp / 1000 AS Timestamp) AS timestamp",        "json.meta.source.hostname AS host",        "json.meta.operation AS operation",        "nvl(json.payload.after.labels, json.payload.before.labels) AS labels",        "explode(json.payload.after.properties)"))

This query is quite important, because it represents how the data will be persisted over the filesystem. Every node will be exploded in a number of JSON snippets, one for each node property, just like this:

{"neo_id":"35340","timestamp":"2018-12-19T23:07:10.465Z","host":"neo4j","operation":"created","labels":["Person"],"key":"name","value":"Name-5wc62uKO5l"}

{"neo_id":"35340","timestamp":"2018-12-19T23:07:10.465Z","host":"neo4j","operation":"created","labels":["Person"],"key":"index","value":"8"}

{"neo_id":"35340","timestamp":"2018-12-19T23:07:10.465Z","host":"neo4j","operation":"created","labels":["Person"],"key":"id","value":"944e58bf-0cf7-49cf-af4a-c803d44f222a"}

{"neo_id":"35340","timestamp":"2018-12-19T23:07:10.465Z","host":"neo4j","operation":"created","labels":["Person"],"key":"gender","value":"F"}

This kind of structure can be easily turned into tabular representation (we’ll see in the next few steps how to do this).

Now let's write a Spark continuous streaming query that saves the data to the file system as JSON:

val writeOnDisk = (dataWarehouseDataFrame    .writeStream    .format("json")    .option("checkpointLocation", "/zeppelin/spark-warehouse/jit-dwh/checkpoint")    .option("path", "/zeppelin/spark-warehouse/jit-dwh")    .queryName("nodes")    .start())

We have now created a simple JIT-DWH. In the second notebook we’ll learn how to query it and how simple it is to deal with dynamical changes in the data structures thanks schema-on-read.

Notebook 2: Query The JIT-DWH

The first paragraph let us query and display our JIT-DWH

val flattenedDF = (spark.read.format("json").load("/zeppelin/spark-warehouse/jit-dwh/**")    .where("neo_id is not null")    .groupBy("neo_id", "timestamp", "host", "labels", "operation")    .pivot("key")    .agg(first($"value")))z.show(flattenedDF)

Remember how we saved the data in JSON some row above? The flattenedDF simply pivoted the JSONs over the key field thus grouping the data over 5 columns that represent the “unique key” (_“neoid”, “timestamp”, “host”, “labels”, “operation”). This allows us to have this tabular representation of the source data as follows:

The result of the query

Now imagine that our Person dataset gets a new field: birth. Let's add this new field to one node; in this case, you must choose an id from your dataset and update it with the following paragraph:

Just fill the form with your data and execute the paragraph

Now the final step: reuse the same query and filter the DWH by the id that we have previously changed in order to check how our dataset changed according to the changes made over Neo4j.

The birth field is present without changes to our queries

Conclusions

In this first part, we learned how to leverage the events produced by Neo4j Stream CDC module in order to build a simple (Real-Time) JIT-DWL that uses the Schema-On-Read approach.

In Part 2 we’ll discover how to use the Sink module in order to ingest data into Neo4j directly from Kafka.

If you have already tested the Neo4j-Streams module or tested it via these notebooks please fill out our feedback survey.

If you run into any issues or have thoughts about improving our work, please raise a GitHub issue.