GitHub

hydration

API reference for hydration.

Save and restore serializable atom state (Effect's effect/reactivity/Hydration).

dehydrate(registry) encodes the values of the atoms marked with atom.serializable (those that cannot be encoded are left out); hydrate(registry, state) preloads them into another registry before the atoms are read. An Initial result is left out, encoded as it is (encode_initial_as="value-only"), or also given a Deferred that settles with the encoded value once the atom leaves Initial ("deferred"); hydrating such an entry updates the target registry when the deferred settles.

DehydratedAtom.to_json() / from_json(...) write an entry as Effect writes it, to send it to another process.

Types

TypeDefinitionDescription
EncodeInitialAstype EncodeInitialAs = Literal['ignore', 'deferred', 'value-only']

Classes

Functions

dehydrate

dehydrate(registry, *, encode_initial_as='ignore') -> list[DehydratedAtom]

The encoded values of the serializable atoms registry holds. Atoms whose value the schema cannot encode are left out.

ParameterTypeDescription
registryAtomRegistryService
encode_initial_asEncodeInitialAs = 'ignore'

Returns list[DehydratedAtom]

def dehydrate(
    registry: AtomRegistryService, *, encode_initial_as: EncodeInitialAs = "ignore"
) -> list[DehydratedAtom]:
    """The encoded values of the serializable atoms ``registry`` holds.
    Atoms whose value the schema cannot encode are left out."""
    entries: list[DehydratedAtom] = []
    now = now_millis()
    nodes = registry.get_nodes()
    # Effect's Map.forEach: a node made meanwhile is visited too.
    for key in live_keys(nodes):
        node = nodes[key]
        info = node.atom.serializable_info
        if info is None:
            continue
        value = node.value()
        is_initial = isinstance(value, Initial)
        if encode_initial_as == "ignore" and is_initial:
            continue
        encoded = _encode(info, value)
        if not isinstance(encoded, Success):
            continue
        deferred = None
        if encode_initial_as == "deferred" and is_initial:
            deferred = _settle_when_not_initial(registry, node.atom, info)
        entries.append(DehydratedAtom(str(key), encoded.value, now, deferred))
    return entries

to_values

to_values(state) -> list[DehydratedAtom]

The entries of a dehydrated state, as a list (Effect's toValues).

ParameterTypeDescription
stateIterable[DehydratedAtom]

Returns list[DehydratedAtom]

def to_values(state: Iterable[DehydratedAtom]) -> list[DehydratedAtom]:
    """The entries of a dehydrated state, as a list (Effect's
    ``toValues``)."""
    return list(state)

hydrate

hydrate(registry, state) -> None

Preload state's values into registry by serialization key. An atom the registry already holds takes its value now (if it is not older than the one it has); an entry with a deferred updates the atom (or preloads the value) when the deferred settles.

ParameterTypeDescription
registryAtomRegistryService
stateIterable[DehydratedAtom]
def hydrate(registry: AtomRegistryService, state: Iterable[DehydratedAtom]) -> None:
    """Preload ``state``'s values into ``registry`` by serialization key.
    An atom the registry already holds takes its value now (if it is not
    older than the one it has); an entry with a deferred updates the atom
    (or preloads the value) when the deferred settles."""
    for entry in state:
        registry.set_serializable(entry.key, entry.value)
        # Apply the value now to an atom already in use.
        existing = registry.get_nodes().get(entry.key)
        if existing is not None:
            registry.ensure_node(existing.atom)
        if entry.result_deferred is not None:
            _hydrate_later(registry, entry.key, entry.result_deferred)