Skip to content

fortrieb/hoodie-connection-status

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

86 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hoodie-connection-status

hoodie.connectionStatus API for the browser

Build Status Coverage Status Dependency Status devDependency Status

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

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 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

About

🐶 connection status API for the browser

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%