https://github.com/mutativejs/xstate-mutative
A faster and more flexible utilities for using Mutative with XState
https://github.com/mutativejs/xstate-mutative
fsm immutability mutative state-machine xstate
Last synced: 4 months ago
JSON representation
A faster and more flexible utilities for using Mutative with XState
- Host: GitHub
- URL: https://github.com/mutativejs/xstate-mutative
- Owner: mutativejs
- License: mit
- Created: 2024-09-14T18:35:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-22T16:28:08.000Z (5 months ago)
- Last Synced: 2025-05-22T16:29:57.305Z (5 months ago)
- Topics: fsm, immutability, mutative, state-machine, xstate
- Language: TypeScript
- Homepage:
- Size: 349 KB
- Stars: 16
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# xstate-mutative
[](https://www.npmjs.com/package/xstate-mutative)
A faster and more flexible utilities for using [Mutative](https://github.com/unadlib/mutative) with XState
`xstate-mutative` is more than 10x faster than `@xstate/immer`. [Read more about the performance comparison in Mutative](https://mutative.js.org/docs/getting-started/performance).
## Installation
In order to use the Mutative utilities in XState, you will need to install Mutative and XState as a direct dependency.
```bash
npm install xstate mutative xstate-mutative
# Or use any package manager of your choice.
```
## Usage
Import the Mutative utilities:
```js
import { createMachine, interpret } from 'xstate';
import { assign, createUpdater } from 'xstate-mutative';
const levelUpdater = createUpdater('UPDATE_LEVEL', (ctx, { input }) => {
ctx.level = input;
});
const toggleMachine = createMachine({
id: 'toggle',
context: {
count: 0,
level: 0,
},
initial: 'inactive',
states: {
inactive: {
on: {
TOGGLE: {
target: 'active',
// Immutably update context the same "mutable"
// way as you would do with Mutative!
actions: assign((ctx) => ctx.count++),
},
},
},
active: {
on: {
TOGGLE: {
target: 'inactive',
},
// Use the updater for more convenience:
[levelUpdater.type]: {
actions: levelUpdater.action,
},
},
},
},
});
const toggleService = interpret(toggleMachine)
.onTransition((state) => {
console.log(state.context);
})
.start();
toggleService.send({ type: 'TOGGLE' });
// { count: 1, level: 0 }
toggleService.send(levelUpdater.update(9));
// { count: 1, level: 9 }
toggleService.send({ type: 'TOGGLE' });
// { count: 2, level: 9 }
toggleService.send(levelUpdater.update(-100));
// Notice how the level is not updated in 'inactive' state:
// { count: 2, level: 9 }
```
### Mutative Options
- [Strict mode](https://mutative.js.org/docs/advanced-guides/strict-mode)
- [Auto Freeze](https://mutative.js.org/docs/advanced-guides/auto-freeze)
- [Marking data structure](https://mutative.js.org/docs/advanced-guides/mark)
## Credits
`xstate-mutative` is inspired by `@xstate/immer`.
It uses the same API as `@xstate/immer` but uses Mutative under the hood. The repository is based on the `@xstate/immer` repository.
## License
`xstate-mutative` is [MIT licensed](https://github.com/mutativejs/xstate-mutative/blob/main/LICENSE).