Support return `ReadableStream<binary>` in .handler

[dinwwwh]

Describe the feature

const sync = os.
  .handler(async ({ context, input, errors }) => {
    return new ReadableStream(<binary data>);
  });

Relates: #954

Tip

You can support this effort by becoming an oRPC sponsor.

Additional information

• Would you be willing to help implement this feature?

[Azarattum]

If this is implemented, would it be possible to also support an async generator of UInt8Array? I have server events which emit in binary format. The payload could be quite large, so serializing as base64 is not an option. As far as I understand, this is not currently possible with oRPC, right?

[dinwwwh]

@Azarattum If this support you must convert async generator -> Readable Stream (both are very familiar, and oRPC already has buit-in utility for this link) to utilize binary support

[uncvrd]

It would be real nice to be able to also support the ability of returning the request early so we can dynamically stream a response back to the user, if possible. Let me explain.

In Fastify, I can create a .zip archive using npm archiver. I can return this immediately back to the browser, then append files to to the zip, finalize it, and close the request.

This allows me to stream each file in to the zip without needing to load every file in memory first.

Here is how I do this using just Fastify

fastify.withTypeProvider<ZodTypeProvider>().post<{
        Body: { ids: number[] }
    }>(
        "/download",
        {
            schema: {
                body: z.object({
                    ids: z.array(z.number()),
                }),
            },
        },
        async (request, reply) => {
            const archive = archiver("zip")

            reply.header("Content-Disposition", "attachment")
            reply.header("Content-Type", "application/zip")

            // I send an HTTP response back to the user with the empty archive
            reply.send(archive)

            for (const id of request.body.ids) {
                // I can now make an S3 request to stream each file in to the archive
                // this function ultimately calls archive.append()

                await archiveTrack({ archive, trackId: id, prefix: track.title ?? `unknown-${generateId(5)}` })
            }

            await archive.finalize()

            // Fastify requires that you return the reply since we've already reply.send() above, which will cleanly resolve your request to the browser
            return reply
        }
    )

[ghdoergeloh]

+1 from us — we hit the exact same issue as @uncvrd with archiver streaming a ZIP archive. We're using Hono + @hono/node-server instead of Fastify, but the problem is identical.

What we tried

oz.file() / oz.blob() — requires full buffer

.output(oz.blob())
.handler(async ({ input }) => {
  const chunks: Buffer[] = [];
  await new Promise((resolve, reject) => {
    archive.on('data', (chunk) => chunks.push(chunk));
    archive.on('end', resolve);
    archive.on('error', reject);
    archive.finalize();
  });
  return new File([Buffer.concat(chunks)], 'export.zip', { type: 'application/zip' });
})

Works, but defeats the purpose — the entire archive must be in memory before the response starts.

Returning Response directly — silently serialized as {}

.handler(async ({ input }) => {
  return new Response(stream as ReadableStream, {
    headers: { 'Content-Type': 'application/zip' },
  });
})

oRPC serializes the Response object as JSON ({}).

z.instanceof(Response) with oz.file() cast — runtime 500

return new Response(stream as unknown as ReadableStream) as unknown as File;

Passes TypeScript but fails at runtime — oRPC's runtime validation rejects it.

Current workaround: spec-only contract + plain framework route

We bypass oRPC for the streaming route and implement it as a plain Hono route. To keep the OpenAPI spec complete, we define a spec-only contract that is intentionally never passed to implement():

// export.contract.ts — NOT passed to implement()
export const exportAdminContract = {
  postExport: oc
    .route({
      method: 'POST',
      path: '/{studyName}/agree/export',
      summary: 'Export compliance agreements as ZIP',
      tags: ['export'],
    })
    .input(z.object({ studyName: z.string() }))
    .output(oz.blob()), // approximate — real response is a ReadableStream
};

// server.ts — plain Hono route, completely outside oRPC
publicApp.post('/admin/:studyName/agree/export', async (c) => {
  const stream = ExportInteractor.export({ studyName: c.req.param('studyName') });
  return new Response(stream as unknown as ReadableStream, {
    headers: {
      'Content-Type': 'application/zip',
      'Content-Disposition': `attachment; filename=${c.req.param('studyName')}-export.zip`,
    },
  });
});

This works but has real downsides:

• Auth middleware defined as oRPC middleware can't be reused — must be duplicated
• The output schema is approximate; oRPC client libraries won't work for this route
• The spec-only contract pattern is entirely undocumented

Would love to see ReadableStream<Uint8Array> supported as a handler return type, as proposed in this issue.

[dinwwwh]

This feature will ship in v2. Sorry, @uncvrd I missed your comment.

[uncvrd]

No problem that's great to hear, thank you!

[ghdoergeloh]

but it should be backwards-compatible. So no need for a major version bump. There is no braking change, as far as I can see.

[dinwwwh]

but it should be backwards-compatible. So no need for a major version bump. There is no braking change, as far as I can see.

Because I want it to fully support the entire oRPC ecosystem, not just OpenAPIHandler, it should also work with RPCHandler/Link, OpenAPILink, WebSocket adapters, and more.