From 0199ad6b97566c2708f9cae60ae2d7d559b022ca Mon Sep 17 00:00:00 2001 From: Denis Rossati Date: Sun, 30 Jul 2023 00:22:16 -0300 Subject: [PATCH] feat: turn most types into interfaces (#615) * Turn most types into interfaces * Turn 'CacheAxiosResponse' into a interface * Update docs * Change docs to be more didactic --- docs/src/guide/interceptors.md | 24 ++++++++++++++++++++++++ src/cache/axios.ts | 15 ++++++++------- src/cache/cache.ts | 10 +++++++--- src/cache/create.ts | 2 +- src/interceptors/util.ts | 6 +++--- src/storage/build.ts | 4 ++-- src/storage/memory.ts | 4 ++-- src/storage/types.ts | 28 ++++++++++++++-------------- src/util/types.ts | 8 ++++---- 9 files changed, 65 insertions(+), 36 deletions(-) diff --git a/docs/src/guide/interceptors.md b/docs/src/guide/interceptors.md index fe57601..743ac30 100644 --- a/docs/src/guide/interceptors.md +++ b/docs/src/guide/interceptors.md @@ -36,3 +36,27 @@ axios.interceptors.request.use((req) => req); // This will be ran BEFORE the cache interceptor axios.interceptors.response.use((res) => res); ``` + +--- + +## Extending types + +When using axios-cache-interceptor, you'll note that it have a different type +than the defaults `AxiosInstance`, `AxiosRequestConfig` and `AxiosResponse`. +That's because was chosen to override axios's interfaces instead of extending, +to avoid breaking changes with other libraries. + +However, this also means that when integrating with other packages or creating +your own custom interceptor, you need to override/extend our own types, +`CacheInstance`, `CacheRequestConfig` and `CacheAxiosResponse` to match your needs. + +This can be done as shown below: + +```ts +declare module 'axios-cache-interceptor' { + interface CacheRequestConfig { + customProperty: string; + } +} +``` + diff --git a/src/cache/axios.ts b/src/cache/axios.ts index 8f82cd7..c6356b7 100644 --- a/src/cache/axios.ts +++ b/src/cache/axios.ts @@ -18,8 +18,8 @@ import type { CacheInstance, CacheProperties } from './cache'; * @template D The type that the request body was * @see https://axios-cache-interceptor.js.org/config/response-object */ -export type CacheAxiosResponse = AxiosResponse & { - config: CacheRequestConfig; +export interface CacheAxiosResponse extends AxiosResponse { + config: InternalCacheRequestConfig; /** * The [Request ID](https://axios-cache-interceptor.js.org/guide/request-id) used in @@ -46,7 +46,7 @@ export type CacheAxiosResponse = AxiosResponse & { * @see https://axios-cache-interceptor.js.org/config/response-object#cached */ cached: boolean; -}; +} /** * Options that can be overridden per request @@ -54,7 +54,7 @@ export type CacheAxiosResponse = AxiosResponse & { * @template R The type returned by this response * @template D The type for the request body */ -export type CacheRequestConfig = AxiosRequestConfig & { +export interface CacheRequestConfig extends AxiosRequestConfig { /** * The [Request ID](https://axios-cache-interceptor.js.org/guide/request-id) used in * this request. @@ -81,12 +81,13 @@ export type CacheRequestConfig = AxiosRequestConfig & { * @see https://axios-cache-interceptor.js.org/config/response-object#cache */ cache?: false | Partial>; -}; +} /** Cached version of type {@link InternalAxiosRequestConfig} */ -export type InternalCacheRequestConfig = CacheRequestConfig & { +export interface InternalCacheRequestConfig + extends CacheRequestConfig { headers: AxiosResponseHeaders; -}; +} /** * Same as the AxiosInstance but with CacheRequestConfig as a config type and diff --git a/src/cache/cache.ts b/src/cache/cache.ts index fbc9ef3..d578733 100644 --- a/src/cache/cache.ts +++ b/src/cache/cache.ts @@ -21,7 +21,7 @@ import type { CacheAxiosResponse, CacheRequestConfig } from './axios'; * @template R The type returned by this response * @template D The type for the request body */ -export type CacheProperties = { +export interface CacheProperties { /** * The time until the cached value is expired in milliseconds. * @@ -211,7 +211,7 @@ export type CacheProperties = { | CachedStorageValue | StaleStorageValue ) => void | Promise); -}; +} /** * These are properties that are used and shared by the entire application. @@ -342,4 +342,8 @@ export interface CacheInstance { * * @see https://axios-cache-interceptor.js.org/#/pages/development-mode */ -export type DebugObject = { id?: string; msg?: string; data?: unknown }; +export interface DebugObject { + id?: string; + msg?: string; + data?: unknown; +} diff --git a/src/cache/create.ts b/src/cache/create.ts index 197839f..6de3e34 100644 --- a/src/cache/create.ts +++ b/src/cache/create.ts @@ -8,7 +8,7 @@ import { defaultKeyGenerator } from '../util/key-generator'; import type { AxiosCacheInstance } from './axios'; import type { CacheInstance, CacheProperties } from './cache'; -export type CacheOptions = Partial & Partial; +export interface CacheOptions extends Partial, Partial {} /** * Apply the caching interceptors for a already created axios instance. diff --git a/src/interceptors/util.ts b/src/interceptors/util.ts index 4d20572..c4a565f 100644 --- a/src/interceptors/util.ts +++ b/src/interceptors/util.ts @@ -25,9 +25,9 @@ export function isMethodIn( return methodList.some((method) => method === requestMethod); } -export type ConfigWithCache = CacheRequestConfig & { - cache: Partial; -}; +export interface ConfigWithCache extends CacheRequestConfig { + cache: Partial>; +} /** * This function updates the cache when the request is stale. So, the next request to the diff --git a/src/storage/build.ts b/src/storage/build.ts index 67575d0..341fb53 100644 --- a/src/storage/build.ts +++ b/src/storage/build.ts @@ -61,7 +61,7 @@ export function isExpired(value: CachedStorageValue | StaleStorageValue): boolea return value.ttl !== undefined && value.createdAt + value.ttl <= Date.now(); } -export type BuildStorage = Omit & { +export interface BuildStorage extends Omit { /** * Returns the value for the given key. This method does not have to make checks for * cache invalidation or anything. It just returns what was previous saved, if present. @@ -74,7 +74,7 @@ export type BuildStorage = Omit & { key: string, currentRequest?: CacheRequestConfig ) => MaybePromise; -}; +} /** * All integrated storages are wrappers around the `buildStorage` function. External diff --git a/src/storage/memory.ts b/src/storage/memory.ts index 1793f79..52872b6 100644 --- a/src/storage/memory.ts +++ b/src/storage/memory.ts @@ -141,10 +141,10 @@ export function buildMemoryStorage( return storage; } -export type MemoryStorage = AxiosStorage & { +export interface MemoryStorage extends AxiosStorage { data: Record; /** The job responsible to cleaning old entries */ cleaner: ReturnType; /** Tries to remove any invalid entry from the memory */ cleanup: () => void; -}; +} diff --git a/src/storage/types.ts b/src/storage/types.ts index 4729e08..fb38018 100644 --- a/src/storage/types.ts +++ b/src/storage/types.ts @@ -1,12 +1,12 @@ import type { CacheAxiosResponse, CacheRequestConfig } from '../cache/axios'; import type { MaybePromise } from '../util/types'; -export type CachedResponse = { +export interface CachedResponse { data?: unknown; headers: CacheAxiosResponse['headers']; status: number; statusText: string; -}; +} /** The value returned for a given key. */ export type StorageValue = @@ -17,15 +17,15 @@ export type StorageValue = export type NotEmptyStorageValue = Exclude; -export type StaleStorageValue = { +export interface StaleStorageValue { data: CachedResponse; ttl?: number; staleTtl?: undefined; createdAt: number; state: 'stale'; -}; +} -export type CachedStorageValue = { +export interface CachedStorageValue { data: CachedResponse; /** * The number in milliseconds to wait after createdAt before the value is considered @@ -35,29 +35,29 @@ export type CachedStorageValue = { staleTtl?: number; createdAt: number; state: 'cached'; -}; +} export type LoadingStorageValue = LoadingEmptiedStorageValue | LoadingStaledStorageValue; -export type LoadingEmptiedStorageValue = { +export interface LoadingEmptiedStorageValue { data?: undefined; ttl?: undefined; staleTtl?: undefined; createdAt?: undefined; state: 'loading'; previous: 'empty'; -}; +} -export type LoadingStaledStorageValue = { +export interface LoadingStaledStorageValue { state: 'loading'; data: CachedResponse; ttl?: undefined; staleTtl?: undefined; createdAt: number; previous: 'stale'; -}; +} -export type EmptyStorageValue = { +export interface EmptyStorageValue { data?: undefined; ttl?: undefined; staleTtl?: undefined; @@ -65,7 +65,7 @@ export type EmptyStorageValue = { /** Defined when the state is cached */ createdAt?: undefined; state: 'empty'; -}; +} /** * A storage interface is the entity responsible for saving, retrieving and serializing @@ -74,7 +74,7 @@ export type EmptyStorageValue = { * @default buildMemoryStorage * @see https://axios-cache-interceptor.js.org/guide/storages */ -export type AxiosStorage = { +export interface AxiosStorage { /** * Sets a new value for the given key * @@ -113,4 +113,4 @@ export type AxiosStorage = { * @see https://axios-cache-interceptor.js.org/guide/storages#buildstorage */ get: (key: string, currentRequest?: CacheRequestConfig) => MaybePromise; -}; +} diff --git a/src/util/types.ts b/src/util/types.ts index 8a55fac..faacc5e 100644 --- a/src/util/types.ts +++ b/src/util/types.ts @@ -10,7 +10,7 @@ export type CachePredicate = Exclude< undefined >; -export type CachePredicateObject = { +export interface CachePredicateObject { /** Matches if this function returned true. */ statusCheck?: (status: number) => MaybePromise; @@ -29,7 +29,7 @@ export type CachePredicateObject = { /** Check if the response matches this predicate. */ responseMatch?: (res: CacheAxiosResponse) => MaybePromise; -}; +} /** * A simple function that receives a cache request config and should return a string id @@ -68,14 +68,14 @@ export type CacheUpdaterFn = ( * `delete` -> Deletes the request cache `predicate()` -> Determines if the cache can be * reused, deleted or modified. */ -export type CacheUpdaterRecord = { +export interface CacheUpdaterRecord { [requestId: string]: | 'delete' | (( cached: Exclude, response: CacheAxiosResponse ) => MaybePromise); -}; +} /** * Updates any specified request cache by applying the response for this network call.