sample

This method can be used for linking two nodes, resulting the third one, which will fire only upon clock node trigger.

Quite a common case, when you need to handle some event with some store's state. Instead of using store.getState(), which may cause race conditions and inconsistency of state, it is more suitable to use sample method.

Formulae

sample({ source?, clock?, fn?, target?}): target

When clock is triggered, read the value from source and trigger target with it.

• If the clock is not passed, sample will be trigged on every source update.
• If the fn is passed, pass value from source through before passing to target
• If the target is not passed, create it and return from sample()

Schema

Type of the created target

If target is not passed to sample() call, it will be created internally. The type of the unit is described in the table below:

clock\source	Store	Event	Effect
Store	Store	Event	Event
Event	Event	Event	Event
Effect	Event	Event	Event

How to read it:

1. You need to know type of the source, it is a column
2. Type of the clock in the rows
3. Match the column and the row

For example:

const $store = sample({clock: $store, source: $store})

// Result will be store, because source and clock are stores.

const event = sample({clock: event, source: $store})

// Because not all arguments are stores.

sample({clock?, source, fn?, target?, greedy?})

Arguments

params (Object): Configuration object

• clock?: Unit or array of units
  • If event or effect: trigger target upon event or effect is called
  • If store: trigger target upon store is updated
  • If array of units: trigger target upon any given unit is called or updated. Shorthand for inline merge call
  • If not passed: source is used as clock
• source?: Unit or object/array with stores
  • If event or effect: take last invocation argument value. That event or effect must be invoked at least once
  • If store: take current state of given store
  • If array or object with stores: take values from given stores combined to object or array. Shorthand for inline combine call
  • If not passed: clock is used as source
• target?: Unit or array of units
  • If event or effect: call given event or effect upon clock is triggered
  • If store: update given store upon clock is triggered
  • If array of units: trigger every given unit upon clock is triggered
  • If not passed: new unit will be created under the hood and will be returned as result of the sample() call. Type of created target is described in table beyond
• fn? ((sourceData, clockData) => result): Combinator function, which will transform data from source and clock before passing it to target, should be pure. If not passed, data from source will be passed to target as it is
• greedy? (boolean) Modifier defines whether sampler will wait for resolving calculation result, and will batch all updates, resulting only one trigger, or will be triggered upon every linked node invocation, e.g. if greedy is true, sampler will fire on trigger of every node, linked to clock, whereas non-greedy sampler(greedy: false) will fire only upon the last linked node trigger

note

Array of units in target are supported since effector 21.8.0

Returns

(Event | Store) - Unit, which fires/updates upon clock is trigged, if source is not passed. The type of returned unit depends on the types of clock and source..

Example

const $userName = createStore('john')

const signIn = createEffect(params => {

console.log(params)

})

const submitForm = createEvent()

sample({

clock: submitForm /* 1 */,

source: $userName /* 2 */,

fn: (name, password) => ({name, password}) /* 3 */,

target: signIn /* 4 */,

})

submitForm(12345678)

// 1. when submitForm is called with params (12345678)

// 2. take $userName store`s state ('john')

// 3. transform payload from event (1) and current store`s state (2)

// 4. trigger effect signIn with params received at the step (3)

Try it

sample(sourceUnit, clockUnit, fn?)

It is just another form of the sample invocation, with the same sense.

Arguments

• sourceUnit: Source unit
  • If event or effect. Take last invocation argument value. That event or effect must be invoked at least once
  • If store. Take current store`s state
• clockUnit: Clock unit. If not passed, source is used as clock
  • If event or effect. Trigger sampled unit, upon event or effect is called
  • If store. Trigger sampled unit, upon store is updated
• fn? ((sourceData, clockData) => result): Optional combinator function, should be pure. Since, this handler is supposed to organize data flow, you should avoid declaring side-effects here. It's more appropriate to place it in watch method for sampled node.

Returns

(Event | Store) - Unit, which fires/updates upon clock is trigged, if source is not passed. The type of returned unit depends on the types of clock and source..

Example

const $userName = createStore('john')

const signIn = createEffect(params => {

console.log(params)

})

const submitForm = createEvent()

const sampleUnit = sample(

$userName /* 2 */,

submitForm /* 1 */,

(name, password) => ({name, password}) /* 3 */,

)

/* 5 */

forward({

from: sampleUnit,

to: signIn,

})

submitForm(12345678)

// 1. when submitForm is called with params (12345678)

// 2. take $userName store`s state ('john')

// 3. transform payload from event (1) and current store`s state (2)

// 4. when sampleUnit (event in this case) is triggered,

// send it payload to effect signIn with params received at the step (3)

Try it

sample({name?})

since

effector 20.4.0

Every unit in effector may have a name.
You now can name sampled entities in the same manner as basic ones.

import {createStore, sample} from 'effector'

const foo = createStore(null)

const sampled = sample({

source: foo,

name: 'sampled foo',

})

console.log(sampled.shortName) // 'sampled foo'

Objects and arrays of Store in sample({ source })

Object of stores

since

effector 20.8.0

sample can be called with object of Store as source:

import {createStore, createEvent, sample} from 'effector'

const trigger = createEvent()

const a = createStore('A')

const b = createStore(1)

// Target has type `Event<{ a: string, b: number }>`

const target = sample({

clock: trigger,

source: {a, b},

})

target.watch(obj => {

console.log('sampled object', obj)

})

trigger()

// => sampled object {a: 'A', b: 1}

Try it

Array of stores

since

effector 20.8.0

sample can be called with array of Store as source:

import {createStore, createEvent, sample} from 'effector'

const trigger = createEvent()

const a = createStore('A')

const b = createStore(1)

// Target has type `Event<[string, number]>`

const target = sample({

clock: trigger,

source: [a, b],

})

target.watch(obj => {

console.log('sampled array', obj)

})

// You can easily destructure arguments to set explicit names

target.watch(([a, b]) => {

console.log('explicit names', a, b)

})

trigger()

// => sampled array ["A", 1]

// => explicit names "A" 1

Try it

Support array in clock

since

effector 21.2.0

Support for sample clock field which acts like a merge call

import {createStore, createEvent, createEffect, sample, merge} from 'effector'

const showNotification = createEvent<string>()

const trigger = createEvent()

const fx = createEffect()

const store = createStore('')

// array of units in clock

sample({

clock: [trigger, fx.doneData],

source: store,

target: showNotification,

})

// merged unit in clock

sample({

clock: merge([trigger, fx.doneData]),

source: store,

target: showNotification,

})

Try it