Factories

You can call factories to create actions for you. These actions will help you change state and control the flow of execution.

Read more about factories in the the guide article.

Store factories∞ 

The methods for changing state within actions are also available as factories.

All store are imported as members of the ‘cerebral/factories’ module. For example:

import { set } from 'cerebral/factories'

concat∞ 

Concatenate a value to an array

concat(state`some.list`, ['foo', 'bar'])

increment∞ 

Increment an integer value by another integer value into an array. The default increment is 1, and a negative value effectively does a decrement.

increment(state`some.integer`)
increment(state`some.integer`, -5)
increment(state`some.integer`, state`some.otherInteger`)
increment(state`some.integer`, props`some.otherInteger`)

merge∞ 

Merge objects into existing value. If no value exists, an empty object will be created. Merge supports using operator tags on key values:

merge(state`clients.$draft`, props`newDraft`, {
  foo: 'bar',
  bar: props`baz`
})

pop∞ 

Pop a value off an array (removes last element from array).

pop(state`some.list`)

push∞ 

Push value into an array (adds the element at the end of the array).

push(state`some.list`, 'foo')

set∞ 

Set a target value in the state or props.

set(state`foo.bar`, true)
set(props`foo`, true)

Optionally transform the value before setting

set(state`some.number`, props`number`, (value) => value * 2)

shift∞ 

Shift a value off an array (removes first element in array).

shift(state`some.list`),

splice∞ 

Splice an array in place.

splice(state`some.list`, 0, 2)

toggle∞ 

Toggle a boolean value.

toggle(state`user.$toolbar`)

unset∞ 

Unset key from object.

unset(state`clients.all.${props`key`}`)

unshift∞ 

Unshift a value into an array (adds the element at the start of the array).

unshift(state`some.list`, 'foo')

Flow control factories∞ 

These factories help control the execution flow.

debounce∞ 

Hold action until the given amount of time in milliseconds has passed. If the sequence triggers again within this time frame, the previous sequence goes down the “discard” path while the new sequence holds for the given time. This is typically used for typeahead functionality. For a debounce that is shared across different signals, you can use debounce.shared() (see example below).

Please note that the discard path has to be present even if it is most often empty.

import { debounce } from 'cerebral/factories'

export default [
  debounce(200),
  {
    continue: runThisActionOrSequence,
    discard: []
  }
]

debounce.shared() is typically used with factories, for example to show notifications where a previous notification should be cancelled by a new one.

import { debounce, set, unset } from 'cerebral/factories'
import { state } from 'cerebral'

const sharedDebounce = debounce.shared()
function showNotificationFactory(message, ms) {
  return [
    set(state.notification, message),
    sharedDebounce(ms),
    {
      continue: unset(state.notification),
      discard: []
    }
  ]
}

Now when this notification factory is used in different sequence, the call to debounceShared will share the same debounce execution state:

import * as factories from './factories'

export default factories.showNotification('User logged in', 5000)

equals∞ 

This operator chooses a specific path based on the provided value.

import { equals } from 'cerebral/factories'
import { state } from 'cerebral'

export default [
  equals(state`user.role`), {
    admin: [],
    user: [],
    otherwise: [] // When no match
  }
],

wait∞ 

Wait for the given time in milliseconds and then continue chain.

import { wait } from 'cerebral/factories'

export default [
  wait(200),
  doSomethingAfterWaiting
]

If you need to wait while executing in parallel, you should use a continue path to isolate the sequence to be run:

import { wait } from 'cerebral/factories'
import { parallel } from 'cerebral'

export default
  someAction,
  parallel('my parallel with wait', [
    wait(200), {
      continue: [doSomethingAfterWaiting]
    },
    otherActionInParallel
  ])
]

when∞ 

Run signal path depending on a truth value or function evaluation.

import { when } from 'cerebral/factories'
import { state } from 'cerebral'

export default [
  when(state`foo.isAwesome`),
  {
    true: [],
    false: []
  },
  // You can also pass your own function
  when(state`foo.isAwesome`, (value) => value.length === 3),
  {
    true: [],
    false: []
  }
]

When used with a truth function, the when operator supports more then a single “value” argument. The predicate function must come last.

import { when } from 'cerebral/factories'
import { props, state } from 'cerebral'

export default [
  when(
    state`clients.$draft.key`,
    props`key`,
    (draftKey, updatedKey) => draftKey === updatedKey
  ),
  {
    true: set(state`clients.$draft`, props`value`),
    false: []
  }
]