Some possible alternative ideas for streaming partials

[MichaelWest22]

Context

I've been working on htmx 4 and recently implemented a streaming partials extension that explores similar territory. I thought there could be some useful ideas to consider as options for this proposal.

Full writeup: Alternative HTML Streaming Patches Design

---

Key Ideas to Consider

1. Leverage Existing id Attributes

Instead of introducing contentname as a new global attribute, the design could use standard id attributes for targeting:

<!-- Current proposal -->
<div contentname="widget">...</div>
<template contentmethod="replace-children">
  <div contentname="widget">New content</div>
</template>

<!-- Alternative -->
<div id="widget">...</div>
<template for="widget" patchmode="replace-children">
  <div>New content</div>
</template>

Benefits:

• No new global attributes
• Works with existing HTML patterns
• Simpler mental model for developers

2. CSS Selectors for Advanced Targeting

For cases where IDs aren't sufficient or users want to avoid duplicate id issues, CSS selectors provide powerful targeting without new primitives:

<!-- Target by position -->
<template selector=".product-card:nth-child(2)" patchmode="replace-children">
  <div>Updated product</div>
</template>

<!-- Update multiple elements -->
<template selector=".status" patchmode="replace-children" multiple>
  <span>Online</span>
</template>

<!-- Conditional targeting (revision control) -->
<template selector="#content:not([data-revision='v2'])" 
          patchmode="replace-children"
          data-revision="v2">
  <div>New content</div>
</template>

3. Revision Control Without New Attributes

CSS :not() selectors combined with auto-copying data-* attributes from template to target can handle revision control:

<div id="content" data-revision="v1">Content v1</div>

<!-- Only applies if revision differs -->
<template selector="#content:not([data-revision='v2'])" 
          patchmode="replace-children"
          data-revision="v2">
  <div>Content v2</div>
</template>

After patching, the target automatically gets data-revision="v2", preventing duplicate applications. data-* auto-copying would also solve many other client state update tasks:

<template for="submit-btn" patchmode="append" 
          data-loading="true" 
          data-disabled="true">
  <!-- Empty: just copies data-* attributes -->
</template>

4. Potential Future: Upsert Mode

For streaming scenarios where you don't know if an item exists:

<ul id="products">
  <li id="product-1">Product 1 (old)</li>
</ul>

<!-- Updates existing by ID, appends new ones -->
<template selector="#products" patchmode="upsert">
  <li id="product-1">Product 1 (updated)</li>
  <li id="product-2">Product 2 (new)</li>
</template>

---

Anyway, just some possible ideas to consider. Also created a quick polyfill and demo to show how some of these ideas might work: demo

[MichaelWest22]

@noamr wrote:

@MichaelWest22 thanks for all these alternative ideas! Do you mind participating in the incubation repo? This issue is becoming rather huge and this feature has gone through months of incubation.

Specifically to your points:

1. We decided to go with a new attribute and not id due to XSS protection. Long story short, we don't want existing content to be patchable without the author's consent when appending new content. Moreover, IDs are built to be unique while markers are resolved in the scope of the template's parent.
2. Selectors are a no go for markers due to performance and ambiguities.
3. The explainer already includes contentrevision as a future enhancement. Seems very similar to what you're proposing.
4. Merging/upserting is a really important future enhancement. It has some complexities, mainly that it can't be used together with streaming, but we're considering it for the future.

So in short, (1) and (2) were ruled out earlier on in incubation, and we'd be happy for a continued discussion in incubation about (3) and (4) as future enhancements.

Just moved my ideas here to avoid more noise in the proposal issue thread

1/2

Yeah id and selector based patching would have some security issues if they are not opt in somehow. While you could do an inherited patchable attribute to opt in to id or selector patching this may not be worth it. It could be a good idea to consider a new standard http response header that the browser or polyfills should respect that has a default streaming patching mode and a couple of levels of override which would then allow you to opt in or out of comment/marker/id/selector based patching as this could improve the XSS issues. even without id and selector lookup options this could still have value to just have Streaming-Patches: none or Streaming-Patches: marker options and a sensible default.

Streaming-Patches: marker
Streaming-Patches: marker, id
Streaming-Patches: marker, id, selector
Streaming-Patches: none

3

Without css selectors my quick initial data-* based revision lookup design would not work. an alternative could be to have it check all data-* attributes on the patching template and if their are any, and all of them match exactly with the same data-* attributes on the target container then it skips the patch otherwise it applies the patch and updates all the data-* on the target. This is kind of more generic and covers more use cases then contentrevision attribute.

Data-Attribute Matching Examples

The template checks its own data-* attributes against the target. If all match exactly, the patch is skipped. Otherwise it applies and copies the attributes over.

Skip when attributes match

<div marker="content" data-rev="5">Content v5</div>

<template for="content" data-rev="5">
  <div>Content v5</div>
</template>
<!-- Skipped - data-rev matches -->

Patch when different

<div marker="content" data-rev="5">Content v5</div>

<template for="content" data-rev="6">
  <div>Content v6</div>
</template>
<!-- Patched - data-rev differs -->
<!-- Result: <div marker="content" data-rev="6">Content v6</div> -->

Patch when target missing attribute

<div marker="content">Content</div>

<template for="content" data-rev="1">
  <div>Content v1</div>
</template>
<!-- Patched - target has no data-rev -->
<!-- Result: <div marker="content" data-rev="1">Content v1</div> -->

Extra target attributes ignored

<div marker="content" data-rev="5" data-cached="true">Content</div>

<template for="content" data-rev="5">
  <div>Content v5</div>
</template>
<!-- Skipped - template's data-rev matches, data-cached ignored -->

No template attributes = always patch

<div marker="content" data-rev="5">Content</div>

<template for="content">
  <div>New content</div>
</template>
<!-- Patched - no data-* to check -->
<!-- Result: <div marker="content" data-rev="5">New content</div> -->
<!-- Note: target's data-rev preserved -->

4

I think the upsert design I had would actually work ok with the streaming use case because it is not full merging solution and just some basic logic that modifies where nodes are streamed to based on a id lookup. Each direct child node of the patch template that is processed with a id and this id is found it will send this to the existing element and all other content gets appended to the end of the target. But this whole idea is not likely to make it into the initial design.

[noamr]

Thank you for all of these!

A few comments:
The out of order streaming solution as currently designed targets ranges between marker nodes rather than elements. It adds a lot of flexibility that using IDs or other forms of element targeting cannot achieve on its own. This came after plenty of community feedback... See issue #6.

Regarding revisions, yes we are thinking along the same lines.

Re upserting and streaming, you would need to know in advance which elements to not remove from the old container. How do you do that when you don't know yet what's in the template? I am currently thinking of merging, even in its simplest form, as mutually exclusive from streaming.

[MichaelWest22]

The secret to making upsert work here is that you do not remove from the old container it is just an insert or update operation after all. as you parse and process the received patch templates inner data you need to process and split on each direct child element of the patch template. For each child element if it has an id attribute then do a lookup in the target children for a matching id and if you find one then we need to replace that element node with this one. not sure if you need to wait for the whole id'ed child node to be parsed and then once you have a full node closing tag do an atomic replaceWith type operation on it (this would prevent you streaming in large things in a progressive streaming way but would be simpler and more reliable). Or you could remove the old node and then stream in the new node and all its children into the same location. Or maybe stream the new node in after it and then remove the old node. But if the node has no id or the id is not found or it is non element data then just stream this data into the end of the targets children or marker range.

The idea is the server just passes in multiple patch templates with id'ed log or card or chat or whatever elements to the stream as they are generated by the server and the server does not have to care if the id is a new element to append or is actually an update for an element it streamed in earlier. The final dom order is just the order each id first arrived.

A much more advanced option is to have an order key where you use the id of the element or choose a custom key attribute like a timestamp. Then when the id is not found you check if it has the key/id and walk down the whole range of nodes till you find a keyed node greater than your key and place it before this node. This advanced pattern lets you stream in say timestamped logs and they will always be added in order. But this is now more complex than you likely should consider at this stage!