Handling forms with the Fetch Client involves preparing FormData objects and sending them via HTTP requests. This is essential for tasks like submitting form data or uploading files.

Submitting Form Data

This example shows how to submit form data using FormData.

async function submitForm(formData: FormData) {
    const response = await http.fetch('submit-form-url', {
        method: 'POST',
        body: formData
    });

    if (!response.ok) {
        // Handle errors
    }
    return await response.json();
}

// Usage
const formElement = document.querySelector('form');
const formData = new FormData(formElement);
submitForm(formData);

Uploading a File

Here's how to upload a file using the Fetch Client, which is common in many web applications.

async function uploadFile(file: File) {
    const formData = new FormData();
    formData.append('file', file);

    const response = await http.fetch('upload-url', {
        method: 'POST',
        body: formData
    });

    if (!response.ok) {
        // Handle errors
    }
    return await response.json();
}

The Aurelia Fetch Client can handle various response types, including JSON, Blob, and text. Proper handling of these types is crucial for correctly processing server responses.

Handling JSON Response

This example demonstrates how to fetch and process a JSON response.

Handling Blob (Binary Data)

This snippet shows how to handle binary data (like images or files) received from the server.

Response Transformation and Mapping

This interceptor transforms JSON responses using a custom transformData function, allowing for consistent data shaping across the application.

Configuring the Fetch Client for specific needs like setting default headers, handling timeouts, or implementing retry logic can enhance application performance and reliability.

Setting Default Headers for JSON and Token Authorization

Setting default headers ensures that every request sent via the Fetch Client includes these headers, maintaining consistency and reducing redundancy in your code.

import { HttpClient } from '@aurelia/fetch-client';

const http = new HttpClient();
http.configure(config => {
    config.withDefaults({
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'Authorization': `Bearer YOUR_TOKEN_HERE`
        }
    });
});

This configuration sets the default Accept and Content-Type headers to handle JSON data and adds an Authorization header with a bearer token.

Response Caching

Response caching can improve performance by storing and reusing responses for identical requests.

const responseCache = new Map();

function createCacheInterceptor() {
    return {
        request(request) {
            const key = request.url + JSON.stringify(request.params);
            if (responseCache.has(key)) {
                return responseCache.get(key);
            }
            return request;
        },
        response(response, request) {
            const key = request.url + JSON.stringify(request.params);
            responseCache.set(key, response.clone()); // Clone the response for caching
            return response;
        }
    };
}

http.configure(config => {
    config.withInterceptor(createCacheInterceptor());
});

This configuration adds a simple caching layer, storing responses in a map and retrieving them for identical subsequent requests. It ensures faster response times for repeated requests to the same endpoints with the same parameters.

Simple Retry Logic on Network Failure

This example sets up a retry mechanism that retries the request up to three times with a one-second delay between attempts, but only for certain types of errors (like network errors).

function createRetryInterceptor(retries: number, delay: number) {
    return {
        response(response, request) {
            return response;
        },
        responseError(error, request) {
            if (retries > 0 && shouldRetry(error)) {
                retries--;
                return new Promise(resolve => setTimeout(resolve, delay))
                    .then(() => http.fetch(request));
            }
            throw error;
        }
    };
}

function shouldRetry(error) {
    // Define logic to determine if the request should be retried
    // For example, retry on network errors but not on HTTP 4xx or 5xx errors
    return error instanceof TypeError; // Network errors are TypeErrors in fetch
}

http.configure(config => {
    config.withInterceptor(createRetryInterceptor(3, 1000)); // Retry 3 times, 1-second delay
});

Interceptors are a powerful feature of Aurelia's Fetch Client, allowing you to modify requests and responses or perform side effects like logging and authentication. They enable developers to implement centralized logic that handles various aspects of HTTP communication.

Understanding Interceptors

Interceptors can be attached to the Fetch Client configuration and consist of four optional methods: request, requestError, response, and responseError. Here’s how each method operates:

• request: Invoked before a request is sent. This method receives the Request object and can modify it or return a new one. It can also return a Response object to short-circuit the fetch operation.

• requestError: Triggered if an error occurs during the request generation or in a request interceptor. This method can handle the error and potentially recover by returning a new Request object.

• response: Called after the server responds. This method receives the Response object, which can be manipulated or replaced before being returned to the original caller.

• responseError: Invoked when a fetch request fails due to network errors or when a response interceptor throws an error. It can handle the error and perform tasks like retrying the request or returning an alternative response.

Each method can return either their respective expected object (Request or Response) or a Promise that resolves to it.

Example Interceptors

Logging Interceptor

The logging interceptor tracks all outgoing requests and incoming responses, which is useful for debugging and monitoring.

Authentication Interceptor

The authentication interceptor appends a bearer token to each request, centralizing the authentication handling for secured API endpoints.

Error Handling Interceptor

A robust error handling interceptor intercepts responses and response errors to manage API errors centrally.

Best Practices for Using Interceptors

• Single Responsibility: Each interceptor should have a single responsibility, whether it's logging, adding headers, or error handling.

• Order Matters: The order in which interceptors are added can affect their behavior, as they are executed in a pipeline.

• Error Recovery: Consider implementing strategies within requestError and responseError interceptors for error recovery, such as retrying failed requests.

• Avoid Side Effects: While interceptors can perform side effects, it's best to avoid them unless necessary for functionality like logging.

• Short-Circuiting: Interceptors can short-circuit the fetch process by returning a Response object in the request interceptor.

Considerations for Interceptors

When implementing interceptors, it is important to be aware of their full potential and how to avoid common pitfalls:

• Interceptor Lifecycle: Interceptors are executed in the order they are registered. Understanding this order is crucial when you have dependencies between interceptors' operations.

• Asynchronous Interceptors: Interceptors can return Promises, allowing for asynchronous operations. Ensure that any asynchronous code is handled properly to avoid unexpected behavior.

• Pitfalls to Avoid: Be cautious when changing shared request configurations within an interceptor, as this might affect other application parts. Always treat the Request and Response objects as immutable.

• Performance Impacts: Remember that complex logic within interceptors can impact the performance of your HTTP requests. Monitor the performance to ensure that interceptors do not introduce significant delays.

• Debugging Interceptors: Use logging within interceptors to help identify the flow of requests and responses. This can be invaluable when debugging unexpected behavior.

• Organizing Interceptors: For better maintainability, organize interceptors in a logical structure, such as grouping related interceptors together or keeping them close to the feature modules they relate to.

• Advanced Use Cases: For more complex scenarios, consider using interceptors for response caching, request retries with backoff strategies, or implementing custom prioritization of outgoing requests.

The Fetch Client can be used in a couple of different ways. You can create a new instance using the new keyboard or use dependency injection to create an instance.

Basic Usage

Here's a quick example of how to set up and make a GET request with the Aurelia Fetch Client in an Aurelia 2 application. The Fetch client ships with Aurelia and requires no additional installation. Import the HttpClient from the @aurelia/fetch-client package to use it.

import { HttpClient } from '@aurelia/fetch-client';

const httpClient = new HttpClient();

httpClient.configure(config => {
  config
    .withDefaults({ mode: 'cors' })
    .withBaseUrl('https://api.example.com/');
});

httpClient.get('users')
  .then(response => response.json())
  .then(users => console.log(users))
  .catch(error => console.error(error));

You can inject a new instance into your component or service class by injecting the Fetch client with the newInstanceOf decorator. This will ensure our component gets a new instance of the Fetch client.

import { IHttpClient } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { ICustomElementViewModel } from 'aurelia';

export class MyComponent {    
    constructor(@newInstanceOf(IHttpClient) readonly http: IHttpClient) {

    }
 }   

import { IHttpClient } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { inject } from 'aurelia';

@inject(newInstanceOf(IHttpClient))

export class MyComponent {    
    constructor(http) {
        this.http = http
    }
 }   

import { IHttpClient } from '@aurelia/fetch-client';
import { resolve, newInstanceOf } from '@aurelia/kernel';
import { inject } from 'aurelia';

export class MyComponent {    
    http = resolve(newInstanceOf(IHttpClient))
} 

Configuring the fetch client

Many configuration options available to the native Fetch API are also available in the Aurelia Fetch Client. You can set default headers, create interceptors (more on that further down) and more.

import { IHttpClient } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { ICustomElementViewModel } from 'aurelia';

export class MyComponent implements ICustomElementViewModel {    
    constructor(@newInstanceOf(IHttpClient) readonly http: IHttpClient) {
      http.configure(config =>
        config
        .withBaseUrl('api/')
        .withDefaults({
          credentials: 'same-origin',
          headers: {
            'Accept': 'application/json',
            'X-Requested-With': 'Fetch'
          }
        })
        .withInterceptor({
          request(request) {
            console.log(`Requesting ${request.method} ${request.url}`);
            return request;
          },
          response(response) {
            console.log(`Received ${response.status} ${response.url}`);
            return response;
          }
        })
      );
    }
 }   

import { IHttpClient } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { inject } from 'aurelia';

@inject(newInstanceOf(IHttpClient))

export class MyComponent {    
    constructor(http) {
        this.http = http
        
        this.http.configure(config =>
          config
          .withBaseUrl('api/')
          .withDefaults({
            credentials: 'same-origin',
            headers: {
              'Accept': 'application/json',
              'X-Requested-With': 'Fetch'
            }
          })
          .withInterceptor({
            request(request) {
              console.log(`Requesting ${request.method} ${request.url}`);
              return request;
            },
            response(response) {
              console.log(`Received ${response.status} ${response.url}`);
              return response;
            }
          })
        );
    }
 }    

In the example above, withBaseUrl() is used to specify a base URL that all fetches will be relative to. The withDefaults() method allows passing an object that can include any properties described in the optional init parameter to the Request constructor and will be merged into the new Request before it is passed to the first request interceptor.

withInterceptor() enables passing an object which can provide any of these four optional methods: request, requestError, response, and responseError. Here's an explanation of how each of these methods works:request takes the Request that will be passed to window.fetch() after interceptors run. It should return the same Request or create a new one. It can also return a Response to short-circuit the call to fetch() and complete the request immediately. Interceptors will handle errors thrown in request interceptors.

• requestError acts as a Promise rejection handler during Request creation and request interceptor execution. It will receive the rejection reason and can either re-throw or recover by returning a valid Request.

• response will be run after fetch() completes, and will receive the resulting Response . As with request, it can either pass the Response along, return a modified response, or throw.

• responseError is similar to requestError and acts as a Promise rejection handler for response rejections.

These methods on the interceptor object can also return a Promisefor their respective return values.

Fetch helpers

There are some caveats with the default Fetch implementation around error handling that Aurelia conveniently provides helper methods to work with.

• config.rejectErrorResponses() will add a response interceptor that causes responses with unsuccessful status codes to result in a rejected Promise.

• config.useStandardConfiguration() will apply rejectErrorResponses(), and also configure credentials: 'same-origin' as a default on all requests.

• The Fetch API has no convenient way of sending JSON in the body of a request. Objects must be manually serialized to JSON, and the Content-Type header must be set appropriately. the Fetch package includes a helper called json for this.

Posting JSON

import { IHttpClient, json } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { ICustomElementViewModel } from 'aurelia';

export class MyComponent implements ICustomElementViewModel {    
    constructor(@newInstanceOf(IHttpClient) readonly http: IHttpClient) {

    }
    
    createComment() {
        let comment = {
          title: 'Awesome!',
          content: 'This Fetch client is pretty rad.'
        };
  
        this.http.fetch('comments', {
          method: 'post',
          body: json(comment)
        });
    }
 }   

import { IHttpClient, json } from '@aurelia/fetch-client';
import { newInstanceOf } from '@aurelia/kernel';
import { inject } from 'aurelia';

@inject(newInstanceOf(IHttpClient))

export class MyComponent {    
    constructor(http) {
        this.http = http
    }
    
    createComment() {
        let comment = {
          title: 'Awesome!',
          content: 'This Fetch client is pretty rad.'
        };
  
        this.http.fetch('comments', {
          method: 'post',
          body: json(comment)
        });
    }
 }       

For the example above, if you prefer .get/.post/etc.. style, you can also use corresponding method on the Fetch client

  ...
  this.http.post('comments', { body: JSON(comment) })

Error Handling and Recovery

Robust error handling is crucial for any application making HTTP requests. It involves not only catching and responding to errors but also implementing strategies for error recovery and user notification.

http.configure(config => {
    config.withInterceptor({
        response(response) {
            if (!response.ok) {
                handleError(response);
            }
            return response;
        },
        responseError(error) {
            handleError(error);
            throw error; // Rethrow error after handling
        }
    });
});

function handleError(error) {
    // Centralized error handling logic
    console.error('Fetch Error:', error);
    // Additional logic like logging, user notification, etc.
}

Retrying failed requests

The Fetch client comes with a retry implementation that can be configured like the following example

http.configure(config => config.withRetry(retryOptions))

There are several options can be specified, per the following type:

export interface IRetryConfiguration {
  maxRetries: number;
  interval?: number;
  strategy?: number | ((retryCount: number) => number);
  minRandomInterval?: number;
  maxRandomInterval?: number;
  counter?: number;
  requestClone?: Request;
  doRetry?(response: Response, request: Request): boolean | Promise<boolean>;
  beforeRetry?(request: Request, client: HttpClient): Request | Promise<Request>;
}

Note that for option strategy, there are 4 default strategies provided via the export RetryStrategy from the @aurelia/fetch-client package:

export const RetryStrategy: {
  fixed: 0;
  incremental: 1;
  exponential: 2;
  random: 3;
}

Per the names suggest, the interval which a request will be attempted again will be calcuated accordingly for each strategy. If you want to supply your own strategy, the strategy option can take a callback to be invoked with the number of the retry and the return value is treated as the time to wait until the next fetch attempt.

The @aurelia/fetch-client is a HTTP client for making network requests, designed to integrate seamlessly with Aurelia 2 applications. It is built on top of the Fetch API, providing an easy-to-use and promise-based interface to communicate with RESTful APIs.

Features

The Aurelia Fetch Client comes with a host of features that make it a powerful tool for developers:

• Fetch API Compliance: Utilizes the native Fetch API, ensuring a standards-compliant requesting mechanism.

• Fluent and Chainable API: Offers a fluent interface to build requests in a readable and chainable manner.

• Flexible Interceptors: Interceptors allow for request and response manipulation, enabling tasks such as adding headers, logging, or handling authentication globally.

• Configurable: Easy to configure with sensible defaults that can be overridden as needed for different request scenarios.

• Promise-based Workflow: Built around Promises, it provides a streamlined way to handle asynchronous HTTP operations.

Aurelia Fetch Client vs Native Fetch

Compared to the native Fetch API, Aurelia's Fetch Client offers several advantages. It provides a more straightforward configuration process, better default settings for common scenarios, and helper methods that simplify common tasks. For instance, setting default headers or handling JSON data becomes more intuitive with Aurelia's approach.

Configuration Options

The Aurelia Fetch Client supports a variety of configuration options to tailor its behavior to your application's needs. These include setting default headers, base URLs, timeout settings, and more.

Interceptors

Enhance the capabilities of your HTTP requests and responses by using interceptors. This feature allows you to handle various cross-cutting concerns such as logging, authentication, or adding common headers.

Error Handling

Efficient error handling is crucial for a robust application. The Aurelia Fetch Client provides mechanisms for catching and managing errors that may occur during the request lifecycle.

Advanced Usage

For more complex scenarios, the Aurelia Fetch Client supports advanced configurations and use cases, such as creating custom interceptors, managing request retries, and working with various content types.

Conclusion

The @aurelia/fetch-client is a versatile HTTP client that simplifies network communication in Aurelia 2 applications. By leveraging the Fetch API and providing additional features for customization and extensibility, it equips developers with the tools required for efficient and effective API interactions.

For in-depth information on configuration, usage examples, interceptor implementation, and more, please explore the other sections of this documentation.