flow.stop()

The flow.stop() method stops a flow immediately. Its cleanup callbacks are run, and the flow is prevented from ever triggering again.

This method does not interact with the flow pipeline; when called, it stops the flow immediately. After calling it once, doing so again has no effect.

Note: If a flow is created in a monitored context (one monitoring for type "undo" then it is not necessary to manually stop a Flow; when the context is undone, the flow is stopped automatically.

Syntax

flow.stop();

Parameters

None.

Return value

The same Flow object the method was called on.

Examples

Stop a listener

For the sake of the example, let's set up and take down a listener without the usual methods, i.e. without monitored contexts or .until(). To do so, we'll need to keep a reference to the Flow returned by when():

const button = document.querySelector('button'); const listener = when(button).clicks().then(() => { // do things… });

Now, with a reference (listener) to the Flow object for the event listener, we can stop it at any point by calling

listener.stop()

If any additional .cleanup() callbacks were added, then these are run once we .stop() the flow.

Usage notes

Once a flow has been stopped, all references to pipeline callbacks are removed, and no more can be added. Additionally, cleanup callbacks are run synchronously as soon as a flow stops. When a cleanup callback is added after a flow has been stopped, that cleanup callback fires immediately.

A stopped flow is essentially useless, because it can no longer trigger; not even by manually calling flow.now(). As such, it is not advised to retain references to flows after they have been stopped.