📦 Streaming Client Transport SDK

A TypeScript SDK for streaming server responses in various transport modes such as WebSockets, Server-Sent Events (SSE), and Streaming HTTP. It provides a unified Client interface to simplify communication with backend systems that support streamable responses.

✨ Features

• 🔄 Unified streaming interface
• ⚙️ Pluggable transport layer (WebSocket, SSE, HTTP)
• 🧠 Support for object and text streaming
• ❌ Graceful abort & close handling
• 🔌 Easy transport switching

📦 Installation

npm install @diptabose/chat-client

📐 TypeScript Types

export type StreamResponse = {
  response: Promise<Response>;
  readableStream: ReadableStream;
};

export type ObjectStreamResponse = {
  response: Promise<Response>;
  readableStream: ReadableStream<any>;
};

export type ContentResponse = {
  response: Promise<Response>;
  content: string;
};

export type SendReturnType<
  Options extends { stream: boolean; objectMode: boolean }
> = Options["stream"] extends false
  ? ContentResponse
  : Options["objectMode"] extends true
  ? ObjectStreamResponse
  : StreamResponse;

🚀 Usage

1. Create a Transport

You can use one of the following transports:

• WebSocketTransport
• SSETransport
• StreambleHttpTransport

import { WebSocketTransport } from "@diptabose/chat-client/transports/websocket";

const wsTransport = new WebSocketTransport("ws://localhost:4000", {
  eventName: "message",
});

2. Create a Client

import { Client } from "@diptabose/chat-client/client/client";

const client = new Client(wsTransport, {
  stream: true,
  objectMode: false,
});

3. Send Request

const result = await client.send("/api/chat", { message: "hello" });

const reader = result.readableStream.getReader();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log("Chunk:", value);
}

🌐 Transports

✅ WebSocketTransport

• Listens for server-side events via WebSocket.
• Sends an HTTP POST to initiate the stream.

new WebSocketTransport("ws://localhost:4000", { eventName: "message" });

✅ SSETransport

• Uses EventSource to listen to SSE streams.

new SSETransport("/events", { eventName: "data" });

✅ StreambleHttpTransport

• Sends an HTTP POST and receives text/event-stream over fetch().

new StreambleHttpTransport("/stream");

🔧 API Reference

Client

new Client(transport: Transport, options: { stream: boolean, objectMode: boolean })

send(url?: string, data?: object, options?: RequestInit)

• Returns a response + stream object
• Respects AbortSignal

transport(newTransport: Transport)

• Dynamically switch transport at runtime

📤 Streaming Modes

| stream | objectMode | Output Type | | ------ | ---------- | ---------------------- | | false | - | ContentResponse | | true | false | StreamResponse | | true | true | ObjectStreamResponse |

❌ Graceful Aborting

All transports support AbortSignal to cancel ongoing requests and close streams.

const controller = new AbortController();
client.send("/api", {}, { signal: controller.signal });
controller.abort();

🧪 Example

const transport = new SSETransport("/events", { eventName: "data" });
const client = new Client(transport, { stream: true, objectMode: false });

const { readableStream } = await client.send("/chat", { prompt: "hi" });
const reader = readableStream.getReader();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log("Chunk:", value);
}

🛠️ Utilities Used

• Streamable - wraps ReadableStream with controller
• TransformableReadableStream - transforms stream data
• parseEventStream - parses SSE chunked data

🧩 Extending

You can build your own transport by implementing:

export interface Transport {
  send(
    url: string,
    data?: Record<string, unknown>,
    options?: Omit<RequestInit, "body">
  ): Promise<{
    response: Promise<Response>;
    readableStream: ReadableStream | null;
  }>;
  transportUrl: () => string | URL;
  close(): void;
}

🧾 License

MIT

👨‍💻 Author

Developed by [Dipta Bose] — Contributions are welcome!