1Introduction

⁠1.1⁠What XJog is for

At its heart, XJog is a TypeScript library for running XState statecharts. XState in turn is a library for running Harel statecharts.

It differs from the XState's built-in interpreter mainly in that it persists the state in a database. This way, logical processes that outlive the execution time of the runner, can be run. In-memory statecharts would disappear and their state would be lost, when the running process is terminated.

For example, a customer journey in an online shop could be modelled as a statechart and run by XJog. The charts could orchestrate the cart, price calculations, checkout and even delivery. The benefit is that the whole customer journey is in a single, well-defined state, with well-defined transitions between them.

Persisting server state is another example. A service in a Kubernetes cluster, could be terminated by Kubernetes itself, in case of running out of memory, for example. With state persisted with XJog, the service can continue right where it was interrupted.

Using SQLite database adapter, shipped with XJog, local applications too could persist state on disk without external database.

⁠1.2⁠Instance lifecycle

XJog runs as a single instance per database. The purpose is to make sure that timing of deferred events, management of ongoing activities etc. are only handled in one place.

When starting up, a new instance will signal the previously running instance that it needs to shut down. During a grace period, it waits for the old XJog instance to release control of its charts. After the grace period has passed, it will take the rest without waiting.

Fig. 1⁠ XJog instance's lifecycle

Note

This design prevents usual horizontal scaling associated with stateless services, because XJog runs stateful activities and provides timing capabilities. External sharding can be applied if there is need for horizontal scaling.

⁠1.3⁠Building blocks

There are three main components in XJog, as presented in figure 2. They are connected to a database using a persistence adapter.

Fig. 2⁠ Fundamental components of XJog

XJog is the main orchestrator for registering XState machines, managing ongoing activities, and managing timers. XJogMachine gives an interface for creating and accessing charts of their type. XJogChart is an interface to individual charts. It can be used to read state and send events.

In XState, all of these functions are taken care by an Interpreter.

⁠1.4⁠Additional features

Deltas (optional) are a record of any changes to chart states and of the events that caused them. This can be useful for audit logging, monitoring, debugging and troubleshooting purposes.

External identifiers are key-value pairs associated with a chart. They are useful for routing events to correct charts when, for example, listening to events from an external service.