guard

note

since effector 20.4.0

Method for conditional event routing. It provides a way to control one dataflow with the help of another: when the condition and the data are in different places, we can use guard with stores as filters to trigger events when condition state is true, thereby modulate signals without mixing them.

Formulae

guard({ clock?, source, filter, target? }): target

When clock is triggered, check filter for truthy and call target with data from source if true.

• If the clock is not passed, guard will be trigged on every source update
• If target is not passed, create Event with type of source and return it from guard()
• If filter is Store, check it value for truthy
• If filter is Function, call it with data from source and check result for truthy

since

clock in guard is available since effector 21.8.0

guard({source, filter, target?})

Arguments

1. params (Object): Configuration object

Returns

Event, which fires upon clock trigger

Example

import {createStore, createEffect, createEvent, guard} from 'effector'

const clickRequest = createEvent()

const fetchRequest = createEffect(

n => new Promise(rs => setTimeout(rs, 2500, n)),

)

const clicks = createStore(0).on(clickRequest, x => x + 1)

const requests = createStore(0).on(fetchRequest, x => x + 1)

const isIdle = fetchRequest.pending.map(pending => !pending)

/*

1. on clickRequest

2. if isIdle is true

3. take current clicks value

4. and call fetchRequest with it

*/

guard({

clock: clickRequest, /* 1 */

filter: isIdle, /* 2 */

source: clicks, /* 3 */

target: fetchRequest, /* 4 */

})

See ui visualization

Also, guard accepts a common function predicate as filter, to drop events before forwarding them to target

Example 2

import {createEffect, createEvent, guard} from 'effector'

const searchUser = createEffect()

const submitForm = createEvent()

guard({

source: submitForm,

filter: user => user.length > 0,

target: searchUser,

})

submitForm('') // nothing happens

submitForm('alice') // ~> searchUser('alice')

Try it

guard(source, {filter: booleanStore})

Arguments

1. source (Store/Event/Effect): Source unit. Will trigger given guard on updates
2. filter (Store): Filter store

Example

import {createEvent, createStore, createApi, guard} from 'effector'

const trigger = createEvent()

const $unlocked = createStore(true)

const {lock, unlock} = createApi($unlocked, {

lock: () => false,

unlock: () => true,

})

const target = guard(trigger, {

filter: $unlocked,

})

target.watch(console.log)

trigger('A')

lock()

trigger('B') // nothing happens

unlock()

trigger('C')

Try it

guard(source, {filter: predicate})

Arguments

1. source (Store/Event/Effect): Source unit. Will trigger given guard on updates
2. filter ((payload) => Boolean): Predicate function, should be pure

Example 2

import {createEvent, guard} from 'effector'

const source = createEvent()

const target = guard(source, {

filter: x => x > 0,

})

target.watch(() => {

console.log('target called')

})

source(0)

// nothing happens

source(1)

// target called

Try it