States Language is the JSON specification behind AWS Step Functions, a powerful way to coordinate many disparate services into a cohesive “serverless” system. This library uses the same JSON specification and compiles to Elixir based :gen_statem processes.
Why
The initial idea for the Elixir implementation came about while working on an IVR system and we wanted a way to describe “call flows” in a declarative manner. Ideally building a system on top to allow for solution engineers to visually build call flows for a client, without writing any code.
After researching the space a bit, we landed on the States Language spec and decided it was a great fit for describing state machines. With the power of Elixir macros in-hand, this library was born.
I’ve been working on this for a few months now and have found it to be a super useful way to design state machines. Using JSON as a declarative format has also opened up a lot of opportunities for sharing this structure across projects and UIs. There’s even some mix tasks to quickly output your state machines to Graphviz and DagreD3.
The Hexdocs documentation is pretty robust, but feel free to post any questions you have here.
I hope the community finds this as useful of a tool as we have.
IVR call flows
LiveView state manager
API input normalization
Microservice orchestration
It’s great being able to vidualize your state machines, and build editors around them.
For building editors, I’ve found being able to use the JSON Schema along with JSON Schema UI for domain specific customization to be really powerful. With dropdowns for known Resource types and TransitionEvents, it’s easy to let non programmers design their state machines.
I’d mostly be happy to see a flow of some sort, where you can’t get to an invalid state if the previous state invariants aren’t satisfied. Doesn’t have to be complex.
I struggle with a complex DB structure in my work where too much objects in the DB can be left in an inconsistent state and something that relies on them down the line can easily break, so I am wondering if a state machine can be a frictionless solution to that.
It’s similar in that it uses a declarative text format to define your states and transitions. However Javascript doesn’t have gen_statem And although it abstracts some of the complexities away from utilizing gen_statem, you still have complete access to all the functionality if need be.
whether it’s possible to generate a state machine that is simply a data structure - like https://github.com/sasa1977/fsm for example
I work quite a bit with network protocols, and also with things that get serialised to disk. Having them be independent of a BEAM process and surviving serialisation make testing these things very very nice.
Maybe its already there, & I haven’t finished the examples yet. Thanks for publishing this!
For a visual design tool, you can actually use the AWS Step function editor. I’ll hopefully be working on an editor over the next month or so. We have one at work, but it’s not ready to open source.
Hmm, a process-less version could be really interesting. I hadn’t thought of that. I’m interested in your thoughts around it. How would it maintain it’s current state, would you rely on another process to maintain that?
I’ll dig a little more deeply into Sasa’s work for an idea.
It ends up looking a lot like pipelining, the resulting state is just a struct internally and you drop it into a variable or stash it in a file. Pattern match function calls based on the struct like usual. Then you can embed this into a :gen_tcp or :gen_udp or Connection for example.
I pushed out a new release the other day, 0.2.5. It includes some fixes for string based events and a Graphviz serialization fix for the string events as well.
Unfortunately I haven’t had much time to work on a web based visual editor, but with the Graphviz support, it’s a really quick way to visually validate your logic.
For the editor, I’ve been looking into https://rete.js.org/ which I think could be really cool!
Here’s a screenshot of the one I’ve built at work, it’s not drag and drop, but does allow you to CRUD states and visualize the state machine in real-time.
I had another request to enable serialization. The main thing that needs to be added is starting the state machine from an arbitrary state. It should be pretty easy to implement, just haven’t gotten around to it yet.
FYI, the JSON that’s outputted right now in the editor isn’t 100% correct. I should have time today to get it corrected, but just in-case anyone wants to play around with it, it’s not quite complete.
This new version sets the child_spec restart setting to :transient, which it probably should have been all along, an oversight on my part.
This release also adds the ability to override the “start” state when starting the process. This would allow you to persist the process state and data and resume where you left off at a later time. There is now an optional start option that can be passed to start_link or start. You can see it’s usage in the documentation here or in the tests here
Editor Updates
The editor allows you to paste in your JSON and reload to use a GUI editor and view the Dagre graph.
All Editor changes should be reflected in the JSON and Dagre graph immediately.
And finally, a new version 0.2.9 was pushed hex.pm to fix a bug where "End": true states were not capturing the state data that was changed in the final state resource.
And although it abstracts some of the complexities away from utilizing gen_statem, you still have complete access to all the functionality if need be.
