rouzer 5.2.0 → 5.2.2

package/README.md

@@ -237,6 +237,12 @@ for await (const event of await client.events()) {
 }
 ```
 
+If a client aborts the request signal or stops iteration early by breaking from
+`for await` or calling the iterator's `return()`, Rouzer cancels the response
+body and calls the server source iterator's `return()`. Sources that wait for
+future events should make those waits abort-aware when they need cleanup to run
+while an awaited operation is still pending.
+
 ## Documentation
 
 - [Concepts, API selection, v5 client input notes, and migration notes](docs/context.md)

package/dist/ndjson.d.ts

@@ -2,6 +2,11 @@ import { type ClientResponsePlugin, type ResponsePluginMarker, type RouterRespon
 declare const codecId = "rouzer/ndjson";
 /** Values accepted by Rouzer's NDJSON response encoder. */
 export type NdjsonSource<T = unknown> = Iterable<T> | AsyncIterable<T>;
+/** Options for Rouzer's NDJSON response encoder. */
+export type NdjsonEncodeOptions = {
+    /** Signal whose abort cancels the source iterator and closes the stream. */
+    signal?: AbortSignal;
+};
 /**
  * Create a compile-time marker for newline-delimited JSON response items.
  *
@@ -32,9 +37,11 @@ export declare const routerPlugin: RouterResponsePlugin;
  *
  * @remarks Each yielded value is serialized with `JSON.stringify` and followed
  * by `\n`. Values that cannot be represented as a JSON text, such as
- * `undefined`, cause the stream to error when read.
+ * `undefined`, cause the stream to error when read. When `options.signal`
+ * aborts, the source iterator's `return()` method is called and the stream is
+ * closed.
  */
-export declare function encodeNdjson(source: NdjsonSource): ReadableStream<Uint8Array>;
+export declare function encodeNdjson(source: NdjsonSource, options?: NdjsonEncodeOptions): ReadableStream<Uint8Array>;
 /**
  * Decode a newline-delimited JSON byte stream.
  *
@@ -50,5 +57,5 @@ export declare function decodeNdjson<T = unknown>(stream: ReadableStream<Uint8Ar
  * `content-type: application/x-ndjson; charset=utf-8` unless the caller supplies
  * a content type in `init.headers`.
  */
-export declare function ndjsonResponse<T>(source: NdjsonSource<T>, init?: ResponseInit): Response;
+export declare function ndjsonResponse<T>(source: NdjsonSource<T>, { signal, ...init }?: ResponseInit & NdjsonEncodeOptions): Response;
 export {};

package/dist/ndjson.js

@@ -36,8 +36,10 @@ export const clientPlugin = {
  */
 export const routerPlugin = {
     id: codecId,
-    encode(value) {
-        return ndjsonResponse(value);
+    encode(value, { request }) {
+        return ndjsonResponse(value, {
+            signal: request.signal,
+        });
     },
 };
 /**
@@ -45,28 +47,12 @@ export const routerPlugin = {
  *
  * @remarks Each yielded value is serialized with `JSON.stringify` and followed
  * by `\n`. Values that cannot be represented as a JSON text, such as
- * `undefined`, cause the stream to error when read.
+ * `undefined`, cause the stream to error when read. When `options.signal`
+ * aborts, the source iterator's `return()` method is called and the stream is
+ * closed.
  */
-export function encodeNdjson(source) {
-    const iterator = getAsyncIterator(source);
-    const encoder = new TextEncoder();
-    return new ReadableStream({
-        async pull(controller) {
-            const { done, value } = await iterator.next();
-            if (done) {
-                controller.close();
-                return;
-            }
-            const line = JSON.stringify(value);
-            if (line === undefined) {
-                throw new TypeError('NDJSON items must serialize to a JSON text; received undefined');
-            }
-            controller.enqueue(encoder.encode(`${line}\n`));
-        },
-        async cancel(reason) {
-            await iterator.return?.(reason);
-        },
-    });
+export function encodeNdjson(source, options = {}) {
+    return new ReadableStream(new NdjsonEncoder(source, options));
 }
 /**
  * Decode a newline-delimited JSON byte stream.
@@ -75,39 +61,175 @@ export function encodeNdjson(source) {
  * are accepted, and a final line does not need a trailing newline. Malformed
  * lines throw a `SyntaxError` that includes the 1-based line number.
  */
-export async function* decodeNdjson(stream) {
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-    let lineNumber = 0;
-    let doneReading = false;
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-                buffer += decoder.decode();
-                doneReading = true;
-                break;
+export function decodeNdjson(stream) {
+    return new NdjsonDecoder(stream);
+}
+class NdjsonEncoder {
+    options;
+    iterator;
+    encoder = new TextEncoder();
+    cancelled = false;
+    cleanup;
+    abortHandler;
+    constructor(source, options) {
+        this.options = options;
+        this.iterator = getAsyncIterator(source);
+    }
+    start(controller) {
+        const { signal } = this.options;
+        if (signal) {
+            this.abortHandler = () => {
+                void this.cancel(signal.reason).catch(() => { });
+                try {
+                    controller.close();
+                }
+                catch { }
+            };
+            if (signal.aborted) {
+                this.abortHandler();
             }
-            buffer += decoder.decode(value, { stream: true });
-            let newlineIndex;
-            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
-                const line = stripCarriageReturn(buffer.slice(0, newlineIndex));
-                buffer = buffer.slice(newlineIndex + 1);
-                lineNumber += 1;
-                yield parseNdjsonLine(line, lineNumber);
+            else {
+                signal.addEventListener('abort', this.abortHandler, { once: true });
             }
         }
-        if (buffer.length > 0) {
-            lineNumber += 1;
-            yield parseNdjsonLine(stripCarriageReturn(buffer), lineNumber);
+    }
+    async pull(controller) {
+        if (this.cancelled) {
+            controller.close();
+            return;
+        }
+        const { done, value } = await this.iterator.next();
+        if (this.cancelled) {
+            return;
+        }
+        if (done) {
+            this.removeAbortHandler();
+            controller.close();
+            return;
+        }
+        const line = JSON.stringify(value);
+        if (line === undefined) {
+            throw new TypeError('NDJSON items must serialize to a JSON text; received undefined');
+        }
+        controller.enqueue(this.encoder.encode(`${line}\n`));
+    }
+    async cancel(reason) {
+        if (!this.cancelled) {
+            this.cancelled = true;
+            this.removeAbortHandler();
+            this.cleanup ??= Promise.resolve(this.iterator.return?.(reason)).then(() => { });
+        }
+        await this.cleanup;
+    }
+    removeAbortHandler() {
+        const { signal } = this.options;
+        if (signal && this.abortHandler) {
+            signal.removeEventListener('abort', this.abortHandler);
+            this.abortHandler = undefined;
+        }
+    }
+}
+class NdjsonDecoder {
+    reader;
+    decoder = new TextDecoder();
+    buffer = '';
+    lineNumber = 0;
+    closed = false;
+    doneReading = false;
+    readerReleased = false;
+    constructor(stream) {
+        this.reader = stream.getReader();
+    }
+    [Symbol.asyncIterator]() {
+        return new NdjsonAsyncIterator(this);
+    }
+    releaseReader() {
+        if (!this.readerReleased) {
+            this.readerReleased = true;
+            this.reader.releaseLock();
+        }
+    }
+    async cancelReader(reason) {
+        if (!this.doneReading) {
+            await this.reader.cancel(reason).catch(() => { });
         }
+        this.releaseReader();
     }
-    finally {
-        if (!doneReading) {
-            await reader.cancel().catch(() => { });
+    async parseNextLine(line) {
+        try {
+            this.lineNumber += 1;
+            return {
+                done: false,
+                value: parseNdjsonLine(stripCarriageReturn(line), this.lineNumber),
+            };
+        }
+        catch (error) {
+            this.closed = true;
+            await this.cancelReader(error);
+            throw error;
         }
-        reader.releaseLock();
+    }
+}
+class NdjsonAsyncIterator {
+    decoder;
+    closed = false;
+    constructor(decoder) {
+        this.decoder = decoder;
+    }
+    async next() {
+        if (this.closed || this.decoder.closed) {
+            return { done: true, value: undefined };
+        }
+        while (true) {
+            const newlineIndex = this.decoder.buffer.indexOf('\n');
+            if (newlineIndex !== -1) {
+                const line = this.decoder.buffer.slice(0, newlineIndex);
+                this.decoder.buffer = this.decoder.buffer.slice(newlineIndex + 1);
+                return this.decoder.parseNextLine(line);
+            }
+            if (this.decoder.doneReading) {
+                this.close();
+                this.decoder.releaseReader();
+                if (this.decoder.buffer.length > 0) {
+                    const line = this.decoder.buffer;
+                    this.decoder.buffer = '';
+                    return this.decoder.parseNextLine(line);
+                }
+                return { done: true, value: undefined };
+            }
+            let chunk;
+            try {
+                chunk = await this.decoder.reader.read();
+            }
+            catch (error) {
+                this.close();
+                this.decoder.releaseReader();
+                throw error;
+            }
+            if (this.closed || this.decoder.closed) {
+                return { done: true, value: undefined };
+            }
+            if (chunk.done) {
+                this.decoder.buffer += this.decoder.decoder.decode();
+                this.decoder.doneReading = true;
+            }
+            else {
+                this.decoder.buffer += this.decoder.decoder.decode(chunk.value, {
+                    stream: true,
+                });
+            }
+        }
+    }
+    async return(reason) {
+        if (!this.closed) {
+            this.close();
+            await this.decoder.cancelReader(reason);
+        }
+        return { done: true, value: undefined };
+    }
+    close() {
+        this.closed = true;
+        this.decoder.closed = true;
     }
 }
 /**
@@ -117,31 +239,28 @@ export async function* decodeNdjson(stream) {
  * `content-type: application/x-ndjson; charset=utf-8` unless the caller supplies
  * a content type in `init.headers`.
  */
-export function ndjsonResponse(source, init = {}) {
+export function ndjsonResponse(source, { signal, ...init } = {}) {
     const headers = new Headers(init.headers);
     if (!headers.has('content-type')) {
         headers.set('content-type', 'application/x-ndjson; charset=utf-8');
     }
-    return new Response(encodeNdjson(source), {
+    return new Response(encodeNdjson(source, { signal }), {
         ...init,
         headers,
     });
 }
 function getAsyncIterator(source) {
-    const asyncIterator = source[Symbol.asyncIterator]?.();
-    if (asyncIterator) {
-        return asyncIterator;
+    if (Symbol.asyncIterator in source) {
+        return source[Symbol.asyncIterator]();
     }
-    const iterator = source[Symbol.iterator]?.();
-    if (iterator) {
+    if (Symbol.iterator in source) {
+        const iterator = source[Symbol.iterator]();
         return {
-            next() {
-                return Promise.resolve(iterator.next());
-            },
-            async return() {
-                iterator.return?.();
-                return { done: true, value: undefined };
-            },
+            next: async (value) => iterator.next(value),
+            return: iterator.return
+                ? async (value) => iterator.return(value)
+                : undefined,
+            throw: iterator.throw ? async (error) => iterator.throw(error) : undefined,
         };
     }
     throw new TypeError('NDJSON source must be iterable');

package/docs/context.md

@@ -424,6 +424,12 @@ Rouzer's decoder accepts `\n` and `\r\n`, handles UTF-8 chunk boundaries, and
 throws a `SyntaxError` with a line number for malformed JSON. If a consumer stops
 reading early, the response body is cancelled.
 
+If a client aborts the request signal or stops iteration early by breaking from
+`for await` or calling the iterator's `return()`, Rouzer cancels the response
+body and calls the server source iterator's `return()`. Sources that wait for
+future events should make those waits abort-aware when they need cleanup to run
+while an awaited operation is still pending.
+
 Rouzer does not convert handler or generator failures into extra NDJSON items. If
 an async generator throws after the response starts, the response stream errors
 and the client's `for await` loop throws. Model application-level stream errors

package/examples/ndjson-stream.ts

@@ -2,17 +2,34 @@ import type { HattipHandler } from '@hattip/core'
 import { createClient, createRouter } from 'rouzer'
 import * as http from 'rouzer/http'
 import * as ndjson from 'rouzer/ndjson'
+import { z } from 'zod'
 
 type Event = {
   id: number
   message: string
 }
 
+const EventFilter = z.object({
+  names: z.array(z.string()),
+  where: z.array(
+    z.object({
+      path: z.string(),
+      equals: z.string(),
+    })
+  ),
+})
+
 export const events = http.get('events', {
   response: ndjson.$type<Event>(),
 })
 
-export const routes = { events }
+// NDJSON responses work for POST routes with ordinary JSON body schemas too.
+export const stream = http.post('events/stream', {
+  body: EventFilter,
+  response: ndjson.$type<Event>(),
+})
+
+export const routes = { events, stream }
 
 /**
  * Tiny Hattip adapter used only to keep this example self-contained. Real apps
@@ -46,6 +63,17 @@ async function collect<T>(source: AsyncIterable<T>) {
   return values
 }
 
+async function readFirst<T>(source: AsyncIterable<T>) {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    return (await iterator.next()).value
+  } finally {
+    // Closing the client iterator cancels the response body. For Rouzer NDJSON
+    // routes, that cancellation reaches the server source iterator's return().
+    await iterator.return?.()
+  }
+}
+
 export async function runNdjsonStreamExample() {
   const handler = createRouter({
     basePath: 'api/',
@@ -55,6 +83,14 @@ export async function runNdjsonStreamExample() {
       yield { id: 1, message: 'ready' }
       yield { id: 2, message: 'done' }
     },
+    async *stream({ body }) {
+      // The POST body was parsed and validated before the stream starts.
+      yield {
+        id: 1,
+        message: `${body.names[0]} for ${body.where[0]?.equals}`,
+      }
+      yield { id: 2, message: 'done' }
+    },
   })
 
   const client = createClient({
@@ -64,5 +100,16 @@ export async function runNdjsonStreamExample() {
     fetch: createLocalFetch(handler),
   })
 
-  return collect(await client.events())
+  const allEvents = await collect(await client.events())
+
+  // This call sends a JSON body, receives an AsyncIterable, and then stops after
+  // one event. Request signals can also be used to cancel long-lived streams.
+  const firstMatchingEvent = await readFirst(
+    await client.stream({
+      names: ['session.message'],
+      where: [{ path: 'id', equals: 'ses_123' }],
+    })
+  )
+
+  return { allEvents, firstMatchingEvent }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "5.2.0",
+  "version": "5.2.2",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@hattip/core": "^0.0.49",
-    "@remix-run/route-pattern": "^0.21.1",
+    "@remix-run/route-pattern": "^0.22.1",
     "alien-middleware": "^0.11.6"
   },
   "prettier": "@alloc/prettier-config",