![\"canc](\"https://raw.githubusercontent.com/cancjs/canc/master/assets/canc-logo.svg\" "\\"canc"){kind=logo}
\n \n \nAxios instances whose request methods return cancelable promises.\n
\n\n---\n\n## Introduction\n\nA drop-in replacement for the axios default export whose request methods return a\n`CancelablePromise`. Calling `.cancel()` aborts the request and rejects with a `CancelError`, so\ncancellation reads as an ordinary rejection in `try`/`catch`.\n\nThe wrapper holds no state of its own. It forwards to a real axios instance, so config merging,\nheader handling, interceptor chains and `create()` seeding are still axios's own code.\n\n## Features\n\n- same call shapes and signatures as axios, including the full `AxiosResponse` result\n- `.cancel()` aborts the in-flight request through an AbortSignal\n- cancellation is supported through the full request lifecycle, including interceptors\n- a caller-supplied `config.signal` also rejects with a `CancelError`\n- instances from `create()` are wrapped too, with their own defaults and interceptors\n- works with the xhr, http and fetch adapters, and with axios 0.22 and up\n- no Proxy, ES5-friendly output\n\n## Getting Started\n\n### Installation\n\n```sh\nnpm install @cancjs/axios axios @cancjs/promise\n```\n\n`axios` (0.22 or later) and `@cancjs/promise` are peer dependencies. This package is ecosystem\ntier: a minor release can carry a breaking change, so pin it with a tilde, `~1.4` (pin the minor, not\n`~1.x`, which npm expands to the same range as `^1`), rather than the default caret. See\n[Versioning](https://github.com/cancjs/canc/blob/master/docs/versioning.md) for the full policy.\n\n### Usage\n\n```js\nimport cancelableAxios from '@cancjs/axios';\nimport { isCancelError } from '@cancjs/promise';\n\nconst promise = cancelableAxios.get('/issues', { params: { q: 'bug' } });\n\npromise.cancel('superseded');\n\ntry {\n const response = await promise;\n console.log(response.data);\n} catch (error) {\n if (isCancelError(error)) {\n // the request was aborted\n }\n}\n```\n\nAn instance keeps its own defaults and interceptors, exactly like `axios.create()`:\n\n```js\nconst api = cancelableAxios.create({ baseURL: 'https://api.example.com' });\n\napi.defaults.headers.common['Authorization'] = 'Bearer token';\n```\n\nThe default export and the named `cancelableAxios` export are the same binding, so\n`import cancelableAxios from '@cancjs/axios'` and `import { cancelableAxios } from '@cancjs/axios'`\ngive you the identical object. Pick whichever reads better next to your existing axios import.\n\nAn axios instance built elsewhere can be wrapped instead:\n\n```js\nimport axios from 'axios';\nimport { cancelableAxios } from '@cancjs/axios';\n\nconst axiosInstance = axios.create({ baseURL: 'https://api.example.com' });\nconst api = cancelableAxios.wrap(axiosInstance);\n```\n\nIn a coroutine the request joins the surrounding cancellation:\n\n```ts\nimport * as canc from '@cancjs/coroutine';\n\nconst loadIssues = canc.async(function* (query: string) {\n const response = yield* canc.await(\n api.get('/issues', { params: { q: query } })\n );\n return response.data;\n});\n\nconst pending = loadIssues('bug');\npending.cancel(); // aborts the request\n```\n\n## How It Works\n\nEach request method (`get`, `post`, `put` and the rest) creates its own `AbortController`, merges\nthe signal into the request config, and returns a `CancelablePromise`. Canceling the promise\naborts that controller, so axios handles the transport-level abort through whichever adapter it is\nusing (xhr, http or fetch).\n\nCancellation is supported through the full lifecycle of a request, not just the network call.\nWhen a request is canceled, interceptors that are still running are canceled too. An interceptor\nthat returns a cancelable promise has that promise canceled along with the request, so work\nstarted in an interceptor (a token refresh, a retry) does not keep going after the caller has\nwalked away.\n\nAn existing `config.signal` from the caller is composed with the internal one. Either source can\nabort the request, and in both cases the promise rejects with a `CancelError`, normalizing the\nerror regardless of which signal aborted.\n\nThe wrapper holds no state beyond what axios itself holds. `defaults` on the wrapper is a live\naccessor onto the underlying instance's defaults, and `interceptors` is a facade over the real\ninterceptor managers, so IDs stay valid and interceptors added directly on the underlying instance\nstill run. `create()` returns another wrapped instance with its own defaults and interceptors, and\n`wrap()` wraps an existing axios instance without creating a new one.\n\n## Description\n\n### Interceptors\n\nInterceptors receive a second argument carrying the cancellation context of the request they run\nfor. The context exposes `signal`, `isCanceled()`, `cancel()` and `link(promise)`:\n\n```js\napi.interceptors.request.use((config, ctx) => {\n if (ctx.isCanceled()) {\n return config;\n }\n\n return refreshToken({ signal: ctx.signal }).then((token) => {\n config.headers.Authorization = `Bearer ${token}`;\n return config;\n });\n});\n```\n\nA cancelable promise returned from an interceptor is canceled along with the request. In the\nexample above, if the request is canceled while the token refresh is in flight, the refresh\npromise is canceled too. `ctx.link(promise)` explicitly ties any cancelable promise to the\nrequest's lifecycle, so work started outside the return path is still canceled with the request.\n\n### Combinators\n\n`all` differs from `axios.all` on purpose: it builds a `CancelablePromise`, so canceling one\nrequest rejects the aggregate and cancels the rest. `spread` is unchanged.\n\n### Accessing the underlying instance\n\nThe wrapped instance is reachable as `.axios` when a plain native promise is needed, for example\nwhen handing a request to code that does not understand cancellation.\n\n## API\n\n`cancelableAxios` is both the default export and a named export (both references point to the same instance). It mirrors the full axios\ninterface: `request`, `get`, `delete`, `head`, `options`, `post`, `put`, `patch`, `getUri`,\n`create`, `defaults`, `interceptors`, `all`, `spread`.\n\n`cancelableAxios.create(config?)` returns a new wrapped instance.\n\n`cancelableAxios.wrap(axiosInstance)` and `wrapAxios(axiosInstance)` wrap an existing axios instance. The argument is\nstructurally typed, so it accepts instances from any axios version without type conflicts.\n\n`CancelScope` is the per-request cancellation scope class managing request lifecycle and interceptor promises.\n\n`.axios` on any wrapped instance returns the underlying axios instance.\n\nMembers axios added after 0.22 (`postForm`, `putForm`, `patchForm`, `AxiosHeaders`, `HttpStatusCode` and the rest) plus standard axios exports (`AxiosError`, `CancelToken`, `CanceledError`, `isAxiosError`, `VERSION`, `formToJSON`, `getAdapter`, `mergeConfig`, `toFormData`) are re-exported.\n\n## Compatibility\n\nAxios 0.22 and later, which is when signal support was added. Node.js 18 and later, current\nbrowsers. Everything else follows\n[`@cancjs/promise`](https://github.com/cancjs/canc/tree/master/packages/canc-promise#compatibility).\n\n## Documentation\n\n- [`@cancjs/promise`](https://github.com/cancjs/canc/tree/master/packages/canc-promise) for the\n cancellation model\n- [Coroutines](https://github.com/cancjs/canc/tree/master/packages/canc-coroutine) for using\n axios inside a cancelable flow\n- [Examples](https://github.com/cancjs/canc/tree/master/examples): `app-axios` for a side-by-side\n comparison against a manual request registry\n- [Repository](https://github.com/cancjs/canc) for the ecosystem overview\n\n## Contributing\n\nYou are welcome to participate through issues and pull requests!\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}