# usestatetransition

> Other flavor of a state machine hook

Latest version **0.3.3** (published 2023-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install usestatetransition
pnpm add usestatetransition
yarn add usestatetransition
bun add usestatetransition
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.3 |
| Published | 2023-09-04 |
| First published | 2021-12-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 61.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Łukasz Marek Sielski |
| Maintainers | sielay |
| Keywords | react, state, machine, state, transition, hook, react-hook, typescript, state-management, statemachine, usestatemachine, state-machine |

## Links

- npm: https://www.npmjs.com/package/usestatetransition
- Repository: https://github.com/sielay/useStateTransition
- Homepage: https://github.com/sielay/useStateTransition#readme
- Issues: https://github.com/sielay/useStateTransition/issues
- npm.io page: https://npm.io/package/usestatetransition

## Dependencies (3)

- [debug](https://npm.io/package/debug.md) ^4.3.3
- [react](https://npm.io/package/react.md) ^18.0.2
- [react-dom](https://npm.io/package/react-dom.md) ^18.0.2

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.3.3 (latest) — 2023-09-04
- 0.2.3 — 2021-12-13
- 0.2.2 — 2021-12-13
- 0.2.1 — 2021-12-13
- 0.2.0 — 2021-12-13
- 0.1.1 — 2021-12-12
- 0.1.0 — 2021-12-11
- 0.0.1 — 2021-12-11

## README

# useStateTransition

If you look for a classic state machine, check [cassiozen/useStateMachine](https://github.com/cassiozen/useStateMachine).

## Problem

One of my project is an app that can open various editors. Each editor can have different implementation, but needs to follow the same lifecycle. I wanted to provide a neat small hook that would handle it, so specific editors don't have too keep too much knowledge about the host app.

While doing it turned out I need some sort of state machine. The difference was that I need it to be focused more on transition between specific states.

Other nice projects implementing state machine hook were following enter/leave version of the pattern, that was focused on the state, rather than transition.

## Example

Check the [tests example](./src/__tests__/example/useEditor.tsx).

```ts
const { state, dispatch } = useStateTransition<EditorState>({
    initial: EditorState.INIT,
    flows: [
      {
        from: EditorState.INIT,
        to: EditorState.READY,
        on: (_, setState) => {
          setState(scenario === "new" ? EditorState.NEW : EditorState.LOAD);
        },
      },
      {
        from: [EditorState.NEW, EditorState.LOAD],
        to: EditorState.OPEN,
      },
    ],
  });
```

## API

```ts
const { state, dispatch, error } = useStateTransition<StateType>(options)
```

### state

Current state of provided `StateType`. The first value comes from `initial` field in `options`.

### dispatch

```ts
type Dispatch = (requestedState: StateType, data?: unknown) => void;
```

You use it to trigger the transition. Transition to the same state won't trigger any updates. If the request create unknown transition `error` will be populated.

#### Conditional dispatch

You can pass a function to dispatch to decide which state you dispatch to based on the current state. It's useful when you dispatch comes from useCallback which would cache the initial state

```ts

dispatchFn((currentState, data) => {
  if (currentState = 1) {
    return {
      to: 2,
      data // you can decide to pass the data
    }
  }
  return {
      to: 3
      // or to filter out the data
  }
}

```

### error

Display the latest error. At the moment it reports only about unknown transitions.

### options

You need to define the `initialValue` of the state and the flows.

```ts
{
    initialValue: StateType,
    flows: Flow[]
}
```

### Flow

```ts
{
    from: StateType | StateType[],
    to: State | StateType[],
    on?: (requestedState: StateType, setState: (state: StateType) => void, data?: unknown) => void;
}
```

 * `from` defines the state you want to transition from; you can specify one or many states.
 * `to` defines the state you want to transition to; you can specify oen or many states.
 * `on` (optional)
    * if absent the state machine will just allow transition
    * if present it works like a guard, in the end you can specify which state you want to set. It won't trigger another guard or test, it will just update the sate.
    * you have access to `data` passed, so you can update your other hooks.
    * it happens in `useEffect`

## License

MIT

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