pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/_to_equivalence.py

@@ -0,0 +1,186 @@
+"""``to_equivalence``: when two values of a schema's decoded side are the
+same (Effect's ``Schema.toEquivalence``).
+
+Structs, tuples and arrays compare part by part with their parts'
+equivalences, a union with the member both values belong to, a class by
+its fields; a ``to_equivalence`` annotation replaces a node's own (the
+built-in declarations carry one: ``Option``, ``Result``, ``Cause``, sets,
+maps, ``Redacted``...). Anything else is ``pyfect._equal.equals``: Python
+``==``, except that ``bool`` is not a number and ``NaN`` equals ``NaN``, as
+Effect's ``Equal.equals``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import Any, cast
+
+from pyfect._equal import equals
+from pyfect._stack import with_fresh_stack
+from pyfect.schema import ast
+from pyfect.schema._schema import Codec
+from pyfect.schema._type_walk import annotation_of, index_keys, member_selector
+
+type Equivalence[A] = Callable[[A, A], bool]
+"""Whether two values are the same (Effect's ``Equivalence``)."""
+
+type EquivalenceAnnotation = Callable[[tuple[Equivalence[Any], ...]], Equivalence[Any]]
+"""A ``to_equivalence`` annotation: a declaration's equivalence from its
+type parameters' (no parameters for other nodes)."""
+
+
+def to_equivalence[T](schema: Codec[T, object, object, object], /) -> Equivalence[T]:
+    """When two values of ``schema``'s decoded side are the same (Effect's
+    ``toEquivalence``)."""
+    return _Derivation()(schema.__codec__().ast)
+
+
+def same_items[A](equivalence: Equivalence[A]) -> Equivalence[Iterable[A]]:
+    """Two collections holding equivalent items, each matched once, in any
+    order (Effect's ``Equal.makeCompareSet``)."""
+
+    def compare(a: Iterable[A], b: Iterable[A]) -> bool:
+        remaining = list(b)
+        for item in a:
+            for i, other in enumerate(remaining):
+                if equivalence(item, other):
+                    remaining[i] = remaining[-1]
+                    remaining.pop()
+                    break
+            else:
+                return False
+        return not remaining
+
+    return compare
+
+
+class _Derivation:
+    """One derivation: each node is derived once."""
+
+    def __init__(self) -> None:
+        self._done: dict[int, tuple[ast.AST, Equivalence[Any]]] = {}
+        self._classes: dict[int, tuple[object, Equivalence[Any]]] = {}
+
+    def __call__(self, node: ast.AST) -> Equivalence[Any]:
+        hit = self._done.get(id(node))
+        if hit is None:
+            hit = (node, self._derive(node))
+            self._done[id(node)] = hit
+        return hit[1]
+
+    def _derive(self, node: ast.AST) -> Equivalence[Any]:  # noqa: PLR0911
+        annotation = annotation_of(node, "to_equivalence")
+        if callable(annotation):
+            derive = cast("EquivalenceAnnotation", annotation)
+            parameters = node.type_parameters if isinstance(node, ast.Declaration) else ()
+            return derive(tuple(map(self, parameters)))
+        match node:
+            case ast.Never():
+                return lambda a, b: a is b
+            case ast.Arrays():
+                return self._arrays(node)
+            case ast.Objects():
+                return self._objects(node)
+            case ast.Union():
+                return self._union(node)
+            case ast.Suspend():
+                return self._suspend(node)
+            case ast.Class():
+                return self._class(node)
+            case _:
+                return equals
+
+    def _arrays(self, node: ast.Arrays) -> Equivalence[object]:
+        elements = [self(e.type) for e in node.elements]
+        rest = [self(r) for r in node.rest]
+
+        def equivalent(a: object, b: object) -> bool:
+            if not isinstance(a, list | tuple) or not isinstance(b, list | tuple):
+                return False
+            a = cast("Sequence[object]", a)
+            b = cast("Sequence[object]", b)
+            if len(a) != len(b):
+                return False
+            n = len(a)
+            fixed = min(n, len(elements))
+            if not all(elements[i](a[i], b[i]) for i in range(fixed)):
+                return False
+            if not rest:
+                return True
+            head, *tail = rest
+            post = max(fixed, n - len(tail))
+            return all(head(a[i], b[i]) for i in range(fixed, post)) and all(
+                tail[j](a[post + j], b[post + j]) for j in range(len(tail))
+            )
+
+        return equivalent
+
+    def _objects(self, node: ast.Objects) -> Equivalence[Any]:
+        if not node.properties and not node.index_signatures:
+            return equals
+        properties = [(p.name, p.optional, self(p.type)) for p in node.properties]
+        indexes = [(i, self(i.type)) for i in node.index_signatures]
+
+        def equivalent(a: object, b: object) -> bool:
+            if not isinstance(a, Mapping) or not isinstance(b, Mapping):
+                return False
+            a = cast("Mapping[object, object]", a)
+            b = cast("Mapping[object, object]", b)
+            for name, optional, equivalence in properties:
+                a_has, b_has = name in a, name in b
+                if optional and a_has != b_has:
+                    return False
+                if a_has and b_has and not equivalence(a[name], b[name]):
+                    return False
+            for index, equivalence in indexes:
+                keys = index_keys(a, index)
+                if len(keys) != len(index_keys(b, index)):
+                    return False
+                if not all(key in b and equivalence(a[key], b[key]) for key in keys):
+                    return False
+            return True
+
+        return equivalent
+
+    def _union(self, node: ast.Union) -> Equivalence[object]:
+        select = member_selector(node)
+        members = [self(t) for t in node.types]
+
+        def equivalent(a: object, b: object) -> bool:
+            for i, guard in select(a):
+                if guard(a) and guard(b):
+                    return members[i](a, b)
+            return False
+
+        return equivalent
+
+    def _suspend(self, node: ast.Suspend) -> Equivalence[object]:
+        target: list[Equivalence[object]] = []
+
+        def equivalent(a: object, b: object) -> bool:
+            if not target:
+                target.append(self(node.target))
+            return with_fresh_stack(lambda: target[0](a, b))
+
+        return equivalent
+
+    def _class(self, node: ast.Class) -> Equivalence[Any]:
+        match node.side:
+            case "decode" | "type":
+                # Derived on first use, once per class: a class may hold itself.
+                shape = node.shape
+                hit = self._classes.get(id(shape))
+                if hit is not None:
+                    return hit[1]
+                fields: list[Equivalence[Any]] = []
+
+                def equivalent(a: Any, b: Any) -> bool:
+                    if not fields:
+                        fields.append(self(shape.fields.to_type()))
+                    values_of = shape.values_of
+                    return with_fresh_stack(lambda: fields[0](values_of(a), values_of(b)))
+
+                self._classes[id(shape)] = (shape, equivalent)
+                return equivalent
+            case "encode" | "encoded":
+                return self(node.shape.encoded)

pyfect/schema/_to_formatter.py

@@ -0,0 +1,180 @@
+"""``to_formatter``: a schema's decoded values as text (Effect's
+``Schema.toFormatter``).
+
+Structs, tuples, arrays and classes are written part by part with their
+parts' formatters (``{ "a": some(1) }``, ``[1, "a"]``, ``A({ ... })``), a
+union value with the member it belongs to; a ``to_formatter`` annotation
+replaces a node's own (the built-in declarations carry one: ``some(1)``,
+``FrozenSet(2) { 1, 2 }``...), and ``on_before`` may take any node first.
+Anything else is ``format_unknown`` (Effect's ``Formatter.format``).
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, cast
+
+from pyfect._stack import with_fresh_stack
+from pyfect.logger._text import format_unknown, json_quote
+from pyfect.schema import ast
+from pyfect.schema._schema import Codec
+from pyfect.schema._type_walk import annotation_of, class_name, index_keys, member_selector
+
+type Formatter[A] = Callable[[A], str]
+"""A value as text (Effect's ``Formatter``)."""
+
+type FormatterAnnotation = Callable[[tuple[Formatter[Any], ...]], Formatter[Any]]
+"""A ``to_formatter`` annotation: a declaration's formatter from its type
+parameters' (no parameters for other nodes)."""
+
+type OnBefore = Callable[[ast.AST, Callable[[ast.AST], Formatter[Any]]], Formatter[Any] | None]
+"""Takes a node before the derivation does: its formatter, or ``None`` to
+leave it to the derivation (which it may call)."""
+
+
+def to_formatter[T](
+    schema: Codec[T, object, object, object], /, *, on_before: OnBefore | None = None
+) -> Formatter[T]:
+    """``schema``'s decoded values as text (Effect's ``toFormatter``)."""
+    return _Derivation(on_before)(schema.__codec__().ast)
+
+
+def format_key(key: object) -> str:
+    """A property key as Effect writes it: a string quoted."""
+    return json_quote(key) if isinstance(key, str) else format_unknown(key)
+
+
+def _format_leaf(value: object) -> str:
+    # An enum member is written as its value, as Effect's enums are values.
+    return format_unknown(value.value if isinstance(value, enum.Enum) else value)
+
+
+class _Derivation:
+    """One derivation: each node is derived once."""
+
+    def __init__(self, on_before: OnBefore | None) -> None:
+        self._on_before = on_before
+        self._done: dict[int, tuple[ast.AST, Formatter[Any]]] = {}
+        self._classes: dict[int, tuple[object, Formatter[Any]]] = {}
+
+    def __call__(self, node: ast.AST) -> Formatter[Any]:
+        hit = self._done.get(id(node))
+        if hit is None:
+            hit = (node, self._compile(node))
+            self._done[id(node)] = hit
+        return hit[1]
+
+    def _compile(self, node: ast.AST) -> Formatter[Any]:
+        annotation = annotation_of(node, "to_formatter")
+        if callable(annotation):
+            derive = cast("FormatterAnnotation", annotation)
+            parameters = node.type_parameters if isinstance(node, ast.Declaration) else ()
+            return derive(tuple(map(self, parameters)))
+        if self._on_before is not None:
+            formatter = self._on_before(node, self)
+            if formatter is not None:
+                return formatter
+        return self._derive(node)
+
+    def _derive(self, node: ast.AST) -> Formatter[Any]:  # noqa: PLR0911
+        match node:
+            case ast.Never():
+                return lambda _: "never"
+            case ast.Arrays():
+                return self._arrays(node)
+            case ast.Objects():
+                return self._objects(node)
+            case ast.Union():
+                return self._union(node)
+            case ast.Suspend():
+                return self._suspend(node)
+            case ast.Class():
+                return self._class(node)
+            case _:
+                return _format_leaf
+
+    def _arrays(self, node: ast.Arrays) -> Formatter[Sequence[object]]:
+        elements = [(self(e.type), e.optional) for e in node.elements]
+        rest = [self(r) for r in node.rest]
+
+        def format(value: Sequence[object]) -> str:
+            n = len(value)
+            out = [element(value[i]) for i, (element, _) in enumerate(elements) if i < n]
+            if rest:
+                head, *tail = rest
+                start = len(elements)
+                post = max(start, n - len(tail))
+                out += [head(value[i]) for i in range(start, post)]
+                out += [tail[j](value[post + j]) for j in range(len(tail))]
+            return "[" + ", ".join(out) + "]"
+
+        return format
+
+    def _objects(self, node: ast.Objects) -> Formatter[Any]:
+        if not node.properties and not node.index_signatures:
+            return format_unknown
+        properties = [(p.name, self(p.type)) for p in node.properties]
+        indexes = [(i, self(i.type)) for i in node.index_signatures]
+
+        def format(value: Mapping[object, object]) -> str:
+            out: list[str] = []
+            visited: set[object] = set()
+            for name, formatter in properties:
+                visited.add(name)
+                if name not in value:  # an optional key
+                    continue
+                out.append(f"{format_key(name)}: {formatter(value[name])}")
+            for index, formatter in indexes:
+                for key in index_keys(value, index):
+                    if key not in visited:
+                        visited.add(key)
+                        out.append(f"{format_key(key)}: {formatter(value[key])}")
+            return "{ " + ", ".join(out) + " }" if out else "{}"
+
+        return format
+
+    def _union(self, node: ast.Union) -> Formatter[object]:
+        select = member_selector(node)
+        members = [self(t) for t in node.types]
+
+        def format(value: object) -> str:
+            for i, guard in select(value):
+                if guard(value):
+                    return members[i](value)
+            return format_unknown(value)
+
+        return format
+
+    def _suspend(self, node: ast.Suspend) -> Formatter[object]:
+        target: list[Formatter[object]] = []
+
+        def format(value: object) -> str:
+            if not target:
+                target.append(self(node.target))
+            return with_fresh_stack(lambda: target[0](value))
+
+        return format
+
+    def _class(self, node: ast.Class) -> Formatter[Any]:
+        match node.side:
+            case "decode" | "type":
+                # Derived on first use, once per class: a class may hold itself.
+                shape = node.shape
+                hit = self._classes.get(id(shape))
+                if hit is not None:
+                    return hit[1]
+                fields: list[Formatter[Any]] = []
+                name = class_name(node)
+
+                def format(instance: Any) -> str:
+                    if not fields:
+                        fields.append(self(shape.fields.to_type()))
+                    return with_fresh_stack(
+                        lambda: f"{name}({fields[0](shape.values_of(instance))})"
+                    )
+
+                self._classes[id(shape)] = (shape, format)
+                return format
+            case "encode" | "encoded":
+                return self(node.shape.encoded)

pyfect/schema/_to_iso.py

@@ -0,0 +1,73 @@
+"""``to_iso``: an optic between a schema's values and their plain form, where each class is its
+fields and each data type its ``to_codec`` form (Effect's ``Schema.toIso`` and ``toCodecIso``)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any, cast
+
+from pyfect import optic
+from pyfect.schema import ast
+from pyfect.schema._codec_derivation import CodecDerivation
+from pyfect.schema._codec_links import UNKNOWN_TO_JSON
+from pyfect.schema._parse import decode_sync, encode_sync
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema.transformation import Transformation
+
+
+def to_codec_iso[T](schema: Codec[T, object, object, object], /) -> Bottom[T, Any]:
+    return Bottom(_Derivation()(schema.__codec__().ast.to_type()))
+
+
+def to_iso[T](schema: Codec[T, object, object, object], /) -> optic.Iso[T, Any]:
+    serializer: Any = to_codec_iso(schema)
+    return optic.make_iso(encode_sync(serializer), decode_sync(serializer))
+
+
+def to_iso_source[T](_: Codec[T, object, object, object], /) -> optic.Iso[T, T]:
+    return optic.Id()
+
+
+def to_iso_focus(_: Codec[object, object, object, object], /) -> optic.Iso[Any, Any]:
+    return optic.Id()
+
+
+def override_to_codec_iso[T, I](
+    to: Codec[I, object, object, object], transformation: Transformation[T, I], /
+) -> Callable[[Codec[T, Any, Any, Any]], Bottom[T, Any, Any, Any]]:
+    """``schema`` whose plain form is ``to``, read through ``transformation``."""
+    link = ast.Link(to.__codec__().ast, transformation)
+
+    def get_link(_: tuple[ast.AST, ...]) -> ast.Link:
+        return link
+
+    def override(schema: Codec[T, Any, Any, Any]) -> Bottom[T, Any, Any, Any]:
+        return Bottom(ast.annotate(schema.__codec__().ast, {"to_codec_iso": get_link}))
+
+    return override
+
+
+class _Derivation(CodecDerivation):
+    opaque = UNKNOWN_TO_JSON
+
+    def _leaf(self, node: ast.AST) -> ast.AST:
+        if not isinstance(node, ast.Declaration):
+            return node
+        annotations = node.annotations or {}
+        get_link = annotations.get("to_codec_iso") or annotations.get("to_codec")
+        if not callable(get_link):
+            return node
+        make = cast("Callable[[tuple[ast.AST, ...]], ast.Link | None]", get_link)
+        link = make(node.type_parameters)
+        if link is None:
+            return node
+        return replace(node, encoding=(ast.Link(self(link.to), link.transformation),))
+
+    def _priority(self, encoded: ast.AST) -> int:
+        return 0
+
+    def _objects(self, node: ast.Objects) -> ast.Objects:
+        properties = tuple(replace(p, type=self(p.type)) for p in node.properties)
+        indexes = tuple(replace(i, type=self(i.type)) for i in node.index_signatures)
+        return replace(node, properties=properties, index_signatures=indexes)

pyfect/schema/_to_strategy.py

@@ -0,0 +1,31 @@
+"""``to_strategy``: a Hypothesis strategy for a schema's decoded values
+(Effect's ``Arbitrary.schema``; Hypothesis is the runner, so Effect's
+``checkEffect`` / ``sampleEffect`` are ``@given`` and ``.example()``).
+
+Needs the ``pyfect-dev[hypothesis]`` extra; importing ``pyfect.schema`` does
+not import Hypothesis.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfect.schema._schema import Codec
+
+if TYPE_CHECKING:
+    from hypothesis.strategies import SearchStrategy
+
+
+def to_strategy[T](schema: Codec[T, object, object, object], /) -> SearchStrategy[T]:
+    """Values of ``schema``'s decoded side that pass its checks and that
+    ``schema`` encodes (a JSON string holds no ``NaN``, say).
+
+    Common checks (bounds, lengths, sizes, patterns, integers) shape what is
+    drawn; every check also filters it. A declaration is drawn with its
+    ``to_arbitrary`` annotation (its type parameters' strategies in, a
+    strategy out), else through its ``to_codec_arbitrary``, ``to_codec_json``
+    or ``to_codec`` link. Raises ``ValueError`` when the schema has no
+    finite value or a declaration says neither."""
+    from pyfect.schema._strategy import derive
+
+    return derive(schema.__codec__().ast)

pyfect/schema/_transform.py

@@ -0,0 +1,210 @@
+"""Schemas transforming between two others (Effect's ``decodeTo``,
+``encodeTo``, ``decode``, ``encode``, ``flip``, ``toType``, ``toEncoded``).
+
+``source.pipe(S.decode_to(target, transformation))`` decodes a value of
+``source``'s Encoded through ``source``, then ``transformation.decode``,
+then ``target``; encoding runs the other way. Without a transformation the
+value passes unchanged. The source may be ``S.optional_key(schema)``: the
+struct key is then optional on the encoded side.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Generic, Never, TypeVar, overload
+
+from pyfect.schema import ast
+from pyfect.schema._arrays import OptionalKey
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema.transformation import Transformation, passthrough
+
+T_co = TypeVar("T_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+RD_co = TypeVar("RD_co", covariant=True, default=Never)
+RE_co = TypeVar("RE_co", covariant=True, default=Never)
+
+type Source[T, E, RD, RE] = Codec[T, E, RD, RE] | OptionalKey[T, E, RD, RE]
+"""What ``decode_to`` takes as its source: a schema, or one in
+``optional_key``."""
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class DecodeToSchema(Bottom[T_co, E_co, RD_co, RE_co], Generic[T_co, E_co, RD_co, RE_co]):
+    """A schema decoding ``from_``'s Encoded into ``to``'s Type."""
+
+    from_: Source[object, E_co, RD_co, RE_co]
+    to: Codec[T_co, object, RD_co, RE_co]
+
+
+def _source_ast(source: Source[Any, Any, Any, Any]) -> ast.AST:
+    if isinstance(source, OptionalKey):
+        return ast.optional_key(source.schema.__codec__().ast)
+    return source.__codec__().ast
+
+
+def _make[T, E, RD, RE](
+    from_: Source[Any, E, RD, RE],
+    to: Codec[T, Any, RD, RE],
+    transformation: Transformation[Any, Any, Any, Any],
+) -> DecodeToSchema[T, E, RD, RE]:
+    node = ast.decode_to(_source_ast(from_), to.__codec__().ast, transformation)
+    return DecodeToSchema(node, from_, to)
+
+
+class DecodeTo(Generic[T_co, E_co, RD_co, RE_co]):
+    """``decode_to(to, transformation)``: apply with ``.pipe`` to a source
+    whose Type is ``E``."""
+
+    __slots__ = ("_to", "_transformation")
+
+    def __init__(
+        self, to: Codec[T_co, Any, RD_co, RE_co], transformation: Transformation[Any, Any, Any, Any]
+    ) -> None:
+        self._to = to
+        self._transformation = transformation
+
+    def __call__[I, RD2 = Never, RE2 = Never](
+        self, source: Source[E_co, I, RD2, RE2], /
+    ) -> DecodeToSchema[T_co, I, RD_co | RD2, RE_co | RE2]:
+        return _make(source, self._to, self._transformation)
+
+
+@overload
+def decode_to[T, M, RD, RE](to: Codec[T, M, RD, RE], /) -> DecodeTo[T, M, RD, RE]: ...
+@overload
+def decode_to[T, M, F, RD, RE](
+    to: Codec[T, M, RD, RE], transformation: Transformation[M, F, RD, RE], /
+) -> DecodeTo[T, F, RD, RE]: ...
+def decode_to(
+    to: Codec[Any, Any, Any, Any],
+    transformation: Transformation[Any, Any, Any, Any] | None = None,
+    /,
+) -> DecodeTo[Any, Any, Any, Any]:
+    """The source's values decoded through ``transformation`` (none: kept
+    as they are) into ``to``'s (Effect's ``decodeTo``)."""
+    return DecodeTo(to, passthrough() if transformation is None else transformation)
+
+
+class EncodeTo(Generic[T_co, E_co, RD_co, RE_co]):
+    """``encode_to(to, transformation)``: apply with ``.pipe`` to a schema
+    whose Encoded is ``T``."""
+
+    __slots__ = ("_to", "_transformation")
+
+    def __init__(
+        self,
+        to: Source[Any, E_co, RD_co, RE_co],
+        transformation: Transformation[Any, Any, Any, Any],
+    ) -> None:
+        self._to = to
+        self._transformation = transformation
+
+    def __call__[A, RD2 = Never, RE2 = Never](
+        self, schema: Codec[A, T_co, RD2, RE2], /
+    ) -> DecodeToSchema[A, E_co, RD_co | RD2, RE_co | RE2]:
+        return _make(self._to, schema, self._transformation)
+
+
+@overload
+def encode_to[M, E, RD, RE](to: Source[M, E, RD, RE], /) -> EncodeTo[M, E, RD, RE]: ...
+@overload
+def encode_to[M, F, E, RD, RE](
+    to: Source[M, E, RD, RE], transformation: Transformation[F, M, RD, RE], /
+) -> EncodeTo[F, E, RD, RE]: ...
+def encode_to(
+    to: Source[Any, Any, Any, Any],
+    transformation: Transformation[Any, Any, Any, Any] | None = None,
+    /,
+) -> EncodeTo[Any, Any, Any, Any]:
+    """The schema's Encoded encoded further into ``to``'s: ``s.pipe(
+    S.encode_to(to, t))`` is ``to.pipe(S.decode_to(s, t))`` (Effect's
+    ``encodeTo``)."""
+    return EncodeTo(to, passthrough() if transformation is None else transformation)
+
+
+class Decode(Generic[T_co, RD_co, RE_co]):
+    """``decode(transformation)``: apply with ``.pipe``."""
+
+    __slots__ = ("_transformation",)
+
+    def __init__(self, transformation: Transformation[Any, Any, Any, Any]) -> None:
+        self._transformation = transformation
+
+    def __call__[E, RD2 = Never, RE2 = Never](
+        self, schema: Codec[T_co, E, RD2, RE2], /
+    ) -> DecodeToSchema[T_co, E, RD_co | RD2, RE_co | RE2]:
+        return _make(schema, to_type(schema), self._transformation)
+
+
+def decode[T, RD = Never, RE = Never](
+    transformation: Transformation[T, T, RD, RE], /
+) -> Decode[T, RD, RE]:
+    """The schema, then ``transformation`` on its decoded values (Effect's
+    ``decode``)."""
+    return Decode(transformation)
+
+
+class Encode(Generic[E_co, RD_co, RE_co]):
+    """``encode(transformation)``: apply with ``.pipe``."""
+
+    __slots__ = ("_transformation",)
+
+    def __init__(self, transformation: Transformation[Any, Any, Any, Any]) -> None:
+        self._transformation = transformation
+
+    def __call__[T, RD2 = Never, RE2 = Never](
+        self, schema: Codec[T, E_co, RD2, RE2], /
+    ) -> DecodeToSchema[T, E_co, RD_co | RD2, RE_co | RE2]:
+        return _make(to_encoded(schema), schema, self._transformation)
+
+
+def encode[E, RD = Never, RE = Never](
+    transformation: Transformation[E, E, RD, RE], /
+) -> Encode[E, RD, RE]:
+    """``transformation`` on the encoded values, before the schema (Effect's
+    ``encode``)."""
+    return Encode(transformation)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class FlipSchema(Bottom[T_co, E_co, RD_co, RE_co], Generic[T_co, E_co, RD_co, RE_co]):
+    """``schema`` the other way: it decodes what ``schema`` encodes."""
+
+    schema: Codec[E_co, T_co, RE_co, RD_co]
+
+
+@overload
+def flip[T, E, RD, RE](  # pyright: ignore[reportOverlappingOverload]
+    schema: FlipSchema[T, E, RD, RE], /
+) -> Codec[E, T, RE, RD]: ...
+@overload
+def flip[T, E, RD, RE](schema: Codec[T, E, RD, RE], /) -> FlipSchema[E, T, RE, RD]: ...
+def flip(schema: Codec[Any, Any, Any, Any], /) -> Codec[Any, Any, Any, Any]:
+    """The schema decoding its Type into its Encoded (Effect's ``flip``);
+    the flip of a flip is the original schema, rebuilt on the flipped node
+    (so checks added in between stay)."""
+    if isinstance(schema, FlipSchema):
+        node = schema.ast.flip()
+        original = schema.schema.__codec__()
+        return original if original.ast is node else replace(original, ast=node)
+    return FlipSchema(schema.__codec__().ast.flip(), schema)
+
+
+def to_type[T](schema: Codec[T, object, object, object], /) -> Bottom[T]:
+    """The schema's decoded side: it checks a Type value and keeps it
+    (Effect's ``toType``)."""
+    return Bottom(schema.__codec__().ast.to_type())
+
+
+def to_encoded[E](schema: Codec[object, E, object, object], /) -> Bottom[E]:
+    """The schema's encoded side (Effect's ``toEncoded``)."""
+    return Bottom(ast.to_encoded(schema.__codec__().ast))
+
+
+def link[T, M](
+    encode_to: Codec[M, object, object, object], transformation: Transformation[T, M], /
+) -> ast.Link:
+    """A declaration's codec step (Effect's ``link<T>()(encodeTo, t)``): its
+    ``T`` values encoded through ``transformation`` to ``encode_to``, for a
+    ``to_codec`` / ``to_codec_json`` annotation."""
+    return ast.Link(encode_to.__codec__().ast, transformation)