pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_layer_core.py

@@ -0,0 +1,403 @@
+"""``Layer`` itself, the ``MemoMap`` that shares builds, and building.
+
+A layer is a build function ``(memo_map, scope) -> Effect[Context]``.
+``from_build`` gives each build a child of ``scope`` that closes if the
+build fails; ``from_build_memo`` also shares the build through the memo map.
+
+A memo map entry owns a scope of its own and counts its users: every scope
+that builds or reuses the layer holds one count, and gives it back when it
+closes. The last one to leave closes the entry, releasing the layer, and a
+later build starts afresh. A forked map reuses its parent's entries but
+keeps the layers first built through it to itself.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any, Generic, Never, Self, TypeVar, Unpack, overload
+
+from pyfect._core import Effect, _FailCause, _Locally, _Succeed, _Suspend, _WithFiber
+from pyfect._effect_args import require_effect, wrong_argument
+from pyfect.cause import Cause
+from pyfect.cause import fail as fail_cause
+from pyfect.context import Context, Tag, TagLike
+from pyfect.deferred import Deferred
+from pyfect.effect import never
+from pyfect.exit import Exit, Failure
+from pyfect.scope import CloseableScope, Scope, scoped
+
+if TYPE_CHECKING:
+    from pyfect._layer_tracing import OnEnd
+    from pyfect._stack_frame import CaptureStackTrace
+    from pyfect.tracer import AnySpan, TracedSpanOptions
+
+ROut_contra = TypeVar("ROut_contra", contravariant=True)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+RIn_co = TypeVar("RIn_co", covariant=True, default=Never)
+
+type Builder = Callable[[MemoMap, CloseableScope], Effect[Context, Any, Any]]
+
+_VOID: Effect[None] = _Succeed(None)
+
+
+_LAYER_HINT = "to build a layer lazily, pass fx.layer.suspend(f)"
+
+
+def require_layer(value: object, name: str, expected: str = "a Layer") -> None:
+    """``require_effect`` for a ``Layer`` parameter."""
+    if not isinstance(value, Layer):
+        raise TypeError(wrong_argument(value, name, expected, _LAYER_HINT))
+
+
+def require_layers(values: Iterable[object], name: str) -> None:
+    """``require_layer`` for each of a ``*args`` parameter's values."""
+    for i, value in enumerate(values):
+        require_layer(value, f"{name}[{i}]")
+
+
+class _Entry:
+    """A shared build: its result, its scope, and how many scopes use it."""
+
+    __slots__ = ("deferred", "finalizer", "observers", "scope")
+
+    def __init__(self, memo: MemoMap, layer: Layer[Any, Any, Any]) -> None:
+        self.observers = 0
+        self.deferred: Deferred[Context, Any] = Deferred()
+        self.scope = CloseableScope()
+
+        def leave(ex: Exit[Any, Any]) -> Effect[None]:
+            self.observers -= 1
+            if self.observers > 0:
+                return _VOID
+            memo._entries.pop(layer, None)
+            return self.scope.close(ex)
+
+        def finalizer(ex: Exit[Any, Any]) -> Effect[None]:
+            return _Suspend(lambda: leave(ex))
+
+        self.finalizer = finalizer
+
+    def observe(self, scope: CloseableScope) -> bool:
+        """Count ``scope`` as a user until it closes, at once, so no
+        interruption can lose the count. A closed scope can't use it."""
+        if scope._closed is not None:
+            return False
+        self.observers += 1
+        scope._add(object(), self.finalizer)
+        return True
+
+
+class MemoMap:
+    """Shares layer builds by layer identity, releasing each layer when the
+    last scope using it closes. ``fork`` gives a map that reuses this one's
+    layers and keeps its own builds to itself."""
+
+    __slots__ = ("_entries", "_parent")
+
+    def __init__(self, parent: MemoMap | None = None) -> None:
+        self._parent = parent
+        self._entries: dict[Layer[Any, Any, Any], _Entry] = {}
+
+    def fork(self) -> MemoMap:
+        return MemoMap(self)
+
+    def get[O, E, R](
+        self, layer: Layer[O, E, R], scope: CloseableScope
+    ) -> Effect[Context[O], E, R] | None:
+        """The shared build of ``layer``, if this map or a parent has one.
+        ``scope`` uses it from now on, whether or not the effect runs."""
+        require_layer(layer, "layer")
+        entry = self._entries.get(layer)
+        if entry is not None:
+            entry.observe(scope)
+            return entry.deferred.wait()
+        return self._parent.get(layer, scope) if self._parent is not None else None
+
+    def get_or_else_memoize[O, E, R](
+        self,
+        layer: Layer[O, E, R],
+        scope: CloseableScope,
+        build: Callable[[MemoMap, CloseableScope], Effect[Context[O], E, R]],
+    ) -> Effect[Context[O], E, R]:
+        """Reuse ``layer``'s shared build, or run ``build`` as it."""
+        require_layer(layer, "layer")
+
+        def run() -> Effect[Context[O], E, R]:
+            published: list[Deferred[Context, Any]] = []
+
+            def reuse_or_build() -> Effect[Context[O], E, R]:
+                existing = self.get(layer, scope)
+                if existing is not None:
+                    return existing
+                entry = _Entry(self, layer)
+                if not entry.observe(scope):
+                    return build(self, scope)
+                published.append(entry.deferred)
+                self._entries[layer] = entry
+                return build(self, entry.scope)
+
+            def settle(ex: Exit[Any, Any]) -> Effect[None]:
+                for deferred in published:
+                    deferred.done_unsafe(ex)
+                return _VOID
+
+            # ``settle`` is in place before the entry is published, so even
+            # an interrupted first requester completes it for the others.
+            return _Suspend(reuse_or_build).on_exit(settle)
+
+        return _Suspend(run)
+
+
+class CurrentMemoMap(Tag[MemoMap]):
+    """The memo map of the enclosing build. ``provide`` and ``build`` fork
+    it, so layers built further out are reused."""
+
+
+def fork_or_create(ctx: Context) -> MemoMap:
+    """A fork of ``ctx``'s memo map, or a new map if it has none."""
+    found, current = ctx.lookup(CurrentMemoMap)
+    return current.fork() if found else MemoMap()
+
+
+class Layer(Generic[ROut_contra, E_co, RIn_co]):
+    """Builds the services ``ROut``, may fail with ``E``, needs ``RIn``.
+
+    ``Layer(build)`` is Effect's ``fromBuildUnsafe``: no child scope and no
+    sharing. Use ``from_build`` / ``from_build_memo`` or the constructors in
+    ``pyfect.layer``."""
+
+    __slots__ = ("_build",)
+
+    def __init__(self, build: Builder) -> None:
+        self._build = build
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        return f(self)
+
+    # --- building ---------------------------------------------------------------
+
+    def build_with_memo_map(
+        self, memo_map: MemoMap, scope: CloseableScope
+    ) -> Effect[Context[ROut_contra], E_co, RIn_co]:
+        """Build with ``memo_map``, releasing into ``scope``. The memo map is
+        ``CurrentMemoMap`` during the build and in the built context."""
+        building: Effect[Context, Any, Any] = _Locally(
+            _Suspend(lambda: self._build(memo_map, scope)),
+            lambda ctx: ctx.add(CurrentMemoMap, memo_map),
+        )
+        return building.map(lambda built: built.add(CurrentMemoMap, memo_map))
+
+    def build_with_scope(self, scope: CloseableScope) -> Effect[Context[ROut_contra], E_co, RIn_co]:
+        """Build into ``scope``, reusing what an enclosing build built."""
+        return _WithFiber(
+            lambda fiber: self.build_with_memo_map(fork_or_create(fiber._context), scope)
+        )
+
+    def build(self) -> Effect[Context[ROut_contra], E_co, RIn_co | Scope]:
+        """Build into the current ``Scope``, reusing what an enclosing build
+        built."""
+        return _WithFiber(
+            lambda fiber: self.build_with_memo_map(
+                fork_or_create(fiber._context), fiber._context.get_unsafe(Scope)
+            )
+        )
+
+    def launch(self) -> Effect[Never, E_co, RIn_co]:
+        """Build the layer and keep it until interrupted, as for a server."""
+        return scoped(self.build().and_then(never))
+
+    # --- sequencing -------------------------------------------------------------
+
+    def flat_map[O2, E2 = Never, R2 = Never](
+        self, f: Callable[[Context[ROut_contra]], Layer[O2, E2, R2]]
+    ) -> Layer[O2, E_co | E2, RIn_co | R2]:
+        """Build the layer ``f`` makes from this one's services."""
+        return from_build(
+            lambda memo, scope: self._build(memo, scope).flat_map(
+                lambda ctx: f(ctx)._build(memo, scope)
+            )
+        )
+
+    @overload
+    def tap[E2 = Never](
+        self, f: Callable[[Context[ROut_contra]], Effect[object, E2, Scope]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co]: ...
+    @overload
+    def tap[E2 = Never, R2 = Never](
+        self, f: Callable[[Context[ROut_contra]], Effect[object, E2, Scope | R2]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co | R2]: ...
+    def tap(self, f: Callable[[Context], Effect[object, Any, Any]]) -> Layer[Any, Any, Any]:
+        """Run ``f`` on the built services, in the layer's scope."""
+        return from_build(
+            lambda memo, scope: self._build(memo, scope).flat_map(
+                lambda ctx: _in_scope(f(ctx), scope).as_(ctx)
+            )
+        )
+
+    @overload
+    def tap_error[E2 = Never](
+        self, f: Callable[[E_co], Effect[object, E2, Scope]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co]: ...
+    @overload
+    def tap_error[E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[object, E2, Scope | R2]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co | R2]: ...
+    def tap_error(self, f: Callable[[Any], Effect[object, Any, Any]]) -> Layer[Any, Any, Any]:
+        """Run ``f`` on a typed build error, in the layer's scope; the build
+        still fails with it."""
+        return from_build(
+            lambda memo, scope: self._build(memo, scope).catch_all(
+                lambda e: _in_scope(f(e), scope).and_then(_FailCause(fail_cause(e)))
+            )
+        )
+
+    @overload
+    def tap_cause[E2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[object, E2, Scope]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co]: ...
+    @overload
+    def tap_cause[E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[object, E2, Scope | R2]]
+    ) -> Layer[ROut_contra, E_co | E2, RIn_co | R2]: ...
+    def tap_cause(
+        self, f: Callable[[Cause[Any]], Effect[object, Any, Any]]
+    ) -> Layer[Any, Any, Any]:
+        """Run ``f`` on the cause of a failed build, in the layer's scope;
+        the build still fails with it."""
+        return from_build(
+            lambda memo, scope: self._build(memo, scope).catch_cause(
+                lambda c: _in_scope(f(c), scope).and_then(_FailCause(c))
+            )
+        )
+
+    # --- errors -----------------------------------------------------------------
+
+    def or_die(self) -> Layer[ROut_contra, Never, RIn_co]:
+        """Die with a typed build error instead of failing with it."""
+        return Layer(lambda memo, scope: self._build(memo, scope).or_die())
+
+    def catch_all[O, E, R, E2 = Never, R2 = Never](
+        self: Layer[O, E, R], f: Callable[[E], Layer[O, E2, R2]]
+    ) -> Layer[O, E2, R | R2]:
+        """Build ``f(error)`` instead when the build fails with a typed
+        error. The fallback must build at least what this layer builds."""
+        return Layer(
+            lambda memo, scope: self._build(memo, scope).catch_all(
+                lambda e: f(e)._build(memo, scope)
+            )
+        )
+
+    def catch_cause[O, E, R, E2 = Never, R2 = Never](
+        self: Layer[O, E, R], f: Callable[[Cause[E]], Layer[O, E2, R2]]
+    ) -> Layer[O, E2, R | R2]:
+        """Build ``f(cause)`` instead when the build fails, defects
+        included. The fallback must build at least what this layer builds."""
+        return Layer(
+            lambda memo, scope: self._build(memo, scope).catch_cause(
+                lambda c: f(c)._build(memo, scope)
+            )
+        )
+
+    # --- services ---------------------------------------------------------------
+
+    def update_service[S, T](
+        self, tag: TagLike[S, T], f: Callable[[S], S]
+    ) -> Layer[ROut_contra, E_co, RIn_co | T]:
+        """Build with ``f`` applied to the service of ``tag`` that this
+        layer needs (which it then needs from outside)."""
+        updated = effect_context(tag().map(lambda service: Context.make(tag, f(service))))
+        return feed(updated, self, keep_dep=False)
+
+    # --- tracing ----------------------------------------------------------------
+
+    def with_span(
+        self,
+        name: str,
+        *,
+        on_end: OnEnd | None = None,
+        **options: Unpack[TracedSpanOptions],
+    ) -> Layer[ROut_contra, E_co, RIn_co]:
+        """Build inside a new span, the parent of the spans made while
+        building, and inside its stack frame (this call site unless
+        ``capture_stack_trace`` says otherwise). The span ends, and
+        ``on_end`` runs, when the layer's scope closes."""
+        from pyfect._layer_tracing import with_span
+        from pyfect._stack_frame import stack_of
+
+        stack = stack_of(options.get("capture_stack_trace", True), 1)
+        return with_span(self, name, on_end, options, stack)
+
+    def with_parent_span(
+        self, span: AnySpan, *, capture_stack_trace: CaptureStackTrace = True
+    ) -> Layer[ROut_contra, E_co, RIn_co]:
+        """Build with ``span`` as the parent of the spans made while
+        building, and, unless it is external, inside its stack frame."""
+        from pyfect._layer_tracing import with_parent_span
+        from pyfect._stack_frame import stack_of
+
+        return with_parent_span(self, span, stack_of(capture_stack_trace, 1))
+
+
+def _in_scope[A, E](eff: Effect[A, E, Any], scope: CloseableScope) -> Effect[A, E, Any]:
+    return _Locally(eff, lambda ctx: ctx.add(Scope, scope))
+
+
+def from_build[O, E = Never, R = Never](
+    build: Callable[[MemoMap, CloseableScope], Effect[Context[O], E, R]],
+) -> Layer[O, E, R]:
+    """A layer from its build function. Each build gets a child of the
+    scope it is given, closed at once if the build fails."""
+
+    def child_scoped(memo: MemoMap, scope: CloseableScope) -> Effect[Context, Any, Any]:
+        def run() -> Effect[Context, Any, Any]:
+            layer_scope = scope.fork_unsafe()
+            return build(memo, layer_scope).on_exit(
+                lambda ex: layer_scope.close(ex) if isinstance(ex, Failure) else _VOID
+            )
+
+        return _Suspend(run)
+
+    return Layer(child_scoped)
+
+
+def from_build_memo[O, E = Never, R = Never](
+    build: Callable[[MemoMap, CloseableScope], Effect[Context[O], E, R]],
+) -> Layer[O, E, R]:
+    """``from_build``, shared through the memo map: within one build, and
+    across builds with the same memo map while a scope still uses it."""
+    layer: Layer[O, E, R] = from_build(
+        lambda memo, scope: memo.get_or_else_memoize(layer, scope, build)
+    )
+    return layer
+
+
+@overload
+def effect_context[A, E](eff: Effect[Context[A], E, Scope]) -> Layer[A, E]: ...
+@overload
+def effect_context[A, E = Never, R = Never](
+    eff: Effect[Context[A], E, Scope | R],
+) -> Layer[A, E, R]: ...
+def effect_context(eff: Effect[Context, Any, Any]) -> Layer[Any, Any, Any]:
+    """Build every service of the context ``eff`` makes. ``eff`` may acquire
+    resources (it runs with a ``Scope``); they are released with the layer."""
+    require_effect(eff, "eff")
+    return from_build_memo(lambda _memo, scope: _in_scope(eff, scope))
+
+
+def feed(
+    dep: Layer[Any, Any, Any], target: Layer[Any, Any, Any], *, keep_dep: bool
+) -> Layer[Any, Any, Any]:
+    """Build ``target`` with ``dep``'s services (both in one scope), giving
+    ``target``'s services, plus ``dep``'s when ``keep_dep``."""
+
+    def build(memo: MemoMap, scope: CloseableScope) -> Effect[Context, Any, Any]:
+        def with_dep(dep_ctx: Context) -> Effect[Context, Any, Any]:
+            built: Effect[Context, Any, Any] = _Locally(
+                target._build(memo, scope), lambda ctx: ctx.merge(dep_ctx)
+            )
+            return built.map(dep_ctx.merge) if keep_dep else built
+
+        return dep._build(memo, scope).flat_map(with_dep)
+
+    return from_build_memo(build)

pyfect/_layer_for_life.py

@@ -0,0 +1,33 @@
+"""``make(..., layer=...)``: a value made with a layer that lives as long as
+the value does.
+
+``made.pipe(provide(layer))`` releases the layer once ``made`` returns, so a
+client made that way outlives its protocol or handlers. ``with_layer(make,
+layer)`` builds ``layer`` into the caller's ``Scope`` instead, the scope the
+value is valid in, and is what every ``layer=`` parameter uses.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._core import Effect
+from pyfect._layer_core import Layer, require_layer
+from pyfect.effect import provide_context
+
+
+def with_layer(
+    make: Callable[[], Effect[Any, Any, Any]], layer: Layer[Any, Any, Any] | None
+) -> Effect[Any, Any, Any]:
+    """``make()``, with the services of ``layer`` built into the caller's
+    ``Scope`` (``layer`` is checked first); without ``layer``, ``make()``
+    alone."""
+    if layer is None:
+        return make()
+    require_layer(layer, "layer")
+    made = make()
+    return layer.build().flat_map(lambda built: made.pipe(provide_context(built)))
+
+
+__all__ = ["with_layer"]

pyfect/_layer_tracing.py

@@ -0,0 +1,70 @@
+"""Layers and spans: a layer providing a parent span, and spans around a
+layer's construction (Effect's ``Layer.span`` / ``parentSpan`` /
+``withSpan`` / ``withParentSpan``)."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, Unpack
+
+from pyfect._core import Effect, _Succeed
+from pyfect._layer_core import Layer, feed
+from pyfect._stack_frame import CurrentStackFrame, push
+from pyfect.context import Context
+from pyfect.exit import Exit
+from pyfect.scope import Scope, add_finalizer
+from pyfect.tracer import AnySpan, ExternalSpan, ParentSpan, Span, SpanOptions
+from pyfect.tracer._spans import span_scoped
+
+type OnEnd = Callable[[Span, Exit[Any, Any]], Effect[object]]
+"""Runs when a layer's span ends (when the layer's scope closes)."""
+
+
+def parent_span(span: AnySpan) -> Layer[ParentSpan]:
+    """Provide ``span`` as the parent of the spans made with it."""
+    built: Effect[Context] = _Succeed(Context.make(ParentSpan, span))
+    return Layer(lambda _memo, _scope: built)
+
+
+def _scoped_span(
+    name: str, on_end: OnEnd | None, options: SpanOptions
+) -> Effect[Span, Never, Scope]:
+    made = span_scoped(name, options)
+    if on_end is None:
+        return made
+    return made.tap(lambda span: add_finalizer(lambda ex: on_end(span, ex)))
+
+
+def span(
+    name: str, *, on_end: OnEnd | None = None, **options: Unpack[SpanOptions]
+) -> Layer[ParentSpan]:
+    """Provide a new span as the parent of the spans made with it. The span
+    ends, and ``on_end`` runs, when the layer's scope closes."""
+    from pyfect.layer import effect
+
+    return effect(ParentSpan, _scoped_span(name, on_end, options))
+
+
+def with_parent_span[O, E, R](
+    layer: Layer[O, E, R], span: AnySpan, stack: Callable[[], str | None]
+) -> Layer[O, E, R]:
+    """``layer`` built with ``span`` as the parent span and, unless it is
+    external, inside a stack frame named after it at ``stack``."""
+    if not isinstance(span, ExternalSpan):
+        layer = layer.update_service(CurrentStackFrame, push(span.name, stack))
+    return feed(parent_span(span), layer, keep_dep=False)
+
+
+def with_span[O, E, R](
+    layer: Layer[O, E, R],
+    name: str,
+    on_end: OnEnd | None,
+    options: SpanOptions,
+    stack: Callable[[], str | None],
+) -> Layer[O, E, R]:
+    from pyfect.layer import unwrap
+
+    return unwrap(
+        _scoped_span(name, on_end, options).map(lambda s: with_parent_span(layer, s, stack))
+    )

pyfect/_locked_ref.py

@@ -0,0 +1,147 @@
+"""``LockedRef[A]``: the operations ``SynchronizedRef`` and
+``SubscriptionRef`` share.
+
+Every update holds a one-permit semaphore, so an effectful update (the
+``*_effect`` methods) sees no other update between reading the value and
+storing its result. ``get`` takes no permit: it reads the last stored
+value. A subclass decides what storing does by overriding ``_store``.
+
+Each operation is written as a transition from the current value to a
+result and an optional new value (``None`` keeps the current one), which
+``_locked`` / ``_locked_effect`` run under the semaphore.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Never
+
+from pyfect._core import Effect, _Suspend, _Sync
+from pyfect.option import Option, Some
+from pyfect.semaphore import Semaphore
+
+type _Transition[A, B] = tuple[B, Option[A]]
+
+
+class LockedRef[A]:
+    __slots__ = ("_lock", "_value")
+
+    def __init__(self, value: A) -> None:
+        self._value = value
+        self._lock = Semaphore(1)
+
+    def _store(self, value: A) -> None:
+        self._value = value
+
+    def _commit[B](self, transition: _Transition[A, B]) -> B:
+        result, new = transition
+        if new is not None:
+            self._store(new.value)
+        return result
+
+    def _locked[B](self, f: Callable[[A], _Transition[A, B]]) -> Effect[B]:
+        return self._lock.with_permits(_Sync(lambda: self._commit(f(self._value))))
+
+    def _locked_effect[B, E, R](
+        self, f: Callable[[A], Effect[_Transition[A, B], E, R]]
+    ) -> Effect[B, E, R]:
+        return self._lock.with_permits(_Suspend(lambda: f(self._value).map(self._commit)))
+
+    # --- reading ----------------------------------------------------------
+
+    def get_unsafe(self) -> A:
+        return self._value
+
+    def get(self) -> Effect[A]:
+        return _Sync(lambda: self._value)
+
+    # --- plain updates ----------------------------------------------------
+
+    def set(self, value: A) -> Effect[None]:
+        return self._locked(lambda _: (None, Some(value)))
+
+    def set_and_get(self, value: A) -> Effect[A]:
+        return self._locked(lambda _: (value, Some(value)))
+
+    def get_and_set(self, value: A) -> Effect[A]:
+        return self._locked(lambda old: (old, Some(value)))
+
+    def update(self, f: Callable[[A], A]) -> Effect[None]:
+        return self._locked(lambda old: (None, Some(f(old))))
+
+    def update_and_get(self, f: Callable[[A], A]) -> Effect[A]:
+        return self._locked(lambda old: _new_and_get(f(old)))
+
+    def get_and_update(self, f: Callable[[A], A]) -> Effect[A]:
+        return self._locked(lambda old: (old, Some(f(old))))
+
+    def update_some(self, f: Callable[[A], Option[A]]) -> Effect[None]:
+        return self._locked(lambda old: (None, f(old)))
+
+    def update_some_and_get(self, f: Callable[[A], Option[A]]) -> Effect[A]:
+        return self._locked(lambda old: _some_and_get(old, f(old)))
+
+    def get_and_update_some(self, f: Callable[[A], Option[A]]) -> Effect[A]:
+        return self._locked(lambda old: (old, f(old)))
+
+    def modify[B](self, f: Callable[[A], tuple[B, A]]) -> Effect[B]:
+        return self._locked(lambda old: _modified(f(old)))
+
+    def modify_some[B](self, f: Callable[[A], tuple[B, Option[A]]]) -> Effect[B]:
+        return self._locked(f)
+
+    # --- effectful updates ------------------------------------------------
+
+    def update_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[A, E, R]]
+    ) -> Effect[None, E, R]:
+        return self._locked_effect(lambda old: f(old).map(lambda new: (None, Some(new))))
+
+    def update_and_get_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[A, E, R]]
+    ) -> Effect[A, E, R]:
+        return self._locked_effect(lambda old: f(old).map(_new_and_get))
+
+    def get_and_update_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[A, E, R]]
+    ) -> Effect[A, E, R]:
+        return self._locked_effect(lambda old: f(old).map(lambda new: (old, Some(new))))
+
+    def update_some_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[Option[A], E, R]]
+    ) -> Effect[None, E, R]:
+        return self._locked_effect(lambda old: f(old).map(lambda new: (None, new)))
+
+    def update_some_and_get_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[Option[A], E, R]]
+    ) -> Effect[A, E, R]:
+        return self._locked_effect(lambda old: f(old).map(lambda new: _some_and_get(old, new)))
+
+    def get_and_update_some_effect[E = Never, R = Never](
+        self, f: Callable[[A], Effect[Option[A], E, R]]
+    ) -> Effect[A, E, R]:
+        return self._locked_effect(lambda old: f(old).map(lambda new: (old, new)))
+
+    def modify_effect[B, E = Never, R = Never](
+        self, f: Callable[[A], Effect[tuple[B, A], E, R]]
+    ) -> Effect[B, E, R]:
+        return self._locked_effect(lambda old: f(old).map(_modified))
+
+    def modify_some_effect[B, E = Never, R = Never](
+        self, f: Callable[[A], Effect[tuple[B, Option[A]], E, R]]
+    ) -> Effect[B, E, R]:
+        return self._locked_effect(f)
+
+
+def _new_and_get[A](new: A) -> _Transition[A, A]:
+    return new, Some(new)
+
+
+def _some_and_get[A](old: A, new: Option[A]) -> _Transition[A, A]:
+    return (old if new is None else new.value), new
+
+
+def _modified[A, B](pair: tuple[B, A]) -> _Transition[A, B]:
+    result, new = pair
+    return result, Some(new)