Merge pull request #1 from malcolm-kee/claude/validate-sse-example-FIuJh

Improve examples

Author: malcolm-kee

docs/openapi-ts/clients/angular.md

@@ -210,13 +210,79 @@ When your OpenAPI spec defines endpoints with `text/event-stream` responses, the
 
 ### Consuming a stream
 
-```js
+Create a service to manage the SSE connection and expose state via signals.
+
+```ts
+import { Injectable, signal } from '@angular/core';
 import { watchStockPrices } from './client/sdk.gen';
+import type { StockUpdate } from './client/types.gen';
+
+@Injectable({ providedIn: 'root' })
+export class StockService {
+  readonly updates = signal<StockUpdate[]>([]);
+  readonly status = signal<'connected' | 'disconnected' | 'error'>('disconnected');
+
+  #controller: AbortController | null = null;
+
+  async connect() {
+    this.#controller = new AbortController();
+    this.status.set('connected');
+    this.updates.set([]);
+
+    try {
+      const { stream } = await watchStockPrices({
+        signal: this.#controller.signal,
+      });
+
+      for await (const event of stream) {
+        this.updates.update((prev) => [...prev, event]);
+      }
+    } catch {
+      if (!this.#controller?.signal.aborted) {
+        this.status.set('error');
+        return;
+      }
+    }
+    this.status.set('disconnected');
+  }
+
+  disconnect() {
+    this.#controller?.abort();
+    this.#controller = null;
+    this.status.set('disconnected');
+  }
+}
+```
 
-const { stream } = await watchStockPrices();
+Then inject the service in your component and clean up on destroy.
 
-for await (const event of stream) {
-  console.log(event);
+```ts
+import { Component, inject, OnDestroy } from '@angular/core';
+import { StockService } from './stock.service';
+
+@Component({
+  selector: 'app-stock-ticker',
+  template: `
+    <button (click)="connect()">Connect</button>
+    <button (click)="stockService.disconnect()">Disconnect</button>
+    <p>Status: {{ stockService.status() }}</p>
+    <ul>
+      @for (update of stockService.updates(); track $index) {
+        <li>{{ update | json }}</li>
+      }
+    </ul>
+  `,
+})
+export class StockTickerComponent implements OnDestroy {
+  stockService = inject(StockService);
+
+  connect() {
+    this.stockService.connect();
+  }
+
+  ngOnDestroy() {
+    this.stockService.disconnect();
+  }
 }
 ```
 
@@ -262,6 +328,41 @@ const { stream } = await watchStockPrices({
 });
 ```
 
+### RxJS alternative
+
+If your codebase uses RxJS pipelines, you can wrap the async generator in an Observable.
+
+```ts
+import { Observable } from 'rxjs';
+import { watchStockPrices } from './client/sdk.gen';
+import type { StockUpdate } from './client/types.gen';
+
+function watchPrices$(): Observable<StockUpdate> {
+  return new Observable((subscriber) => {
+    const controller = new AbortController();
+
+    (async () => {
+      try {
+        const { stream } = await watchStockPrices({
+          signal: controller.signal,
+        });
+
+        for await (const event of stream) {
+          subscriber.next(event);
+        }
+        subscriber.complete();
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          subscriber.error(error);
+        }
+      }
+    })();
+
+    return () => controller.abort();
+  });
+}
+```
+
 ::: warning
 Angular `HttpClient` interceptors do not apply to SSE connections. The SSE client uses the native Fetch API under the hood.
 :::

docs/openapi-ts/clients/angular/v19.md

@@ -210,13 +210,79 @@ When your OpenAPI spec defines endpoints with `text/event-stream` responses, the
 
 ### Consuming a stream
 
-```js
+Create a service to manage the SSE connection and expose state via signals.
+
+```ts
+import { Injectable, signal } from '@angular/core';
 import { watchStockPrices } from './client/sdk.gen';
+import type { StockUpdate } from './client/types.gen';
+
+@Injectable({ providedIn: 'root' })
+export class StockService {
+  readonly updates = signal<StockUpdate[]>([]);
+  readonly status = signal<'connected' | 'disconnected' | 'error'>('disconnected');
+
+  #controller: AbortController | null = null;
+
+  async connect() {
+    this.#controller = new AbortController();
+    this.status.set('connected');
+    this.updates.set([]);
+
+    try {
+      const { stream } = await watchStockPrices({
+        signal: this.#controller.signal,
+      });
+
+      for await (const event of stream) {
+        this.updates.update((prev) => [...prev, event]);
+      }
+    } catch {
+      if (!this.#controller?.signal.aborted) {
+        this.status.set('error');
+        return;
+      }
+    }
+    this.status.set('disconnected');
+  }
+
+  disconnect() {
+    this.#controller?.abort();
+    this.#controller = null;
+    this.status.set('disconnected');
+  }
+}
+```
 
-const { stream } = await watchStockPrices();
+Then inject the service in your component and clean up on destroy.
 
-for await (const event of stream) {
-  console.log(event);
+```ts
+import { Component, inject, OnDestroy } from '@angular/core';
+import { StockService } from './stock.service';
+
+@Component({
+  selector: 'app-stock-ticker',
+  template: `
+    <button (click)="connect()">Connect</button>
+    <button (click)="stockService.disconnect()">Disconnect</button>
+    <p>Status: {{ stockService.status() }}</p>
+    <ul>
+      @for (update of stockService.updates(); track $index) {
+        <li>{{ update | json }}</li>
+      }
+    </ul>
+  `,
+})
+export class StockTickerComponent implements OnDestroy {
+  stockService = inject(StockService);
+
+  connect() {
+    this.stockService.connect();
+  }
+
+  ngOnDestroy() {
+    this.stockService.disconnect();
+  }
 }
 ```
 
@@ -262,6 +328,41 @@ const { stream } = await watchStockPrices({
 });
 ```
 
+### RxJS alternative
+
+If your codebase uses RxJS pipelines, you can wrap the async generator in an Observable.
+
+```ts
+import { Observable } from 'rxjs';
+import { watchStockPrices } from './client/sdk.gen';
+import type { StockUpdate } from './client/types.gen';
+
+function watchPrices$(): Observable<StockUpdate> {
+  return new Observable((subscriber) => {
+    const controller = new AbortController();
+
+    (async () => {
+      try {
+        const { stream } = await watchStockPrices({
+          signal: controller.signal,
+        });
+
+        for await (const event of stream) {
+          subscriber.next(event);
+        }
+        subscriber.complete();
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          subscriber.error(error);
+        }
+      }
+    })();
+
+    return () => controller.abort();
+  });
+}
+```
+
 ::: warning
 Angular `HttpClient` interceptors do not apply to SSE connections. The SSE client uses the native Fetch API under the hood.
 :::

docs/openapi-ts/clients/next-js.md

@@ -251,13 +251,54 @@ When your OpenAPI spec defines endpoints with `text/event-stream` responses, the
 
 ### Consuming a stream
 
-```js
+SSE requires a client component since it uses browser APIs and React hooks.
+
+```tsx
+'use client';
+
+import { useRef, useState } from 'react';
 import { watchStockPrices } from './client/sdk.gen';
+import type { StockUpdate } from './client/types.gen';
+
+export function StockTicker() {
+  const [updates, setUpdates] = useState<StockUpdate[]>([]);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  const connect = async () => {
+    const controller = new AbortController();
+    controllerRef.current = controller;
+
+    try {
+      const { stream } = await watchStockPrices({
+        signal: controller.signal,
+      });
+
+      for await (const event of stream) {
+        setUpdates((prev) => [...prev, event]);
+      }
+    } catch {
+      if (!controller.signal.aborted) {
+        console.error('Stream failed');
+      }
+    }
+  };
 
-const { stream } = await watchStockPrices();
+  const disconnect = () => {
+    controllerRef.current?.abort();
+    controllerRef.current = null;
+  };
 
-for await (const event of stream) {
-  console.log(event);
+  return (
+    <>
+      <button onClick={connect}>Connect</button>
+      <button onClick={disconnect}>Disconnect</button>
+      <ul>
+        {updates.map((u, i) => (
+          <li key={i}>{JSON.stringify(u)}</li>
+        ))}
+      </ul>
+    </>
+  );
 }
 ```
 
@@ -303,6 +344,73 @@ const { stream } = await watchStockPrices({
 });
 ```
 
+### Custom hook factory
+
+You can create a reusable factory that wraps any SSE SDK function into a React hook.
+
+```tsx
+'use client';
+
+import { useCallback, useRef, useState } from 'react';
+
+export function createUseSse<
+  TFn extends (...args: any[]) => Promise<{ stream: AsyncGenerator<any> }>,
+>(sseFn: TFn) {
+  type TEvent = Awaited<ReturnType<TFn>> extends { stream: AsyncGenerator<infer E> } ? E : never;
+  type TOptions = Parameters<TFn>[0];
+
+  return function useSse() {
+    const [events, setEvents] = useState<TEvent[]>([]);
+    const [status, setStatus] = useState<'connected' | 'disconnected' | 'error'>('disconnected');
+    const controllerRef = useRef<AbortController | null>(null);
+
+    const connect = useCallback(async (options?: Omit<TOptions, 'signal'>) => {
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      setStatus('connected');
+      setEvents([]);
+
+      try {
+        const { stream } = await sseFn({
+          ...options,
+          signal: controller.signal,
+        } as TOptions);
+
+        for await (const event of stream) {
+          setEvents((prev) => [...prev, event as TEvent]);
+        }
+      } catch {
+        if (!controller.signal.aborted) {
+          setStatus('error');
+          return;
+        }
+      }
+      setStatus('disconnected');
+    }, []);
+
+    const disconnect = useCallback(() => {
+      controllerRef.current?.abort();
+      controllerRef.current = null;
+      setStatus('disconnected');
+    }, []);
+
+    return { connect, disconnect, events, status };
+  };
+}
+```
+
+```tsx
+import { watchStockPrices } from './client/sdk.gen';
+import { createUseSse } from './hooks/createUseSse';
+
+const useStockPrices = createUseSse(watchStockPrices);
+
+function StockTicker() {
+  const { events, status, connect, disconnect } = useStockPrices();
+  // ...
+}
+```
+
 ::: tip
 Request interceptors registered through `client.interceptors.request` apply to SSE connections, including on each reconnect attempt.
 :::