@coji/durably-react 0.13.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @coji/durably-react
 
-React bindings for [Durably](https://github.com/coji/durably) - step-oriented resumable batch execution.
+React bindings for [Durably](https://github.com/coji/durably) — steps that survive crashes.
 
 **[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)**
 

package/dist/{chunk-33VIIDHK.js → chunk-IXJA5WWJ.js}

@@ -1,3 +1,13 @@
+// src/shared/use-stable-value.ts
+import { useMemo } from "react";
+function useStableValue(value) {
+  const key = value !== void 0 ? JSON.stringify(value) : void 0;
+  return useMemo(
+    () => key !== void 0 ? JSON.parse(key) : void 0,
+    [key]
+  );
+}
+
 // src/types.ts
 function isJobDefinition(obj) {
   return typeof obj === "object" && obj !== null && "name" in obj && "run" in obj && typeof obj.run === "function";
@@ -134,6 +144,7 @@ export {
   initialSubscriptionState,
   subscriptionReducer,
   useSubscription,
+  useStableValue,
   isJobDefinition
 };
-//# sourceMappingURL=chunk-33VIIDHK.js.map
+//# sourceMappingURL=chunk-IXJA5WWJ.js.map

package/dist/chunk-IXJA5WWJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/use-stable-value.ts","../src/types.ts","../src/shared/create-log-entry.ts","../src/shared/subscription-reducer.ts","../src/shared/use-subscription.ts"],"sourcesContent":["import { useMemo } from 'react'\n\n/**\n * Stabilize a value reference using JSON serialization.\n * Prevents re-render loops when callers pass inline arrays/objects.\n */\nexport function useStableValue<T>(value: T | undefined): T | undefined {\n  const key = value !== undefined ? JSON.stringify(value) : undefined\n  return useMemo(\n    () => (key !== undefined ? (JSON.parse(key) as T) : undefined),\n    [key],\n  )\n}\n","// Shared type definitions for @coji/durably-react\n\nimport type { ClientRun, JobDefinition, Run, RunStatus } from '@coji/durably'\n\nexport type { RunStatus }\n\n// Type inference utilities for extracting Input/Output types from JobDefinition\nexport type InferInput<T> =\n  T extends JobDefinition<string, infer TInput, unknown>\n    ? TInput extends Record<string, unknown>\n      ? TInput\n      : Record<string, unknown>\n    : T extends { trigger: (input: infer TInput) => unknown }\n      ? TInput extends Record<string, unknown>\n        ? TInput\n        : Record<string, unknown>\n      : Record<string, unknown>\n\nexport type InferOutput<T> =\n  T extends JobDefinition<string, unknown, infer TOutput>\n    ? TOutput extends Record<string, unknown>\n      ? TOutput\n      : Record<string, unknown>\n    : T extends {\n          trigger: (input: unknown) => Promise<{ output?: infer TOutput }>\n        }\n      ? TOutput extends Record<string, unknown>\n        ? TOutput\n        : Record<string, unknown>\n      : Record<string, unknown>\n\nexport interface Progress {\n  current: number\n  total?: number\n  message?: string\n}\n\nexport interface LogEntry {\n  id: string\n  runId: string\n  stepName: string | null\n  level: 'info' | 'warn' | 'error'\n  message: string\n  data: unknown\n  timestamp: string\n}\n\n// Shared subscription state (used by both direct and SSE subscriptions)\nexport interface SubscriptionState<TOutput = unknown> {\n  status: RunStatus | null\n  output: TOutput | null\n  error: string | null\n  logs: LogEntry[]\n  progress: Progress | null\n}\n\n// SSE event types (sent from server).\n// Note: Unlike core DurablyEvent, these omit timestamp/sequence because\n// the SSE handler in server.ts sends only the fields needed by the UI.\nexport type DurablyEvent =\n  | { type: 'run:leased'; runId: string; jobName: string; input: unknown }\n  | {\n      type: 'run:complete'\n      runId: string\n      jobName: string\n      output: unknown\n      duration: number\n    }\n  | { type: 'run:fail'; runId: string; jobName: string; error: string }\n  | { type: 'run:cancel'; runId: string; jobName: string }\n  | { type: 'run:delete'; runId: string; jobName: string }\n  | { type: 'run:trigger'; runId: string; jobName: string; input: unknown }\n  | {\n      type: 'run:coalesced'\n      runId: string\n      jobName: string\n      labels: Record<string, string>\n      skippedInput: unknown\n      skippedLabels: Record<string, string>\n    }\n  | {\n      type: 'run:progress'\n      runId: string\n      jobName: string\n      progress: Progress\n    }\n  | {\n      type: 'step:start'\n      runId: string\n      jobName: string\n      stepName: string\n      stepIndex: number\n    }\n  | {\n      type: 'step:complete'\n      runId: string\n      jobName: string\n      stepName: string\n      stepIndex: number\n      output: unknown\n    }\n  | {\n      type: 'step:cancel'\n      runId: string\n      jobName: string\n      stepName: string\n      stepIndex: number\n      labels: Record<string, string>\n    }\n  | {\n      type: 'log:write'\n      runId: string\n      jobName: string\n      stepName: string | null\n      labels: Record<string, string>\n      level: 'info' | 'warn' | 'error'\n      message: string\n      data: unknown\n    }\n\n// =============================================================================\n// Typed Run types for useRuns hooks\n// =============================================================================\n\n/**\n * A typed version of Run with generic input/output types.\n * Used by browser hooks (direct durably access).\n */\nexport type TypedRun<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined = Record<string, unknown>,\n> = Omit<Run, 'input' | 'output'> & {\n  input: TInput\n  output: TOutput | null\n}\n\n// ClientRun is imported from '@coji/durably' and re-exported for consumers.\nexport type { ClientRun } from '@coji/durably'\n\n/**\n * A typed version of ClientRun with generic input/output types.\n * Used by client hooks (HTTP/SSE connection).\n */\nexport type TypedClientRun<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined = Record<string, unknown>,\n> = Omit<ClientRun, 'input' | 'output'> & {\n  input: TInput\n  output: TOutput | null\n}\n\n/**\n * Type guard to check if an object is a JobDefinition.\n * Used to distinguish between JobDefinition and options objects in overloaded functions.\n */\nexport function isJobDefinition<\n  TName extends string = string,\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined = undefined,\n>(obj: unknown): obj is JobDefinition<TName, TInput, TOutput> {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    'name' in obj &&\n    'run' in obj &&\n    typeof (obj as { run: unknown }).run === 'function'\n  )\n}\n","import type { LogEntry } from '../types'\n\nexport interface CreateLogEntryParams {\n  runId: string\n  stepName: string | null\n  level: 'info' | 'warn' | 'error'\n  message: string\n  data: unknown\n}\n\n/**\n * Creates a LogEntry with auto-generated id and timestamp.\n * Extracted to eliminate duplication between subscription hooks.\n */\nexport function createLogEntry(params: CreateLogEntryParams): LogEntry {\n  return {\n    id: crypto.randomUUID(),\n    runId: params.runId,\n    stepName: params.stepName,\n    level: params.level,\n    message: params.message,\n    data: params.data,\n    timestamp: new Date().toISOString(),\n  }\n}\n\n/**\n * Appends a log entry to the array, respecting maxLogs limit.\n */\nexport function appendLog(\n  logs: LogEntry[],\n  newLog: LogEntry,\n  maxLogs: number,\n): LogEntry[] {\n  const newLogs = [...logs, newLog]\n  if (maxLogs > 0 && newLogs.length > maxLogs) {\n    return newLogs.slice(-maxLogs)\n  }\n  return newLogs\n}\n","import type { Progress, SubscriptionState } from '../types'\nimport { appendLog, createLogEntry } from './create-log-entry'\n\n// Action types for subscription state transitions\nexport type SubscriptionAction<TOutput = unknown> =\n  | { type: 'run:leased' }\n  | { type: 'run:complete'; output: TOutput }\n  | { type: 'run:fail'; error: string }\n  | { type: 'run:cancel' }\n  | { type: 'run:progress'; progress: Progress }\n  | {\n      type: 'log:write'\n      runId: string\n      stepName: string | null\n      level: 'info' | 'warn' | 'error'\n      message: string\n      data: unknown\n      maxLogs: number\n    }\n  | { type: 'reset' }\n  | { type: 'clear_logs' }\n  | { type: 'connection_error'; error: string }\n\nexport const initialSubscriptionState: SubscriptionState<unknown> = {\n  status: null,\n  output: null,\n  error: null,\n  logs: [],\n  progress: null,\n}\n\n/**\n * Pure reducer for subscription state transitions.\n * Extracted to eliminate duplication between useRunSubscription and useSSESubscription.\n */\nexport function subscriptionReducer<TOutput = unknown>(\n  state: SubscriptionState<TOutput>,\n  action: SubscriptionAction<TOutput>,\n): SubscriptionState<TOutput> {\n  switch (action.type) {\n    case 'run:leased':\n      return { ...state, status: 'leased' }\n\n    case 'run:complete':\n      return { ...state, status: 'completed', output: action.output }\n\n    case 'run:fail':\n      return { ...state, status: 'failed', error: action.error }\n\n    case 'run:cancel':\n      return { ...state, status: 'cancelled' }\n\n    case 'run:progress':\n      return { ...state, progress: action.progress }\n\n    case 'log:write': {\n      const newLog = createLogEntry({\n        runId: action.runId,\n        stepName: action.stepName,\n        level: action.level,\n        message: action.message,\n        data: action.data,\n      })\n      return { ...state, logs: appendLog(state.logs, newLog, action.maxLogs) }\n    }\n\n    case 'reset':\n      return initialSubscriptionState as SubscriptionState<TOutput>\n\n    case 'clear_logs':\n      return { ...state, logs: [] }\n\n    case 'connection_error':\n      return { ...state, error: action.error }\n\n    default:\n      return state\n  }\n}\n","import { useCallback, useEffect, useReducer, useRef } from 'react'\nimport type { SubscriptionState } from '../types'\nimport type { EventSubscriber } from './event-subscriber'\nimport {\n  initialSubscriptionState,\n  subscriptionReducer,\n} from './subscription-reducer'\n\nexport interface UseSubscriptionOptions {\n  /**\n   * Maximum number of logs to keep (0 = unlimited)\n   */\n  maxLogs?: number\n}\n\nexport interface UseSubscriptionResult<\n  TOutput = unknown,\n> extends SubscriptionState<TOutput> {\n  /**\n   * Clear all logs\n   */\n  clearLogs: () => void\n  /**\n   * Reset all state\n   */\n  reset: () => void\n}\n\n/**\n * Core subscription hook that works with any EventSubscriber implementation.\n * This unifies the subscription logic between Durably.on and SSE.\n */\nexport function useSubscription<TOutput = unknown>(\n  subscriber: EventSubscriber | null,\n  runId: string | null,\n  options?: UseSubscriptionOptions,\n): UseSubscriptionResult<TOutput> {\n  const [state, dispatch] = useReducer(\n    subscriptionReducer<TOutput>,\n    initialSubscriptionState as SubscriptionState<TOutput>,\n  )\n\n  const runIdRef = useRef<string | null>(runId)\n  const prevRunIdRef = useRef<string | null>(null)\n\n  const maxLogs = options?.maxLogs ?? 0\n\n  // Reset state when runId changes\n  if (prevRunIdRef.current !== runId) {\n    prevRunIdRef.current = runId\n    if (runIdRef.current !== runId) {\n      dispatch({ type: 'reset' })\n    }\n  }\n  runIdRef.current = runId\n\n  useEffect(() => {\n    if (!subscriber || !runId) return\n\n    const unsubscribe = subscriber.subscribe<TOutput>(runId, (event) => {\n      // Verify runId hasn't changed during async operation\n      if (runIdRef.current !== runId) return\n\n      switch (event.type) {\n        case 'run:leased':\n        case 'run:cancel':\n          dispatch({ type: event.type })\n          break\n        case 'run:complete':\n          dispatch({ type: 'run:complete', output: event.output })\n          break\n        case 'run:fail':\n          dispatch({ type: 'run:fail', error: event.error })\n          break\n        case 'run:progress':\n          dispatch({ type: 'run:progress', progress: event.progress })\n          break\n        case 'log:write':\n          dispatch({\n            type: 'log:write',\n            runId: event.runId,\n            stepName: event.stepName,\n            level: event.level,\n            message: event.message,\n            data: event.data,\n            maxLogs,\n          })\n          break\n        case 'connection_error':\n          dispatch({ type: 'connection_error', error: event.error })\n          break\n      }\n    })\n\n    return unsubscribe\n  }, [subscriber, runId, maxLogs])\n\n  const clearLogs = useCallback(() => {\n    dispatch({ type: 'clear_logs' })\n  }, [])\n\n  const reset = useCallback(() => {\n    dispatch({ type: 'reset' })\n  }, [])\n\n  return {\n    ...state,\n    clearLogs,\n    reset,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { R as RunStatus, L as LogEntry, P as Progress, I as InferInput, a as InferOutput, T as TypedClientRun } from './types-DMtqQ6Wp.js';
-export { D as DurablyEvent } from './types-DMtqQ6Wp.js';
-import { JobDefinition, ClientRun } from '@coji/durably';
-export { ClientRun } from '@coji/durably';
+import { L as LogEntry, P as Progress, I as InferInput, a as InferOutput, T as TypedClientRun } from './types-CQltMEdB.js';
+export { D as DurablyEvent } from './types-CQltMEdB.js';
+import { RunStatus, JobDefinition, ClientRun } from '@coji/durably';
+export { ClientRun, RunStatus } from '@coji/durably';
 
 interface UseJobClientOptions {
     /**
@@ -85,6 +85,14 @@ interface UseJobClientResult<TInput, TOutput> {
      * Whether the run was cancelled
      */
     isCancelled: boolean;
+    /**
+     * Whether the run reached a terminal status (completed, failed, or cancelled)
+     */
+    isTerminal: boolean;
+    /**
+     * Whether the run is pending or leased (actively queued or executing)
+     */
+    isActive: boolean;
     /**
      * Current run ID
      */
@@ -199,6 +207,14 @@ interface UseJobRunClientResult<TOutput = unknown> {
      * Whether the run was cancelled
      */
     isCancelled: boolean;
+    /**
+     * Whether the run reached a terminal status (completed, failed, or cancelled)
+     */
+    isTerminal: boolean;
+    /**
+     * Whether the run is pending or leased (actively queued or executing)
+     */
+    isActive: boolean;
 }
 /**
  * Hook for subscribing to an existing run via server API.
@@ -226,17 +242,15 @@ interface JobHooks<TInput, TOutput> {
     /**
      * Hook for triggering and monitoring the job
      */
-    useJob: () => UseJobClientResult<TInput, TOutput>;
+    useJob: (options?: Omit<UseJobClientOptions, 'api' | 'jobName'>) => UseJobClientResult<TInput, TOutput>;
     /**
      * Hook for subscribing to an existing run by ID
      */
-    useRun: (runId: string | null) => UseJobRunClientResult<TOutput>;
+    useRun: (runId: string | null, options?: Omit<UseJobRunClientOptions, 'api' | 'runId'>) => UseJobRunClientResult<TOutput>;
     /**
      * Hook for subscribing to logs from a run
      */
-    useLogs: (runId: string | null, options?: {
-        maxLogs?: number;
-    }) => UseJobLogsClientResult;
+    useLogs: (runId: string | null, options?: Omit<UseJobLogsClientOptions, 'api' | 'runId'>) => UseJobLogsClientResult;
 }
 /**
  * Create type-safe hooks for a specific job.
@@ -301,14 +315,6 @@ interface UseRunActionsClientResult {
      * Get steps for a run
      */
     getSteps: (runId: string) => Promise<StepRecord[]>;
-    /**
-     * Whether an action is in progress
-     */
-    isLoading: boolean;
-    /**
-     * Error message from last action
-     */
-    error: string | null;
 }
 /**
  * Hook for run actions via server API.
@@ -316,23 +322,38 @@ interface UseRunActionsClientResult {
  * @example
  * ```tsx
  * function RunActions({ runId, status }: { runId: string; status: string }) {
- *   const { retrigger, cancel, isLoading, error } = useRunActions({
+ *   const { retrigger, cancel } = useRunActions({
  *     api: '/api/durably',
  *   })
+ *   const [isPending, startTransition] = useTransition()
  *
  *   return (
  *     <div>
  *       {status === 'failed' && (
- *         <button onClick={() => retrigger(runId)} disabled={isLoading}>
+ *         <button
+ *           onClick={() =>
+ *             startTransition(() =>
+ *               // Handle errors in production (e.g. toast, local state)
+ *               retrigger(runId).catch(console.error),
+ *             )
+ *           }
+ *           disabled={isPending}
+ *         >
  *           Run Again
  *         </button>
  *       )}
  *       {(status === 'pending' || status === 'leased') && (
- *         <button onClick={() => cancel(runId)} disabled={isLoading}>
+ *         <button
+ *           onClick={() =>
+ *             startTransition(() =>
+ *               cancel(runId).catch(console.error),
+ *             )
+ *           }
+ *           disabled={isPending}
+ *         >
  *           Cancel
  *         </button>
  *       )}
- *       {error && <span className="error">{error}</span>}
  *     </div>
  *   )
  * }
@@ -350,9 +371,9 @@ interface UseRunsClientOptions {
      */
     jobName?: string | string[];
     /**
-     * Filter by status
+     * Filter by status(es). Pass one status, or an array for multiple (OR).
      */
-    status?: RunStatus;
+    status?: RunStatus | RunStatus[];
     /**
      * Filter by labels (all specified labels must match)
      */
@@ -368,7 +389,7 @@ interface UseRunsClientOptions {
      */
     realtime?: boolean;
 }
-interface UseRunsClientResult<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> | undefined = Record<string, unknown> | undefined> {
+interface UseRunsClientResult<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> | undefined = Record<string, unknown>> {
     /**
      * List of runs for the current page
      */
@@ -517,4 +538,4 @@ type DurablyClient<T> = {
  */
 declare function createDurably<T>(options: CreateDurablyOptions): DurablyClient<T>;
 
-export { type CreateDurablyOptions, type CreateJobHooksOptions, type DurablyClient, type JobHooks, LogEntry, Progress, RunStatus, type StepRecord, TypedClientRun, type UseJobClientOptions, type UseJobClientResult, type UseJobLogsClientOptions, type UseJobLogsClientResult, type UseJobRunClientOptions, type UseJobRunClientResult, type UseRunActionsClientOptions, type UseRunActionsClientResult, type UseRunsClientOptions, type UseRunsClientResult, createDurably, createJobHooks, useJob, useJobLogs, useJobRun, useRunActions, useRuns };
+export { type CreateDurablyOptions, type CreateJobHooksOptions, type DurablyClient, type JobHooks, LogEntry, Progress, type StepRecord, TypedClientRun, type UseJobClientOptions, type UseJobClientResult, type UseJobLogsClientOptions, type UseJobLogsClientResult, type UseJobRunClientOptions, type UseJobRunClientResult, type UseRunActionsClientOptions, type UseRunActionsClientResult, type UseRunsClientOptions, type UseRunsClientResult, createDurably, createJobHooks, useJob, useJobLogs, useJobRun, useRunActions, useRuns };

package/dist/index.js

@@ -1,7 +1,8 @@
 import {
   isJobDefinition,
+  useStableValue,
   useSubscription
-} from "./chunk-33VIIDHK.js";
+} from "./chunk-IXJA5WWJ.js";
 
 // src/client/use-job.ts
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -138,7 +139,7 @@ function useJob(options) {
     eventSource.onmessage = (event) => {
       try {
         const data = JSON.parse(event.data);
-        if ((data.type === "run:trigger" || data.type === "run:leased") && data.runId) {
+        if ((data.type === "run:trigger" || data.type === "run:coalesced" || data.type === "run:leased") && data.runId) {
           setCurrentRunId(data.runId);
         }
       } catch {
@@ -232,6 +233,8 @@ function useJob(options) {
     isCompleted: effectiveStatus === "completed",
     isFailed: effectiveStatus === "failed",
     isCancelled: effectiveStatus === "cancelled",
+    isTerminal: effectiveStatus === "completed" || effectiveStatus === "failed" || effectiveStatus === "cancelled",
+    isActive: effectiveStatus === "pending" || effectiveStatus === "leased",
     currentRunId,
     reset
   };
@@ -293,7 +296,9 @@ function useJobRun(options) {
     isPending,
     isCompleted,
     isFailed,
-    isCancelled
+    isCancelled,
+    isTerminal: isCompleted || isFailed || isCancelled,
+    isActive: isPending || isLeased
   };
 }
 
@@ -301,162 +306,128 @@ function useJobRun(options) {
 function createJobHooks(options) {
   const { api, jobName } = options;
   return {
-    useJob: () => {
-      return useJob({ api, jobName });
+    useJob: (jobOptions) => {
+      return useJob({
+        api,
+        jobName,
+        ...jobOptions
+      });
     },
-    useRun: (runId) => {
-      return useJobRun({ api, runId });
+    useRun: (runId, runOptions) => {
+      return useJobRun({ api, runId, ...runOptions });
     },
     useLogs: (runId, logsOptions) => {
-      return useJobLogs({ api, runId, maxLogs: logsOptions?.maxLogs });
+      return useJobLogs({ api, runId, ...logsOptions });
     }
   };
 }
 
 // src/client/use-run-actions.ts
-import { useCallback as useCallback2, useState as useState2 } from "react";
+import { useCallback as useCallback2 } from "react";
+async function parseErrorResponse(response, actionName) {
+  let errorMessage = `Failed to ${actionName}: ${response.statusText}`;
+  try {
+    const data = await response.json();
+    if (typeof data === "object" && data !== null && "error" in data && data.error) {
+      errorMessage = String(data.error);
+    }
+  } catch {
+  }
+  return errorMessage;
+}
 function useRunActions(options) {
   const { api } = options;
-  const [isLoading, setIsLoading] = useState2(false);
-  const [error, setError] = useState2(null);
-  const executeAction = useCallback2(
+  const executeJson = useCallback2(
     async (url, actionName, init) => {
-      setIsLoading(true);
-      setError(null);
-      try {
-        const response = await fetch(url, init);
-        if (!response.ok) {
-          let errorMessage = `Failed to ${actionName}: ${response.statusText}`;
-          try {
-            const data = await response.json();
-            if (data.error) {
-              errorMessage = data.error;
-            }
-          } catch {
-          }
-          throw new Error(errorMessage);
-        }
-        return await response.json();
-      } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
-        setError(message);
-        throw err;
-      } finally {
-        setIsLoading(false);
+      const response = await fetch(url, init);
+      if (!response.ok) {
+        const errorMessage = await parseErrorResponse(response, actionName);
+        throw new Error(errorMessage);
       }
+      return await response.json();
     },
     []
   );
   const retrigger = useCallback2(
     async (runId) => {
       const enc = encodeURIComponent(runId);
-      const data = await executeAction(
+      const data = await executeJson(
         `${api}/retrigger?runId=${enc}`,
         "retrigger",
         { method: "POST" }
       );
       if (!data.runId) {
-        const message = "Failed to retrigger: missing runId in response";
-        setError(message);
-        throw new Error(message);
+        throw new Error("Failed to retrigger: missing runId in response");
       }
       return data.runId;
     },
-    [api, executeAction]
+    [api, executeJson]
   );
   const cancel = useCallback2(
     async (runId) => {
       const enc = encodeURIComponent(runId);
-      await executeAction(`${api}/cancel?runId=${enc}`, "cancel", {
+      await executeJson(`${api}/cancel?runId=${enc}`, "cancel", {
         method: "POST"
       });
     },
-    [api, executeAction]
+    [api, executeJson]
   );
   const deleteRun = useCallback2(
     async (runId) => {
       const enc = encodeURIComponent(runId);
-      await executeAction(`${api}/run?runId=${enc}`, "delete", {
+      await executeJson(`${api}/run?runId=${enc}`, "delete", {
         method: "DELETE"
       });
     },
-    [api, executeAction]
+    [api, executeJson]
   );
   const getRun = useCallback2(
     async (runId) => {
-      setIsLoading(true);
-      setError(null);
-      try {
-        const enc = encodeURIComponent(runId);
-        const response = await fetch(`${api}/run?runId=${enc}`);
-        if (response.status === 404) {
-          return null;
-        }
-        if (!response.ok) {
-          let errorMessage = `Failed to get run: ${response.statusText}`;
-          try {
-            const data = await response.json();
-            if (data.error) {
-              errorMessage = data.error;
-            }
-          } catch {
-          }
-          throw new Error(errorMessage);
-        }
-        return await response.json();
-      } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
-        setError(message);
-        throw err;
-      } finally {
-        setIsLoading(false);
+      const enc = encodeURIComponent(runId);
+      const response = await fetch(`${api}/run?runId=${enc}`);
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        const errorMessage = await parseErrorResponse(response, "get run");
+        throw new Error(errorMessage);
       }
+      return await response.json();
     },
     [api]
   );
   const getSteps = useCallback2(
     async (runId) => {
       const enc = encodeURIComponent(runId);
-      return executeAction(
-        `${api}/steps?runId=${enc}`,
-        "get steps"
-      );
+      return executeJson(`${api}/steps?runId=${enc}`, "get steps");
     },
-    [api, executeAction]
+    [api, executeJson]
   );
   return {
     retrigger,
     cancel,
     deleteRun,
     getRun,
-    getSteps,
-    isLoading,
-    error
+    getSteps
   };
 }
 
 // src/client/use-runs.ts
-import { useCallback as useCallback3, useEffect as useEffect3, useMemo as useMemo2, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState as useState2 } from "react";
 function useRuns(jobDefinitionOrOptions, optionsArg) {
   const isJob = isJobDefinition(jobDefinitionOrOptions);
   const jobName = isJob ? jobDefinitionOrOptions.name : jobDefinitionOrOptions.jobName;
   const options = isJob ? optionsArg : jobDefinitionOrOptions;
   const { api, status, labels, pageSize = 10, realtime = true } = options;
-  const labelsKey = labels ? JSON.stringify(labels) : void 0;
-  const stableLabels = useMemo2(
-    () => labelsKey ? JSON.parse(labelsKey) : void 0,
-    [labelsKey]
-  );
-  const jobNameKey = jobName ? JSON.stringify(jobName) : void 0;
-  const stableJobName = useMemo2(
-    () => jobNameKey ? JSON.parse(jobNameKey) : void 0,
-    [jobNameKey]
-  );
-  const [runs, setRuns] = useState3([]);
-  const [page, setPage] = useState3(0);
-  const [hasMore, setHasMore] = useState3(false);
-  const [isLoading, setIsLoading] = useState3(true);
-  const [error, setError] = useState3(null);
+  const stableLabels = useStableValue(labels);
+  const stableJobName = useStableValue(jobName);
+  const stableStatus = useStableValue(status);
+  const normalizedStatus = Array.isArray(stableStatus) && stableStatus.length === 0 ? void 0 : stableStatus;
+  const [runs, setRuns] = useState2([]);
+  const [page, setPage] = useState2(0);
+  const [hasMore, setHasMore] = useState2(false);
+  const [isLoading, setIsLoading] = useState2(true);
+  const [error, setError] = useState2(null);
   const isMountedRef = useRef3(true);
   const eventSourceRef = useRef3(null);
   const refresh = useCallback3(async () => {
@@ -464,8 +435,8 @@ function useRuns(jobDefinitionOrOptions, optionsArg) {
     setError(null);
     try {
       const params = new URLSearchParams();
-      appendJobNameToParams(params, stableJobName);
-      if (status) params.set("status", status);
+      appendArrayParam(params, "jobName", stableJobName);
+      appendArrayParam(params, "status", normalizedStatus);
       appendLabelsToParams(params, stableLabels);
       params.set("limit", String(pageSize + 1));
       params.set("offset", String(page * pageSize));
@@ -488,7 +459,7 @@ function useRuns(jobDefinitionOrOptions, optionsArg) {
         setIsLoading(false);
       }
     }
-  }, [api, stableJobName, status, stableLabels, pageSize, page]);
+  }, [api, stableJobName, normalizedStatus, stableLabels, pageSize, page]);
   useEffect3(() => {
     isMountedRef.current = true;
     refresh();
@@ -505,7 +476,7 @@ function useRuns(jobDefinitionOrOptions, optionsArg) {
       return;
     }
     const params = new URLSearchParams();
-    appendJobNameToParams(params, stableJobName);
+    appendArrayParam(params, "jobName", stableJobName);
     appendLabelsToParams(params, stableLabels);
     const sseUrl = `${api}/runs/subscribe${params.toString() ? `?${params.toString()}` : ""}`;
     const eventSource = new EventSource(sseUrl);
@@ -513,7 +484,7 @@ function useRuns(jobDefinitionOrOptions, optionsArg) {
     eventSource.onmessage = (event) => {
       try {
         const data = JSON.parse(event.data);
-        if (data.type === "run:trigger" || data.type === "run:leased" || data.type === "run:complete" || data.type === "run:fail" || data.type === "run:cancel" || data.type === "run:delete") {
+        if (data.type === "run:trigger" || data.type === "run:coalesced" || data.type === "run:leased" || data.type === "run:complete" || data.type === "run:fail" || data.type === "run:cancel" || data.type === "run:delete") {
           refresh();
         }
         if (data.type === "run:progress") {
@@ -566,10 +537,10 @@ function useRuns(jobDefinitionOrOptions, optionsArg) {
     refresh
   };
 }
-function appendJobNameToParams(params, jobName) {
-  if (!jobName) return;
-  for (const name of Array.isArray(jobName) ? jobName : [jobName]) {
-    params.append("jobName", name);
+function appendArrayParam(params, key, value) {
+  if (value === void 0) return;
+  for (const v of Array.isArray(value) ? value : [value]) {
+    params.append(key, v);
   }
 }
 function appendLabelsToParams(params, labels) {