@tashiscool/stream 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# @llm-utils/stream
+
+Streaming utilities for real-time LLM responses. Handle HTTP streaming, chunk aggregation, and JSONL parsing with ease.
+
+## Installation
+
+```bash
+pnpm add @llm-utils/stream
+# or
+npm install @llm-utils/stream
+```
+
+## Features
+
+- **HTTP Response Interception** - Transform streaming responses without breaking semantics
+- **Chunk Aggregation** - Aggregate chunks from multiple sources with lifecycle handlers
+- **JSONL Streaming** - Parse and serialize JSONL streams (server and client)
+- **Type-Safe** - Full TypeScript support with generics
+
+## Usage
+
+### Intercept and Transform Streaming Responses
+
+```typescript
+import { interceptResponseWrites } from '@llm-utils/stream';
+
+app.post('/chat', async (req, res) => {
+  const llmStream = await callLLM(req.body);
+
+  interceptResponseWrites(res, {
+    transform: async (chunk) => {
+      // Transform each chunk before sending to client
+      const data = JSON.parse(chunk);
+      const enriched = { ...data, timestamp: Date.now() };
+      return JSON.stringify(enriched) + '\n';
+    },
+    onFinish: async () => {
+      // Cleanup after stream ends
+      await saveConversation();
+    }
+  });
+
+  llmStream.pipe(res);
+});
+```
+
+### Aggregate Chunks from Multiple Sources
+
+```typescript
+import { createChunkAggregator } from '@llm-utils/stream';
+
+const aggregator = createChunkAggregator({
+  onBegin: async (message) => {
+    console.log(`Starting message from node: ${message.nodeId}`);
+  },
+  onItem: async (message, delta) => {
+    // Stream delta to client
+    sendToClient(delta);
+  },
+  onEnd: async (message) => {
+    // Save complete message
+    await saveMessage(message);
+  },
+  onError: async (message, error) => {
+    console.error(`Error in ${message.nodeId}:`, error);
+  }
+});
+
+// Ingest structured chunks
+for await (const chunk of structuredStream) {
+  await aggregator.ingest(chunk);
+}
+
+// Finalize any incomplete messages
+await aggregator.finalizeAll();
+```
+
+### JSONL Streaming
+
+```typescript
+import { streamJsonLines, parseJsonLines } from '@llm-utils/stream';
+
+// Server: Stream objects as JSONL
+app.get('/events', (req, res) => {
+  streamJsonLines(res, async function* () {
+    for (const event of events) {
+      yield event;
+    }
+  });
+});
+
+// Client: Parse JSONL stream
+const response = await fetch('/events');
+for await (const event of parseJsonLines(response)) {
+  handleEvent(event);
+}
+```
+
+## API Reference
+
+### `interceptResponseWrites(res, options)`
+
+Intercepts Express response writes for transformation.
+
+```typescript
+interface InterceptOptions {
+  transform: (text: string) => Promise<string | undefined>;
+  onFinish?: () => Promise<void>;
+  onError?: (error: Error) => void;
+}
+```
+
+### `createChunkAggregator(handlers)`
+
+Creates a stateful chunk aggregator for multi-source streaming.
+
+```typescript
+interface StructuredChunk {
+  nodeId: string;
+  runIndex: number;
+  itemIndex: number;
+  type: 'begin' | 'item' | 'end' | 'error';
+  data?: string;
+  error?: string;
+}
+
+interface ChunkHandlers {
+  onBegin?: (message: AggregatedMessage) => Promise<void>;
+  onItem?: (message: AggregatedMessage, delta: string) => Promise<void>;
+  onEnd?: (message: AggregatedMessage) => Promise<void>;
+  onError?: (message: AggregatedMessage, error?: string) => Promise<void>;
+}
+```
+
+### `streamJsonLines(res, generator)`
+
+Streams objects as JSONL to an HTTP response.
+
+### `parseJsonLines(response)`
+
+Parses a JSONL stream from a fetch Response.
+
+## License
+
+MIT

package/dist/aggregator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Chunk Aggregation
+ * Aggregate streaming chunks from multiple sources with lifecycle handlers
+ */
+/**
+ * A structured chunk from a streaming source
+ */
+export interface StructuredChunk {
+    /** Identifier for the source node */
+    nodeId: string;
+    /** Run index for parallel executions */
+    runIndex: number;
+    /** Item index within the run */
+    itemIndex: number;
+    /** Chunk lifecycle type */
+    type: 'begin' | 'item' | 'end' | 'error';
+    /** Content data (for 'item' type) */
+    data?: string;
+    /** Error message (for 'error' type) */
+    error?: string;
+}
+/**
+ * An aggregated message from multiple chunks
+ */
+export interface AggregatedMessage {
+    /** Source node identifier */
+    nodeId: string;
+    /** Run index */
+    runIndex: number;
+    /** Item index */
+    itemIndex: number;
+    /** Accumulated content */
+    content: string;
+    /** Current status */
+    status: 'streaming' | 'complete' | 'error';
+    /** Error message if status is 'error' */
+    error?: string;
+    /** Timestamp when message started */
+    startedAt: Date;
+    /** Timestamp when message completed */
+    completedAt?: Date;
+}
+/**
+ * Handlers for chunk lifecycle events
+ */
+export interface ChunkHandlers {
+    /** Called when a new message stream begins */
+    onBegin?: (message: AggregatedMessage) => Promise<void>;
+    /** Called for each content chunk */
+    onItem?: (message: AggregatedMessage, delta: string) => Promise<void>;
+    /** Called when a message stream ends successfully */
+    onEnd?: (message: AggregatedMessage) => Promise<void>;
+    /** Called when a message stream errors */
+    onError?: (message: AggregatedMessage, error?: string) => Promise<void>;
+}
+/**
+ * Chunk aggregator interface
+ */
+export interface ChunkAggregator {
+    /** Ingest a structured chunk */
+    ingest: (chunk: StructuredChunk) => Promise<AggregatedMessage>;
+    /** Finalize all incomplete messages */
+    finalizeAll: () => Promise<void>;
+    /** Get all current messages */
+    getMessages: () => Map<string, AggregatedMessage>;
+    /** Get a specific message by key */
+    getMessage: (nodeId: string, runIndex: number, itemIndex: number) => AggregatedMessage | undefined;
+    /** Clear all messages */
+    clear: () => void;
+}
+/**
+ * Creates a stateful chunk aggregator for multi-source streaming.
+ *
+ * @example
+ * ```typescript
+ * const aggregator = createChunkAggregator({
+ *   onBegin: async (message) => {
+ *     console.log(`Starting: ${message.nodeId}`);
+ *   },
+ *   onItem: async (message, delta) => {
+ *     sendToClient(delta);
+ *   },
+ *   onEnd: async (message) => {
+ *     await saveMessage(message);
+ *   }
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   await aggregator.ingest(chunk);
+ * }
+ * await aggregator.finalizeAll();
+ * ```
+ */
+export declare function createChunkAggregator(handlers?: ChunkHandlers): ChunkAggregator;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IACzC,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;IAC3C,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,EAAE,IAAI,CAAC;IAChB,uCAAuC;IACvC,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,oCAAoC;IACpC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/D,uCAAuC;IACvC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAClD,oCAAoC;IACpC,UAAU,EAAE,CACV,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,KACd,iBAAiB,GAAG,SAAS,CAAC;IACnC,yBAAyB;IACzB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,aAAkB,GAC3B,eAAe,CAqHjB"}

package/dist/aggregator.js

@@ -0,0 +1,127 @@
+/**
+ * Chunk Aggregation
+ * Aggregate streaming chunks from multiple sources with lifecycle handlers
+ */
+/**
+ * Creates a stateful chunk aggregator for multi-source streaming.
+ *
+ * @example
+ * ```typescript
+ * const aggregator = createChunkAggregator({
+ *   onBegin: async (message) => {
+ *     console.log(`Starting: ${message.nodeId}`);
+ *   },
+ *   onItem: async (message, delta) => {
+ *     sendToClient(delta);
+ *   },
+ *   onEnd: async (message) => {
+ *     await saveMessage(message);
+ *   }
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   await aggregator.ingest(chunk);
+ * }
+ * await aggregator.finalizeAll();
+ * ```
+ */
+export function createChunkAggregator(handlers = {}) {
+    const messages = new Map();
+    function getKey(chunk) {
+        return `${chunk.nodeId}:${chunk.runIndex}:${chunk.itemIndex}`;
+    }
+    async function ingest(chunk) {
+        const key = getKey(chunk);
+        switch (chunk.type) {
+            case 'begin': {
+                const message = {
+                    nodeId: chunk.nodeId,
+                    runIndex: chunk.runIndex,
+                    itemIndex: chunk.itemIndex,
+                    content: '',
+                    status: 'streaming',
+                    startedAt: new Date(),
+                };
+                messages.set(key, message);
+                await handlers.onBegin?.(message);
+                return message;
+            }
+            case 'item': {
+                let message = messages.get(key);
+                // Auto-create message if 'begin' was missed
+                if (!message) {
+                    message = {
+                        nodeId: chunk.nodeId,
+                        runIndex: chunk.runIndex,
+                        itemIndex: chunk.itemIndex,
+                        content: '',
+                        status: 'streaming',
+                        startedAt: new Date(),
+                    };
+                    messages.set(key, message);
+                    await handlers.onBegin?.(message);
+                }
+                if (chunk.data) {
+                    message.content += chunk.data;
+                    await handlers.onItem?.(message, chunk.data);
+                }
+                return message;
+            }
+            case 'end': {
+                const message = messages.get(key);
+                if (message) {
+                    message.status = 'complete';
+                    message.completedAt = new Date();
+                    await handlers.onEnd?.(message);
+                }
+                return message;
+            }
+            case 'error': {
+                let message = messages.get(key);
+                // Auto-create message if 'begin' was missed
+                if (!message) {
+                    message = {
+                        nodeId: chunk.nodeId,
+                        runIndex: chunk.runIndex,
+                        itemIndex: chunk.itemIndex,
+                        content: '',
+                        status: 'error',
+                        startedAt: new Date(),
+                    };
+                    messages.set(key, message);
+                }
+                message.status = 'error';
+                message.error = chunk.error;
+                message.completedAt = new Date();
+                await handlers.onError?.(message, chunk.error);
+                return message;
+            }
+        }
+    }
+    async function finalizeAll() {
+        for (const message of messages.values()) {
+            if (message.status === 'streaming') {
+                message.status = 'complete';
+                message.completedAt = new Date();
+                await handlers.onEnd?.(message);
+            }
+        }
+    }
+    function getMessages() {
+        return new Map(messages);
+    }
+    function getMessage(nodeId, runIndex, itemIndex) {
+        return messages.get(`${nodeId}:${runIndex}:${itemIndex}`);
+    }
+    function clear() {
+        messages.clear();
+    }
+    return {
+        ingest,
+        finalizeAll,
+        getMessages,
+        getMessage,
+        clear,
+    };
+}
+//# sourceMappingURL=aggregator.js.map

package/dist/aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.js","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @llm-utils/stream
+ * Streaming utilities for real-time LLM responses
+ */
+export { interceptResponseWrites } from './interceptor.js';
+export type { InterceptOptions, ChunkTransformer } from './interceptor.js';
+export { createChunkAggregator } from './aggregator.js';
+export type { StructuredChunk, AggregatedMessage, ChunkHandlers, ChunkAggregator, } from './aggregator.js';
+export { streamJsonLines, parseJsonLines, toJsonLine, fromJsonLine } from './jsonl.js';
+export type { JsonLineGenerator } from './jsonl.js';
+export { mux, muxSimple, parseCursor, serializeCursor, createCursor, createReplayableStream, mapEvents, filterEvents, accumulateDeltas, } from './mux.js';
+export type { StreamEvent, StreamCursor, MuxOptions, NamedStream, } from './mux.js';
+export { sse, jsonl, raw, streamToResponse, textStreamResponse, parseSSEResponse, parseJSONLResponse, streamToNodeResponse, createAIEvent, toEventStream, } from './response.js';
+export type { StreamProtocol, StreamResponseOptions, ProtocolEncoder, NodeServerResponse, } from './response.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvF,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,EACZ,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,GACZ,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,GAAG,EACH,KAAK,EACL,GAAG,EACH,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @llm-utils/stream
+ * Streaming utilities for real-time LLM responses
+ */
+// Response Interception
+export { interceptResponseWrites } from './interceptor.js';
+// Chunk Aggregation
+export { createChunkAggregator } from './aggregator.js';
+// JSONL Streaming
+export { streamJsonLines, parseJsonLines, toJsonLine, fromJsonLine } from './jsonl.js';
+// Stream Multiplexing
+export { mux, muxSimple, parseCursor, serializeCursor, createCursor, createReplayableStream, mapEvents, filterEvents, accumulateDeltas, } from './mux.js';
+// HTTP Response Utilities
+export { sse, jsonl, raw, streamToResponse, textStreamResponse, parseSSEResponse, parseJSONLResponse, streamToNodeResponse, createAIEvent, toEventStream, } from './response.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAwB;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,oBAAoB;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAQxD,kBAAkB;AAClB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGvF,sBAAsB;AACtB,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,EACZ,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAQlB,0BAA0B;AAC1B,OAAO,EACL,GAAG,EACH,KAAK,EACL,GAAG,EACH,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC"}

package/dist/interceptor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * HTTP Response Interception
+ * Transform streaming responses without breaking HTTP semantics
+ */
+import type { ServerResponse } from 'node:http';
+/**
+ * Transform function for stream chunks
+ * Return undefined to skip the chunk
+ */
+export type ChunkTransformer = (text: string) => Promise<string | undefined>;
+/**
+ * Options for response interception
+ */
+export interface InterceptOptions {
+    /** Transform each chunk before sending */
+    transform: ChunkTransformer;
+    /** Called when stream finishes */
+    onFinish?: () => Promise<void>;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Intercepts HTTP response writes for transformation.
+ * Preserves Express/Node response API compatibility.
+ *
+ * @example
+ * ```typescript
+ * interceptResponseWrites(res, {
+ *   transform: async (chunk) => {
+ *     const data = JSON.parse(chunk);
+ *     return JSON.stringify({ ...data, timestamp: Date.now() }) + '\n';
+ *   },
+ *   onFinish: async () => {
+ *     await saveConversation();
+ *   }
+ * });
+ * ```
+ */
+export declare function interceptResponseWrites<T extends ServerResponse>(res: T, options: InterceptOptions): T;
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,SAAS,EAAE,gBAAgB,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,cAAc,EAC9D,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,gBAAgB,GACxB,CAAC,CAgGH"}

package/dist/interceptor.js

@@ -0,0 +1,94 @@
+/**
+ * HTTP Response Interception
+ * Transform streaming responses without breaking HTTP semantics
+ */
+/**
+ * Intercepts HTTP response writes for transformation.
+ * Preserves Express/Node response API compatibility.
+ *
+ * @example
+ * ```typescript
+ * interceptResponseWrites(res, {
+ *   transform: async (chunk) => {
+ *     const data = JSON.parse(chunk);
+ *     return JSON.stringify({ ...data, timestamp: Date.now() }) + '\n';
+ *   },
+ *   onFinish: async () => {
+ *     await saveConversation();
+ *   }
+ * });
+ * ```
+ */
+export function interceptResponseWrites(res, options) {
+    const { transform, onFinish, onError } = options;
+    // Store original methods
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    // Buffer for incomplete chunks
+    let buffer = '';
+    // Override write
+    res.write = function (chunk, encodingOrCallback, callback) {
+        const encoding = typeof encodingOrCallback === 'string' ? encodingOrCallback : 'utf8';
+        const cb = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        const text = typeof chunk === 'string' ? chunk : chunk.toString(encoding);
+        buffer += text;
+        // Process complete lines
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line in buffer
+        // Process each complete line
+        (async () => {
+            try {
+                for (const line of lines) {
+                    if (line.trim()) {
+                        const transformed = await transform(line);
+                        if (transformed !== undefined) {
+                            originalWrite(transformed + '\n', encoding);
+                        }
+                    }
+                }
+                cb?.(null);
+            }
+            catch (error) {
+                onError?.(error);
+                cb?.(error);
+            }
+        })();
+        return true;
+    };
+    // Override end
+    res.end = function (chunkOrCallback, encodingOrCallback, callback) {
+        const chunk = typeof chunkOrCallback === 'function' ? undefined : chunkOrCallback;
+        const cb = typeof chunkOrCallback === 'function'
+            ? chunkOrCallback
+            : typeof encodingOrCallback === 'function'
+                ? encodingOrCallback
+                : callback;
+        (async () => {
+            try {
+                // Process any remaining chunk
+                if (chunk) {
+                    const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+                    buffer += text;
+                }
+                // Process remaining buffer
+                if (buffer.trim()) {
+                    const transformed = await transform(buffer);
+                    if (transformed !== undefined) {
+                        originalWrite(transformed);
+                    }
+                }
+                // Call finish handler
+                await onFinish?.();
+                // End the response
+                originalEnd(cb);
+            }
+            catch (error) {
+                onError?.(error);
+                originalEnd(cb);
+            }
+        })();
+        return res;
+    };
+    return res;
+}
+//# sourceMappingURL=interceptor.js.map

package/dist/interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.js","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"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"}

package/dist/jsonl.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JSONL Streaming
+ * Parse and serialize JSONL (JSON Lines) streams
+ */
+/**
+ * Generator function that yields objects to stream as JSONL
+ */
+export type JsonLineGenerator<T> = () => AsyncIterable<T>;
+/**
+ * A minimal Response-like interface for parsing JSONL
+ */
+interface ReadableResponse {
+    body: ReadableStream<Uint8Array> | null;
+}
+/**
+ * A minimal ServerResponse-like interface for streaming JSONL
+ */
+interface WritableResponse {
+    setHeader(name: string, value: string): void;
+    write(chunk: string): boolean;
+    end(): void;
+}
+/**
+ * Streams objects as JSONL (JSON Lines) to an HTTP response.
+ *
+ * @example
+ * ```typescript
+ * app.get('/events', (req, res) => {
+ *   streamJsonLines(res, async function* () {
+ *     for (const event of events) {
+ *       yield event;
+ *     }
+ *   });
+ * });
+ * ```
+ */
+export declare function streamJsonLines<T>(res: WritableResponse, generator: JsonLineGenerator<T>): void;
+/**
+ * Parses a JSONL stream from a fetch Response.
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/events');
+ * for await (const event of parseJsonLines(response)) {
+ *   handleEvent(event);
+ * }
+ * ```
+ */
+export declare function parseJsonLines<T = unknown>(response: ReadableResponse): AsyncGenerator<T, void, unknown>;
+/**
+ * Serializes an object to a JSONL line
+ */
+export declare function toJsonLine<T>(obj: T): string;
+/**
+ * Parses a single JSONL line
+ */
+export declare function fromJsonLine<T>(line: string): T;
+export {};
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../src/jsonl.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC;AAE1D;;GAEG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;CACzC;AAED;;GAEG;AACH,UAAU,gBAAgB;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,GAAG,IAAI,IAAI,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAgBN;AAED;;;;;;;;;;GAUG;AACH,wBAAuB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC/C,QAAQ,EAAE,gBAAgB,GACzB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAgDlC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAE/C"}