@mui/internal-docs-infra/useStream/useStream.d.mts

MUI Infra - internal documentation creation tools.

import * as React from 'react';
import type { StreamSource } from "./types.mjs";
/** Options for {@link useStream}. */
export interface UseStreamOptions<P, O> {
  /**
   * The source that produces the chunk list, by `mode`: `urls` resolves the
   * chunk URLs then loads each, `stream` pushes chunks over time, `data` yields
   * a single chunk. Streamed snapshots accumulate into `chunks`.
   */
  source: StreamSource<P, O>;
  /** Options passed to the source loaders. */
  loaderOptions?: O;
  /** Coordination channel forwarded to the owned controller. */
  channelKey?: string | null;
  /**
   * Opt into stale-while-revalidate: once the list has finished streaming,
   * automatically {@link UseStreamResult.refresh} it once on the first idle
   * period (via `requestIdleCallback`). Client-only; the current list stays
   * visible while the background re-stream runs.
   */
  revalidateOnIdle?: boolean;
}
/** Result of {@link useStream}. */
export interface UseStreamResult<P> {
  /** The chunks loaded so far, accumulating as they stream in. */
  chunks: P[];
  /** Controller provider that scopes the rendered chunks' coordination. */
  Controller: React.ComponentType<{
    children: React.ReactNode;
  }>;
  /** `true` until the list has finished streaming and every chunk has settled. */
  loading: boolean;
  /** `true` once the list has finished streaming (the last chunk arrived). */
  streamComplete: boolean;
  /** `true` while a background re-stream (revalidation) is in flight; the current list stays. */
  revalidating: boolean;
  /**
   * Re-stream the list in the background and swap the fresh list in atomically
   * once it completes, keeping the current list visible meanwhile
   * (stale-while-revalidate). Aborts any prior in-flight refresh.
   */
  refresh: () => void;
}
/**
 * Stream a list of chunks on the client and own a `StreamController` that scopes
 * their coordination. Render the returned `chunks` as chunk components inside
 * the returned `Controller`; each chunk registers its swap with the controller,
 * and the list's completion (`markLast`) plus those swaps drive `loading`.
 *
 * The controller runs in `streaming` mode, so it stays `loading` until the list
 * finishes streaming - at which point the chunks present can settle it.
 *
 * `refresh()` (and the opt-in `revalidateOnIdle`) re-stream the list in the
 * background and swap the result in atomically when it completes, without a
 * loading flash — the current list stays visible the whole time.
 */
export declare function useStream<P, O>(options: UseStreamOptions<P, O>): UseStreamResult<P>;