xstate offline machine
The offline
machine should be used within a browser to enable offline/online state management.
It reacts to network state changes (You can force this in devtools) and has the ability to force offline
for testing apps in an offline environment.
Installation
yarn add xstate-offline-machine
States
The offline machine can only ever be in two states: offline
and online
, with the additional capability to be forced offline for testing purposes.
Events
OFFLINE_STATUS
This event can be sent at any time and will send the current status back to the parent via a NotifyParent
event.
Responses
STATUS_ONLINE
when online
Configurable event name sent to parent.
// Example
app.send('OFFLINE_STATUS'); // ping the offline machine
// offline responds with
{
"type": "STATUS_ONLINE",
"isForcedOffline": false
}
STATUS_OFFLINE
when offline
Configurable event name sent to parent.
// Example
app.send('OFFLINE_STATUS'); // ping the offline machine
// offline responds with
{
"type": "STATUS_OFFLINE",
"isForcedOffline": false
}
OFFLINE_FORCE_OFFLINE
This event can be sent to force the machine into an offline
state even when online. Very helpful for testing applications under offline circumstances.
Any offline
or online
navigator events will be ignored while forced offline.
OFFLINE_FORCE_OFFLINE_UNDO
Disables forcing the machine offline, the machine is realigned into the current offline
or online
states depending on the current navigator.onLine
status
NotifyParent
All the parent messages are of type NotifyParent
interface NotifyParent {
type: string;
isForcedOffline: boolean;
}
Integration
Should be invoked by a parent machine
The offline
machine is much more useful when invoked by a parent. The idea is that this can be reused in any app, that needs to handle offline capabilities.
Example
import { assign, send, spawn } from 'xstate';
import isOfflineMachine from 'xstate-offline-machine';
const { Machine } = require('xstate');
const appMachine = Machine({
id: 'app',
initial: 'idle',
context: {
offline: undefined,
},
states: {
idle: {
on: {
INITIALIZE: {
target: 'ready',
actions: assign({
offline: () => spawn(isOfflineMachine, { name: 'offline' }),
}),
},
},
},
},
});
And then running the app like this
import appMachine from './machines/app.machine';
const app = interpret(appMachine).start();
app.send('INITIALIZE');
Note: This is just an example, you can invoke however you want.
Configuration
buildOfflineMachine
and buildOfflineMachineOptions
are exported and can be used to configure the machine to suit your needs. If you would like to return different messages to the parent then it can be done like so.
import { buildOfflineMachine, buildOfflineMachineOptions } from 'xstate-offline-machine';
const isOfflineMachine = Machine(
buildOfflineMachine({
statusOnlineEventName: 'MY_APP_IS_ONLINE',
statusOfflineEventName: 'MY_APP_IS_OFFLINE',
}),
buildOfflineMachineOptions({})
);
// ...
And the app would reecive MY_APP_IS_ONLINE
and MY_APP_IS_OFFLINE
events after an OFFLINE_STATUS
event.