flow
A minimalistic functional state machine
This is an attempt to build the simplest functional state machine without any external dependencies. Reviewers who can contribute to make it simpler or more efficient without compromising funcionality are welcome.
Borrowing from functional programming, coroutines, and generator functions; this "coded by convention" loop sets the foundation to compose more complex applications with just three basic constructs:
-
Actions - Pure functions with logic to drive internal transitions
-
Reducer - Pure function with logic to reduce the state from internal and external transition payloads
-
Flow - A closure with the coroutine implementing the loop and holding the state
Conventions
-
Anonymous actions yield control back to the caller (User). Think of it as a one-time yielding generator function.
-
Actions can optionally return:
- An Object - action payload
- An Action - (named or anonymous) to allow composition
- An Array of the above - to be executed in order
The loop
The flow is initialized with a map of actions, optional parameters, the reducer, and optional callbacks (invoked, shifted) for tracing and debugging actions. The injected action map allows composition without coupling modules.
The returned coroutine must be started with a root action and can be successively invoked with transition payloads. It always returns its internal structure including the current state and scope.
Actions are internally invoked with 3 arguments: (state, scope, { params, actions }).
The flow keeps track of action recursion, indentation, and stack depth levels in the scope object.
Schema
flow = state: ... // current reduced state scope: // current scope name: 'string' // action name recur: 'int' // recurrence counter parent: ... // parent scope level: 'int' // indentation level depth: 'int' // stack depth yielding: 'function' // yielding action stack: // current stack done: 'bool' // true when end of stack reached
How to use
const flow = { return ask: `Am I speaking with ?` { if stateaction1answer === 'yes' return if recur < 2 return action1 } } const root = { return actionsaction1 { if stateaction1answer === 'yes' return say: `Hello . How are you today?` return say: "I'm sorry for the inconvenience." } } const next = let $ = // start root action$ = // update action1 state$ = // update action1 stateconsole
Test
npm test
The provided tests are self explanatory and should log a trace like this:
simple test 0 { // [authenticate(state,scope,{params}), next({authenticate,verifyPhone,canComeToThePhone})] 2 { // [{"ask":"Am I speakin...}, (state,{recur})] 2 "ask":"Am I speaking with John Doe?" 2 staterecur ... "authenticate":"answer":"whatever" 3 authenticate: // [{"ask":"Am I speakin...}, (state,{recur})] 3 "ask":"Am I speaking with John Doe?" 3 staterecur ... "authenticate":"answer":"yes" 3 // authenticate:1 2 } // authenticate 1 { 1 "say":"Hello John Doe. How are you today?""authenticated":true 1 } // next 0 } // root === state: ask: 'Am I speaking with John Doe?' authenticate: answer: 'yes' say: 'Hello John Doe. How are you today?' authenticated: true scope: {} stack: done: true=== √ should authenticate
Leonardo da Vinci
Contributing
In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.