batchMiddleware

This can be used to batch together multiple calls to an endpoint (or endpoints) to make it more efficient.

For example say you had an endpoint that accepted either 'id' or a list of 'ids' and would return the corresponding records with those ids. For ease of use you could allow calling the endpoint with a body of { id: 2} to get the record of id=2 but to minimise the number of requests you want to batch together any of these calls into a combined body of { ids: [2, 4, 8] } but still transparently return each individual record to the original caller who requested it. This might look like:

batchMiddleware({
    execute(calls) {
        // Our implementation of getBatchkey() guarantees that all the endpoints are the same URL (see below)
        const { resolvedUrl } = calls[0];
        // Extract the requested 'id' from each call
        const ids = calls.map(call => {
            return JSON.parse(call.requestInit.body as string).id;
        });
        // Call fetch, merge all other fetch options (headers etc) and create a
        // new body with all the extracted ids.
        return fetch(resolvedUrl, {
             // In this example all calls share the same headers etc
             ...calls[0].requestInit,
            body: JSON.stringify({ ids }),
        });
    },
    // You can also access `response` in addition to `result` if you need the raw `Response` object.
    resolve(call, { result }) {
        // For each call to the endpoint extract only the record it specifically request
        return result[JSON.parse(call.requestInit.body as string).id];
    },
})

But how do we distinguish between two completely different endpoints? getBatchKey can be used to determine how calls are batched together:

batchMiddleware({
  getBatchKey(call) {
    // Batch together all calls that have identical URL (including query parameters)
    return call.resolvedUrl;
  },
  ...
});

If each call has options to fetch that may differ then you can combine them using mergeRequestInit. This will combine multiple init arguments to fetch into a single init argument. Headers will be combined into a single headers object with the last argument taking precedence in the case of a conflict. Any other init arguments use the value from the last argument passed.

fetch(resolvedUrl, {
  ...mergeRequestInit(...calls.map(call => call.requestInit)),
  body: JSON.stringify({ ids }),
});

The process for batching looks like:

• Endpoint is called like normal and hits batchMiddleware
• options.getBatchKey is called.
  • If this is false then the call proceeds to the next middleware in the chain.
  • If this returns anything else that is used as the batch key. If the batch already exist this call is added to the batch otherwise a new batch is created and it's execution is scheduled in batchDelay milliseconds. The batchMiddleware will then skip any further middleware in the chain and wait for the fetch call.
• Any further calls to an endpoint before the batchDelay time elapses are added to the batch
• Once batchDelay time elapses execute is called which combines all the batched calls into a single call to fetch
  • Once fetch finishes decodeBody is called.
  • resolve is then called on success (2xx status) or reject called on error (non-2xx status).
• The middleware stack continue to unwind and all middleware before batchMiddleware can handle the response/error returned by resolve/reject.

NOTE: You can have multiple batchMiddleware in the middleware chain for an Endpoint (including global middleware) but only one the first one that chooses to batch an item will ever apply (the others will be skipped). This allows you to have multiple conditional batching middleware for example. All batchMiddleware must appear last in the chain (ie. batchingMiddleware can only be proceeded by another batchMiddleware).