hoodie-connection-status

hoodie.connectionStatus API for the browser

hoodie-connection-status is a browser library to monitor a connection status. It emits disconnect & reconnect events if the request status changes and persists its status in localStorage.

Example

var connectionStatus = new ConnectionStatus('https://example.com/ping')

connectionStatus.on('disconnect', showOfflineNotification)
connectionStatus.on('reconnect reset', hideOfflineNotification)

myOtherRemoteApiThing.on('error', connectionStatus.check)

API

• Constructor
• connectionStatus.ok
• connectionStatus.check()
• connectionStatus.startChecking()
• connectionStatus.stopChecking()
• connectionStatus.reset()
• Events

Constructor

new ConnectionStatus(options)

Argument	Type	Description	Required
options.url	String	Full url to send pings to	Yes
options.method	String	Defaults to HEAD. Must be valid http verb like 'GET' or 'POST' (case insensitive)	No
options.interval	Number	Interval in ms. If set a request is send immediately. The interval starts after each request response. Can also be set to an object to differentiate intervals by connection status, see below	No
options.interval.connected	Number	Interval in ms while connectionStatus.ok is not false. If set, a request is send immediately. The interval starts after each request response.	No
options.interval.disconnected	Number	Interval in ms while connectionStatus.ok is false. If set, a request is send immediately. The interval starts after each request response.	No
options.cache	Object or false	Defaults to { prefix: 'connection_' }. If set to false, nothing is persisted.	No
options.cache.prefix	String	Defaults to 'connection_'. will be used as the localStorage key prefix, followed by options.url	No
options.cache.timeout	Number	time in ms after which a cache shall be invalidated. When invalidated on initialisation, a reset event gets triggered on next tick.	No

Example

var connectionStatus = new ConnectionStatus('https://example.com/ping')

connectionStatus.on('disconnect', showOfflineNotification)
connectionStatus.check()

connectionStatus.ok

Read-only

connectionStatus.ok

• Returns undefined if no status yet
• Returns true last check responded ok
• Returns false if last check failed

The state is persisted in cache.

connectionStatus.isChecking

Read-only

connectionStatus.isChecking

Returns true if connection is checked continuously, otherwise false. The state is persisted in cache.

connectionStatus.check(options)

connectionStatus.check(options)

Argument	Type	Description	Required
options.timeout	Number	Time in ms after which a ping shall be aborted with a timeout error	No

Resolves without value.

Rejects with:

name	status	message
TimeoutError	0	Connection timeout
ServerError	as returned by server	as returned by server
ConnectionError	undefined	Server could not be reached

Example

connectionStatus.check()

.then(function () {
  // Connection is good, connectionStatus.ok is true
})

.catch(function () {
  // Cannot connect to server, connectionStatus.ok is false
})

connectionStatus.startChecking(options)

Starts checking connection continuously

connectionStatus.startChecking(options)

Argument	Type	Description	Required
options.interval	Number	Interval in ms. The interval starts after each request response. Can also be set to an object to differentiate interval by connection state, see below	Yes
options.interval.connected	Number	Interval in ms while connectionStatus.ok is not false. The interval starts after each request response.	No
options.interval.disconnected	Number	Interval in ms while connectionStatus.ok is false. The interval starts after each request response.	No
options.timeout	Number	Time in ms after which a ping shall be aborted with a timeout error	No

Returns connectionStatus API

Example

connectionStatus.startChecking({interval: 30000})
  .on('disconnect', showOfflineNotification)

connectionStatus.stopChecking()

Stops checking connection continuously.

connectionStatus.stopChecking()

Returns connectionStatus API

connectionStatus.reset(options)

Clears status & cache, aborts all pending requests.

connectionStatus.reset(options)

options is the same as in Constructor

Resolves without values. Does not reject.

Example

connectionStatus.reset(options).then(function () {
  connectionStatus.ok === undefined // true
})

Events

disconnect	Ping fails and connectionStatus.ok isn’t false
reconnect	Ping succeeds and connectionStatus.ok is false
reset	Cache invalidated on initialisation or connectionStatus.reset() called

Example

connectionStatus.on('disconnect', function () {})
connectionStatus.on('reconnect', function () {})
connectionStatus.on('reset', function () {})

Testing

Local setup

git clone [email protected]:hoodiehq/hoodie-connection-status.git
cd hoodie-connection-status
npm install

Run all tests and code style checks

npm test

Run all tests on file change

npm run test:watch

Run specific tests only

node tests/specs # run unit tests
node tests/specs/check # run .check() unit tests
node tests/integration/walkthrough # run walkthrough integration test
# PROTIP™ Pipe output through a [pretty reporter](https://www.npmjs.com/package/tape#pretty-reporters)

Contributing

Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join our Hoodie Community Chat.

License

Apache 2.0