\n\n`feature-fetch` turns `fetch` into a typed API client with explicit success and error branches. Requests return tuple results instead of throwing, TypeScript checks request shapes, and built-in or custom `.with()` features add REST helpers, OpenAPI, GraphQL, retry, cache, auth, or tracing without changing the client model.\n\n- Handle network errors, HTTP errors, and client errors without `try/catch`\n- Add REST helpers, OpenAPI types, GraphQL, retry, cache, or delay only when needed\n- Catch unknown OpenAPI paths, missing params, and wrong bodies at compile time\n- Move auth, logging, tracing, and other cross-cutting behavior into client features\n\n```ts\nimport { createApiFetchClient, retryFeature } from 'feature-fetch';\n\nconst api = createApiFetchClient({\n baseUrl: 'https://api.example.com/v1'\n}).with(retryFeature({ maxRetries: 3 }));\n\nconst [isPostOk, postErr, post] = await api.get<{ id: string; title: string }>('/posts/{postId}', {\n pathParams: { postId: '123' }\n});\n\nif (!isPostOk) {\n console.error(postErr.message); // NetworkError | HttpError | FetchError\n} else {\n console.log(post.title); // typed as { id: string; title: string }\n}\n```\n\nMigrating from `0.0.x`? See [MIGRATION.md](./MIGRATION.md).\n\n## Install\n\n```bash\nnpm install feature-fetch\n```\n\n## Usage\n\nPick the client that matches your API shape:\n\n- `createApiFetchClient`: REST endpoints without generated schema types\n- `createOpenApiFetchClient`: REST endpoints typed from an OpenAPI schema\n- `createGraphQLFetchClient`: GraphQL endpoints with operation and variable types\n\nFor REST endpoints, start with `createApiFetchClient`:\n\n```ts\nimport { createApiFetchClient } from 'feature-fetch';\n\nconst api = createApiFetchClient({\n baseUrl: 'https://api.example.com/v1'\n});\n\nconst [isPostOk, postErr, post] = await api.get<{ id: string; title: string }>('/posts/{postId}', {\n pathParams: { postId: '123' }\n});\n\nif (!isPostOk) {\n console.error(postErr.message);\n} else {\n console.log(post.title);\n}\n```\n\nFor OpenAPI schemas, generate a `paths` type and pass it to `createOpenApiFetchClient`:\n\n```ts\nimport { createOpenApiFetchClient } from 'feature-fetch';\nimport type { paths } from './schema';\n\nconst api = createOpenApiFetchClient({\n baseUrl: 'https://api.example.com/v1'\n});\n\nconst [isPetOk, petErr, pet] = await api.get('/pets/{petId}', {\n pathParams: { petId: 123 }\n});\n\nif (!isPetOk) {\n throw petErr;\n}\n\nconsole.log(pet);\n```\n\nFor GraphQL endpoints, use `createGraphQLFetchClient`:\n\n```ts\nimport { createGraphQLFetchClient, gql } from 'feature-fetch';\n\nconst graphql = createGraphQLFetchClient({\n baseUrl: 'https://api.example.com/graphql'\n});\n\nconst getUser = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n }\n }\n`;\n\nconst [isUserOk, userErr, userResult] = await graphql.query<\n { user: { id: string; name: string } },\n { id: string }\n>(getUser, { variables: { id: '123' } });\n\nif (!isUserOk) {\n throw userErr;\n}\n\nconsole.log(userResult.user.name);\n```\n\nCompose features with `createFetchClient` when you want control over which features are installed and in what order:\n\n```ts\nimport { apiFeature, cacheFeature, createFetchClient, retryFeature } from 'feature-fetch';\n\nconst api = createFetchClient({\n baseUrl: 'https://api.example.com/v1'\n}).with(apiFeature(), cacheFeature({ maxAgeMs: 30_000 }), retryFeature());\n```\n\n## Client\n\n### `createFetchClient(options)`\n\nCreates a base fetch client with a single `request()` method. All built-in features build on top of this method.\n\n```ts\nconst client = createFetchClient({\n baseUrl: 'https://api.example.com'\n});\n\nconst [isHealthOk, healthErr, health] = await client.request<{ status: string }>('GET', '/health');\n\nif (!isHealthOk) {\n throw healthErr;\n}\n\nconsole.log(health.data.status);\n```\n\n| Option | Default | Description |\n| ----------------- | ---------------------- | ------------------------------------------------------------------- |\n| `baseUrl` | `''` | Prepended to every request path |\n| `headers` | `{}` | Default headers applied to every request |\n| `fetch` | `globalThis.fetch` | Custom fetch implementation |\n| `requestInit` | `{}` | Default `RequestInit` values except `body`, `method`, and `headers` |\n| `pathSerializer` | `serializePathParams` | Serializes `{path}` parameters |\n| `querySerializer` | `serializeQueryParams` | Serializes query parameters |\n| `bodySerializer` | `serializeBody` | Serializes request bodies |\n| `prepareRequest` | `[]` | Hooks called before URL and body are built |\n| `prepareResponse` | `[]` | Hooks called after a response is received, before parsing |\n| `middleware` | `[]` | Wrappers around the final fetch call |\n\n**Request options**\n\nEach call to `request()` and the method helpers from installed features accept these core options:\n\n| Option | Default | Description |\n| ------------- | -------- | --------------------------------------------------------------------------------- |\n| `pathParams` | `{}` | Values for `{param}` placeholders in the path |\n| `queryParams` | `{}` | Appended to the URL as a query string |\n| `headers` | | Per-request headers merged after client defaults. `null` removes a default header |\n| `parseAs` | `'json'` | Response parser: `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'stream'` |\n| `signal` | | `AbortSignal` for cancellation |\n| `meta` | `{}` | Request-scoped metadata passed to `prepareRequest` and `prepareResponse` hooks |\n| `middleware` | `[]` | Request-scoped middleware appended after client middleware |\n| `baseUrl` | | Overrides the client base URL for this request |\n| `requestInit` | | Overrides native `RequestInit` values except `body`, `method`, and `headers` |\n\n`request()` and body-capable helpers also accept `body` and `bodySerializer`. Non-body REST helpers and OpenAPI operations without a request body reject body-specific options.\n\nThe REST, OpenAPI, and GraphQL helpers also accept `withResponse: true` when you need the raw `Response` on the success branch.\n\n`FormData` bodies automatically have `Content-Type` removed so the browser can add the required multipart boundary.\n\n## Built-in Features\n\n### `apiFeature()`\n\nAdds typed HTTP method helpers: `get`, `post`, `put`, `patch`, `delete`, `options`, `head`, and `trace`.\n\n```ts\nimport { apiFeature, createFetchClient } from 'feature-fetch';\n\nconst api = createFetchClient({ baseUrl: '/api' }).with(apiFeature());\n\nconst [isPostOk, postErr, post] = await api.post<{ id: string }>('/posts', {\n body: { title: 'Hello' }\n});\n\nif (!isPostOk) {\n throw postErr;\n}\n\nconsole.log(post.id);\n\nawait api.delete('/posts/{postId}', { pathParams: { postId: '123' } });\n```\n\n`createApiFetchClient(options)` is shorthand for `createFetchClient(options).with(apiFeature())`.\n\n### `openApiFeature()`\n\nAdds HTTP helpers fully typed from an OpenAPI schema. Unknown paths, missing required params, wrong bodies, and unexpected fields are rejected at compile time.\n\nGenerate the `paths` type from your schema:\n\n```bash\nnpx openapi-typescript ./schema.yaml -o ./schema.d.ts\n```\n\n```ts\nimport { createOpenApiFetchClient } from 'feature-fetch';\nimport type { paths } from './schema';\n\nconst api = createOpenApiFetchClient({\n baseUrl: 'https://api.example.com/v1'\n});\n\nconst [isPetOk, petErr, pet] = await api.get('/pets/{petId}', {\n pathParams: { petId: 123 }\n});\n\nif (!isPetOk) {\n throw petErr;\n}\n\nconst [isCreated, createErr, created] = await api.post('/pets', {\n body: { name: 'Jeff', photoUrls: [] }\n});\n\nif (!isCreated) {\n throw createErr;\n}\n\nconsole.log(pet, created);\n```\n\nSchema-declared header parameters are typed in `headers`. Extra transport headers such as `Authorization` remain allowed alongside them.\n\n`createOpenApiFetchClient(options)` is shorthand for `createFetchClient(options).with(openApiFeature())`.\n\n### `graphqlFeature()`\n\nAdds `query()`, `mutate()`, and raw variants for GraphQL POST requests. Set `baseUrl` to the full GraphQL endpoint.\n\n```ts\nimport { createGraphQLFetchClient, gql } from 'feature-fetch';\n\nconst graphql = createGraphQLFetchClient({\n baseUrl: 'https://api.example.com/graphql'\n});\n\nconst getUser = gql`\n query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n }\n }\n`;\n\nconst [isUserOk, userErr, userResult] = await graphql.query<\n { user: { id: string; name: string } },\n { id: string }\n>(getUser, { variables: { id: '123' } });\n\nif (!isUserOk) {\n throw userErr;\n}\n\nconsole.log(userResult.user.name);\n```\n\n`query()` and `mutate()` return operation data by default and unwrap GraphQL `errors` arrays into a `GraphQLError` on the error branch. Pass `withResponse: true` to receive `{ data, extensions?, response }`, or use `queryRaw()` and `mutateRaw()` to receive the raw `{ data, errors, extensions }` response without that unwrapping.\n\n`createGraphQLFetchClient(options)` is shorthand for `createFetchClient(options).with(graphqlFeature())`.\n\n### `retryFeature(options)`\n\nRetries failed requests. Network errors use exponential backoff. HTTP responses are retried when `shouldRetryResponse` returns `true`, defaulting to HTTP 429. Respects `Retry-After`, and uses `x-rate-limit-reset` when `x-rate-limit-remaining` is `0`.\n\n```ts\nimport { createApiFetchClient, retryFeature } from 'feature-fetch';\n\nconst api = createApiFetchClient({ baseUrl: '/api' }).with(retryFeature({ maxRetries: 3 }));\n```\n\n| Option | Default | Description |\n| -------------------------- | ---------- | --------------------------------------------- |\n| `maxRetries` | `3` | Number of retries after the initial request |\n| `networkError.baseDelayMs` | `1000` | Base delay in ms for exponential backoff |\n| `networkError.maxDelayMs` | `30000` | Maximum delay in ms for network-error backoff |\n| `shouldRetryResponse` | HTTP `429` | Predicate for retryable HTTP responses |\n\n### `cacheFeature(options)`\n\nCaches successful GET responses in memory. Respects `Cache-Control` response headers. Skips requests with `Authorization` or `Cookie` headers to avoid mixing user-specific responses.\n\n```ts\nimport { cacheFeature, createApiFetchClient } from 'feature-fetch';\n\nconst api = createApiFetchClient({ baseUrl: '/api' }).with(cacheFeature({ maxAgeMs: 30_000 }));\n\n// Clear all cached responses\napi.cache.clear();\n\n// Invalidate entries matching a predicate\napi.cache.invalidate((key) => key.includes('/posts'));\n```\n\n| Option | Default | Description |\n| ------------- | ------------------------- | ----------------------------------------------------------------------------------------- |\n| `maxAgeMs` | `300000` (5 minutes) | Maximum age in milliseconds |\n| `getCacheKey` | GET URL, no auth headers | Returns the cache key for a request, or `null` to skip caching |\n| `shouldCache` | OK, non-private responses | Returns whether a response should be cached. Skips `no-store`, `no-cache`, and `private`. |\n\nThe default cache also skips `requestInit.cache: 'no-store' | 'reload'` and responses with `Set-Cookie`.\n\n### `delayFeature(ms)`\n\nWaits the given number of milliseconds before forwarding each request. Useful in tests and demos.\n\n```ts\nimport { createApiFetchClient, delayFeature } from 'feature-fetch';\n\nconst api = createApiFetchClient({ baseUrl: '/api' }).with(delayFeature(500));\n```\n\n## Extending with Features\n\nFetch features are regular `feature-core` features. A feature can add new methods, push hooks or middleware into the client config, or both.\n\n```ts\nimport { defineFeature, type TFeature } from 'feature-core';\nimport type { TFetchClientBase } from 'feature-fetch';\n\nexport function authFeature(getToken: () => string): TAuthFeature {\n return defineFeature({\n key: 'auth',\n install(client: TFetchClientBase) {\n client._config.prepareRequest.push((cx) => {\n cx.headers.authorization = `Bearer ${getToken()}`;\n });\n\n return {};\n }\n });\n}\n\ntype TAuthFeature = TFeature<'auth', object>;\n```\n\nThree extension points are available in `_config`:\n\n- `prepareRequest`: hooks that mutate the request context before URL and body are built\n- `middleware`: wrappers around the final `fetch` call (receives the next function and returns a new one)\n- `prepareResponse`: hooks that can inspect or replace the raw response before parsing\n\nFeature order matters because middleware is applied outermost-first. Install `cacheFeature` before `retryFeature` so cache is checked first and the retry logic only runs on cache misses.\n\n## Results\n\nAll request methods return a `tuple-result`.\n\nUse the re-exported `Ok`, `Err`, and `TResult` when implementing custom methods that follow the same result contract. Import additional tuple utilities directly from `tuple-result`.\n\n## Errors\n\nThe error branch is one of three types:\n\n| Error | When it occurs |\n| -------------- | -------------------------------------------------------------------------- |\n| `NetworkError` | The fetch call threw before any HTTP response was received |\n| `HttpError` | The server returned a non-2xx response |\n| `FetchError` | Request preparation, serialization, middleware, or response parsing failed |\n\nGraphQL `errors` arrays return `GraphQLError`, which extends `FetchError`.\n\n```ts\nimport { FetchError, hasStatusCode, isHttpError, NetworkError } from 'feature-fetch';\n\nconst [isUserOk, userErr, user] = await api.get('/users/123');\n\nif (!isUserOk) {\n if (hasStatusCode(userErr, 404)) {\n console.error('Not found');\n } else if (userErr instanceof NetworkError) {\n console.error('Network error:', userErr.message);\n } else if (isHttpError(userErr)) {\n console.error('HTTP error:', userErr.status, userErr.data); // userErr.data is the parsed error body\n } else if (userErr instanceof FetchError) {\n console.error('Client error:', userErr.code, userErr.message); // userErr.code e.g. '#ERR_SERIALIZE_BODY'\n }\n}\n```\n\n`hasStatusCode(error, code)` checks `HttpError` instances and error-like objects with a numeric `status`. Use `isHttpError(error)` when you need the typed HTTP response body. Use `isGraphQLError(error)` when you need typed partial GraphQL operation data.\n\n## Examples\n\n- [Vanilla basic](https://github.com/builder-group/community/tree/develop/examples/feature-fetch/vanilla/basic)\n\n## FAQ\n\n### How does it compare to ky, openapi-fetch, and graphql-request?\n\n`feature-fetch` focuses on typed results and feature composition. Use it when you want one client model for REST, OpenAPI, GraphQL, retry, cache, auth, and custom transport behavior.\n\n- [ky](https://www.npmjs.com/package/ky): compact fetch wrapper with a polished request API\n- [openapi-fetch](https://www.npmjs.com/package/openapi-fetch): OpenAPI-first typed fetch client\n- [graphql-request](https://www.npmjs.com/package/graphql-request): focused GraphQL request client\n\n### How do I add auth headers to every request?\n\nPass static headers in the client options:\n\n```ts\nconst api = createApiFetchClient({\n baseUrl: 'https://api.example.com/v1',\n headers: { Authorization: 'Bearer ' }\n});\n```\n\nFor dynamic tokens that may change between requests, use a `prepareRequest` hook instead. See [Extending with Features](#extending-with-features) for an `authFeature` example that calls `getToken()` on each request.\n\n### What is the difference between `middleware` and `prepareRequest`?\n\nUse `prepareRequest` to mutate the structured request context: headers, path, query params, body, and metadata. It runs before the URL is built and before the body is serialized.\n\nUse `middleware` for transport-level concerns that wrap the fetch call itself: retry, caching, timing, and tracing. Middleware receives `(next) => (url, requestInit) => Promise` and can call `next` zero or more times.\n\nIf you need to read or modify the final URL or `RequestInit`, use middleware. If you need to modify request inputs in a structured way, use `prepareRequest`.\n\n### Can I type the error response body?\n\nYes. Pass it as the second generic parameter on an API request method. OpenAPI clients infer it from the operation's non-2xx response bodies.\n\n```ts\ninterface ApiError {\n code: string;\n message: string;\n}\n\nconst [isUserOk, userErr, user] = await api.get('/users/123');\n\nif (!isUserOk && isHttpError(userErr)) {\n console.error(userErr.data?.code); // data is typed as ApiError | undefined\n}\n```\n\n`userErr.data` is typed as `ApiError` when the error is an `HttpError`. It remains `unknown` for `NetworkError` and `FetchError`.\n\n### In what order should I install features?\n\nInstall features in the order you want them to intercept requests, outermost first. For common combinations:\n\n- `cacheFeature` before `retryFeature`: cache is checked first; retry only runs on cache misses\n- `retryFeature` before a logging middleware: retry attempts are each logged individually\n\nFeatures that add methods (`apiFeature`, `openApiFeature`, `graphqlFeature`) can go in any position relative to middleware features.\n\n### How do I mock requests in tests?\n\nPass a custom `fetch` function to `createFetchClient`. Return any `Response` you need:\n\n```ts\nconst api = createApiFetchClient({\n baseUrl: '/api',\n fetch: async () => new Response(JSON.stringify({ id: '1' }), { status: 200 })\n});\n```\n\nFor more control, use `delayFeature` in development or a mock server in integration tests.\n\n### How do I cancel a request?\n\nPass an `AbortSignal` in the request options:\n\n```ts\nconst controller = new AbortController();\n\nconst postsRequest = api.get('/posts', {\n signal: controller.signal\n});\n\n// Cancel from anywhere\ncontroller.abort();\n\nconst [isPostsOk, postsErr, posts] = await postsRequest;\n\nif (!isPostsOk) {\n console.error(postsErr.message);\n} else {\n console.log(posts);\n}\n```\n\nA cancelled request returns `NetworkError` on the error branch.\n\n### Why is `@0no-co/graphql.web` a dependency if GraphQL is opt-in?\n\n`@0no-co/graphql.web` is imported dynamically only when a `DocumentNode` input needs to be printed to a string. If you pass operation strings directly or never install `graphqlFeature()`, modern bundlers tree-shake that path out of the bundle.\n","readmeFilename":""}
![\"feature-fetch](\"https://raw.githubusercontent.com/builder-group/community/develop/packages/feature-fetch/.github/banner.svg\")
\n![\"GitHub](\"https://img.shields.io/github/license/builder-group/community.svg?label=license&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"NPM](\"https://img.shields.io/bundlephobia/minzip/feature-fetch.svg?label=minzipped%20size&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"NPM](\"https://img.shields.io/npm/dt/feature-fetch.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"Join](\"https://img.shields.io/discord/795291052897992724.svg?label=&logo=discord&logoColor=000000&color=293140&labelColor=FDE200\")
\n \n