h3

You can stream data to a client as soon as it becomes available, which is ideal for large files or long-running responses. To implement this in H3, create a ReadableStream using the standard Web API and return it from your event handler.

When streaming, it is recommended to set the following response headers manually via event.res.headers:

• Content-Type: To specify the data format (e.g., text/html).
• Cache-Control: Set to no-cache to prevent caching of the stream.
• Transfer-Encoding: Set to chunked to indicate chunked transfer encoding.

import { H3 } from "h3";

export const app = new H3();

app.use((event) => {
  // Set response headers for streaming
  event.res.headers.set("Content-Type", "text/html");
  event.res.headers.set("Cache-Control", "no-cache");
  event.res.headers.set("Transfer-Encoding", "chunked");

  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue("<ul>");
      
      const interval = setInterval(() => {
        controller.enqueue("<li>" + Math.random() + "</li>");
      }, 100);

      setTimeout(() => {
        clearInterval(interval);
        controller.enqueue("</ul>");
        controller.close();
      }, 1000);
    },
    cancel() {
      // Handle cleanup if the stream is cancelled
    },
  });

  return stream;
});

You can use the .mount(prefix, subApp) method to add a nested H3 instance to a main H3 instance. When an H3 sub-app is mounted, its routes and middleware are merged with the provided base URL prefix.

Important considerations:

• Path Resolution: In a wildcard route like /**:slug within a mounted app, the pathname will include the full path (including the prefix), but the wildcard parameter will only capture the part after the prefix.
• Inheritance: Global configuration and hooks are not inherited from the nested app. You should define global config and hooks on the main app instance.

import { H3, serve } from "h3";

const nestedApp = new H3()
  .use((event) => {
    event.res.headers.set("x-api", "1");
  })
  .get("/**:slug", (event) => ({
    pathname: event.url.pathname,
    slug: event.context.params?.slug,
  }));

const app = new H3().mount("/api", nestedApp);

To send specific HTTP error responses, throw an instance of HTTPError. H3 supports several ways to instantiate it:

1. Message and Status: Provide a message string and a status code object.
2. Static Method: Use HTTPError.status(code, statusText).
3. Configuration Object: Pass a single object containing all error details.

When an HTTPError is thrown, H3 returns a JSON response containing the status, statusText, message, and any additional data or body properties provided.

import { HTTPError } from "h3";

app.get("/error", (event) => {
  // Using message and details
  throw new HTTPError("Invalid user input", { status: 400 });

  // Using HTTPError.status(code)
  throw HTTPError.status(400, "Bad Request");

  // Using single object
  throw new HTTPError({
    status: 400,
    statusText: "Bad Request",
    message: "Invalid user input",
    data: { field: "email" },
    body: { date: new Date().toJSON() },
    headers: {},
  });
});