{"id":13495819,"url":"https://github.com/kuitos/axios-extensions","last_synced_at":"2025-05-15T03:07:23.055Z","repository":{"id":41364446,"uuid":"105122051","full_name":"kuitos/axios-extensions","owner":"kuitos","description":"🍱 axios extensions lib, including throttle, cache, retry features etc...","archived":false,"fork":false,"pushed_at":"2024-06-25T08:25:57.000Z","size":323,"stargazers_count":837,"open_issues_count":19,"forks_count":49,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-13T21:52:17.501Z","etag":null,"topics":["axios","axios-adapter","axios-ecosystem","axios-extensions","axios-plugin","cache","http"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuitos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T08:23:09.000Z","updated_at":"2025-05-10T10:12:53.000Z","dependencies_parsed_at":"2024-10-09T13:39:29.138Z","dependency_job_id":"1005b3d5-f732-4345-a86f-08266801e318","html_url":"https://github.com/kuitos/axios-extensions","commit_stats":{"total_commits":97,"total_committers":9,"mean_commits":"10.777777777777779","dds":0.134020618556701,"last_synced_commit":"0b64fd7b155efe0fa65d1025da3ed04d65faef5f"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Faxios-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Faxios-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Faxios-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Faxios-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuitos","download_url":"https://codeload.github.com/kuitos/axios-extensions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264766,"owners_count":22041793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axios","axios-adapter","axios-ecosystem","axios-extensions","axios-plugin","cache","http"],"created_at":"2024-07-31T19:01:38.562Z","updated_at":"2025-05-15T03:07:18.013Z","avatar_url":"https://github.com/kuitos.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# axios-extensions\n\n[![npm version](https://img.shields.io/npm/v/axios-extensions.svg?style=flat-square)](https://www.npmjs.com/package/axios-extensions)\n[![coverage](https://img.shields.io/codecov/c/github/kuitos/axios-extensions.svg?style=flat-square)](https://codecov.io/gh/kuitos/axios-extensions)\n[![npm downloads](https://img.shields.io/npm/dt/axios-extensions.svg?style=flat-square)](https://www.npmjs.com/package/axios-extensions)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/kuitos/axios-extensions/ci.yml?branch=master\u0026style=flat-square)](https://github.com/kuitos/axios-extensions/actions/workflows/ci.yml)\n\nA non-invasive, simple, reliable collection of axios extension\n\n## Extension List\n*v3.x has a lot of api changes, if you are looking for v2.x doc, see [here](https://github.com/kuitos/axios-extensions/tree/v2.0.3)*\n\n*Not working with axios v0.19.0 as its custom config bug, See https://github.com/axios/axios/pull/2207.*   \n\n* [cacheAdapterEnhancer](#cacheadapterenhancer) makes request cacheable\n* [throttleAdapterEnhancer](#throttleadapterenhancer) makes GET requests throttled automatically\n* [retryAdapterEnhancer](#retryadapterenhancer) makes request retry with special times while it failed\n\n## Installing\n```bash\nnpm i axios-extensions -S\n```\nor\n```bash\nyarn add axios-extensions\n```\n\nor \n```html\n// exposed as window['axios-extensions']\n\u003cscript src=\"https://unpkg.com/axios-extensions/dist/axios-extensions.min.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\n```javascript\nimport axios from 'axios';\nimport { cacheAdapterEnhancer, throttleAdapterEnhancer } from 'axios-extensions';\n\n// enhance the original axios adapter with throttle and cache enhancer \nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\tadapter: throttleAdapterEnhancer(cacheAdapterEnhancer(axios.defaults.adapter))\n});\n```\n\n### Enable Logging\n\nIt is highly recommended to enable the request logging recorder in development environment(disabled by default).\n\n#### browser (webpack)\n```js\nnew webpack.DefinePlugin({\n  'process.env.LOGGER_LEVEL': JSON.stringify('info')\n})\n```\n#### node\n```json\n// package.json\n\"scripts\": {\n\t\"start\": \"cross-env LOGGER_LEVEL=info node server.js\"\n}\n```\n\n## API\n\n### cacheAdapterEnhancer\n\n\u003e Makes axios cacheable\n\n```typescript\ncacheAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter\n```\n\nWhere `adapter` is an axios adapter which following the [axios adapter standard](https://github.com/axios/axios/blob/master/lib/adapters/README.md), `options` is an optional that configuring caching: \n\n| Param            | Type | Default value                            | Description                                                  |\n| ---------------- | ---------------------------------------- | ------------------------------------------------------------ | ---- |\n| enabledByDefault | boolean                              | true | Enables cache for all requests without explicit definition in request config (e.g. `cache: true`) |\n| cacheFlag        | string                            | 'cache' | Configures key (flag) for explicit definition of cache usage in axios request |\n| defaultCache     | CacheLike | \u003cpre\u003enew LRUCache({ maxAge: FIVE_MINUTES, max: 100 })\u003c/pre\u003e | a CacheLike instance that will be used for storing requests by default, except you define a custom Cache with your request config |\n\n`cacheAdapterEnhancer` enhances the given adapter and returns a new cacheable adapter back, so you can compose it with any other enhancers, e.g.  `throttleAdapterEnhancer`.\n\n#### basic usage\n\n```javascript\nimport axios from 'axios';\nimport { cacheAdapterEnhancer } from 'axios-extensions';\n\nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\t// cache will be enabled by default\n\tadapter: cacheAdapterEnhancer(axios.defaults.adapter)\n});\n\nhttp.get('/users'); // make real http request\nhttp.get('/users'); // use the response from the cache of previous request, without real http request made\nhttp.get('/users', { cache: false }); // disable cache manually and the the real http request invoked\n```\n\n#### custom cache flag\n\n```javascript\nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\t// disable the default cache and set the cache flag\n\tadapter: cacheAdapterEnhancer(axios.defaults.adapter, { enabledByDefault: false, cacheFlag: 'useCache'})\n});\n\nhttp.get('/users'); // default cache was disabled and then the real http request invoked \nhttp.get('/users', { useCache: true }); // make the request cacheable(real http request made due to first request invoke)\nhttp.get('/users', { useCache: true }); // use the response cache from previous request\n```\n\n##### custom cache typing\n\nNote that if you are using custom cache flag and typescript, you may need to add the typing declaration like below:\n\n```ts\nimport { ICacheLike } from 'axios-extensions';\ndeclare module 'axios' {\n  interface AxiosRequestConfig {\n    // if your cacheFlag was setting to 'useCache'\n    useCache?: boolean | ICacheLike\u003cany\u003e;\n  }\n}\n```\n\n#### more advanced\n\nBesides configuring the request through the `cacheAdapterEnhancer`, we can enjoy more advanced features via configuring every individual request.\n\n```js\nimport axios from 'axios';\nimport { cacheAdapterEnhancer, Cache } from 'axios-extensions';\n\nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\t// disable the default cache\n\tadapter: cacheAdapterEnhancer(axios.defaults.adapter, { enabledByDefault: false })\n});\n\nhttp.get('/users', { cache: true }); // make the request cacheable(real http request made due to first request invoke)\n\n// define a cache manually\nconst cacheA = new Cache();\n// or a cache-like instance\nconst cacheB = { get() {/*...*/}, set() {/*...*/}, del() {/*...*/} };\n\n// two actual request will be made due to the different cache \nhttp.get('/users', { cache: cacheA });\nhttp.get('/users', { cache: cacheB });\n\n// a actual request made and cached due to force update configured\nhttp.get('/users', { cache: cacheA, forceUpdate: true });\n```\n\n*Note: If you are using typescript, do not forget to enable `\"esModuleInterop\": true` and `\"allowSyntheticDefaultImports\": true` for better development experience.*\n\n### throttleAdapterEnhancer\n\n\u003e Throttle GET requests most once per threshold milliseconds\n\n```ts\nthrottleAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter\n```\n\nWhere `adapter` is an axios adapter which following the [axios adapter standard](https://github.com/axios/axios/blob/master/lib/adapters/README.md), `options` is an optional object that configuring throttling: \n\n| Param     | Type |Default value               | Description                                                  |\n| --------- | ---- |--------------------------- | ------------------------------------------------------------ |\n| threshold | number |1000                        | The number of milliseconds to throttle request invocations to |\n| cache     | CacheLike |\u003cpre\u003enew LRUCache({ max: 10 })\u003c/pre\u003e | CacheLike instance that will be used for storing throttled requests |\n\nBasically we recommend using the `throttleAdapterEnhancer` with `cacheAdapterEnhancer` together for the maximum caching benefits.\nNote that POST and other methods besides GET are not affected. \n\n```js\nthrottleAdapterEnhancer(cacheAdapterEnhancer(axios.defaults.adapter))\n```\n\nCheck [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/) to learn more details about throttle and how it differs from debounce.\n\n#### basic usage\n\n```js\nimport axios from 'axios';\nimport { throttleAdapterEnhancer } from 'axios-extensions';\n\nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\tadapter: throttleAdapterEnhancer(axios.defaults.adapter, { threshold: 2 * 1000 })\n});\n\nhttp.get('/users'); // make real http request\nhttp.get('/users'); // responsed from the cache\nhttp.get('/users'); // responsed from the cache\n\nsetTimeout(() =\u003e {\n\thttp.get('/users'); // after 2s, the real request makes again\n}, 2 * 1000);\n```\n\n### retryAdapterEnhancer\n\n\u003e Retry the failed request with special times\n\n```ts\nretryAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter\n```\n\nWhere `adapter` is an axios adapter which following the [axios adapter standard](https://github.com/axios/axios/blob/master/lib/adapters/README.md), `options` is an optional that configuring caching: \n| Param            | Type | Default value                            | Description                                                  |\n| ---------------- | ---------------------------------------- | ------------------------------------------------------------ | ---- |\n| times | number                         | 2 | Set the retry times for failed request globally. |\n\n#### basic usage\n\n```ts\nimport axios from 'axios';\nimport { retryAdapterEnhancer } from 'axios-extensions';\n\nconst http = axios.create({\n\tbaseURL: '/',\n\theaders: { 'Cache-Control': 'no-cache' },\n\tadapter: retryAdapterEnhancer(axios.defaults.adapter)\n});\n\n// this request will retry two times if it failed\nhttp.get('/users');\n\n// you could also set the retry times for a special request\nhttp.get('/special', { retryTimes: 3 });\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuitos%2Faxios-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuitos%2Faxios-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuitos%2Faxios-extensions/lists"}