The Pilota library provides a command dispatcher for use with RxJS streams. The bus receives and executes command objects that transform from one immutable state to another. See the "store" within the Redux framework for a similar pattern.
This shows a set of commands that increment and decrement a simple integer state:
import {newCmdBus$} from 'pilota'
const state$ = new Rx.BehaviorSubject(0)
...
const bus$ = newCmdBus$(state$)
bus$.addHandler('increment', x => x + 1)
bus$.addHandler('decrement', x => x - 1)
...
// explicitly execute a command...
bus$.next('increment')
// ...or feed it directly from anther stream:
Rx.Observer.fromEvent(e, 'click').mapTo('decrement').subscribe(bus$)
Use [email protected] for RxJS 5, and then later releases for 6.
Use an RxJS Subject
to represent the model or state. An Rx.BehaviorSubject
works well.
const bus$ = newCmdBus$(state$)
Trigger the execution of a command using a command objects. This is any Javascript object with a name
property, but it can-- and will often-- have other properties:
bus$.next({ name: 'add', value: 1, other_data: 'abcdef', ... })
The name of the command should be a String. You are free to use constants if that floats your boat.
If there are no other properties, a simple string may be used, and the command object will be created automatically:
bus$.next('increment')
The command bus provides a method to map specific command names to given handler function:
bus$.addHandler(name, handlerFn)
A command handler itself is a simple function with this signature:
fn(previous-state, cmdObject) # => new-state
The command handler function receives the current state (considered immutable) and returns the new state based on the effect of the command. This simple contract makes it quite easy to unit test the business logic.
The name appears on the command bus, it triggers the given handler function. In Redux parlance, the name of the command is called its "type", and the handler is a "reducer" function.
A generic '*' handler name may be added to catch unassigned commands. It still must conform to the contract of returning a new state. This presumably could be used to write your own dispatcher in a switch
statement.
If there is no matching function, and no wildcard was registered, then no new state is triggered, and the command is ignored.
The examples are push style, and therefore not "reactive". It's more common to feed the command bus in response to an existing stream, such as:
Rx.Observable
.fromEvent(elem, 'click')
.mapTo('increment')
.subscribe(bus$)
Internally addHandler
simply builds a hashmap of the command names to the functions that handle them. This can be DRYed by creating the command bus from a Javascript object:
const commands = {
increment: (x) => x + 1,
decrement: (x) => x - 1
}
const bus$ = newCmdBus$(state$, commands)
or simply:
const bus$ = newCmdBus$(state$, {
increment: (x) => x + 1,
decrement: (x) => x - 1
})
The bus is an observer of commands, and if a handler is available, it is called. Each command generates a new state.
Each handler receives the command object as a second parameter. Therefore, a handler for this command:
bus$.next({ name: 'add', value: 1, other_data: 'abcdef', ... })
might look like:
bus$.addHandler('add', function(state, cmdObj) {
return state + cmdObj.value
})
This second parameter can often be ignored. In fact, it is also provided as the "context" or this
of the handler. The function can access this.name
to determine the name of the command. The additional attributes will be included in the context as well. For example:
function addProperty(state) {
return Object.assign({}, state, { this.key: this.value }
}
The function normally returns the next state. This function can also return undefined
to indicate no state change, in which case the state will not be modified.
The easiest technique to provide modularity is to use separate command buses for different parts of the app. This allows separation of concerns around different parts of the model.
Given that, basic support for nested states is available with submodelCmd
. This is a wrapper for a handler:
submodelCmd([property-name], [original-handler]) // => handler
To use this, create a function that only cares about a sub-model value, and does the appropriate reducing. Normal usage is:
const state = {
foos: [...]
likes: 0
}
...
cmdBus$.addHandler('incLikes', submodelCmd('likes', (state) => state + 1))
[Experimental] It can also be partially applied, with just the function, as in:
inc = submodelCmd((state) => state + 1)
cmdBus$.addHandler('incLikes', inc('likes')
The dispatching strategy can be overriden by passing your own dispatcher. See newDispatcher
for the standard implementation. Using this technique, the command bus can be object-oriented, where each command is handled by a method of an object. Or it could be implemented using a switch statement, as is common to Redux.
- decide
addHandler
vs.on
addHandlers
- asynchronous pattern
Copyright (c) 2016-2021 Andrew J. Peterson Apache 2.0 License