fix: resolveHtmlStream error handling

.changeset/tame-dancers-change.md

@@ -0,0 +1,6 @@
+---
+'@kitajs/fastify-html-plugin': patch
+'@kitajs/html': patch
+---
+
+Fixed resolveHtmlStream error handling

packages/fastify-html-plugin/index.js

@@ -2,11 +2,7 @@
 
 const fp = require('fastify-plugin');
 const { isTagHtml } = require('./lib/is-tag-html');
-
-// Loads the suspense component if it wasn't already loaded
-if (!globalThis.SUSPENSE_ROOT) {
-  require('@kitajs/html/suspense');
-}
+const { resolveHtmlStream } = require('@kitajs/html/suspense');
 
 /** @type {import('./types/index').kAutoDoctype} */
 const kAutoDoctype = Symbol.for('fastify-kita-html.autoDoctype');
@@ -68,11 +64,12 @@ function handleHtml(htmlStr, reply) {
       .send(htmlStr);
   }
 
-  requestData.stream.push(htmlStr);
-
   // Content-length is optional as long as the connection is closed after the response is done
   // https://www.rfc-editor.org/rfc/rfc7230#section-3.3.3
-  return reply.send(requestData.stream);
+  return reply.send(
+    // htmlStr might resolve after one of its suspense components
+    resolveHtmlStream(htmlStr, requestData)
+  );
 }
 
 const fastifyKitaHtml = fp(plugin, {

packages/html/suspense.d.ts

@@ -95,8 +95,8 @@ export function renderToStream(
 ): Readable;
 
 /**
- * Prepends the fallback into a html stream handled manually without
- * {@linkcode renderToStream}.
+ * Joins the html base template (with possible suspense's fallbacks) with the request data
+ * and returns the final Readable to be piped into the response stream.
  *
  * **This API is meant to be used by library authors and should not be used directly.**
  *
@@ -120,7 +120,7 @@ export function renderToStream(
  * @returns The same stream or another one with the fallback prepended.
  * @see {@linkcode renderToStream}
  */
-export function writeFallback(fallback: JSX.Element, stream: Readable): Readable;
+export function resolveHtmlStream(template: JSX.Element, data: RequestData): Readable;
 
 /**
  * This script needs to be loaded at the top of the page. You do not need to load it

packages/html/suspense.js

@@ -1,5 +1,5 @@
 const { contentsToString, contentToString } = require('./index');
-const { Readable } = require('node:stream');
+const { Readable, PassThrough } = require('node:stream');
 
 // Avoids double initialization in case this file is not cached by
 // module bundlers.
@@ -262,42 +262,34 @@ function renderToStream(html, rid) {
     });
   }
 
-  return writeFallback(html, requestData.stream);
+  return resolveHtmlStream(html, requestData);
 }
 
-/** @type {import('./suspense').writeFallback} */
-function writeFallback(fallback, readable) {
+/** @type {import('./suspense').resolveHtmlStream} */
+function resolveHtmlStream(template, requestData) {
   // Impossible to sync templates have their
-  // streams being written before the fallback
-  if (typeof fallback === 'string') {
-    readable.push(fallback);
-    return readable;
+  // streams being written (sent = true) before the fallback
+  if (typeof template === 'string') {
+    requestData.stream.push(template);
+    return requestData.stream;
   }
 
-  // The fallback might resolve after a suspense resolves,
-  // so we need to ensure the fallback is written and sent
-  // before anything the requestData.stream might already have.
-
-  const copy = new Readable({ read: noop });
-
-  void fallback
-    .then(async (result) => {
-      copy.push(result);
-
-      for await (const chunk of readable) {
-        copy.push(chunk);
-      }
+  const prepended = new PassThrough();
 
-      copy.push(null);
-    })
-    .catch((error) => {
-      copy.emit('error', error);
-    });
+  void template.then(
+    (result) => {
+      prepended.push(result);
+      requestData.stream.pipe(prepended);
+    },
+    (error) => {
+      prepended.emit('error', error);
+    }
+  );
 
-  return copy;
+  return prepended;
 }
 
 exports.Suspense = Suspense;
 exports.renderToStream = renderToStream;
-exports.writeFallback = writeFallback;
+exports.resolveHtmlStream = resolveHtmlStream;
 exports.SuspenseScript = SuspenseScript;