@raid/addons > Addons and helpers for use with raid
Documentation
Getting Started Install with yarn or npm
``sh`
`sh`
Raid does one job, it helps to manage the state of your application. It does this job simply enough but sometimes you want to add some sugar or some extra _stuff_ for tasks you typically do often.
This is a disparate list of add-ons and whilst they were created with Raid in mind they could equally be used with other libraries. They are typically small utility functions and often best used composed together.
See the examples for more detailed usage.
Direct imports Addons are also provided via a direct import to the file housing the addon, which will be named the same. All exports are named exports. These are provided as tree shaking is unreliable and you often will not want to carry around every addon when you only want one/a few.
`js
import { adaptor } from '@raid/addons/adaptor'
Add-ons * Adaptor Plug Compress Debug Squash Flow Hook Match Patch Safe Scope Lock Arc
$3 () => >
An adaptor can be attached to a signal and returns a function that can be used to create a higher-order component that has data from the state provided to it, that data will be passed as props.
`js
const El = ({title}) =>
{title} const Title = connect(state => state.title, El)
`
The returned
connect
function should be supplied with a selector function (which is responsible for grabbing parts of the state) and a component function.The state selector function is optional and the component function will become the first argument if omitted.
> Libraries like reselect , which help to create the selector function for you, work great with this pattern.
When creating an adaptor a new observer is attached to the signal, the returned
connect
function has a method to remove that observer if required:
`
jsconnect.detach()
`
> The source uses JSX to pass through the
Component
and is currently building only for use with React .
$3
(
) => > => >A plug is functionally identical to
, but without the property massaging to be used any component specification i.e. it can be used with raw functions instead.Plug returns a
connect function which can be used to decorate a function and pass through state from a Raid Signal.
`jsconst hof = connect(
hof('world')
`When creating a plug a new observer is attached to the signal, the returned
function has a method to remove that observer if required:
`jsconnect.detach()
`
$3
) => >Compress is used to add functions to a particular event type and will assume events are objects of the type
. This removes the restriction to switch on events within the update function.This pattern can be applied to simplify attaching update functions to specific events.
`jsconst add = (state, payload = {}) => {
signal.register(compress({
signal.emit({
`> The signature of the update function changes semantics slightly as it will now be passed the
, rather than the entire event object.
$3
() => >Compress can also be supplied a string referencing the event type, in this case it will return a function which can be used to attach a function to that event type.
This pattern can be really effective when composing various utilities together to generate update functions.
jsconst add = (state, payload = {}) => {
signal.register(compress('ADD')(add))
signal.emit({
`> This is a one-to-one mapping between event type and update function, to add more functions to a single event use squash .
$3
=> >> _Warning_ Creates side effects
Debug creates an update function that logs the current state and the event being passed through the fold. Be aware of when you register the debug update with a signal i.e. if it is registered first then it will get the current state _before_ any mutation has occurred from another update function, if it is registered last then you’ll get the state after an update mutation has occurred.
Debug accepts a single argument when instantiating the update function and this is a string that will be prepended to the event type.
js`Adding debug twice to the top and bottom of your registered updates can give you the previous and next states but be aware that any updates that are registered later in your program will appear _after_ the final debug, which is often less than ideal.
js`Debug is either on or off and it is up to the consumer to remove it from production builds if required, if your build process does dead-code removal then something like the following could be used:
js`Or you may wish to implement a more complicated method that checks for the existence of a variable in local storage (for example) and choose whether to register the debug update or not. You could even take this one step further and make it dynamic, something like the following:
jssignal.register(checkDebug(debug('::')))
`
$3
=> > => >Squash adds several update functions to the same event and runs them sequentially meaning that order can be important.
jsconst add = (state, payload) => {
const log = state => {
signal.register(squash('ADD', [
signal.emit({
`
$3
>) => >Flow is a utility function that creates an update function ready to register with a signal by composing together all functions passed to it as arguments. Updates are invoked serially.
It combines well with compress to attach several functions to the same event, although squash can achieve the same functionality.
jsconst add = (state, event) => {
const restrict = mod => (state, event) => {
signal.register(flow(
`> It is conceptually identical to lodash/fp/compose (or compose from any FP library) but returns a function ready to be used as an updater and expects to be supplied with update functions. For general case use of composing functions together, use the implementation provided by your favourite FP library.
$3
) => >Hooks can be used to add update functions to a range of events using a predicate supplied in the
parameter. The predicate for whether a hook should invoke or not can be supplied as a string, regex or function.
`jsconst ACTIONS = {
const add = (state, event) => {
signal.register(hook(add, {
// or
// or
// All 3 predicates would fire for the following event
`> This is a terse example to highlight how to use
, no-one ever needs multiple actions that do the _exact_ same thing, always aim to restrict to the minimal.
$3
>> => >Match provides a form of pattern matching for events by allowing consumers to supply a predicate function to do the matching and an arm function that returns a new representation of the state to pass back to the signal. This is tied to how the match library implements pattern matching.
Match automatically adds a default case on to the pattern matching so consumers should not supply one.
Predicate functions match only on the event. If you need to also match on the current state then consider wrapping in scope with a state predicate function.
Arm functions are expected to be regular update functions with a signature of
.
`jssignal.register(match([
`
$3
=> >Patch allows an update function to have a view on to a specific root-level state key by specifying that key by a string.
jsconst counter = (count, event) =>({
signal.register(patch('count', counter))
// or
signal.emit({type: 'XXX'})
`In this example
will remain unchanged, patch has ensured that the update function only knows about its own key, in this case count.
$3
=> >Safe just wraps an update function to ensure state is always spat out of it. It will default to using the output of an update function, throwing out the state in the event undefined is returned.
js`
$3
=> >Scope provides a short-circuit so that the update function only executes when a certain condition is met, that condition can be specified as a string or regex that will match against the event type (or just the event if it is a string) or as a function which will accept both state and event as parameters so that the scoping can be defined by either current application state, event parameters or a combination of both.
Scoped updates have two primary use-cases:
* Remove application logic from components and move it into update functions.
jsconst update = (state, event) => ({
signal.register(scope(predicate, update))
`Scope can also be called with just the predicate function, allowing an update to be attached later.
jsconst update = (state, event) => ({
signal.register(isMain(update))
`> Using scope to match against certain actions is fine, but consider if compress would be a better solution.
$3
) => > => >Lock provides a mechanism whereby only one function registered through the lock will be active at any one time on a signal, i.e. it locks the signal for the last function supplied through the lock register function. Lock returns a function which can be used to register updates to a signal, this registration function will return a dispose function for each update to remove them from the signal.
jsconst dispose1 = register(safe(() => {
// ...later
// ...later
`Note that signal emissions are delayed a tick to be consistent so asynchronicity is something that needs to be considered i.e. the above example, run as written, will not work as you expect as the 2nd update function will be registered and disposed (whereby registering the 1st one again) synchronously whilst the emission will be on the next tick, leading to only 'one' being logged to the console.
$3 Arcs can be used to create functions which can handle side effects away from regular update functions by ensuring that async-await can be handled correctly.
Arcs are connected to the signal state and can request copies of it meaning that state inside an arc effectively becomes detached _but_ representative of the system state so it can be inspected but not directly manipulated from within an arc, instead, arcs should fire dispatches to infer state changes.
Once an arc is created by attaching it to a signal the actual function works great combined with something like compress to attach it to a specific event.
jsconst signalArc = arc(signal)
const add = compress({
const delay = ms => ({
const wait = compress({
signal.register(add)
signal.emit({type: 'WAIT'})
`
Running tests
sh`
Contributing Pull requests are always welcome, the project uses the standard code style. Please run
For bugs and feature requests, please create an issue .
See the root readme for more information about how the repository is structured.
License MIT