https://github.com/imbhargav5/armin
Declarative state machines for React!
https://github.com/imbhargav5/armin
flux react react-context state-machine store
Last synced: about 1 year ago
JSON representation
Declarative state machines for React!
- Host: GitHub
- URL: https://github.com/imbhargav5/armin
- Owner: imbhargav5
- License: mit
- Created: 2018-04-14T18:29:20.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-05-30T07:16:02.000Z (about 8 years ago)
- Last Synced: 2025-03-17T16:19:39.683Z (about 1 year ago)
- Topics: flux, react, react-context, state-machine, store
- Language: JavaScript
- Homepage:
- Size: 278 KB
- Stars: 21
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Declarative state machines for React!
React Component state is a powerful way of managing state within a component, but can we do more? Can we create and maintain state which is more readable and self-explantory and powerful at the same time?
## Quick Example
```javascript
import {createMachine} from "armin"
const ViewToggler = createMachine({
allStates: ["visible", "hidden"],
state : "visible",
reducers : {
hide : {
from : ["visible"],
setState : () => "hidden"
},
show : {
from : ["hidden"],
setState : () => "visible"
}
}
})
// In your component's render method
...
{toggler => <>
Show
Hide
>}
...
```
So what is going on there?
The configuration for a state machine like above means that,
- All your states have names
- Reducers describe how state can be updated using `from` and `setState` keywords.
- `allStates` defines all the valid states your state machine can take.
- When you create a state machine you get a `Provider` and `Consumer` and the `Consumer` is able to expose a `controller` which is capable of performing actions and manipulate state of your machine. You can create as many consumers as you like and they all talk to each other through the `Provider`.
Is that all `Armin` can do? Nope. Let's take a slightly larger example.
### Single State Machine -> An async counter example with armin
1. Create a machine
```javascript
import {createMachine} from "armin"
const { Provider, Consumer } = createMachine({
allStates: ["ready", "running", "stopped"],
state: "ready",
value: 0,
reducers: {
increment: {
setValue: ({ value, state }, payload = 1) => value + payload,
setState: () => "running"
},
decrement: {
from: ["running"],
setValue: ({ value, state }, payload = 1) => value - payload,
setState: (opts, setValue) =>
setValue <= 0 ? "stopped" : "running"
// setState function has access to the newValue that was generated in setValue as the second argument. Opts
// contains current value and current state.
},
stop: {
from: ["ready", "running"],
setValue: ({ value }) => value,
setState: () => "stopped"
}
},
effects: {
async incrementAsync() {
console.log("waiting");
await new Promise(resolve =>
setTimeout(() => {
console.log("done waiting");
resolve();
}, 1000)
);
this.increment(5);
}
}
});
```
So in the example above, we also use the `value` property to give the machine a value to keep track of. This can be any javascript value including strings, numbers, objects and functions.
The `effects` key is where we define `async` actions for our state machine. All async actions have access to the reducers defined in the `reducers` key. They are bound to the controller hence, `this.increment` is perfectly valid inside an async action. This means that, while all reducers are synchronous, you can create async actions and call the reducers within them as and when needed. This was inspired from Rematch.
2. Using the machine inside React
```javascript
{machineController => {
return (
machineController.increment(2)}
>
Increment By 2
Value is {machineController.value}
machineController.decrement(1)}
>
Decrement
machineController.incrementAsync()}
>
Wait for a second and increment by 5
machineController.stop()}
>
Stop counter
);
}}
```
Here our machineController object has two special keys `can` and `is`. `can` tells us whether a particular `reducer` action is valid for the state the controller is in. This is automatic and is derived from the reducer configuration given during machine creation. `is` just tells us if the machine is in a particular state or not. For eg: `machineController.is.stopped` etc.
These are handy when you want to control the views by disabling/enabling input, permissions etc.
Now, let's take a more complex example.
### Multiple state machines
Just like above, but we can create multiple machines at once and then subscribe to only the ones we need to ensure maximum performance during rerenders on update.
```javascript
import {init} from "armin"
// create a an object with state machine config as above
const toggler = {
allStates: ["showing", "hiding"],
state: "hiding",
reducers: {
show: {
from: ["hiding"],
setState: () => "showing"
},
hide: {
from: ["showing"],
setState: () => "hiding"
}
}
}
const counter = {
...
}
const user = {
...
}
const { store, Provider, createConsumer } = init({
toggler,
counter,
user
});
const Consumer = createConsumer(["toggler","counter"]);
class MyChildComponent extends Component{
render(){
return
{([toggler,counter]) => {counter.value}}
}
}
class MyRootComponent extends Component{
render(){
return
}
}
```
Almost everything above is the same as in previous examples. Except here, we are able to combine multiple machines together for a component using the `init` function and subscribe to all or a subset of those using the `createConsumer` utility. This means that we can subscribe to only those machines that we need and prevent unnecessary renders when an update occurs.
## Motivation
Let's compare these two examples.
```javascript
Delete
```
vs
```javascript
0 && counter.value < counter.MAX_VALUE}
onClick={counter.increment} >
Decrement
```
The first one is extremely readable and you can immeditately tell what the developer is trying to do in this code. It hardly requires comments. That is the motivation for this project.
State machines in Arminjs with meaningful names for states have great potential to make developer experience great for building applications with React.
## Features :
- State machine creation is similar to the api of Rematch
- Uses the new 16.3 React Context API for data flow across components
- Async actions are supported
- Multiple state machines are supported but you can subscribe to only the ones you need
within a component
### License
MIT