d2l-fetch

Provides support for wrapping window.fetch calls within middleware functions.

Setup

npm ci

Usage

Reference the script in your html:

<script type="module" src="../d2l-fetch/d2l-fetch.js"></script>

This will add a d2lfetch object to the global scope, with two methods: use and fetch.

Alternatively, you can reference the global d2lfetch instance via es6 import

import { d2lfetch } from '../d2l-fetch/src/index.js';

Use

Use the 'use' function to append functions to the middleware chain. These functions will be executed in the order they are 'use'd.

Each middleware function will be passed two parameters: a Request object and the next function in the middleware to be executed. Unless you wish to exit the chain early your middleware should execute the next function during its own execution and return the result.

Example:

var myMiddlewareFunc = (request, next) => {
	// Do something with the request, like maybe add a custom header
	request.headers.set('X-My-Custom-Header', 'hello');

	// Continue to the next function in the chain
	var response = next(request);

	// If you want you can do something with the response now, or not, up to you
	// in this example we'll just return it back up the chain

	return response;
};

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

If you do wish to exit the chain early no further middleware will be executed, nor will the window.fetch call. You should return a Promise with your desired output (keep in mind that callers are probably expecting it to contain a Response).

Example:

var myEarlyExitFunc = (request, next) => {
	// Check if we have a cached response for this request
	if (CACHED_RESPONSES[request.url]) {
		// Return what we have, this will skip further
		// middleware functions as well as the `window.fetch` call
		return Promise.resolve(CACHED_RESPONSES[request.url]);
	}

	// We've got nothing so continue to the next function in the chain
	return next(request);
};

window.d2lfetch.use({name: 'myEarlyExitName', fn: myEarlyExitFunc});
window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc}); // this may never get called

Fetch

Use the fetch function to execute the middleware chain followed by a window.fetch call. Returns the Promise result of the window.fetch call or whatever result was returned by any middleware that exited early from the chain.

Example:

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

window.d2lfetch.fetch(new Request('http://www.example.com/api/stuff'))
	.then(function(response) {
		// do something with the response
	})
	.catch(function(reason) {
		console.log(reason);
	});

AddTemp

Use the addTemp function to temporarily add middleware to the middleware chain. Returns a new D2LFetch object with the updated middleware chain.

Example:

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

window.d2lfetch
	.addTemp({
		name: 'addedMiddlewareName',
		fn: function() {
			// added middleware functionality
		}
	})
	.fetch(new Request('http://www.example.com/api/stuff'))
	.then(function(response) {
		// do something with the response
	})
	.catch(function(reason) {
		console.log(reason);
	});

If you want to have the temporary middleware added to the beginning of the middleware chain, you can pass prepend: true into the options object.

Example:

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

window.d2lfetch
	.addTemp(
		{ name: 'addedMiddlewareName', fn: function() { /* added middleware functionality */ } },
		{ prepend: true }
	)

RemoveTemp

Use the removeTemp function to temporarily remove a specified middleware from the middleware chain. Returns a new D2LFetch object with the updated middleware chain.

Example:

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

window.d2lfetch
	.removeTemp('myMiddlewareName')
	.fetch(new Request('http://www.example.com/api/stuff'))
	.then(function(response) {
		// do something with the response
	})
	.catch(function(reason) {
		console.log(reason);
	});

addTemp and removeTemp can be chain called together like so:

window.d2lfetch.use({name: 'myMiddlewareName', fn: myMiddlewareFunc});

window.d2lfetch
	.addTemp({
		name: 'tempMiddlewareName',
		fn: function() {
			// ...
		}
	})
	.addTemp(
		{
		name: 'moreTempMiddlewareName',
		fn: function() {
			// ...
		}
	})
	.removeTemp('myMiddlewareName')
	.fetch(new Request('http://www.example.com/api/stuff'))
	.then(function(response) {
		// do something with the response
	})
	.catch(function(reason) {
		console.log(reason);
	});

Browser compatibility

d2l-fetch makes use of two javascript features that are not yet fully supported across all modern browsers: the Fetch API and Promises. If you need to support browsers that do not yet implement these features you will need to include polyfills for this functionality.

We recommend:

• fetch
• promise-polyfill

Versioning and Releasing

This repo is configured to use semantic-release. Commits prefixed with fix: and feat: will trigger patch and minor releases when merged to main.

To learn how to create major releases and release from maintenance branches, refer to the semantic-release GitHub Action documentation.