diff --git a/docs/fundamentals/tools/ajax/overview.md b/docs/fundamentals/tools/ajax/overview.md index 64b93ac28..12cc8e17e 100644 --- a/docs/fundamentals/tools/ajax/overview.md +++ b/docs/fundamentals/tools/ajax/overview.md @@ -1,5 +1,46 @@ # Tools >> Ajax >> Overview ||10 +`Ajax` is a small wrapper around `fetch` which: + +- Allows globally registering request and response interceptors +- Throws on 4xx and 5xx status codes +- Supports caching, so a request can be prevented from reaching to network, by returning the cached response. +- Supports JSON with `ajax.fetchJSON` by automatically serializing request body and deserializing response payload as JSON, and adding the correct Content-Type and Accept headers. +- Adds accept-language header to requests based on application language +- Adds XSRF header to request if the cookie is present + +## Installation + +```bash +npm i --save @lion/ajax +``` + +### Relation to fetch + +`Ajax` delegates all requests to fetch. `ajax.fetch` and `ajax.fetchJson` have the same function signature as `window.fetch`, you can use any online resource to learn more about fetch. [MDN](http://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) is a great start. + +## Ajax class options + +| Property | Type | Default Value | Description | +| -------------------------------- | -------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| addAcceptLanguage | boolean | `true` | Whether to add the Accept-Language header from the `data-localize-lang` document property | +| addCaching | boolean | `false` | Whether to add the cache interceptor and start storing responses in the cache, even if `cacheOptions.useCache` is `false` | +| xsrfCookieName | string | `"XSRF-TOKEN"` | The name for the Cross Site Request Forgery cookie | +| xsrfHeaderName | string | `"X-XSRF-TOKEN"` | The name for the Cross Site Request Forgery header | +| jsonPrefix | string | `""` | The prefix to add to add to responses for the `.fetchJson` functions | +| cacheOptions.useCache | boolean | `false` | Whether to use the default cache interceptors to cache requests | +| cacheOptions.getCacheIdentifier | function | a function returning the string `_default` | A function to determine the cache that should be used for each request; used to make sure responses for one session are not used in the next | +| cacheOptions.methods | string[] | `["get"]` | The HTTP methods to cache reponses for. Any other method will invalidate the cache for this request, see "Invalidating cache", below | +| cacheOptions.maxAge | number | `360000` | The time to keep a response in the cache before invalidating it automatically | +| cacheOptions.invalidateUrls | string[] | `undefined` | Urls to invalidate each time a method not in `cacheOptions.methods` is encountered, see "Invalidating cache", below | +| cacheOptions.invalidateUrlsRegex | regex | `undefined` | Regular expression matching urls to invalidate each time a method not in `cacheOptions.methods` is encountered, see "Invalidating cache", below | +| cacheOptions.requestIdFunction | function | a function returning the base url and serialized search parameters | Function to determine what defines a unique URL | +| cacheOptions.contentTypes | string[] | `undefined` | Whitelist of content types that will be stored to or retrieved from the cache | +| cacheOptions.maxResponseSize | number | `undefined` | The maximum response size in bytes that will be stored to or retrieved from the cache | +| cacheOptions.maxCacheSize | number | `undefined` | The maxiumum total size in bytes of the cache; when the cache gets larger it is truncated | + +## Usage + ```js script import { ajax, createCacheInterceptors } from '@lion/ajax'; @@ -28,21 +69,60 @@ ajax.addRequestInterceptor(cacheRequestInterceptor); ajax.addResponseInterceptor(cacheResponseInterceptor); ``` -`Ajax` is a small wrapper around `fetch` which: +Or use a custom cache object and add the cache config to the constructor: -- Allows globally registering request and response interceptors -- Throws on 4xx and 5xx status codes -- Supports caching, so a request can be prevented from reaching to network, by returning the cached response. -- Supports JSON with `ajax.fetchJSON` by automatically serializing request body and deserializing response payload as JSON, and adding the correct Content-Type and Accept headers. -- Adds accept-language header to requests based on application language -- Adds XSRF header to request if the cookie is present +```js +import { Ajax } from '@lion/ajax'; -## Installation +const storeButDontRetrieveByDefaultConfig = { + addCaching: true, + cacheOptions: { + getCacheIdentifier, + useCache: false, + maxAge: TEN_MINUTES, + }, +}; -```bash -npm i --save @lion/ajax +const customAjax = new Ajax(storeButDontRetrieveByDefaultConfig); ``` -### Relation to fetch +### Invalidating the cache -`Ajax` delegates all requests to fetch. `ajax.fetch` and `ajax.fetchJson` have the same function signature as `window.fetch`, you can use any online resource to learn more about fetch. [MDN](http://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) is a great start. +Invalidating the cache, or cache busting, can be done in multiple ways: + +- Going past the `maxAge` of the cache object +- Changing cache identifier (e.g. user session or active profile changes) +- Doing a non GET request to the cached endpoint + - Invalidates the cache of that endpoint + - Invalidates the cache of all other endpoints matching `invalidatesUrls` and `invalidateUrlsRegex` + +### Restricting what to cache + +The library has a number of options available to restrict what should be cached. They include: + +#### By content type + +`cacheOptions.contentTypes` + +If this option is set, it is interpreted as a whitelist for which content types to cache. The content types of a given +response is derived from its `Content-Type` header. If this option is set, responses that do not have a `Content-Type` +header are never added to or retrieved from the cache. + +#### By response size + +`cacheOptions.maxResponseSize` + +This option sets a maximum size (in bytes) for a single response to be cached. The size of the response is determined first by looking +at the `Content-Length` header; if this header is not available, the response is inspected (through the `blob()` function) +and its size retrieved. + +### Limiting the cache size + +`cacheOptions.maxCacheSize` + +This option sets a maximum size (in bytes) for the whole cache. The size of a response is determined first by looking +at the `Content-Length` header; if this header is not available, the response is inspected (through the `blob()` function) +and its size retrieved. + +If the cache grows larger than the `maxCacheSize` option, the cache is truncated according to a First-In-First-Out +(FIFO) algorithm that simply removes the oldest entries until the cache is smaller than `options.maxCacheSize`.