@trigger.dev/react-hooks 0.0.0-bun-runtimes-20260909131057

package/dist/esm/hooks/useRealtime.d.ts

@@ -0,0 +1,336 @@
+import type { AnyTask, InferStreamType, RealtimeDefinedStream, RealtimeRun, RealtimeRunSkipColumns, SSEStreamPart } from "@trigger.dev/core/v3";
+import type { UseApiClientOptions } from "./useApiClient.js";
+export type UseRealtimeRunOptions = UseApiClientOptions & {
+    id?: string;
+    enabled?: boolean;
+    /**
+     * The number of milliseconds to throttle the stream updates.
+     *
+     * @default 16
+     */
+    throttleInMs?: number;
+};
+export type UseRealtimeSingleRunOptions<TTask extends AnyTask = AnyTask> = UseRealtimeRunOptions & {
+    /**
+     * Callback this is called when the run completes, an error occurs, or the subscription is stopped.
+     *
+     * @param {RealtimeRun<TTask>} run - The run object
+     * @param {Error} [err] - The error that occurred
+     */
+    onComplete?: (run: RealtimeRun<TTask>, err?: Error) => void;
+    /**
+     * Whether to stop the subscription when the run completes
+     *
+     * @default true
+     *
+     * Set this to false if you are making updates to the run metadata after completion through child runs
+     */
+    stopOnCompletion?: boolean;
+    /**
+     * Skip columns from the subscription.
+     *
+     * @default []
+     */
+    skipColumns?: RealtimeRunSkipColumns;
+};
+export type UseRealtimeRunInstance<TTask extends AnyTask = AnyTask> = {
+    run: RealtimeRun<TTask> | undefined;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately.
+     */
+    stop: () => void;
+};
+/**
+ * Hook to subscribe to realtime updates of a task run.
+ *
+ * @template TTask - The type of the task
+ * @param {string} [runId] - The unique identifier of the run to subscribe to
+ * @param {UseRealtimeSingleRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunInstance<TTask>} An object containing the current state of the run, error handling, and control methods
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { run, error } = useRealtimeRun<typeof myTask>('run-id-123');
+ * ```
+ */
+export declare function useRealtimeRun<TTask extends AnyTask>(runId?: string, options?: UseRealtimeSingleRunOptions<TTask>): UseRealtimeRunInstance<TTask>;
+export type StreamResults<TStreams extends Record<string, any>> = {
+    [K in keyof TStreams]: Array<TStreams[K]>;
+};
+export type UseRealtimeRunWithStreamsInstance<TTask extends AnyTask = AnyTask, TStreams extends Record<string, any> = Record<string, any>> = {
+    run: RealtimeRun<TTask> | undefined;
+    streams: StreamResults<TStreams>;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately, keep the generated tokens if any.
+     */
+    stop: () => void;
+};
+/**
+ * Hook to subscribe to realtime updates of a task run with associated data streams.
+ *
+ * @template TTask - The type of the task
+ * @template TStreams - The type of the streams data
+ * @param {string} [runId] - The unique identifier of the run to subscribe to
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunWithStreamsInstance<TTask, TStreams>} An object containing the current state of the run, streams data, and error handling
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { run, streams, error } = useRealtimeRunWithStreams<typeof myTask, {
+ *   output: string;
+ * }>('run-id-123');
+ * ```
+ */
+export declare function useRealtimeRunWithStreams<TTask extends AnyTask = AnyTask, TStreams extends Record<string, any> = Record<string, any>>(runId?: string, options?: UseRealtimeSingleRunOptions<TTask>): UseRealtimeRunWithStreamsInstance<TTask, TStreams>;
+export type UseRealtimeRunsInstance<TTask extends AnyTask = AnyTask> = {
+    runs: RealtimeRun<TTask>[];
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately.
+     */
+    stop: () => void;
+};
+export type UseRealtimeRunsWithTagOptions = UseRealtimeRunOptions & {
+    /**
+     * Filter runs by the time they were created. You must specify the duration string like "1h", "10s", "30m", etc.
+     *
+     * @example
+     * "1h" - 1 hour ago
+     * "10s" - 10 seconds ago
+     * "30m" - 30 minutes ago
+     * "1d" - 1 day ago
+     * "1w" - 1 week ago
+     *
+     * The maximum duration is 1 week
+     *
+     * @note The timestamp will be calculated on the server side when you first subscribe to the runs.
+     *
+     */
+    createdAt?: string;
+    /**
+     * Skip columns from the subscription.
+     *
+     * @default []
+     */
+    skipColumns?: RealtimeRunSkipColumns;
+};
+/**
+ * Hook to subscribe to realtime updates of task runs filtered by tag(s).
+ *
+ * @template TTask - The type of the task
+ * @param {string | string[]} tag - The tag or array of tags to filter runs by
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunsInstance<TTask>} An object containing the current state of the runs and any error encountered
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>('my-tag');
+ * // Or with multiple tags
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>(['tag1', 'tag2']);
+ * // Or with a createdAt filter
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>('my-tag', { createdAt: '1h' });
+ * ```
+ */
+export declare function useRealtimeRunsWithTag<TTask extends AnyTask>(tag: string | string[], options?: UseRealtimeRunsWithTagOptions): UseRealtimeRunsInstance<TTask>;
+/**
+ * Hook to subscribe to realtime updates of a batch of task runs.
+ *
+ * @template TTask - The type of the task
+ * @param {string} batchId - The unique identifier of the batch to subscribe to
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunsInstance<TTask>} An object containing the current state of the runs, error handling, and control methods
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { runs, error } = useRealtimeBatch<typeof myTask>('batch-id-123');
+ * ```
+ */
+export declare function useRealtimeBatch<TTask extends AnyTask>(batchId: string, options?: UseRealtimeRunOptions): UseRealtimeRunsInstance<TTask>;
+export type UseRealtimeStreamInstance<TPart> = {
+    parts: Array<TPart>;
+    /**
+     * The event id of the last part seen. Persist this (e.g. to localStorage) and
+     * pass it back as the `lastEventId` option to resume the stream where you left
+     * off after a page reload. Updated on each throttled flush.
+     */
+    lastEventId: string | undefined;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately, keep the generated tokens if any.
+     */
+    stop: () => void;
+};
+export type UseRealtimeStreamOptions<TPart> = UseApiClientOptions & {
+    id?: string;
+    enabled?: boolean;
+    /**
+     * The number of milliseconds to throttle the stream updates.
+     *
+     * @default 16
+     */
+    throttleInMs?: number;
+    /**
+     * The number of seconds to wait for new data to be available,
+     * If no data arrives within the timeout, the stream will be closed.
+     *
+     * @default 60 seconds
+     */
+    timeoutInSeconds?: number;
+    /**
+     * The index to start reading from.
+     * If not provided, the stream will start from the beginning.
+     * @default 0
+     */
+    startIndex?: number;
+    /**
+     * The event id to resume from, as returned in `lastEventId`. Persist it across
+     * a page reload and pass it back to continue where the previous session left
+     * off, with no replay and no gap. Takes precedence over `startIndex` and
+     * `from`.
+     */
+    lastEventId?: string | number;
+    /**
+     * Where a fresh subscription starts reading.
+     *
+     * - `"beginning"` (default): replay the full stream history, then live-tail.
+     * - `"latest"`: start at the current tail (the latest record, then live
+     *   updates) instead of replaying history, for a last-value / live view. On
+     *   reconnect or remount the subscription resumes from the last record it
+     *   saw, so no frames are missed and none are replayed.
+     *
+     * Ignored when `startIndex` is set (which pins an absolute start position).
+     */
+    from?: "beginning" | "latest";
+    /**
+     * Cap the number of parts kept in the accumulated `parts` array. When more
+     * than `maxParts` parts have been received, only the most recent `maxParts`
+     * are retained (older parts are dropped). Use `maxParts: 1` together with
+     * `from: "latest"` for a pure last-value view with bounded memory.
+     *
+     * When unset, `parts` accumulates every record for the lifetime of the
+     * subscription (the default).
+     */
+    maxParts?: number;
+    /**
+     * Callback this is called when new data is received.
+     */
+    onData?: (data: TPart) => void;
+    /**
+     * Callback invoked once per throttled flush with the batch of parts in that
+     * flush, each carrying its event `id`, `chunk` and `timestamp`. Use it to
+     * track the resume cursor without re-rendering on every record. Fires at the
+     * `throttleInMs` cadence, not per record.
+     */
+    onParts?: (parts: Array<SSEStreamPart<TPart>>) => void;
+};
+export declare function useRealtimeStream<TDefinedStream extends RealtimeDefinedStream<any>>(stream: TDefinedStream, runId: string, options?: UseRealtimeStreamOptions<InferStreamType<TDefinedStream>>): UseRealtimeStreamInstance<InferStreamType<TDefinedStream>>;
+/**
+ * Hook to subscribe to realtime updates of a stream with a specific stream key.
+ *
+ * This hook automatically subscribes to a stream and updates the `parts` array as new data arrives.
+ * The stream subscription is automatically managed: it starts when the component mounts (or when
+ * `enabled` becomes `true`) and stops when the component unmounts or when `stop()` is called.
+ *
+ * @template TPart - The type of each chunk/part in the stream
+ * @param runId - The unique identifier of the run to subscribe to
+ * @param streamKey - The unique identifier of the stream to subscribe to. Use this overload
+ *   when you want to read from a specific stream key.
+ * @param options - Optional configuration for the stream subscription
+ * @returns An object containing:
+ *   - `parts`: An array of all stream chunks received so far (accumulates over time)
+ *   - `error`: Any error that occurred during subscription
+ *   - `stop`: A function to manually stop the subscription
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useRealtimeStream } from "@trigger.dev/react-hooks";
+ *
+ * function StreamViewer({ runId }: { runId: string }) {
+ *   const { parts, error } = useRealtimeStream<string>(
+ *     runId,
+ *     "my-stream",
+ *     {
+ *       accessToken: process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_KEY,
+ *     }
+ *   );
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   // Parts array accumulates all chunks
+ *   const fullText = parts.join("");
+ *
+ *   return <div>{fullText}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom options
+ * const { parts, error, stop } = useRealtimeStream<ChatChunk>(
+ *   runId,
+ *   "chat-stream",
+ *   {
+ *     accessToken: publicKey,
+ *     timeoutInSeconds: 120,
+ *     startIndex: 10, // Start from the 10th chunk
+ *     throttleInMs: 50, // Throttle updates to every 50ms
+ *     onData: (chunk) => {
+ *       console.log("New chunk received:", chunk);
+ *     },
+ *   }
+ * );
+ *
+ * // Manually stop the subscription
+ * <button onClick={stop}>Stop Stream</button>
+ * ```
+ */
+export declare function useRealtimeStream<TPart>(runId: string, streamKey: string, options?: UseRealtimeStreamOptions<TPart>): UseRealtimeStreamInstance<TPart>;
+/**
+ * Hook to subscribe to realtime updates of a stream using the default stream key (`"default"`).
+ *
+ * This is a convenience overload that allows you to subscribe to the default stream without
+ * specifying a stream key. The stream will be accessed with the key `"default"`.
+ *
+ * @template TPart - The type of each chunk/part in the stream
+ * @param runId - The unique identifier of the run to subscribe to
+ * @param options - Optional configuration for the stream subscription
+ * @returns An object containing:
+ *   - `parts`: An array of all stream chunks received so far (accumulates over time)
+ *   - `error`: Any error that occurred during subscription
+ *   - `stop`: A function to manually stop the subscription
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useRealtimeStream } from "@trigger.dev/react-hooks";
+ *
+ * function DefaultStreamViewer({ runId }: { runId: string }) {
+ *   // Subscribe to the default stream
+ *   const { parts, error } = useRealtimeStream<string>(runId, {
+ *     accessToken: process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_KEY,
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   const fullText = parts.join("");
+ *   return <div>{fullText}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditionally enable the stream
+ * const { parts } = useRealtimeStream<string>(runId, {
+ *   accessToken: publicKey,
+ *   enabled: !!runId && isStreaming, // Only subscribe when runId exists and isStreaming is true
+ * });
+ * ```
+ */
+export declare function useRealtimeStream<TPart>(runId: string, options?: UseRealtimeStreamOptions<TPart>): UseRealtimeStreamInstance<TPart>;