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

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 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 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:

// A simple GET request
const response = await ajax.fetch('/api/foo');
const data = await response.json(); // or .text(), .clone(), .formData(), etc

// 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, fetchJson returns an object containing the Response and a JSON.parse'd body

// A simple GET request
const { response, body } = await ajax.fetchJson('/api/foo');
// body.foo === 'bar';

// 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 or Response objects of a network request.

Request interceptors

A request interceptor is a function that takes a Request object, and returns a Request object, or a 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 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:

function addAcceptLanguage(request) {
  request.headers.set('accept-language', 'EN_GB');
  return request;
}

ajax.addRequestInterceptor(addAcceptLanguage);

Returning a Response:

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 object, and returns a 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.

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.

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

Caching

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:

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.