YoltraYoltra
TSPy
La referencia de la API está disponible solo en inglés por ahora.

Store

class
yoltra/store.py:83

A reactive, event-sourced state container. Prefer `create_store` to construct one. Reducers, middleware, and effects may also be registered at runtime.

Constructor

constructor

Initialize self. See help(type(self)) for accurate signature.

signature
new(name?, effects_mode?, on_effect_error?, allow_replay?, dedup_window_ms?): None

Initialize self. See help(type(self)) for accurate signature.

Parameters

NameTypeDescription
name?str
NameTypeDescription
effects_mode?"auto" | "inline" | "asyncio"
NameTypeDescription
on_effect_error?any
NameTypeDescription
allow_replay?bool
NameTypeDescription
dedup_window_ms?float

Returns

None

Properties

NameTypeDescription
queue_depthintNumber of events whose effects are currently in flight.

Methods

aemit

`emit` then await the event's effects. See `emit`.

signature
aemit(channel, type, payload, dedup_key?): None

`emit` then await the event's effects. See `emit`.

Parameters

NameTypeDescription
channelstr
NameTypeDescription
typestr
NameTypeDescription
payloadany
NameTypeDescription
dedup_key?str | None

Returns

None

connect

Subscribe to fine-grained changes at a slice path (or glob).

signature
connect(reducer, property, handler): () => None

Subscribe to fine-grained changes at a slice path (or glob).

Parameters

NameTypeDescription
reducerstrThe slice name to observe.
NameTypeDescription
propertystrA dotted path (`"items.0.title"`) or glob (`"items.*.title"`, `"items.**"`) relative to the slice.
NameTypeDescription
handleranyCalled with a `Change` when the path changes.

Returns

() => None — An unsubscribe function.

dispose

Release subscriptions and tear down the effect worker.

signature
dispose(): None

Release subscriptions and tear down the effect worker.

Returns

None

effect

Decorator that registers the wrapped function as an effect.

signature
effect(when?): any

Decorator that registers the wrapped function as an effect.

Parameters

NameTypeDescription
when?When | NoneOptional targeting matcher; untargeted means "all events".

Returns

any — A decorator that registers the effect and returns it unchanged.

emit

Emit an event. State is committed by the time this returns.

signature
emit(channel, type, payload, dedup_key?): EmitHandle

Emit an event. State is committed by the time this returns.

Parameters

NameTypeDescription
channelstrEvent channel.
NameTypeDescription
typestrEvent type.
NameTypeDescription
payloadanyEvent payload.
NameTypeDescription
dedup_key?str | NoneOptional identity dedup key (see `yoltra.dedup`).

Returns

EmitHandle — An `EmitHandle` that settles when this event's effects finish. A deduplicated emit returns an already-settled, uncommitted handle.

get_state

Return the current immutable state snapshot. The reference may change on the next commit; read once and reuse within a computation. In development the result is a read-only proxy.

signature
get_state(): any

Return the current immutable state snapshot. The reference may change on the next commit; read once and reuse within a computation. In development the result is a read-only proxy.

Returns

any

instrument

Register a devtools/metrics observer, called once per committed event. The observer receives an `InstrumentedEvent` synchronously after each event's reduce phase. Observers are exception-isolated. Registering none keeps the instrumentation path entirely off the hot path.

signature
instrument(observer): () => None

Register a devtools/metrics observer, called once per committed event. The observer receives an `InstrumentedEvent` synchronously after each event's reduce phase. Observers are exception-isolated. Registering none keeps the instrumentation path entirely off the hot path.

Parameters

NameTypeDescription
observer(a0: InstrumentedEvent) => None

Returns

() => None

middleware

Decorator that registers the wrapped function as middleware.

signature
middleware(): any

Decorator that registers the wrapped function as middleware.

Returns

any — A decorator that registers the middleware and returns it unchanged.

on_effect

Register an effect for a single `(channel, type)`.

signature
on_effect(channel, type, handler): () => None

Register an effect for a single `(channel, type)`.

Parameters

NameTypeDescription
channelstr
NameTypeDescription
typestr
NameTypeDescription
handler(a0: Event, a1: () => any, a2: (args: any) => any) => Awaitable<None> | None

Returns

() => None

on_event

Subscribe to events by `(channel, type)` and phase (fire-and-forget).

signature
on_event(channel, type, handler, phase?): () => None

Subscribe to events by `(channel, type)` and phase (fire-and-forget).

Parameters

NameTypeDescription
channelstrChannel to observe.
NameTypeDescription
typestrEvent type to observe.
NameTypeDescription
handlerany`(event, get_state, emit, phase) -> None` (sync; a returned coroutine is fired-and-forgotten on a running loop).
NameTypeDescription
phase?"committed" | "uncommitted" | "all"`"committed"` (default), `"uncommitted"`, or `"all"`.

Returns

() => None — An unsubscribe function.

reducer

Decorator that mounts the wrapped function as a slice reducer.

signature
reducer(name, state, when?, coarse_only?): any

Decorator that mounts the wrapped function as a slice reducer.

Parameters

NameTypeDescription
namestrThe slice name this reducer owns.
NameTypeDescription
stateanyThe slice's initial value.
NameTypeDescription
when?When | NoneOptional targeting matcher; untargeted means "all events".
NameTypeDescription
coarse_only?boolSkip the per-slice diff (performance opt-out, §9).

Returns

any — A decorator that registers the reducer and returns it unchanged.

Example

example
>>> store = create_store("Todos")
>>> @store.reducer(name="todos", state={"items": []},
...                 when={"keys": [("ui", "add")]})
... def todos(s, evt):
...     return {"items": [*s["items"], evt.payload]}

register_effect

Register an effect for the events its `when` matches.

signature
register_effect(spec): () => None

Register an effect for the events its `when` matches.

Parameters

NameTypeDescription
specEffectSpec

Returns

() => None

register_middleware

Register a middleware (runs before reducers; return `False` to veto).

signature
register_middleware(mw): () => None

Register a middleware (runs before reducers; return `False` to veto).

Parameters

NameTypeDescription
mw(a0: any, a1: Event, a2: (args: any) => any) => bool | None

Returns

() => None

register_reducer

Mount a slice reducer and return an unmount function.

signature
register_reducer(spec): () => None

Mount a slice reducer and return an unmount function.

Parameters

NameTypeDescription
specReducerSpec

Returns

() => None

subscribe

Subscribe a coarse listener, fired once per commit that changed state.

signature
subscribe(fn): () => None

Subscribe a coarse listener, fired once per commit that changed state.

Parameters

NameTypeDescription
fnany

Returns

() => None