chore: more docs

new-docs/src/.vuepress/config.js

@@ -58,11 +58,11 @@ module.exports = defineConfig({
       ],
       '/config/': [
         {
-          title: 'Config reference',
+          title: 'Config',
           collapsable: false,
           children: [
             '/config/',
-            '/config/per-request-configuration',
+            '/config/request-specifics',
             '/config/response-object'
           ]
         }

new-docs/src/config/README.md

@@ -1,24 +1,31 @@
-# Global Configuration
+# Global
 
-These are properties that are used by the entire application.
+These are properties that are used and shared by the entire application.
 
 ```js
 const axios = setupCache(axios, OPTIONS);
 ```
 
-## storage
+::: tip
+
+The `setupCache` function receives global options and all [request specifics](./request-specifics.md) ones too. This
+way, you can customize the defaults for all requests.
+
+:::
+
+## storage <Badge text="optional" type="warning"/>
 
 - Type: `AxiosStorage`
-- default: `buildMemoryStorage()`
+- Default: `buildMemoryStorage()`
 
 The object responsible to save, retrieve and serialize (if needed) cache data.
 
 See the [Storages](../guide/storages.md) page for more information.
 
-## generateKey
+## generateKey <Badge text="optional" type="warning"/>
 
 - Type: `KeyGenerator<unknown, unknown>`
-- default: `defaultKeyGenerator`
+- Default: `defaultKeyGenerator`
 
 The function used to create different keys for each request. Defaults to a function that
 priorizes the id, and if not specified, a string is generated using the `method`,
@@ -27,21 +34,21 @@ priorizes the id, and if not specified, a string is generated using the `method`
 You can learn on how to use them on the
 [Request ID](../guide/request-id.md#custom-generator) page.
 
-## waiting
+## waiting <Badge text="optional" type="warning"/>
 
-- type: `Record<string, Deferred<CachedResponse>>`
-- default: `{}`
+- Type: `Record<string, Deferred<CachedResponse>>`
+- Default: `{}`
 
 A simple object that will hold a promise for each pending request. Used to handle
 concurrent requests.
 
 You'd normally not need to change this, but it is exposed in case you need to use it as
 some sort of listener of know when a request is waiting for other to finish.
 
-## headerInterpreter
+## headerInterpreter <Badge text="optional" type="warning"/>
 
-- type: `HeadersInterpreter`
-- default: `defaultHeaderInterpreter`
+- Type: `HeadersInterpreter`
+- Default: `defaultHeaderInterpreter`
 
 The function used to interpret all headers from a request and determine a time to live
 (`ttl`) number.
@@ -74,10 +81,10 @@ const myHeaderInterpreter: HeaderInterpreter = (headers) => {
 
 :::
 
-## requestInterceptor
+## requestInterceptor <Badge text="optional" type="warning"/>
 
-- type: `AxiosInterceptor<CacheRequestConfig<unknown, unknown>>`
-- default: `defaultRequestInterceptor()`
+- Type: `AxiosInterceptor<CacheRequestConfig<unknown, unknown>>`
+- Default: `defaultRequestInterceptor()`
 
 The function that will be used to intercept the request before it is sent to the axios
 adapter.
@@ -91,10 +98,10 @@ to this property.
 See its code for more information
 [here](https://github.com/arthurfiorette/axios-cache-interceptor/tree/main/src/interceptors).
 
-## responseInterceptor
+## responseInterceptor <Badge text="optional" type="warning"/>
 
-- type: `AxiosInterceptor<CacheAxiosResponse<unknown, unknown>>`
-- default: `defaultResponseInterceptor()`
+- Type: `AxiosInterceptor<CacheAxiosResponse<unknown, unknown>>`
+- Default: `defaultResponseInterceptor()`
 
 The function that will be used to intercept the request after it is returned by the axios
 adapter.
@@ -108,10 +115,10 @@ to this property.
 See its code for more information
 [here](https://github.com/arthurfiorette/axios-cache-interceptor/tree/main/src/interceptors).
 
-## debug
+## debug <Badge text="optional" type="warning"/> <Badge text="dev only" type="error"/>
 
-- type: `(msg: { id?: string; msg?: string; data?: unknown }) => void` or `undefined`
-- default: `undefined`
+- Type: `(msg: { id?: string; msg?: string; data?: unknown }) => void` or `undefined`
+- Default: `undefined`
 
 ::: warning
 

new-docs/src/config/per-request-configuration.md → new-docs/src/config/request-specifics.md

@@ -1,16 +1,33 @@
-# Per-request configuration
+# Request specifics
 
-By using this axios client and using an ide with intellisense, you'll see a custom
-property called `cache`.
+Each request can have its own cache customization, by using the `cache` property. This
+way, you can have requests behaving differently from each other without much effort.
 
-The inline documentation is self explanatory, but here are some examples and information:
+The inline documentation is self explanatory, but here is a shortly brief of what each
+property does:
 
-## `id`
+## id <Badge text="optional" type="warning"/>
+
+- Type: `string`
+- default: _(auto generated by the current
+  [key generator](../guide/request-id.md#custom-generator))_
 
 You can override the request id used by this property.
 [See more about ids](pages/request-id.md).
 
-## `cache: false`
+## cache <Badge text="optional" type="warning"/>
+
+- Type: `false` or `Partial<CacheProperties<R, D>>`.
+- Default: `{}` _(Inherits from global options)_
+
+::: tip
+
+This property is optional, and if not provided, the default cache properties will be used.
+
+:::
+
+The cache option available through the request config is where all the cache customization
+happens.
 
 Setting the `cache` property to `false` will disable the cache for this request.
 
@@ -25,44 +42,65 @@ const { id: requestId } = await axios.get('url', { cache: false });
 await axios.storage.remove(requestId);
 ```
 
-## `cache.ttl`
+## cache.ttl <Badge text="optional" type="warning"/>
+
+- Type: `number`
+- Default: `1000 * 60 * 5` _(5 Minutes)_
+
+::: warning
+
+When using [**interpretHeader**](#cache-interpretheader), this value will only be used if
+the interpreter can't determine their TTL value to override this one.
+
+:::
 
 The time until the cached value is expired in milliseconds.
 
 If a function is used, it will receive the complete response and waits to return a TTL
 value
 
-When using `interpretHeader: true`, this value will only be used if the interpreter can't
-determine their TTL value to override this
+## cache.interpretHeader <Badge text="optional" type="warning"/>
 
-## `cache.interpretHeader`
+- Type: `boolean`
+- Default: `true`
 
 If activated, when the response is received, the `ttl` property will be inferred from the
-requests headers. See the actual implementation of the
+requests headers. As described in the MDN docs and HTML specification.
+
+::: tip
+
+You can override the default behavior by setting the
+**[headerInterpreter](./README.md#headerinterpreter)** when creating the cached axios
+client.
+
+:::
+
+See the actual implementation of the
 [`interpretHeader`](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/src/header/interpreter.ts)
-method for more information. You can override the default behavior by setting the
-`headerInterpreter` when creating the cached axios client.
+method for more information.
+
+## cache.methods <Badge text="optional" type="warning"/>
 
-## `cache.methods`
+- Type: `Method[]`
+- Default: `["get"]`
 
 Specify what request methods should be cached.
 
-Defaults to only `GET` methods.
+Defaults to only cache `GET` methods.
 
-## `cache.cachePredicate`
+## cache.cachePredicate <Badge text="optional" type="warning"/>
 
-An object or function that will be tested against the response to test if it can be
-cached. See the
-[CachePredicate](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/src/util/types.ts)
-type for more.
+- Type: `CachePredicate<R, D>`
+- Default: `{}`
 
-An simple example with all values:
+An object or function that will be tested against the response to test if it can be
+cached.
 
-```ts
+```ts{5,8,13}
 axios.get<{ auth: { status: string } }>('url', {
   cache: {
     cachePredicate: {
-      // Only cache if the response comes with a *good* status code
+      // Only cache if the response comes with a "good" status code
       statusCheck: (status) => /* some calculation */ true,
 
       // Tests against any header present in the response.
@@ -80,7 +118,10 @@ axios.get<{ auth: { status: string } }>('url', {
 });
 ```
 
-## `cache.update`
+## cache.update <Badge text="optional" type="warning"/>
+
+- Type: `CacheUpdater<R, D>`
+- Default: `{}`
 
 Once the request is resolved, this specifies what other responses should change their
 cache. Can be used to update the request or delete other caches. It is a simple `Record`
@@ -125,54 +166,75 @@ axios.post<{ auth: { user: User } }>(
 );
 ```
 
-## `cache.etag`
+## cache.etag <Badge text="optional" type="warning"/>
 
-If the request should handle `ETag` and `If-None-Match support`. Use a string to force a
-custom static value or true to use the previous response ETag. To use `true` (automatic
-etag handling), `interpretHeader` option must be set to `true`. Default: `false`
+- Type: `boolean`
+- Default: `true`
 
-## `cache.modifiedSince`
+If the request should handle
+[`ETag`](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Headers/ETag) and
+[`If-None-Match support`](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Headers/If-None-Match).
+Use a string to force a custom static value or true to use the previous response ETag.
+
+To use `true` (automatic ETag handling), `interpretHeader` option must be set to `true`.
+
+## cache.modifiedSince <Badge text="optional" type="warning"/>
+
+- Type: `boolean`
+- Default: `true`
 
 Use `If-Modified-Since` header in this request. Use a date to force a custom static value
-or true to use the last cached timestamp. If never cached before, the header is not set.
-If `interpretHeader` is set and a `Last-Modified` header is sent then value from that
-header is used, otherwise cache creation timestamp will be sent in `If-Modified-Since`.
-Default: `true`
+or true to use the last cached timestamp.
+
+If never cached before, the header is not set.
 
-## `cache.staleIfError`
+If `interpretHeader` is set and a `Last-Modified` header is sent to us, then value from
+that header is used, otherwise cache creation timestamp will be sent in
+`If-Modified-Since`.
+
+## cache.staleIfError
+
+- Type: `number` or `boolean` or `StaleIfErrorPredicate<R, D>`
+- Default: `true`
 
 Enables cache to be returned if the response comes with an error, either by invalid status
 code, network errors and etc. You can filter the type of error that should be stale by
 using a predicate function.
 
-**Note**: If the response is treated as error because of invalid status code _(like from
-AxiosRequestConfig#invalidateStatus)_, and this ends up `true`, the cache will be
-preserved over the "invalid" request. So, if you want to preserve the response, you can
-use this predicate:
+::: warning
+
+If the response is treated as error because of invalid status code _(like when using
+[statusCheck](#cache-cachepredicate))_, and this ends up `true`, the cache will be
+preserved over the "invalid" request.
+
+So, if you want to preserve the response, you can use the below predicate:
+
+:::
 
 ```js
 const customPredicate = (response, cache, error) => {
   // Blocks staleIfError if has a response
   return !response;
 
   // Note that, this still respects axios default implementation
-  // and throws an error, (but it has the response)
+  // and throws an error, (but it keeps the response)
 };
 ```
 
-Possible types:
+Types Explanations
 
 - `number` -> the max time (in seconds) that the cache can be reused.
 - `boolean` -> `false` disables and `true` enables with infinite time.
 - `function` -> a predicate that can return `number` or `boolean` as described above.
 
-## `cache.override`
+## cache.override <Badge text="optional" type="warning"/>
+
+- Type: `boolean`
+- Default: `false`
 
 This option bypasses the current cache and always make a new http request. This will not
 delete the current cache, it will just replace the cache when the response arrives.
 
 Unlike as `cache: false`, this will not disable the cache, it will just ignore the
 pre-request cache checks before making the request. This way, all post-request options are
 still available and will work as expected.
-
-Default: `false`