Summary

• Refactors the monolithic workflow-api-client.ts (~1,330 lines) into 8 focused, single-responsibility modules while preserving a barrel re-export for backward compatibility
• Sets up vitest + jsdom + @testing-library/react test infrastructure for packages/web and adds comprehensive unit tests across all extracted modules

Motivation

workflow-api-client.ts had grown to 1,329 lines with extensive duplication across 5 distinct patterns — paginated list hooks, exhaustive fetch helpers, merge-by-ID functions, poll functions, and server action wrappers — each repeated 2-3 times with only the fetch call or ID key varying. This made it difficult to test, navigate, and reason about individual concerns, and the package had no unit tests or test runner configured.

What Changed?

The monolith was split along natural boundaries into standalone modules:

• workflow-errors.ts —> WorkflowWebAPIError class, getErrorMessage, unwrapServerActionResult, and unwrapOrThrow helpers for consistent error handling across the package
• workflow-primitives.ts —> Pure utility functions (mergeById, fetchAllPaginated, pollResource) that provide the generic pagination and polling building blocks used by the hooks
• workflow-actions.ts —> Thin wrappers around server actions (cancelRun, recreateRun, reenqueueRun, wakeUpRun, resumeHook) with uniform error unwrapping
• workflow-streams.ts —> readStream and listStreams for fetching workflow stream data via the Fetch API
• Four React hooks were extracted into hooks/:
  • use-paginated-list.ts —> Generic usePaginatedList hook with page caching and navigation, plus concrete useWorkflowRuns and useWorkflowHooks hooks built on top of it
  • use-resource-data.ts —> useWorkflowResourceData for fetching individual run/step/hook/sleep detail views with auto-refresh
  • use-trace-viewer.ts —> useWorkflowTraceViewerData for the trace viewer, combining run, steps, hooks, and events with live polling and exhaustive pagination
  • use-workflow-streams.ts —> useWorkflowStreams for polling the list of stream IDs on a run
    workflow-api-client.ts is now a ~39-line barrel that re-exports everything, so existing consumers are unaffected.

Test infrastructure

• Added vitest, jsdom, and @testing-library/react as dev dependencies
• Created vitest.config.ts with jsdom environment and ~ path alias
• Added pnpm test script (pnpm test)

Test coverage

Added 8 test files organized to mirror the module structure:

Utilities & core logic

• workflow-errors.test.ts —> error class construction, 403 message handling, unwrapOrThrow success/failure/rejection paths
• workflow-primitives.test.ts —> mergeById deduplication and custom ID keys, fetchAllPaginated multi-page traversal and error bail-out, pollResource with both always and onHasMore cursor strategies
• workflow-actions.test.ts —> success and failure cases for all 5 action wrappers
• workflow-streams.test.ts —> readStream with startIndex/abort signal/non-ok responses/null body, listStreams success and structured error parsing

React hooks (using @testing-library/react + jsdom)

• use-paginated-list.test.ts —> initial fetch, error propagation, parameter forwarding, cursor-based nextPage, previousPage cache hit, and reload (covers both useWorkflowRuns and useWorkflowHooks)
• use-resource-data.test.ts —> run/step/hook/sleep resource types, enabled: false short-circuit, error states
• use-trace-viewer.test.ts —> combined initial load of run + steps + hooks + events, paginated step population, error handling
• use-workflow-streams.test.ts—> initial fetch and error handling

Notes

Apologies for the size of this PR, the extraction touched a lot of files but the actual logic is unchanged. Happy to break it up differently or address any feedback.

As a new contributor still getting familiar with the codebase, there may be rough edges I've missed. I'd appreciate any guidance on the following directions I'm interested in exploring next:

• Convex world — implementing a new world for convex.
• Observability improvements — continuing to expand test coverage, refactoring, and improving latency in the web package

Would love to know if either of these aligns with the project's priorities!