hoodie-client-connection-status
hoodie.connectionStatus API for the browser
hoodie-client-connection-status
is a JavaScript library for the browser. It
allows to check a connection, and emits disconnect
& reconnect
events if
the request status changes. Status is persisted in localStorage
.
Example
var connectionStatus = 'https://example.com/ping' connectionStatusconnectionStatus myOtherRemoteApiThing
API
- Constructor
- connectionStatus.ok
- connectionStatus.check()
- connectionStatus.startChecking()
- connectionStatus.stopChecking()
- connectionStatus.reset()
- Events
Constructor
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 = 'https://example.com/ping' connectionStatusconnectionStatus
connectionStatus.ok
Read-only
connectionStatusok
- 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
connectionStatusisChecking
Returns true
if connection is checked continuously, otherwise false
.
The state is persisted in cache.
connectionStatus.check(options)
connectionStatus
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
connectionStatus.startChecking(options)
Starts checking connection continuously
connectionStatus
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
connectionStatus.stopChecking()
Stops checking connection continuously.
connectionStatus
Returns connectionStatus
API
connectionStatus.reset(options)
Clears status & cache, aborts all pending requests.
connectionStatus
options
is the same as in Constructor
Resolves without values. Does not reject.
Example
connectionStatus
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
connectionStatusconnectionStatusconnectionStatus
Testing
Local setup
git clone git@github.com:hoodiehq/hoodie-client-connection-status.git
cd hoodie-client-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)