Connection Status

import { isOnline, isOffline, getPingCache } from '@bbc/front-end-kit/js/utils/connection-status';

The navigator.onLine property is a built-in value in the browser that returns a boolean value indicating whether the user is connected to a network. The issue is that it is not sufficient to determine if the browser is connected to the internet.

The connection-status library solves this by providing a method to send a heartbeat ping to a server on the internet.

This library is a small collection of useful utility methods to help you determine the status of the user's connection to the internet.

Caution

Pinging a server too many times will cause the server to block your IP address. Make sure the expires parameter is fine-tuned with the reactivity required in the project.

The longer it is, the less often the server will block the ping and cause a false negative.

Behind the scenes

When the ping is made to the target server, it expects a response of any kind. This means the connection exists. When there is no connection to that given domain, the ping will fail with an error. This error is caught and interpreted as a falsy value for the connected property.

Caching

Pings are cached to avoid excessive requests and causing the target server to block the IP address. To avoid this, the cache layer was implemented so that cached ping results could be recycled when recurrent pings are made in too short a time frame.

The time between two real pings can be tweaked by setting the expires parameter. Every call before the expiration time will use the cached result instead.

Use the getPingCache method to inspect the cache for a specific URL or all cached results.

Values kept in cache per url

Every URL used to check the online status is cached in an object containing the following properties:

url: The URL used to check the online status
expires: Timestamp (ms) after which the cached result is considered stale
connected: A boolean value indicating whether the user is connected to the internet
response: The response from the server
error: The error from the server

Cache expiration

The cache expiration is set to 5000ms (5 seconds) by default. After that, the cached result is invalidated and a new ping is made on the next call.

The expiration time can be changed by passing a different expires value in milliseconds.

Methods

`isOnline(url, options)`

Async. Returns true if a real internet connection is detected, false if failed or timed out.

Parameters

url (string, optional): The URL to ping (default: "https://www.google.com")
options (object, optional): Configuration options
- timeout (number, default 5000): Maximum time in ms to wait for a response before aborting
- expires (number, default 5000): Time in ms before the cached result expires

Returns

Promise<boolean>

Example

import { isOnline } from '@bbc/front-end-kit/js/utils/connection-status';

const online = await isOnline();

if (online) {
    console.log('User is online');
} else {
    console.log('User is offline');
}

`isOffline(...args)`

Returns the inverse of isOnline. Accepts the same arguments.

Known bug

isOffline is not async — it returns !isOnline(...args), which negates a Promise object directly. Since !Promise is always false, isOffline always returns false regardless of connection state. Use !(await isOnline(...args)) as a workaround until this is fixed in the source.

import { isOnline } from '@bbc/front-end-kit/js/utils/connection-status';

// workaround for the isOffline bug
const offline = !(await isOnline());

if (offline) {
    console.log('User is offline');
} else {
    console.log('User is online');
}

`getPingCache(url)`

Returns cached ping results. Useful for debugging.

Parameters

url (string, optional): A specific URL to retrieve the cache entry for. If omitted, returns all entries.

Returns

No url → Map<string, Object> of all cached results
With url → Object cache entry for that URL, or undefined if not cached

Example

import { getPingCache } from '@bbc/front-end-kit/js/utils/connection-status';

// all cached results
const cache = getPingCache();
console.log(cache);

// single URL entry
const entry = getPingCache('https://www.google.com');
console.log(entry.connected, entry.expires);