Streaming files with "readableWebStream"

[eric-burel]

Hey folks,

I've previously proposed an implementation of file streaming from route handlers, the tricky part being that Node.js "fs" streams are not exactly the same data structure as web platform ReadableStream.

@karlhorky has kindly pointed me towards Node.js builtin (but experimental) readableWebStream method. It would drastically simplify my previous implementation.

I've started a demo application but couldn't make it work yet.

Code: https://github.com/eric-burel/demo-readableWebStream

You just need to clone, install, run and open the home page. It will trigger an API request that should load an image. But I currently hit an error [cause]: TypeError [ERR_INVALID_ARG_TYPE]: The "chunk" argument must be of type string or an instance of Buffer or Uint8Array. Received an instance of ArrayBuffer. Any idea how to fix this application?

[Juneezee]

I had a similar situation as yours. In my case, I was using Puppeteer to create a PDF of a HTML page. The createPDFStream returns a Node.js Readable stream. This is what I did to convert the Node stream to a Web stream.

import { Readable } from "node:stream";
import type { ReadableStream as NodeReadableStream } from "node:stream/web";
import type { Browser, PDFOptions } from "puppeteer";
import { launch } from "puppeteer";

async function generatePdfFromHtml(
  html: string,
): ReturnType<typeof page.createPDFStream> {
  const browser = await launchBrowser();
  const page = await browser.newPage();
  await page.setContent(html);

  const reader = await page
    .createPDFStream(DEFAULT_PDF_OPTIONS)
    .then((stream) => stream.getReader());

  return new ReadableStream<Uint8Array>({
    start(controller): Promise<void> {
      async function pump(): Promise<void> {
        const { done, value } = await reader.read();
        if (done) {
          controller.close();
          closeBrowser(browser);
          return;
        }
        controller.enqueue(value);
        await pump();
      }
      return pump();
    },
    cancel(reason): void {
      void reader.cancel(reason);
      closeBrowser(browser);
    },
  });
}

export async function POST(request: Request): Promise<Response> {
    // ....
    return new Response(await generatePdfFromHtml(html), {
      headers: {
        "Content-Type": "application/pdf",
      },
    });
}

Hope it helps!

[karlhorky]

Apparently this is a bug in Node.js with fileHandle.readableWebStream() - I reported an issue:

• filehandle.readableWebStream() chunks return incompatible ArrayBuffer instead of Uint8Array nodejs/node#54041
• https://x.com/karlhorky/status/1816428748092158288

[karlhorky]

Now that PR nodejs/node#55461 has been released in Node.js v23.8.0:

I can confirm that Node.js v23.8.0 FileHandle.readableWebStream() can be used without configuration to easily create Web Streams, which can then be passed to Route Handlers 🎉

import fs from "node:fs/promises";
import http from "node:http";
import path from "node:path";
import { Readable } from "node:stream";

const filePath = "./image.jpg";

const server = http.createServer(async (nodeRequest, nodeResponse) => {
  const stats = await fs.stat(filePath);
  const fileHandle = await fs.open(filePath);
  const webStream = fileHandle.readableWebStream();

  nodeResponse.writeHead(200, {
    "Content-Type": "image/jpeg",
    "Content-Length": String(stats.size),
  });

  const nodeStream = Readable.fromWeb(webStream);

  nodeStream.pipe(nodeResponse).on("finish", async () => {
    await fileHandle.close();
  });
});

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

CodeSandbox demo: https://codesandbox.io/p/devbox/filehandle-readablewebstream-with-new-response-forked-rly47y?file=%2Findex.js%3A9%2C35&workspaceId=ws_GfAuHrswXyA1DoeSwsjjjz

[karlhorky]

Update: with autoClose option to FileHandle readableWebStream from @jasnell being a part of Node.js v24.2.0, I guess that the 'finish' callback and the fileHandle.close() can be omitted from the example code?

Maybe something like this:

import fs from "node:fs/promises";
import http from "node:http";
import path from "node:path";
import { Readable } from "node:stream";

const filePath = "./image.jpg";

const server = http.createServer(async (nodeRequest, nodeResponse) => {
  const stats = await fs.stat(filePath);
  const fileHandle = await fs.open(filePath);
- const webStream = fileHandle.readableWebStream();
+ const webStream = fileHandle.readableWebStream({ autoClose: true });

  nodeResponse.writeHead(200, {
    "Content-Type": "image/jpeg",
    "Content-Length": String(stats.size),
  });

  const nodeStream = Readable.fromWeb(webStream);

- nodeStream.pipe(nodeResponse).on("finish", async () => {
-   await fileHandle.close();
- }); 
+ nodeStream.pipe(nodeResponse);
});

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

[eric-burel]

Thanks @karlhorky for the heads up!

Slightly related: I now use this use case as a test for AI-based tooling capabilities - since modern features + lesser documented patterns tend to be their weak point. I've recently tried teaching GitHub Copilot to output a proper file streaming route handler, and documented the ride on my technical blog : https://www.ericburel.tech/blog/teaching-nextjs-to-github-copilot