Tarjima qoshish uchun havola boyicha o'tib Pull Request oching (havolaga o'tish).
Standart til uchun tarkibni ko'rsatadi.
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
.
Learn how to compose units and use the sample
method
How it works
- When
clock
triggers, the value fromsource
is read. - If a
filter
is specified and returnstrue
, or if itβs a store withtrue
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 ofsource
. - 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:
clock \ source | Store | Event | Effect |
---|---|---|---|
Store | Store | Event | Event |
Event | Event | Event | Event |
Effect | Event | Event | Event |
How to use this table:
- Pick the type of
clock
(column). - Pick the type of
source
(row). - 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 callStore<T>
β triggers on store updateEffect<T, Done, Fail>
β triggers on effect executionUnit<T>[]
β triggers when any unit in the array is triggered
Although the clock
argument is optional, when using the sample
method you must provide either clock
or source
.
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 storeEvent<T>
β takes the most recent payload from the eventEffect<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
Although the source
argument is optional, when using the sample
method you must provide either source
or clock
.
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})
The type of data returned must match the type of data in 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 calledEffect<T, Done, Fail>
β an effect that will be triggeredStoreWritable<T>
β a writable store that will be updatedUnit<T>[]
β all units in the array will be called
If target
is not specified, sample
returns a new derived unit.
const targetEvent = createEvent<string>();const targetFx = createEffect<string, void>();const $targetStore = createStore("");
// Event as targetsample({ source: $store, clock: trigger, target: targetEvent,});
// Effect as targetsample({ source: $store, clock: trigger, target: targetFx,});
// Store as targetsample({ source: $store, clock: trigger, target: $targetStore,});
greedy
As of effector 23.0.0, the greedy
property is deprecated.
Use batch
instead of 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:
- All arguments:
sample(source, clock, fn)
β with a transformation function - Just
source
andclock
:sample(source, clock)
β no transformation function source
andfn
:sample(source, fn)
β noclock
, sosource
acts as the trigger- One argument:
sample(source)
β onlysource
, 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 storeEvent<T>
β last triggered payloadEffect<T, Done, Fail>
β last payload sent to the effectUnit<T>[]
β array of units that triggers when any unit is activated
If clock
is not specified, then source
behaves as clock
- that is, it acts as the trigger.
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 callStore<T>
β triggered on store updateEffect<T, Done, Fail>
β triggered on effect executionUnit<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
-
Articles
Ingliz tilidagi hujjatlar eng dolzarb hisoblanadi, chunki u effector guruhi tomonidan yozilgan va yangilanadi. Hujjatlarni boshqa tillarga tarjima qilish jamiyat tomonidan kuch va istaklar mavjud bo'lganda amalga oshiriladi.
Esda tutingki, tarjima qilingan maqolalar yangilanmasligi mumkin, shuning uchun eng aniq va dolzarb ma'lumot uchun hujjatlarning asl inglizcha versiyasidan foydalanishni tavsiya etamiz.