@lion/ui 0.25.0 → 0.26.0

package/docs/fundamentals/tools/ajax/index.md

@@ -1,15 +0,0 @@
----
-parts:
-  - Ajax
-  - Tools
-title: 'Ajax'
-eleventyNavigation:
-  key: Tools >> Ajax
-  title: Ajax
-  order: 20
-  parent: Tools
----
-
-# Ajax
-
--> go to Overview

package/docs/fundamentals/tools/ajax/overview.md

@@ -1,269 +0,0 @@
----
-parts:
-  - Overview
-  - Ajax
-  - Tools
-title: 'Overview'
-eleventyNavigation:
-  key: Tools >> Ajax >> Overview
-  title: Overview
-  order: 10
-  parent: Tools >> Ajax
----
-
-# Overview
-
-`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 and the request is for a mutable action (POST/PUT/PATCH/DELETE) and if the origin is the same as current origin or the request origin is in the xsrfTrustedOrigins list.
-
-## 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.fetch`
-
-The `fetch` method of `ajax` is a very small wrapper around native `window.fetch` and returns a native [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, the main differences with native `window.fetch` are:
-
-- it will use any caching options that you've configured in the `Ajax` class
-- it will throw on response statuses between 400 and 600 (native fetch doesn't throw)
-- it will run any interceptors that you've configured
-- it will add a XSRF header to the request if the XSRF cookie is present
-
-Otherwise, you can expect the same usage as from `window.fetch`. Here are some simple examples:
-
-```js
-// A simple GET request
-const response = await ajax.fetch('/api/foo');
-const data = await response.json(); // or .text(), .clone(), .formData(), etc
-```
-
-```js
-// A simple POST request
-const response = await ajax.fetch('/api/foo', {
-  method: 'POST',
-  body: JSON.stringify({ foo: 'bar' }),
-});
-```
-
-## `ajax.fetchJson`
-
-The `fetchJson` method of `ajax` has some additional features, added for convenience and ease of use. For example, the `fetchJson` method:
-
-- adds the `accept` header with a value of `application/json`
-- adds the `content-type` header with a value of `application/json`, if a request body is provided
-- automatically `JSON.stringifies` the request body, if one is provided
-- will attempt to parse the response body as JSON if available
-  - and also automatically remove a JSON prefix from the response body if one is configured
-
-> Note that instead of returning only a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), `fetchJson` returns an object containing the [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) and a `JSON.parse`'d `body`
-
-```js
-// A simple GET request
-const { response, body } = await ajax.fetchJson('/api/foo');
-// body.foo === 'bar';
-```
-
-```js
-// A simple POST request
-const { response, body } = await ajax.fetchJson('/api/foo', {
-  method: 'POST',
-  body: { foo: 'bar' },
-});
-```
-
-## Interceptors
-
-Interceptors are functions that can be used to inspect or modify the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) or `Response` objects of a network request.
-
-### Request interceptors
-
-A request interceptor is a function that takes a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object, and returns a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object, or a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, and runs _before_ the native `window.fetch` call is done, allowing you to modify or inspect a request before it's made.
-
-If you return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, the response will be returned by the `fetch`
-or `fetchJson` methods, instead of passing the `Request` to the native `window.fetch` function.
-
-Returning a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request):
-
-```js
-function addAcceptLanguage(request) {
-  request.headers.set('accept-language', 'EN_GB');
-  return request;
-}
-
-ajax.addRequestInterceptor(addAcceptLanguage);
-```
-
-Returning a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response):
-
-```js
-function interceptFooRequest(request) {
-  if (request.headers.get('foo')) {
-    return Response.json({ foo: 'bar' });
-  }
-
-  return request;
-}
-
-ajax.addRequestInterceptor(interceptFooRequest);
-```
-
-Request interceptors can be async and will be awaited.
-
-### Response interceptors
-
-A response interceptor is a function that takes a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, and runs _after_ the native `window.fetch` call is done, allowing you to modify or inspect the response before it's returned by `fetch`/`fetchJson`.
-
-```js
-async function rewriteFoo(response) {
-  const body = await response.clone().text();
-
-  return new Response(body.replaceAll('foo', 'bar'), response);
-}
-
-ajax.addResponseInterceptor(rewriteFoo);
-```
-
-Response interceptors can be async and will be awaited.
-
-### Response JSON object interceptors
-
-A response JSON object interceptor is a function that takes a successfully parsed response JSON object and `response` object and returns a new response JSON object.
-It's used only when the request is made with the `fetchJson` method, providing a convenience API to directly modify or inspect the parsed JSON without the need to parse it and handle errors manually.
-
-```js
-async function interceptJson(jsonObject, response) {
-  if (response.url === '/my-api') {
-    return {
-      ...jsonObject,
-      changed: true,
-    };
-  }
-  return jsonObject;
-}
-
-ajax.addResponseJsonInterceptor(interceptJson);
-```
-
-Response JSON object interceptors can be async and will be awaited.
-
-## 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                                                                                                          |
-| xsrfTrustedOrigins               | string[] | []                                                                 | List of trusted origins, the XSRF header will also be added if the origin is in this list.                                                                  |
-| 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. Can be async. |
-| 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                                                                   |
-
-## Caching
-
-```js
-import { ajax, createCacheInterceptors } from '@lion/ajax';
-
-// Note: getCacheIdentifier can be async
-const getCacheIdentifier = () => {
-  let userId = localStorage.getItem('lion-ajax-cache-demo-user-id');
-  if (!userId) {
-    localStorage.setItem('lion-ajax-cache-demo-user-id', '1');
-    userId = '1';
-  }
-  return userId;
-};
-
-const TEN_MINUTES = 1000 * 60 * 10; // in milliseconds
-
-const cacheOptions = {
-  useCache: true,
-  maxAge: TEN_MINUTES,
-};
-
-const { cacheRequestInterceptor, cacheResponseInterceptor } = createCacheInterceptors(
-  getCacheIdentifier,
-  cacheOptions,
-);
-
-ajax.addRequestInterceptor(cacheRequestInterceptor);
-ajax.addResponseInterceptor(cacheResponseInterceptor);
-```
-
-Or use a custom cache object and add the cache config to the constructor:
-
-```js
-import { Ajax } from '@lion/ajax';
-
-const storeButDontRetrieveByDefaultConfig = {
-  addCaching: true,
-  cacheOptions: {
-    getCacheIdentifier,
-    useCache: false,
-    maxAge: TEN_MINUTES,
-  },
-};
-
-const customAjax = new Ajax(storeButDontRetrieveByDefaultConfig);
-```
-
-### Invalidating the cache
-
-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`.