Store · pyoltra

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

Constructor

Name	Type	Description
`name`?	`str`

Name	Type	Description
`effects_mode`?	`"auto" \| "inline" \| "asyncio"`

Name	Type	Description
`on_effect_error`?	`any`

Name	Type	Description
`allow_replay`?	`bool`

Name	Type	Description
`dedup_window_ms`?	`float`

Properties

Name	Type	Description
`queue_depth`	`int`	Number of events whose effects are currently in flight.

Methods

Name	Type	Description
`payload`	`any`

Name	Type	Description
`dedup_key`?	`str \| None`

Name	Type	Description
`reducer`	`str`	The slice name to observe.

Name	Type	Description
`property`	`str`	A dotted path (`"items.0.title"`) or glob (`"items..title"`, `"items.*"`) relative to the slice.

Name	Type	Description
`handler`	`any`	Called with a `Change` when the path changes.

`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

Name	Type	Description
`when`?	`When \| None`	Optional 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

Name	Type	Description
`channel`	`str`	Event channel.

Name	Type	Description
`type`	`str`	Event type.

Name	Type	Description
`payload`	`any`	Event payload.

Name	Type	Description
`dedup_key`?	`str \| None`	Optional 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

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

Parameters

Name	Type	Description
`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`

signature

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

Parameters

Name	Type	Description
`channel`	`str`

Name	Type	Description
`type`	`str`

Name	Type	Description
`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

Name	Type	Description
`channel`	`str`	Channel to observe.

Name	Type	Description
`type`	`str`	Event type to observe.

Name	Type	Description
`handler`	`any`	`(event, get_state, emit, phase) -> None` (sync; a returned coroutine is fired-and-forgotten on a running loop).

Name	Type	Description
`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

Name	Type	Description
`name`	`str`	The slice name this reducer owns.

Name	Type	Description
`state`	`any`	The slice's initial value.

Name	Type	Description
`when`?	`When \| None`	Optional targeting matcher; untargeted means "all events".

Name	Type	Description
`coarse_only`?	`bool`	Skip 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`

signature

register_effect(spec): () => None

Parameters

Name	Type	Description
`spec`	`EffectSpec`

Returns

() => None

`register_middleware`

signature

register_middleware(mw): () => None

Parameters

Name	Type	Description
`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

Name	Type	Description
`spec`	`ReducerSpec`

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

Name	Type	Description
`fn`	`any`

Returns

() => None