sample API

import { sample } from "effector";

The sample method is used to connect units. Its main purpose is to take data from one place source and send it to another target when a certain trigger clock occurs.

A common use case is when you need to process an event using data from a store. Instead of using store.getState(), which can lead to inconsistent state, it’s better to use sample.

How it works

• When clock triggers, the value from source is read.
• If a filter is specified and returns true, or if it’s a store with true value, processing continues.
• If a fn is provided, data is transformed.
• Data is then passed to the target.

Special behavior of sample

• If clock is not provided, sample will trigger on every update of source.
• If target is not provided, sample will create and return a new derived unit.

Returned unit and value

If target is not provided, it will be created at runtime. The type of unit returned depends on this table:

How to use this table:

1. Pick the type of clock (column).
2. Pick the type of source (row).
3. The intersecting cell shows the return type.

If target is explicitly provided, then that target is returned.

Example:

const event = createEvent();
const $store = createStore();
const $secondStore = createStore();

const $derivedStore = sample({
  clock: $store,
  source: $secondStore,
});
// Returns a derived store because both clock and source are stores

const derivedEvent = sample({
  clock: event,
  source: $store,
});
// Returns a derived event because the clock is an event

Full form

• Formula

sample({
  clock?, // trigger
  source?, // data source
  filter?, // filter predicate
  fn?, // transformation function
  target?, // target unit
  batch?, // batching flag
  name? // unit name
})

clock

A trigger unit that determines when to sample the source.
Optional.

• Type

sample({
  clock?: Unit<T> | Unit<T>[],
})

Can be:

• Event<T> — triggers on event call
• Store<T> — triggers on store update
• Effect<T, Done, Fail> — triggers on effect execution
• Unit<T>[] — triggers when any unit in the array is triggered

const clicked = createEvent();
const $store = createStore(0);
const fetchFx = createEffect();

sample({
  source: $data,
  clock: clicked,
});

sample({
  source: $data,
  clock: $store,
});

sample({
  source: $data,
  clock: [clicked, fetchFx.done],
});

source

The data source to be read when the clock unit triggers. If clock is not provided, then source is used as the clock. Optional.

• Type

sample({
  source?: Unit<T> | Unit<T>[] | { [key: string]: Unit<T> },
})

Can be:

• Store<T> — reads the current value of the store
• Event<T> — takes the most recent payload from the event
• Effect<T, Done, Fail> — takes the most recent payload from the effect call
• Object of units — for combining multiple sources
• Array of units — for combining multiple sources

filter

A predicate function or store used to filter the data. If it returns false (or is a store that holds false), the data will not be passed to target. Optional.

• Type

sample({
  filter?: Store<boolean> | (source: Source, clock: Clock) => (boolean | Store<boolean>),
})

Can be:

• Store<boolean> — a boolean store (either base or derived)
• Predicate function — returns a boolean value

const $isUserActive = createStore(false);

sample({
  clock: checkScore,
  source: $score,
  filter: (score) => score > 100,
  target: showWinnerFx,
});

sample({
  clock: action,
  source: $user,
  filter: $isUserActive,
  target: adminActionFx,
});

fn

A function used to transform the data before passing it to the target. The function must be pure. Optional.

• Type

sample({
  fn?: (source: Source, clock: Clock) => Target
})

const $user = createStore<User>({});
const saveUserFx = createEffect((user: User) => {
  // ...
});

sample({
  clock: updateProfile,
  source: $user,
  fn: (user, updates) => ({ ...user, ...updates }),
  target: saveUserFx,
});

sample({
  clock: submit,
  source: $form,
  fn: (form) => form.email,
  target: sendEmailFx,
});

target

The destination unit that will receive the data and be triggered. Optional.

• Type

sample({
  target?: Unit<T> | Unit<T>[],
})

Can be:

• EventCallable<T> — a regular event (not derived) that will be called
• Effect<T, Done, Fail> — an effect that will be triggered
• StoreWritable<T> — a writable store that will be updated
• Unit<T>[] — all units in the array will be called

const targetEvent = createEvent<string>();
const targetFx = createEffect<string, void>();
const $targetStore = createStore("");

// Event as target
sample({
  source: $store,
  clock: trigger,
  target: targetEvent,
});

// Effect as target
sample({
  source: $store,
  clock: trigger,
  target: targetFx,
});

// Store as target
sample({
  source: $store,
  clock: trigger,
  target: $targetStore,
});

greedy

batch

Enables batching of updates for better performance. Default is true. Optional.

• Type

sample({
  batch?: boolean // Default: true
})

name

The name field allows you to assign a debug-friendly name to the created unit. Optional.

• Type

sample({
  name?: string
})

Short Form

• Formula

sample(source, clock, fn?): Unit

This is a shorthand version of the sample method, which always implicitly returns a target.

It supports multiple patterns:

1. All arguments: sample(source, clock, fn) — with a transformation function
2. Just source and clock: sample(source, clock) — no transformation function
3. source and fn: sample(source, fn) — no clock, so source acts as the trigger
4. One argument: sample(source) — only source, which acts as the trigger and the source

• Return value

The return type depends on the combination of units used and the return type of fn, if present. Otherwise, it falls back to the source.

source

Acts as the data source when the clock triggers. If no clock is provided, source is used as the trigger.

• Type

sample(source?: Unit<T> | Unit<T>[])

Can be:

• Store<T> — current value of the store
• Event<T> — last triggered payload
• Effect<T, Done, Fail> — last payload sent to the effect
• Unit<T>[] — array of units that triggers when any unit is activated

clock

The unit that acts as the trigger to read from source. Optional.

• Type

sample(clock?: Unit<T> | Unit<T>[])

Can be:

• Event<T> — triggered on event call
• Store<T> — triggered on store update
• Effect<T, Done, Fail> — triggered on effect execution
• Unit<T>[] — triggers on any unit in the array

const clicked = createEvent();
const $store = createStore(0);
const fetchFx = createEffect();

sample($data, clicked);

sample($data, $store);

fn

A transformation function to be applied before sending the result to the implicit target. The function must be pure. Optional.

• Type

sample(fn: (source: Source, clock: Clock) => result)

• Example

const $userName = createStore("john");

const submitForm = createEvent();

const sampleUnit = sample(
  $userName /* 2 */,
  submitForm /* 1 */,
  (name, password) => ({ name, password }) /* 3 */,
);

submitForm(12345678);

// 1. submitForm is triggered with 12345678
// 2. $userName value is read ("john")
// 3. The values are transformed and passed to sampleUnit

Related APIs and Articles

• API

  • merge — Combines updates from an array of units
  • Store — Store description with methods and properties
  • Event — Event description with methods and properties
  • Effect — Effect description with methods and properties

• Articles

  • Typing units and methods
  • Unit composition and working with sample