# @dra2020/fsm

> Library for managing execution of tree of finite state machines.

Latest version **1.3.3** (published 2020-12-15) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @dra2020/fsm
pnpm add @dra2020/fsm
yarn add @dra2020/fsm
bun add @dra2020/fsm
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2020-12-15 |
| First published | 2019-08-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 66.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Terry Crowley |
| Maintainers | alecramsay, terrencecrowley, davebradlee, david-js, johnwana, mbradlee, iwahbe |
| Keywords | Typescript |

## Links

- npm: https://www.npmjs.com/package/@dra2020/fsm
- Repository: https://github.com/dra2020/fsm
- Homepage: https://github.com/dra2020/fsm#readme
- Issues: https://github.com/dra2020/fsm/issues
- npm.io page: https://npm.io/package/@dra2020/fsm

## Dependencies (1)

- [@dra2020/util](https://npm.io/package/@dra2020/util.md) ^1.1.3

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.3.3 (latest) — 2020-12-15
- 1.3.2 — 2020-12-14
- 1.3.1 — 2020-03-19
- 1.2.1 — 2020-03-17
- 1.2.0 — 2020-03-14
- 1.1.0 — 2020-01-28
- 1.0.16 — 2019-10-25
- 1.0.15 — 2019-08-26
- 1.0.14 — 2019-08-20
- 1.0.13 — 2019-08-13
- 1.0.12 — 2019-08-13

## README

# fsm
Library for managing the execution of a linked tree of finite state machines.

# Overview

The `Fsm` library and class serves as the base class for chainable finite state machines.

The library improves management of asynchronous work in several ways over more primitive syntactic approaches
like plain callbacks, async/await, promises or async libraries. These include:

- The state of your computation is managed as an explicit set of objects rather than
an opaque mixture of callbacks and closures.

- It is easy to model a computation that proceeds through multiple intermediate states rather
than simply "in-process" or "done".

- Computations (objects) can be built as a tree of dependent computations, effectively acting as a
data-flow model, a natural way of describing many computations.

- The mechanism integrates well with existing mechanisms like callbacks and promises.

- A state machine more directly models how the computation is proceeding rather than syntactic models
like async/await that explicitly try to hide the real control flow.

- Requiring a class definition to represent the computation tends to facilitate reuse of the
asynchronous logic rather than having callbacks sprinkled through the code base.

A potential disadvantage of the FSM mechanism is that requiring a new subclass tends
to have a heavier syntactic weight than
mechanisms like simple callbacks.
For some, this is an advantage in not trivializing the additional
state complexity that an outstanding asynchronous computation represents for the application.

The normal usage is to sub-class the Fsm base class and override the `tick` function to walk the
state machine through its states.

Each machine begins in the FSM_STARTING state.
The `tick` function on the class gets scheduled to be called (asynchronously) initially after
construction and then explicitly whenever
the state changes (by a call to the class function `setState`).

A subclass overrides the `tick` function to run the machine through its state transitions.

Additionally, a finite state machine can `waitOn` another state machine.
When that machine is marked complete (either `FSM_DONE` or `FSM_ERROR`),
any machines waiting on that state machine get scheduled to have their `tick` function called as well.

A machine is `ready` when all `Fsm`'s it is waiting on have been marked complete.

The `tick` function of a dependent state machine is called whenever any machine it is waiting on completes,
but normally the `tick` function only performs activity when the machine is `ready`.

Most usage involves the `tick` function first testing if it is `ready` before doing any activity,
although a usage that wanted to take action whenever any waitedOn dependent completes might omit that test
(e.g. to race multiple asynchronous operations and use whichever result completes first or
immediately complete if any one of several outstanding dependents fail).

For example, this is typical usage:

```javascript
tick(): void
{
  if (this.ready)
  {
    // all dependents are complete, take action now
  }
}
```

Of course, a state machine can go from `ready` to not `ready` as many times as necessary simply by waiting on
some new `Fsm` within its `tick` function.

Normally a Fsm-based class does not fire off any activity until the first time its `tick` function is called (rather than
in the constructor).

So,

```javascript
constructor(env: Environment)
{
  super(env);
  // Don't do any real work here.
}

tick(): void
{
  if (this.ready)
  {
    switch (this.state)
    {
      case FSM_STARTING:
        // Kick off activity here
        break;
    }
  }
}
```

That is not a requirement but increases flexibility by allowing clients to construct the Fsm and
then add dependents it must wait on before any activity is kicked off.

The infrastructure only cares about the starting state FSM_STARTING and the completion states `FSM_ERROR` and `FSM_DONE`.
Any other state values can
be used internally to a state machine to manage walking through different active states prior to completion.
For convenenience, the names `FSM_CUSTOM1` through `FSM_CUSTOM9` are predefined and internal states can use these
values (typically assigned to something semantically meaningful) however they wish.

The state `FSM_PENDING` has no special meaning but is defined for convenience since many state machines go through
a single intermediate state (`FSM_STARTING` to `FSM_PENDING` to `FSM_DONE`).

Callbacks can be integrated easily by having the callback set the `Fsm` state, which allows either completion
notification to any other waiting state machines or the next step in the current state machine to be executed.

```javascript
tick(): void
{
  if (this.ready)
  {
    switch (this.state)
    {
      case FSM_STARTING:
        asyncAPIWithCallback((err: any, result: any) => {
            if (err)
              this.setState(FSM_ERROR);
            else
              this.setState(FSM_DONE);
          });
        break;
    }
  }
}
```

or

```javascript
tick(): void
{
  if (this.ready)
  {
    switch (this.state)
    {
      case FSM_STARTING:
        asyncAPIWithCallback((err: any, result: any) => {
            if (err)
              this.setState(FSM_ERROR);
            else
              this.setState(FSM_PENDING);
          });
        break;

      case FSM_PENDING:
        // Do more stuff here now that callback has completed.
        break;
    }
  }
}
```


### isDependentError

When an `Fsm` that is being waited on completes with an error, any waiting `Fsm`'s get the `isDependentError` flag set
and of course get a chance to run their `tick` function (since the dependent `Fsm` has completed).

They can decide if the semantics of the relationship then requires them to propagate, consume or otherwise handle the
error. No other error propagation happens automatically.
So:

```javascript
tick(): void
{
  if (this.ready && this.isDependentError)
    this.setState(FSM_ERROR);
  else if (this.ready)
  {
    // Normal code here
  }
}
```

would explicitly immediately propagate a dependent error.

Note that the check above to test whether the state machine is `ready` before `isDependentError` is to ensure you do not
loop continuously resetting the state to FSM_ERROR on each `tick` invocation.

### Reuse

An `Fsm` can be reused and transition from `ready` to not `ready` or `done` to not `done`.


### Cancellation

There is no explicit cancellation mechanism.

By convention, a sub-class should override the `end` member function to allow external cancellation or completion.
By default this function sets the `Fsm` to `FSM_DONE` but can optionally take the `FSM_ERROR` state
to indicate error.

Whether calling `end` or setting the state explicitly to `FSM_DONE` or `FSM_ERROR` from external to
the state machine makes semantic sense depends on the specific properties and semantics of the computation.

### FsmOnDone

A simple utility class `FsmOnDone` provides a way of integrating a callback with an Fsm-based infrastructor.

The FsmOnDone class will wait till the `Fsm` passed to the constructor completes and then call the provided
callback, passing the completed Fsm as the argument.

```javascript
let fsm = new FsmOnDone(env, fsmWait, (fsmWait: Fsm) => {
    /* do stuff with fsmWait since it is now complete */
  });
```

### FsmSleep

`FsmSleep` is a  simple utility class that creates a dependency that is marked done after
the number of milliseconds passed to the constructor.

So:

```javascript
fsm.waitOn(new FsmSleep(env, 1000));
```

will result in the object `fsm` having a dependency that will complete in 1000ms.

### FsmLoop

`FsmLoop` is a simple utility class to run an asynchronous process in a loop at some maximum rate.
It waits for the `Fsm` passed in to complete, then uses `FsmSleep` to wait until the specified
minimum interval is complete (starting when the `Fsm` started executing)and restarts the `Fsm`.
It is required that the `Fsm` properly handles going from the `FSM_DONE` state back to `FSM_STARTING`.

### FsmArray

`FsmArray` is a simple utility class that provides a mechanism for waiting for a stream of
objects to appear in an array and consuming them, repeatedly.
It will be marked `done` when any content is made available in the array (through the member `a`)
by calling `push` or `concat`.
When the content is consumed, it should be removed with `splice` or `reset`.
At this point, the `Fsm` will be placed back in the `starting` state and can be waited on again.

---
_Source: https://npm.io/package/@dra2020/fsm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._