yandex/city-services-pub/yx-state-fundamentals

yx_state: one state object behind an operation queue

A StateManager owns one state object, and every write to it goes through handle. The strategy you pick decides what happens when a second call arrives while the first is still running: queue it, drop it, cancel the previous one, or run both. Only the default, sequential, guarantees order.

Principles (cheat sheet)

Details are in the references below; read the one that matches the question, not all of them.

1. All logic lives inside `handle((emit) async {...})`. That is what the operation queue governs.
2. `emit` is only valid inside its own handler. A call that escapes it is a race that debug

catches and release does not - see references/handle.md for what exactly happens and why.

1. Pick the strategy deliberately. Sequential queues the work, restartable cancels the previous

run, droppable ignores the new call while one is running, concurrent runs everything at once.

1. Cancellation is cooperative. A cancelled handler keeps running until it checks emit.isDone,

so long operations have to check it.

1. `close()` is mandatory, and it belongs to whoever owns the manager.
2. What goes outward is `StateReadable<T>`, the read-only interface.

References index - topic to file

Beyond this skill

This skill covers the package itself. Which state belongs in a manager at all, how managers are coordinated when a feature needs several of them, and where a ViewModel fits are questions about the architecture around the package - they are answered by the yx-architecture skill at https://github.com/yandex/city-services-pub/tree/main/yx_architecture.

The DI and navigation packages of the same stack ship their own skills, yx-scope-fundamentals and yx-navigation-fundamentals. Install them with fvm dart run skills@ get --agent <your agent> when the project depends on those packages.