additional react-hooks jsdocs

Author: ericallam

packages/react-hooks/src/hooks/useApiClient.ts

@@ -3,12 +3,38 @@
 import { ApiClient, ApiRequestOptions } from "@trigger.dev/core/v3";
 import { useTriggerAuthContextOptional } from "../contexts.js";
 
+/**
+ * Configuration options for creating an API client instance.
+ */
 export type UseApiClientOptions = {
+  /** Optional access token for authentication */
   accessToken?: string;
+  /** Optional base URL for the API endpoints */
   baseURL?: string;
+  /** Optional additional request configuration */
   requestOptions?: ApiRequestOptions;
 };
 
+/**
+ * Hook to create an API client instance using authentication context or provided options.
+ *
+ * @param {UseApiClientOptions} [options] - Configuration options for the API client
+ * @returns {ApiClient} An initialized API client instance
+ * @throws {Error} When no access token is available in either context or options
+ *
+ * @example
+ * ```ts
+ * // Using context authentication
+ * const apiClient = useApiClient();
+ *
+ * // Using custom options
+ * const apiClient = useApiClient({
+ *   accessToken: "your-access-token",
+ *   baseURL: "https://api.my-trigger.com",
+ *   requestOptions: { retry: { maxAttempts: 10 } }
+ * });
+ * ```
+ */
 export function useApiClient(options?: UseApiClientOptions): ApiClient {
   const auth = useTriggerAuthContextOptional();
 

packages/react-hooks/src/hooks/useRealtime.ts

@@ -24,18 +24,20 @@ export type UseRealtimeRunInstance<TTask extends AnyTask = AnyTask> = {
 };
 
 /**
- * hook to subscribe to realtime updates of a task run.
+ * 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.
- * @returns {{ run: RealtimeRun<TTask> | undefined, error: Error | null }} An object containing the current state of the run and any error encountered.
+ * @template TTask - The type of the task
+ * @param {string} [runId] - The unique identifier of the run to subscribe to
+ * @param {UseRealtimeRunOptions} [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 function useRealtimeRun<TTask extends AnyTask>(
   runId?: string,
   options?: UseRealtimeRunOptions
@@ -133,6 +135,23 @@ export type UseRealtimeRunWithStreamsInstance<
   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 function useRealtimeRunWithStreams<
   TTask extends AnyTask = AnyTask,
   TStreams extends Record<string, any> = Record<string, any>,
@@ -249,6 +268,22 @@ export type UseRealtimeRunsInstance<TTask extends AnyTask = AnyTask> = {
   stop: () => void;
 };
 
+/**
+ * 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']);
+ * ```
+ */
 export function useRealtimeRunsWithTag<TTask extends AnyTask>(
   tag: string | string[],
   options?: UseRealtimeRunOptions
@@ -321,19 +356,20 @@ export function useRealtimeRunsWithTag<TTask extends AnyTask>(
 }
 
 /**
- * hook to subscribe to realtime updates of a batch of task runs.
+ * 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.
- * @returns {{ runs: RealtimeRun<TTask>[], error: Error | null }} An object containing the current state of the runs and any error encountered.
+ * @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 function useRealtimeBatch<TTask extends AnyTask>(
   batchId: string,
   options?: UseRealtimeRunOptions

packages/react-hooks/src/hooks/useTaskTrigger.ts

@@ -19,15 +19,41 @@ import {
   UseRealtimeRunWithStreamsInstance,
 } from "./useRealtime.js";
 
+/**
+ * Base interface for task trigger instances.
+ *
+ * @template TTask - The type of the task
+ */
 export interface TriggerInstance<TTask extends AnyTask> {
+  /** Function to submit the task with a payload */
   submit: (payload: TaskPayload<TTask>) => void;
+  /** Whether the task is currently being submitted */
   isLoading: boolean;
+  /** The handle returned after successful task submission */
   handle?: RunHandleFromTypes<InferRunTypes<TTask>>;
+  /** Any error that occurred during submission */
   error?: Error;
 }
 
 export type UseTaskTriggerOptions = UseApiClientOptions;
 
+/**
+ * Hook to trigger a task and manage its initial execution state.
+ *
+ * @template TTask - The type of the task
+ * @param {TaskIdentifier<TTask>} id - The identifier of the task to trigger
+ * @param {UseTaskTriggerOptions} [options] - Configuration options for the task trigger
+ * @returns {TriggerInstance<TTask>} An object containing the submit function, loading state, handle, and any errors
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { submit, isLoading, handle, error } = useTaskTrigger<typeof myTask>('my-task-id');
+ *
+ * // Submit the task with payload
+ * submit({ foo: 'bar' });
+ * ```
+ */
 export function useTaskTrigger<TTask extends AnyTask>(
   id: TaskIdentifier<TTask>,
   options?: UseTaskTriggerOptions
@@ -74,8 +100,13 @@ export function useTaskTrigger<TTask extends AnyTask>(
   };
 }
 
+/**
+ * Configuration options for task triggers with realtime updates.
+ */
 export type UseRealtimeTaskTriggerOptions = UseTaskTriggerOptions & {
+  /** Whether the realtime subscription is enabled */
   enabled?: boolean;
+  /** Optional throttle time in milliseconds for stream updates */
   experimental_throttleInMs?: number;
 };
 
@@ -88,6 +119,28 @@ export type RealtimeTriggerInstanceWithStreams<
   handle?: RunHandleFromTypes<InferRunTypes<TTask>>;
 };
 
+/**
+ * Hook to trigger a task and subscribe to its realtime updates including stream data.
+ *
+ * @template TTask - The type of the task
+ * @template TStreams - The type of the streams data
+ * @param {TaskIdentifier<TTask>} id - The identifier of the task to trigger
+ * @param {UseRealtimeTaskTriggerOptions} [options] - Configuration options for the task trigger and realtime updates
+ * @returns {RealtimeTriggerInstanceWithStreams<TTask, TStreams>} An object containing the submit function, loading state,
+ *          handle, run state, streams data, and error handling
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { submit, run, streams, error } = useRealtimeTaskTriggerWithStreams<
+ *   typeof myTask,
+ *   { output: string }
+ * >('my-task-id');
+ *
+ * // Submit and monitor the task with streams
+ * submit({ foo: 'bar' });
+ * ```
+ */
 export function useRealtimeTaskTriggerWithStreams<
   TTask extends AnyTask,
   TStreams extends Record<string, any> = Record<string, any>,
@@ -114,6 +167,28 @@ export type RealtimeTriggerInstance<TTask extends AnyTask> = UseRealtimeRunInsta
   handle?: RunHandleFromTypes<InferRunTypes<TTask>>;
 };
 
+/**
+ * Hook to trigger a task and subscribe to its realtime updates.
+ *
+ * @template TTask - The type of the task
+ * @param {TaskIdentifier<TTask>} id - The identifier of the task to trigger
+ * @param {UseRealtimeTaskTriggerOptions} [options] - Configuration options for the task trigger and realtime updates
+ * @returns {RealtimeTriggerInstance<TTask>} An object containing the submit function, loading state,
+ *          handle, run state, and error handling
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { submit, run, error, stop } = useRealtimeTaskTrigger<typeof myTask>('my-task-id');
+ *
+ * // Submit and monitor the task
+ * submit({ foo: 'bar' });
+ *
+ * // Stop monitoring when needed
+ * stop();
+ * ```
+ */
+
 export function useRealtimeTaskTrigger<TTask extends AnyTask>(
   id: TaskIdentifier<TTask>,
   options?: UseRealtimeTaskTriggerOptions