ReplayEngine

^{ref / conversations / ReplayEngine}

A replay engine takes control of the event loop of the JavaScript runtime and lets you execute a JavaScript function in abnormal ways. The function execution can be halted, resumed, aborted, and reversed. This lets you run a function partially and persist the state of execution in a database. Later, function execution can be resumed from where it was left off.

Replay engines are the fundamental building block of the conversations plugin. In a sense, everything else is just a number of wrapper layers to make working with replay engines more convenient, and to integrate the power of replay engines into your bot’s middleware system.

Using a standalone replay engine is straightforward.

1. Create an instance of this class and pass a normal JavaScript function to the constructor. The function receives a ReplayControls object as its only parameter.
2. Call ReplayEngine.play to begin a new execution. It returns a ReplayResult object.
3. Use the ReplayState you obtained inside the result object and resume execution by calling ReplayEngine.replay.

The ReplayEngine class furthermore provides you with static helper methods to supply values to interrupts, and to reset the replay state to a previously created checkpoint.

^Source

Constructors

ReplayEngine(builder: Builder);

Constructs a new replay engine from a builder function. The function receives a single parameter that can be used to control the replay.

^Source

Methods

play

play();

Begins a new execution of the builder function. This starts based on fresh state. The execution is independent from any previously created executions.

A ReplayResult object is returned to communicate the outcome of the execution.

^Source

replay

replay(state: ReplayState);

Resumes execution based on a previously created replay state. This is the most important method of this class.

A ReplayResult object is returned to communicate the outcome of the execution.

^Source

Static Methods

open

open(key: string);

Creates a new replay state with a single unresolved interrupt. This state can be used as a starting point to replay arbitrary builder functions.

You need to pass the collation key for the aforementioned first interrupt. This must be the same value that the builder function will pass to its first interrupt.

^Source

supply

supply(
  state: ReplayState,
  interrupt: number,
  value: unknown,
);

Mutates a given replay state by supplying a value for a given interrupt. The next time the state is replayed, the targeted interrupt will return this value.

The interrupt value has to be one of the interrupts of a previously received Interrupted result.

In addition to mutating the replay state, a checkpoint is created and returned. This checkpoint may be used to reset the replay state to its previous value. This will undo this and all following mutations.

^Source

reset

reset(state: ReplayState, checkpoint: Checkpoint): void;

Resets a given replay state to a previously received checkpoint by mutating the replay state.

^Source