add asyncReplace directive

index.d.ts

@@ -230,6 +230,15 @@ declare module '@popeindustres/lit-html-server/directives/async-append.js' {
   ) => (part: Part) => void;
 }
 
+declare module '@popeindustres/lit-html-server/directives/async-replace.js' {
+  import { Part } from '@popeindustries/lit-html-server';
+
+  export const asyncReplace: (
+    value: AsyncIterable<unknown>,
+    mapper?: ((v: unknown, index?: number | undefined) => unknown) | undefined
+  ) => (part: Part) => void;
+}
+
 declare module '@popeindustres/lit-html-server/directives/cache.js' {
   import { Part } from '@popeindustries/lit-html-server';
 

src/directives/async-replace.js

@@ -0,0 +1,26 @@
+/**
+ * @typedef Part { import('../parts.js').Part }
+ */
+import { directive, isNodePart } from '../index.js';
+
+/**
+ * Render items of an AsyncIterable, replacing previous items as they are resolved.
+ * Not possible to render more than once in a server context, so only the first item is rendered.
+ *
+ * @type { (value: AsyncIterable<unknown>, mapper?: ((v: unknown, index?: number | undefined) => unknown) | undefined) => (part: Part) => void }
+ */
+export const asyncReplace = directive((value, mapper) => (part) => {
+  if (!isNodePart(part)) {
+    throw Error('The `asyncReplace` directive can only be used in text nodes');
+  }
+
+  part.setValue(
+    value.next().then(({ value }) => {
+      if (mapper !== undefined) {
+        value = mapper(value, 0);
+      }
+
+      return value;
+    })
+  );
+});

test/directives-test.js

@@ -1,5 +1,6 @@
 import { directive, html as h, renderToString as render } from '../index.mjs';
 import { asyncAppend } from '../directives/async-append.mjs';
+import { asyncReplace } from '../directives/async-replace.mjs';
 import { cache } from '../directives/cache.mjs';
 import { classMap } from '../directives/class-map.mjs';
 import { createAsyncIterable } from './utils.js';
@@ -25,6 +26,19 @@ describe('directives', () => {
     });
   });
 
+  describe('asyncReplace', () => {
+    it('should render an AsyncIterable value', async () => {
+      const result = h`some ${asyncReplace(createAsyncIterable(['async', ' text']))}`;
+      expect(await render(result)).to.equal('some async');
+    });
+    it('should render a mapped AsyncIterable value', async () => {
+      const result = h`some ${asyncReplace(createAsyncIterable(['async', 'text']), (v, index) => {
+        return `${index}-${v.toUpperCase()}`;
+      })}`;
+      expect(await render(result)).to.equal('some 0-ASYNC');
+    });
+  });
+
   describe('cache', () => {
     it('should render a cached value', async () => {
       const result = h`some ${cache('text')}`;