diff --git a/README.md b/README.md index be64b36..4a2eb35 100644 --- a/README.md +++ b/README.md @@ -79,10 +79,10 @@ Axios Cache Interceptor ```ts import axios from 'axios'; -import { createCache, SessionCacheStorage } from 'axios-cache-interceptor'; +import { setupCache, SessionCacheStorage } from 'axios-cache-interceptor'; // An axios instance with modified types -const api = createCache(axios.create(), { +const api = setupCache(axios.create(), { /* options */ }); @@ -107,6 +107,7 @@ const resp2 = await api.get('https://api.example.com/'); - [Support list](#support-list) - [Getting Started](#getting-started) - [Compiled code](#compiled-code) +- [Typescript users](#typescript-users) - [Basic Knowledge](#basic-knowledge) - [Request id](#request-id) - [Response object](#response-object) @@ -158,9 +159,9 @@ yarn add axios axios-cache-interceptor ``` ```js -const { createCache } = require('axios-cache-interceptor'); +const { setupCache } = require('axios-cache-interceptor'); // or -import { createCache } from 'axios-cache-interceptor'; +import { setupCache } from 'axios-cache-interceptor'; ``` ### Via CDN @@ -182,7 +183,7 @@ import { createCache } from 'axios-cache-interceptor'; ``` ```js -const { createCache } = window.AxiosCacheInterceptor; +const { setupCache } = window.AxiosCacheInterceptor; ```
@@ -197,9 +198,9 @@ by axios was it's types.** | [Version](https://github.com/ArthurFiorette/axios-cache-interceptor/releases) | [Axios](https://github.com/axios/axios/releases) | | ----------------------------------------------------------------------------- | ------------------------------------------------ | -| `>= v0.5` | `>= v0.24` | -| `~ v0.4` | `>= v0.23` | -| `~ v0.3` | `>= v0.22` | +| `>= v0.5` | `>= v0.24` | +| `~ v0.4` | `>= v0.23` | +| `~ v0.3` | `>= v0.22` | | `<= v0.2` | `v0.21` |
@@ -210,35 +211,37 @@ To you use this cache interceptor, you can apply to an existing instance or crea one. ```js -import { createCache } from 'axios-cache-interceptor'; +import { setupCache } from 'axios-cache-interceptor'; // Your axios instance let axios; // Return the same axios instance, but with a modified Typescript type. -axios = createCache(axios, { +axios = setupCache(axios, { /* options here */ }); ``` After that, you can made your own requests normally, as this library respects axios API. -Afterwards, the only thing you may need to configure is per-request configuration, you can change them with the `cache` property. +Afterwards, the only thing you may need to configure is per-request configuration, you can +change them with the `cache` property. ```js -import { createCache } from 'axios-cache-interceptor'; +import { setupCache } from 'axios-cache-interceptor'; // Your axios-cache-interceptor instance let axios; axios.get('url', { cache: { - /** options here */ + /** Options here */ } -}) +}); ``` -You will get syntax highlighting for all options and what they do. But you can also read here: [Per-request configuration](#per-request-configuration). +You will get syntax highlighting for all options and what they do. But you can also read +here: [Per-request configuration](#per-request-configuration).
@@ -257,6 +260,48 @@ the dist with lower ecma script versions.
+## Typescript users + +This package does not pollute the global axios typings. Instead, the `setupCache` returns +the same axios instance but with **extended** typings. + +```ts +const axios = axios.create(); +axios === setupCache(axios, {}); +``` + +In this way, we recommend you to not use a global axios instance with typescript, so you +can use all exported types from `axios-cache-interceptor` by creating a new variable. + +```ts +import Axios from 'axios'; +import { setupCache, AxiosCacheInstance } from 'axios-cache-interceptor'; + +// instance will have our custom typings from the return of this function +const instance = setupCache( + Axios.create({ + // Axios options + }), + { + // Axios-cache-interceptor options + } +); + +// OR + +const instance = axios.create({ + // Axios options +}) as AxiosCacheInstance; + +// As this functions returns the same axios instance but only with +// different typings, you can ignore the function return. +setupCache(instance, { + // Axios-cache-interceptor options +}); +``` + +
+ ## Basic Knowledge ### Request id @@ -313,7 +358,7 @@ the internal code. Remember that, depending on the When applying the interceptor, you can customize some properties: ```js -const axios = createCache(axios, { +const axios = setupCache(axios, { // Properties here }); ``` diff --git a/examples/runkit.js b/examples/runkit.js index 31027ab..a22f814 100644 --- a/examples/runkit.js +++ b/examples/runkit.js @@ -1,37 +1,28 @@ /* eslint-disable @typescript-eslint/no-var-requires */ -const Axios = require('axios'); -const { createCache } = require('axios-cache-interceptor'); +const { create: createAxios } = require('axios').default; +const { setupCache } = require('../dist'); async function main() { - const axios = Axios.create({ - baseUrl: 'https://api.github.com' - }); + const axios = setupCache( + // creating axios instance + createAxios({ + baseUrl: 'https://registry.npmjs.org/' + }), - /** - * The same instance of the previous axios, but has custom Typescript types to better intellisense - * - * @example - * - * ```js - * axios === axiosWithCache; - * ``` - */ - const axiosWithCache = createCache(axios, { - ttl: 99999, + // configuring the cache + { + ttl: 99999, - // Parse the Cache-Control header to determine the cache strategy - interpretHeader: true - }); - - const fetchedResponse = await axiosWithCache.get( - 'https://registry.npmjs.org//axios-cache-interceptor' + // Parse the Cache-Control header to determine the cache strategy + interpretHeader: true + } ); + const fetchedResponse = await axios.get('/axios-cache-interceptor'); + // This won't made a network request, because the response is already cached - const cachedResponse = await axiosWithCache.get( - 'https://registry.npmjs.org//axios-cache-interceptor' - ); + const cachedResponse = await axios.get('/axios-cache-interceptor'); console.log('First request was cached?'); console.log(fetchedResponse.cached, '\n'); @@ -45,7 +36,7 @@ async function main() { console.log('And also the received Age header'); console.log(fetchedResponse.headers['age'], '\n'); - const cacheInformation = await axiosWithCache.storage.get(fetchedResponse.id); + const cacheInformation = await axios.storage.get(fetchedResponse.id); console.log( 'As you can see, the TTL used was the maxAge cache directive minus the Age header', @@ -59,19 +50,16 @@ async function main() { ); // Remove the old cache by brute force - await axiosWithCache.storage.remove(fetchedResponse.id); + await axios.storage.remove(fetchedResponse.id); - const refetchedResponse = await axiosWithCache.get( - 'https://registry.npmjs.org//axios-cache-interceptor', - { - cache: { - // This time with interpretHeader disabled - interpretHeader: false - } + const refetchedResponse = await axios.get('/axios-cache-interceptor', { + cache: { + // This time with interpretHeader disabled + interpretHeader: false } - ); + }); - const refetchedInformation = await axiosWithCache.storage.get(refetchedResponse.id); + const refetchedInformation = await axios.storage.get(refetchedResponse.id); console.log('Third request TTL:'); console.log(refetchedInformation.ttl); diff --git a/src/cache/create.ts b/src/cache/create.ts index 3e592ef..fb50156 100644 --- a/src/cache/create.ts +++ b/src/cache/create.ts @@ -12,11 +12,40 @@ export type CacheOptions = Partial & Partial; /** * Apply the caching interceptors for a already created axios instance. * + * @example + * + * ```ts + * import Axios from 'axios'; + * import { setupCache, AxiosCacheInstance } from 'axios-cache-interceptor'; + * + * // instance will have our custom typings from the return of this function + * const instance = setupCache( + * Axios.create({ + * // Axios options + * }), + * { + * // Axios-cache-interceptor options + * } + * ); + * + * // OR + * + * const instance = axios.create({ + * // Axios options + * }) as AxiosCacheInstance; + * + * // As this functions returns the same axios instance but only with + * // different typings, you can ignore the function return. + * setupCache(instance, { + * // Axios-cache-interceptor options + * }); + * ``` + * * @param axios The already created axios instance * @param config The config for the caching interceptors - * @returns The same instance but with caching enabled + * @returns The same instance with better typescript types. */ -export function createCache( +export function setupCache( axios: AxiosInstance, { storage, @@ -61,12 +90,7 @@ export function createCache( return axiosCache; } -/** - * Apply the caching interceptors for a already created axios instance. - * - * @deprecated Prefer {@link createCache} - * @param axios The already created axios instance - * @param config The config for the caching interceptors - * @returns The same instance but with caching enabled - */ -export const useCache = createCache; +/** @deprecated */ +export const useCache = setupCache as unknown as 'use setupCache instead'; +/** @deprecated */ +export const createCache = setupCache as unknown as 'use setupCache instead'; diff --git a/src/index.browser.ts b/src/index.browser.ts index 78cf44c..a5fca9f 100644 --- a/src/index.browser.ts +++ b/src/index.browser.ts @@ -1,6 +1,6 @@ /** Index file for webpack and cdn usage */ -export { createCache, useCache } from './cache/create'; +export { createCache, setupCache, useCache } from './cache/create'; export { BrowserAxiosStorage } from './storage/browser'; export { MemoryAxiosStorage } from './storage/memory'; export { AxiosStorage } from './storage/storage'; diff --git a/src/interceptors/response.ts b/src/interceptors/response.ts index 37a0926..9463150 100644 --- a/src/interceptors/response.ts +++ b/src/interceptors/response.ts @@ -85,7 +85,7 @@ export class CacheResponseInterceptor ttl = expirationTime || expirationTime === 0 ? expirationTime : ttl; } - const data = CacheResponseInterceptor.createCacheData(response, cache.data); + const data = CacheResponseInterceptor.setupCacheData(response, cache.data); const newCache: CachedStorageValue = { state: 'cached', @@ -135,7 +135,7 @@ export class CacheResponseInterceptor * Creates the new date to the cache by the provided response. Also handles possible 304 * Not Modified by updating response properties. */ - static readonly createCacheData = ( + static readonly setupCacheData = ( response: CacheAxiosResponse, cache?: CachedResponse ): CachedResponse => { diff --git a/test/bundle.test.ts b/test/bundle.test.ts index ae47257..87179b3 100644 --- a/test/bundle.test.ts +++ b/test/bundle.test.ts @@ -1,4 +1,4 @@ -import { createCache } from '../src/cache/create'; +import { setupCache } from '../src/cache/create'; import { BrowserAxiosStorage } from '../src/storage/browser'; import { MemoryAxiosStorage } from '../src/storage/memory'; import { AxiosStorage } from '../src/storage/storage'; @@ -7,7 +7,7 @@ describe('test bundle imports', () => { it('should have basic storages', async () => { const bundle = await import('../src/index.browser'); - expect(bundle.createCache).toBe(createCache); + expect(bundle.setupCache).toBe(setupCache); expect(bundle.AxiosStorage).toBe(AxiosStorage); expect(bundle.BrowserAxiosStorage).toBe(BrowserAxiosStorage); expect(bundle.MemoryAxiosStorage).toBe(MemoryAxiosStorage); diff --git a/test/cache/create.test.ts b/test/cache/create.test.ts index c9649b9..3fd3f36 100644 --- a/test/cache/create.test.ts +++ b/test/cache/create.test.ts @@ -1,13 +1,13 @@ import Axios from 'axios'; -import { createCache } from '../../src/cache/create'; +import { setupCache } from '../../src/cache/create'; describe('tests header interpreter', () => { it('tests argument composition', () => { const axios = Axios.create(); - const withAxios = createCache(axios); + const withAxios = setupCache(axios); expect(withAxios).not.toBeUndefined(); - const withConfig = createCache(axios, { ttl: 1234 }); + const withConfig = setupCache(axios, { ttl: 1234 }); expect(withConfig).not.toBeUndefined(); expect(withConfig.defaults.cache.ttl).toBe(1234); }); diff --git a/test/mocks/axios.ts b/test/mocks/axios.ts index 5f81292..ca1fa8e 100644 --- a/test/mocks/axios.ts +++ b/test/mocks/axios.ts @@ -1,5 +1,5 @@ import Axios from 'axios'; -import { AxiosCacheInstance, CacheProperties, createCache } from '../../src'; +import { AxiosCacheInstance, CacheProperties, setupCache } from '../../src'; import type { CacheInstance } from '../../src/cache/cache'; import { Header } from '../../src/util/headers'; @@ -9,7 +9,7 @@ export function mockAxios( options: Partial & Partial = {}, responseHeaders: Record = {} ): AxiosCacheInstance { - const axios = createCache(Axios.create(), options); + const axios = setupCache(Axios.create(), options); // Axios interceptors are a stack, so apply this after the cache interceptor axios.interceptors.request.use((config) => {