ts-typed-api 0.2.23 → 0.2.24

package/.kilo/plans/1784112824796-stream-bytes-response.md

@@ -0,0 +1,198 @@
+# Plan: Add byte-stream piping to `TypedResponse`
+
+## Goal
+Add a `res.pipeStream(readable, options)` method to `TypedResponse` that pipes a `Readable` (Node.js) or `ReadableStream` (Web) to the client without buffering in memory. Add a `streaming?: boolean` declaration option to route definitions.
+
+## Affected files
+- `src/definition.ts` — add `streaming?: boolean` to route types
+- `src/router.ts` — add `pipeStream` signature to `TypedResponse`
+- `src/handler.ts` — implement `pipeStream` for Express
+- `src/hono-cloudflare-workers.ts` — implement `pipeStream` for Hono
+- `tests/setup.ts` — add a test route using `pipeStream`
+- `tests/simple-api.test.ts` — add streaming tests
+- `examples/simple/definitions.ts` — optionally add a streaming route
+
+## Task list
+
+### 1. Add `streaming?: boolean` to route definition types (`src/definition.ts`)
+
+Add `streaming?: boolean` to both `RouteWithoutBody` (~line 182) and `RouteWithBody` (~line 193). Since `RouteSchema` is a union intersection, add it in the intersection:
+
+```typescript
+export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
+    description?: string;
+    streaming?: boolean;  // <-- add this
+};
+```
+
+### 2. Add `pipeStream` to `TypedResponse` interface (`src/router.ts`)
+
+Add the method signature to `TypedResponse`:
+
+```typescript
+pipeStream: (
+    readable: NodeJS.ReadableStream | ReadableStream<Uint8Array>,
+    options?: { status?: number; contentType?: string; filename?: string }
+) => void;
+```
+
+Since `TypedResponse` extends `express.Response`, this signature is shared by both Express and Hono implementations.
+
+Also add a `PipeStreamFunction` type alias for reuse across backends.
+
+### 3. Implement `pipeStream` for Express (`src/handler.ts`)
+
+In `registerRouteHandlers`, after the `respondContentType` and `setHeader` assignments (~after line 508), add:
+
+```typescript
+typedExpressRes.pipeStream = (readable, options) => {
+    const status = options?.status ?? 200;
+    const contentType = options?.contentType ?? 'application/octet-stream';
+
+    typedExpressRes.status(status);
+    Object.getPrototypeOf(expressRes).setHeader.call(expressRes, 'Content-Type', contentType);
+    if (options?.filename) {
+        Object.getPrototypeOf(expressRes).setHeader.call(
+            expressRes, 'Content-Disposition',
+            `attachment; filename="${encodeURIComponent(options.filename)}"`
+        );
+    }
+
+    if (Symbol.asyncIterator in Object(readable)) {
+        // Node.js Readable — pipe directly
+        (readable as NodeJS.ReadableStream).pipe(expressRes);
+    } else {
+        // Web ReadableStream — convert via reader
+        const reader = (readable as ReadableStream<Uint8Array>).getReader();
+        const nodeReadable = new (require('stream').Readable)({
+            async read() {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        this.push(null);
+                    } else {
+                        this.push(Buffer.from(value));
+                    }
+                } catch (err) {
+                    this.destroy(err as Error);
+                }
+            }
+        });
+        nodeReadable.pipe(expressRes);
+    }
+};
+```
+
+For Hono in `src/hono-cloudflare-workers.ts`, on the fakeRes object (~after line 502):
+
+```typescript
+pipeStream: (readable, options) => {
+    const status = options?.status ?? 200;
+    const contentType = options?.contentType ?? 'application/octet-stream';
+    const filename = options?.filename;
+
+    const headers = new Headers({ 'Content-Type': contentType });
+    if (filename) {
+        headers.set('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`);
+    }
+
+    let webStream: ReadableStream<Uint8Array>;
+    if (Symbol.asyncIterator in Object(readable)) {
+        // Node.js Readable -> convert to ReadableStream
+        // Pipe through a simple bridge
+        const { pipeline } = require('stream/promises');
+        const { PassThrough } = require('stream');
+        const pass = new PassThrough();
+        (readable as NodeJS.ReadableStream).pipe(pass);
+        webStream = new ReadableStream({
+            async pull(controller) {
+                const chunk = pass.read();
+                if (chunk === null) {
+                    await new Promise(r => pass.once('readable', r));
+                    const next = pass.read();
+                    if (next) controller.enqueue(Buffer.from(next));
+                } else {
+                    controller.enqueue(Buffer.from(chunk));
+                }
+            }
+        });
+    } else {
+        webStream = readable as ReadableStream<Uint8Array>;
+    }
+
+    (c as any).__response = new Response(webStream, { status, headers });
+};
+```
+
+Simplify the Hono Web ReadableStream conversion — just use an approach that wraps Readable into ReadableStream:
+
+```typescript
+// Simpler: Use Readable.toWeb() if available (Node 18+ / 16 with flag)
+let webStream: ReadableStream<Uint8Array>;
+if ('toWeb' in (require('stream').Readable) && Symbol.asyncIterator in Object(readable)) {
+    webStream = (require('stream').Readable as any).toWeb(readable) as ReadableStream<Uint8Array>;
+} else if (Symbol.asyncIterator in Object(readable)) {
+    // Fallback conversion
+    const nodeReadable = readable as NodeJS.ReadableStream;
+    webStream = new ReadableStream({
+        start(controller) {
+            nodeReadable.on('data', chunk => controller.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk));
+            nodeReadable.on('end', () => controller.close());
+            nodeReadable.on('error', err => controller.error(err));
+        },
+        cancel() { nodeReadable.destroy(); }
+    });
+} else {
+    webStream = readable as ReadableStream<Uint8Array>;
+}
+```
+
+For the middleware-wrapped `respond` in `createRespondFunction` (~line 142), we should also add `pipeStream` to the `MiddlewareResponse` interface so middleware can use it, but that's lower priority.
+
+### 4. Add test coverage (`tests/setup.ts` + `tests/simple-api.test.ts`)
+
+Add a `streamBytes` route to the simple API definition (in `examples/simple/definitions.ts`):
+
+```typescript
+streamBytes: {
+    method: 'GET',
+    path: '/stream-bytes',
+    description: 'Binary streaming endpoint',
+    streaming: true,
+    responses: CreateResponses({
+        200: z.string() // raw status marker; validation skipped for streaming
+    })
+},
+```
+
+Add a handler that creates a readable stream and pipes it:
+
+```typescript
+streamBytes: async (req: any, res: any) => {
+    const { Readable } = require('stream');
+    const readable = Readable.from([
+        Buffer.from('chunk1'),
+        Buffer.from('chunk2'),
+        Buffer.from('chunk3')
+    ]);
+    res.pipeStream(readable, { contentType: 'application/octet-stream', filename: 'test.bin' });
+},
+```
+
+Add tests that verify:
+- Response status is correct
+- Content-Type / Content-Disposition headers are set
+- Full body matches the expected byte content
+- If a `ReadableStream` (Web) is passed, it's correctly converted
+
+### 5. Update exports if needed
+
+Verify `pipeStream` is accessible through `TypedResponse` — no new exports needed since it's on the existing `TypedResponse` interface already exported from `router.ts`.
+
+## Type considerations
+- `pipeStream` uses a permissive `readable` parameter that accepts both `NodeJS.ReadableStream` and `ReadableStream<Uint8Array>`. We can detect at runtime which one was passed via `Symbol.asyncIterator`.
+- `streaming?: boolean` on `RouteSchema` is purely declarative — the type system allows it on any route, and at runtime it's just metadata (used by OpenAPI generation, client detection, etc.).
+
+## Risks
+- Node 16 compatibility: `Readable.toWeb()` is experimental in Node 16 but available with flag. The fallback manual conversion avoids this dependency. At runtime we detect and use the fallback.
+- Error handling: If the readable stream errors mid-pipe, Express closes the connection. We should `destroy()` the stream on Hono cancel.

package/dist/definition.d.ts

@@ -95,6 +95,7 @@ type RouteWithBody = {
 };
 export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
     description?: string;
+    streaming?: boolean;
 };
 export type ApiDefinitionSchema<TEndpoints extends Record<string, Record<string, RouteSchema>> = Record<string, Record<string, RouteSchema>>> = {
     prefix?: string;

package/dist/handler.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerRouteHandlers = registerRouteHandlers;
 const zod_1 = require("zod");
+const stream_1 = require("stream");
 const multer_1 = __importDefault(require("multer"));
 // Helper function to preprocess parameters for type coercion
 function preprocessParams(params, paramsSchema) {
@@ -441,6 +442,38 @@ middlewares, errorHandler) {
                     Object.getPrototypeOf(expressRes).setHeader.call(expressRes, name, value);
                     return typedExpressRes;
                 };
+                typedExpressRes.pipeStream = (readable, options) => {
+                    const status = options?.status ?? 200;
+                    const contentType = options?.contentType ?? 'application/octet-stream';
+                    typedExpressRes.status(status);
+                    Object.getPrototypeOf(expressRes).setHeader.call(expressRes, 'Content-Type', contentType);
+                    if (options?.filename) {
+                        Object.getPrototypeOf(expressRes).setHeader.call(expressRes, 'Content-Disposition', `attachment; filename="${encodeURIComponent(options.filename)}"`);
+                    }
+                    if (Symbol.asyncIterator in Object(readable)) {
+                        readable.pipe(expressRes);
+                    }
+                    else {
+                        const reader = readable.getReader();
+                        const nodeReadable = new stream_1.Readable({
+                            async read() {
+                                try {
+                                    const { done, value } = await reader.read();
+                                    if (done) {
+                                        this.push(null);
+                                    }
+                                    else {
+                                        this.push(Buffer.from(value));
+                                    }
+                                }
+                                catch (err) {
+                                    this.destroy(err);
+                                }
+                            }
+                        });
+                        nodeReadable.pipe(expressRes);
+                    }
+                };
                 // SSE streaming methods
                 typedExpressRes.startSSE = () => {
                     typedExpressRes.setHeader('Content-Type', 'text/event-stream');

package/dist/hono-cloudflare-workers.js

@@ -406,6 +406,30 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
                         c.header(name, value);
                         return fakeRes;
                     },
+                    pipeStream: (readable, options) => {
+                        const status = options?.status ?? 200;
+                        const contentType = options?.contentType ?? 'application/octet-stream';
+                        const headers = new Headers({ 'Content-Type': contentType });
+                        if (options?.filename) {
+                            headers.set('Content-Disposition', `attachment; filename="${encodeURIComponent(options.filename)}"`);
+                        }
+                        let webStream;
+                        if (Symbol.asyncIterator in Object(readable)) {
+                            const nodeReadable = readable;
+                            webStream = new ReadableStream({
+                                start(controller) {
+                                    nodeReadable.on('data', (chunk) => controller.enqueue(new Uint8Array(chunk)));
+                                    nodeReadable.on('end', () => controller.close());
+                                    nodeReadable.on('error', (err) => controller.error(err));
+                                },
+                                cancel() { nodeReadable.destroy(); }
+                            });
+                        }
+                        else {
+                            webStream = readable;
+                        }
+                        c.__response = new Response(webStream, { status, headers });
+                    },
                     // SSE streaming methods for Hono
                     startSSE: () => {
                         c.header('Content-Type', 'text/event-stream');

package/dist/router.d.ts

@@ -21,6 +21,11 @@ export interface TypedResponse<TDef extends ApiDefinitionSchema, TDomain extends
     startSSE: () => void;
     streamSSE: (eventName?: string, data?: any, id?: string) => void;
     endStream: () => void;
+    pipeStream: (readable: NodeJS.ReadableStream | ReadableStream<Uint8Array>, options?: {
+        status?: number;
+        contentType?: string;
+        filename?: string;
+    }) => void;
 }
 export declare function createRouteHandler<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteKey extends keyof TDef['endpoints'][TDomain], // Using direct keyof for simplicity
 Ctx extends Record<string, any> = Record<string, any>>(domain: TDomain, routeKey: TRouteKey, handler: (req: TypedRequest<TDef, TDomain, TRouteKey, ApiParams<TDef, TDomain, TRouteKey>, ApiBody<TDef, TDomain, TRouteKey>, ApiQuery<TDef, TDomain, TRouteKey>, Record<string, any>, Ctx>, res: TypedResponse<TDef, TDomain, TRouteKey>) => Promise<void> | void): {

package/examples/simple/definitions.ts

@@ -77,6 +77,15 @@ export const PublicApiDefinition = CreateApiDefinition({
                     200: z.string() // Raw SSE data
                 })
             },
+            streamBytes: {
+                method: 'GET',
+                path: '/stream-bytes',
+                description: 'Binary byte streaming endpoint',
+                streaming: true,
+                responses: CreateResponses({
+                    200: z.any()
+                })
+            },
             patchResource: {
                 method: 'PATCH',
                 path: '/patch-resource',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "A lightweight, type-safe RPC library for TypeScript with Zod validation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/definition.ts

@@ -196,6 +196,7 @@ type RouteWithBody = {
 // Union type for all route schemas
 export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
     description?: string;
+    streaming?: boolean;
 };
 
 // Define the structure for the entire API definition object

package/src/handler.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { Readable } from "stream";
 import { ApiDefinitionSchema, RouteSchema, UnifiedError, FileUploadConfig, ErrorHandler } from "./definition";
 import { createRouteHandler, TypedRequest, TypedResponse } from "./router";
 import { MiddlewareResponse } from "./object-handlers";
@@ -513,6 +514,42 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
                     return typedExpressRes;
                 };
 
+                typedExpressRes.pipeStream = (readable, options) => {
+                    const status = options?.status ?? 200;
+                    const contentType = options?.contentType ?? 'application/octet-stream';
+
+                    typedExpressRes.status(status);
+                    Object.getPrototypeOf(expressRes).setHeader.call(expressRes, 'Content-Type', contentType);
+                    if (options?.filename) {
+                        Object.getPrototypeOf(expressRes).setHeader.call(
+                            expressRes,
+                            'Content-Disposition',
+                            `attachment; filename="${encodeURIComponent(options.filename)}"`
+                        );
+                    }
+
+                    if (Symbol.asyncIterator in Object(readable)) {
+                        (readable as NodeJS.ReadableStream).pipe(expressRes);
+                    } else {
+                        const reader = (readable as ReadableStream<Uint8Array>).getReader();
+                        const nodeReadable = new Readable({
+                            async read() {
+                                try {
+                                    const { done, value } = await reader.read();
+                                    if (done) {
+                                        this.push(null);
+                                    } else {
+                                        this.push(Buffer.from(value));
+                                    }
+                                } catch (err) {
+                                    this.destroy(err as Error);
+                                }
+                            }
+                        });
+                        nodeReadable.pipe(expressRes);
+                    }
+                };
+
                 // SSE streaming methods
                 typedExpressRes.startSSE = () => {
                     typedExpressRes.setHeader('Content-Type', 'text/event-stream');

package/src/hono-cloudflare-workers.ts

@@ -1,4 +1,5 @@
 import { Hono, Context, MiddlewareHandler, Env } from 'hono';
+import { Readable } from 'stream';
 import { z } from 'zod';
 import { ApiDefinitionSchema, RouteSchema, UnifiedError, FileUploadConfig } from './definition';
 import { TypedRequest, TypedResponse } from './router';
@@ -489,6 +490,32 @@ export function registerHonoRouteHandlers<
                         c.header(name, value);
                         return fakeRes;
                     },
+                    pipeStream: (readable, options) => {
+                        const status = options?.status ?? 200;
+                        const contentType = options?.contentType ?? 'application/octet-stream';
+
+                        const headers = new Headers({ 'Content-Type': contentType });
+                        if (options?.filename) {
+                            headers.set('Content-Disposition', `attachment; filename="${encodeURIComponent(options.filename)}"`);
+                        }
+
+                        let webStream: ReadableStream<Uint8Array>;
+                        if (Symbol.asyncIterator in Object(readable)) {
+                            const nodeReadable = readable as Readable;
+                            webStream = new ReadableStream<Uint8Array>({
+                                start(controller) {
+                                    nodeReadable.on('data', (chunk: Buffer) => controller.enqueue(new Uint8Array(chunk)));
+                                    nodeReadable.on('end', () => controller.close());
+                                    nodeReadable.on('error', (err) => controller.error(err));
+                                },
+                                cancel() { nodeReadable.destroy(); }
+                            });
+                        } else {
+                            webStream = readable as ReadableStream<Uint8Array>;
+                        }
+
+                        (c as any).__response = new Response(webStream, { status, headers });
+                    },
                     // SSE streaming methods for Hono
                     startSSE: () => {
                         c.header('Content-Type', 'text/event-stream');

package/src/router.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'stream';
 import express from "express";
 import {
     ApiDefinitionSchema, // Changed from ApiDefinition
@@ -68,6 +69,11 @@ export interface TypedResponse<
     startSSE: () => void;
     streamSSE: (eventName?: string, data?: any, id?: string) => void;
     endStream: () => void;
+    // Binary/byte stream piping
+    pipeStream: (
+        readable: NodeJS.ReadableStream | ReadableStream<Uint8Array>,
+        options?: { status?: number; contentType?: string; filename?: string }
+    ) => void;
 }
 
 // Type-safe route handler creation function, now generic over TDef and Ctx

package/tests/setup.ts

@@ -2,6 +2,7 @@ import { beforeAll, afterAll } from '@jest/globals';
 import express from 'express';
 import { Server } from 'http';
 import http from 'http';
+import { Readable } from 'stream';
 import { Hono } from 'hono';
 import { PublicApiDefinition as SimplePublicApiDefinition, PrivateApiDefinition as SimplePrivateApiDefinition } from '../examples/simple/definitions';
 import { PublicApiDefinition as AdvancedPublicApiDefinition, PrivateApiDefinition as AdvancedPrivateApiDefinition } from '../examples/advanced/definitions';
@@ -51,6 +52,19 @@ const simplePublicHandlers = {
             // Close the stream
             res.endStream();
         },
+        streamBytes: async (req: any, res: any) => {
+            const chunks = [
+                Buffer.from('chunk1'),
+                Buffer.from('chunk2'),
+                Buffer.from('chunk3')
+            ];
+            const readable = Readable.from(chunks);
+            res.pipeStream(readable, {
+                contentType: 'application/octet-stream',
+                filename: 'test.bin',
+                status: 200
+            });
+        },
         disconnectTest: async (req: any, res: any) => {
             const delay = req.query?.delay || 1000;
             let disconnected = false;

package/tests/simple-api.test.ts

@@ -251,6 +251,16 @@ describe.each([
             return data ? JSON.parse(data) : null;
         }
 
+        test('should handle binary streaming with pipeStream', async () => {
+            const response = await fetch(`${baseUrl}/api/v1/public/stream-bytes`);
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toBe('application/octet-stream');
+            expect(response.headers.get('content-disposition')).toBe('attachment; filename="test.bin"');
+
+            const body = await response.text();
+            expect(body).toBe('chunk1chunk2chunk3');
+        });
+
         test('should handle client disconnection with req.onClose', async () => {
             // Test that the endpoint works normally when client doesn't disconnect
             const result = await client.callApi('common', 'disconnectTest', {