Integration decisions
Use the least elaborate layer that matches the service you actually have. Move up when it removes repeated work you already maintain, and include its configuration and backend contract in the decision.
Direct, declarative, or generated clients
| Choice | Use when | What you own | Poor fit |
|---|---|---|---|
Direct Fetcher | A few calls or endpoint-specific behavior | Paths, request options, result selection, boundary validation | Many repeated endpoint declarations that drift independently |
| Decorator service | Stable methods benefit from a shared service declaration | Metadata/compiler setup, parameter annotations, endpoint accuracy | You do not want decorator configuration or the API is mostly ad hoc |
| Generated service | An actual OpenAPI document is the maintained contract | Generation command/configuration, review and compilation of output, regeneration on spec changes | Missing or inaccurate specification; server semantics absent from the document |
These share the runtime request boundary: core implements request/extraction (packages/fetcher/src/fetcher.ts:230), decorator has a metadata runtime dependency (packages/decorator/package.json:56), and generator is a CLI (packages/generator/src/cli.ts:8). OpenAPI exports type definitions (packages/openapi/src/index.ts:21). Neither annotations nor generated types validate response data at runtime or invent missing server semantics.
Start with HTTP requests, then use declarative client or the verified workflow in generated client. Configuration details live in decorator reference and generator reference. Check the peer graph separately from the code you expect to execute.
View, Viewer, or FetcherViewer
Maintenance mode (deprecated)
@ahoo-wang/fetcher-viewer is deprecated and in maintenance mode: existing functionality is maintained, with no new features. Further data-view development belongs to @ahoo-wang/fetcher-view-engine; use View Engine for new projects. This page remains a maintenance reference for existing consumers. The packages use different models and APIs, so migration requires adaptation.
| Choice | Data and state contract | Use when | Cost or mismatch |
|---|---|---|---|
View | Receives PagedList; emits interaction changes; optional controlled state | One table/view with application-owned data | Application must apply filtering, sorting, and pagination |
Viewer | Adds saved-view collection and selection; load/save callbacks go to application | Users switch/save views over your existing data service | Application implements persistence, errors, and success-callback timing |
FetcherViewer | Loads definitions/views and rows; sends Wow view commands through the defined backend protocol | Your service implements that protocol and identity model | Requires compatible endpoints and projection behavior; not a generic REST configuration widget |
The first two responsibilities follow packages/viewer/src/view/View.tsx:417 and packages/viewer/src/viewer/Viewer.tsx:140; remote row loading follows packages/viewer/src/fetcherviewer/hooks/useFetchData.ts:53. FetcherViewer creation/update confirmation and deletion have different scopes; review state and resources before promising saved results to users.
For a local table, use local data and implement pagination and sorting in the application. Add saved views when users need persistence. Adopt remote data only with the backend contract. Consult View/Viewer reference and FetcherViewer reference for props.
Service-specific integrations
| Integration | Required contract | Responsibility retained by the service/application |
|---|---|---|
| Wow | Command results/stages and supported query DSL | Authorization, tenant isolation, idempotency, projection freshness |
| CoSec | Token storage, attribution headers, refresh endpoints/session rules | Identity lifetime, replay safety, server authorization |
| SSE / OpenAI streaming | Compatible event stream and payload format | Partial-result UX, cancellation, reconnect policy if required |
Client-side conditions describe the query sent; they are not access control. Command stages describe protocol progress; they are not a universal consistency guarantee. CoSec's guarded refresh implementation is specific to its authentication exchange (packages/cosec/src/authorizationResponseInterceptor.ts:80), while SSE extraction requires a readable body (packages/eventstream/src/eventStreamResultExtractor.ts:38).
Continue with Wow, CoSec, and streaming. Before sharing these integrations across identities, read runtime support; before adding retries, read the failure model.