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.

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.ready
• connectionStatus.ok
• connectionStatus.isChecking
• 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	Object with .get(), .set(properties) and .unset() methods to persist the connection status. Each method must return a promise, .get() must resolve with the current state or an empty object. If set to false the connection status will not be persisted.	Defaults to a localStorage-based API
options.cacheTimeout	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.ready

Read-only

Promise that resolves once the ConnectionStatus instance loaded its current state from the cache.

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 undefined if status not loaded yet, see connectionStatus.ready
• Returns true if connection is checked continuously
• Returns false if connection is not checked continuously

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

Resolves without values.

Example

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

connectionStatus.stopChecking()

Stops checking connection continuously.

connectionStatus.stopChecking()

Resolves without values. Does not reject.

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 git@github.com: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