Stream hooks

Start and cancel typed generic streams without treating them as finite queries.

Use a stream hook to receive a sequence of updates and cancel it when the reader no longer needs them.

Start a stream

useStream exposes start, cancel, and reset. Query-classified streams may opt into autoStart; mutation streams always require an explicit start. Classification controls start/retry policy only. It does not make a stream a finite cache query.

The low-level client returns a single-consumer AsyncIterable. Work starts on the first next(), and breaking iteration cancels upstream work and releases its pinned invocation generation.

Use the typed hook

"use client";

/** Consumes the commerce report route as a cancellable typed stream inside the client provider. */
import { useRelkitClient, useStream } from "@relkit/client/react";

/** Starts one report explicitly and displays its validated progress items.
 * @returns Start/cancel controls and visible progress or stream failure. */
export function Report() {
  const { status } = useRelkitClient();
  const report = useStream("GET /reports/:reportId");

  return (
    <section>
      <button
        disabled={status !== "ready"}
        onClick={() => void report.start({ reportId: "daily" })}
      >
        Run report
      </button>
      <button onClick={() => report.cancel()}>Cancel report</button>
      <p role="status">Completed: {report.items.map((item) => item.completed).join(", ")}</p>
      {report.error && <p role="alert">{String(report.error)}</p>}
    </section>
  );
}

This selector belongs to the commerce streaming route. Its streamOf item schema determines report.items, so do not copy a stream selector into an app that has not declared that route and pulled its contract.

Use useAgent for durable agent threads, useJobRun for accepted jobs, and useChannel for shared application updates. Those have separate identity and recovery contracts. Reference: useStream.