trcks.fp.monads.result_tuple

def construct_failure(value: _F, /) -> Failure[_F]:
    """Create a [trcks.Failure][] object from a value.

    Args:
        value: Value to be wrapped in a [trcks.Failure][].

    Returns:
        [trcks.Failure][] object containing the given value.

    Note:
        This function is an alias for
        [trcks.fp.monads.result.construct_failure][].

    Examples:
        >>> from trcks.fp.monads import result_tuple as rt
        >>> rt.construct_failure("not found")
        ('failure', 'not found')
    """
    return r.construct_failure(value)

def construct_from_result(rslt: Result[_F, _S], /) -> ResultTuple[_F, _S]:
    """Create a [trcks.ResultTuple][] object from a [trcks.Result][].

    Args:
        rslt: The [trcks.Result][] object to be wrapped.

    Returns:
        A new [trcks.ResultTuple][] instance with the success payload
            wrapped in a homogeneous tuple.

    Examples:
        >>> from trcks.fp.monads import result_tuple as rt
        >>> rt.construct_from_result(("success", 7))
        ('success', (7,))
        >>> rt.construct_from_result(("failure", "oops"))
        ('failure', 'oops')
    """
    return r.map_success(t.construct)(rslt)

def construct_from_result_iterable(
    r_it: ResultIterable[_F, _S], /
) -> ResultTuple[_F, _S]:
    """Create a [trcks.ResultTuple][] object from a [trcks.ResultIterable][].

    Args:
        r_it: The [trcks.ResultIterable][] object to be converted.

    Returns:
        A new [trcks.ResultTuple][] instance
            with the success payload converted to a tuple,
            or the original failure.

    Examples:
        >>> from trcks.fp.monads import result_tuple as rt
        >>> rt.construct_from_result_iterable(("success", [1, 2]))
        ('success', (1, 2))
        >>> rt.construct_from_result_iterable(("failure", "oops"))
        ('failure', 'oops')
    """
    mapped: Callable[[ResultIterable[_F, _S]], ResultTuple[_F, _S]] = (
        r.map_success_to_result(construct_successes_from_iterable)
    )
    return mapped(r_it)

@deprecated("Use construct_from_result_iterable instead")
def construct_from_result_tuple(
    r_tpl: ResultTuple[_F1, _S1],
    /,
) -> ResultTuple[_F1, _S1]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.construct_from_result_iterable][].
    """
    return construct_from_result_iterable(r_tpl)  # pragma: no cover

def construct_successes(value: _S, /) -> SuccessTuple[_S]:
    """Create a [trcks.SuccessTuple][] object from a single value.

    Args:
        value: A single value.

    Returns:
        A new [trcks.SuccessTuple][] instance containing the single value.

    Examples:
        >>> from trcks.fp.monads import result_tuple as rt
        >>> rt.construct_successes(42)
        ('success', (42,))
    """
    return r.construct_success(t.construct(value))

def construct_successes_from_iterable(it: Iterable[_S], /) -> SuccessTuple[_S]:
    """Create a [trcks.SuccessTuple][] object from an iterable.

    Args:
        it: The iterable to create
            the [trcks.SuccessTuple][] from.

    Returns:
        The [trcks.SuccessTuple][] created from the iterable.

    Examples:
        >>> from trcks.fp.monads import result_tuple as rt
        >>> rt.construct_successes_from_iterable((1, 2))
        ('success', (1, 2))
    """
    return r.construct_success(tuple(it))

@deprecated("Use construct_successes_from_iterable instead")
def construct_successes_from_tuple(tpl: tuple[_S, ...], /) -> SuccessTuple[_S]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.construct_successes_from_iterable][].
    """
    return construct_successes_from_iterable(tpl)  # pragma: no cover

def map_failure(
    callable_: Callable[Concatenate[_F1, _P], _F2],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F2, _S1]]:
    """Create function that maps [trcks.Failure][] values to [trcks.Failure][] values.

    [trcks.SuccessTuple][] values are left unchanged.

    Args:
        callable_: Function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to new [trcks.Failure][] values
            according to the given function and
            leaves [trcks.SuccessTuple][] values unchanged.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _add_prefix(description: str) -> str:
        ...     return f"err: {description}"
        ...
        >>> add_prefix: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_failure(_add_prefix)
        >>> add_prefix(("failure", "not found"))
        ('failure', 'err: not found')
        >>> add_prefix(("success", (1, 2)))
        ('success', (1, 2))
    """
    return r.map_failure(callable_, *args, **kwargs)

def map_failure_to_awaitable(
    callable_: Callable[Concatenate[_F1, _P], Awaitable[_F2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F2, _S1]]:
    """Create function that maps [trcks.Failure][] values
    to [trcks.AwaitableFailure][] values.

    [trcks.Success][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to [trcks.AwaitableFailure][] values
            according to the given asynchronous function and
            leaves [trcks.Success][] values unchanged.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def prefix_slowly(e: str) -> str:
        ...     await asyncio.sleep(0.001)
        ...     return f"err: {e}"
        ...
        >>> add_prefix_to_failure = rt.map_failure_to_awaitable(prefix_slowly)
        >>> a_r_tpl_1 = add_prefix_to_failure(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'err: not found')
        >>> a_r_tpl_2 = add_prefix_to_failure(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (1, 2))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_failure_to_awaitable(callable_, *args, **kwargs),
    )

def map_failure_to_awaitable_iterable(
    callable_: Callable[Concatenate[_F1, _P], AwaitableIterable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[
    [ResultTuple[_F1, _S1]],
    Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
]:
    """Create function that maps [trcks.Failure][] values
    to new [trcks.AwaitableSuccessTuple][] values.

    [trcks.Success][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to the [trcks.Failure][] values,
            returning an [trcks.AwaitableIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to new [trcks.AwaitableSuccessTuple][]
            values according to the given asynchronous function and
            leaves [trcks.Success][] values unchanged.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def slowly_recover_from_failure(description: str) -> list[int]:
        ...     await asyncio.sleep(0.001)
        ...     if description == "not found":
        ...         return [0]
        ...     return []
        ...
        >>> recover_from_failure = rt.map_failure_to_awaitable_iterable(
        ...     slowly_recover_from_failure
        ... )
        >>> a_r_tpl_1 = recover_from_failure(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0,))
        >>> a_r_tpl_2 = recover_from_failure(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (1, 2))
    """
    c: tuple[
        Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1, _S1]],
        Callable[
            [AwaitableResultTuple[_F1, _S1]],
            Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
        ],
    ] = (
        art.construct_from_result_iterable,
        art.map_failure_to_awaitable_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

def map_failure_to_awaitable_result(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResult[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Create function that maps [trcks.Failure][] values
    to [trcks.AwaitableResult][] values.

    [trcks.Success][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values
            to [trcks.AwaitableFailure][] and [trcks.AwaitableSuccess][] values
            according to the given asynchronous function and
            leaves [trcks.Success][] values unchanged.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def slowly_recover_from_not_found(e: str) -> Result[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if e == "not found":
        ...         return "success", 0
        ...     return "failure", e
        ...
        >>> recover_from_failure = rt.map_failure_to_awaitable_result(
        ...     slowly_recover_from_not_found
        ... )
        >>> a_r_tpl_1 = recover_from_failure(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0,))
        >>> a_r_tpl_2 = recover_from_failure(("failure", "fatal"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'fatal')
        >>> a_r_tpl_3 = recover_from_failure(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_3))
        ('success', (1, 2))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_failure_to_awaitable_result(callable_, *args, **kwargs),
    )

def map_failure_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Create function that maps [trcks.Failure][] values
    to [trcks.AwaitableResultTuple][] values.

    [trcks.Success][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to new [trcks.AwaitableResultTuple][] values
            according to the given asynchronous function and
            leaves [trcks.Success][] values unchanged.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def recover(e: str) -> AwaitableResultTuple[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if e == "not found":
        ...         return "success", (0, 1)
        ...     return "failure", e
        ...
        >>> recover_from_failure = rt.map_failure_to_awaitable_result_iterable(
        ...     recover
        ... )
        >>> a_r_tpl_1 = recover_from_failure(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0, 1))
        >>> a_r_tpl_2 = recover_from_failure(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (1, 2))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_failure_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )

@deprecated("Use map_failure_to_awaitable_result_iterable instead")
def map_failure_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResultTuple[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_failure_to_awaitable_result_iterable][].
    """
    return map_failure_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_failure_to_awaitable_iterable instead")
def map_failure_to_awaitable_tuple(
    callable_: Callable[Concatenate[_F1, _P], AwaitableTuple[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[
    [ResultTuple[_F1, _S1]],
    Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_failure_to_awaitable_iterable][].
    """
    return map_failure_to_awaitable_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

def map_failure_to_iterable(
    callable_: Callable[Concatenate[_F1, _P], Iterable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], SuccessTuple[_S1] | SuccessTuple[_S2]]:
    """Create function that maps [trcks.Failure][] values
    to homogeneous [tuple][]s.

    [trcks.SuccessTuple][] values are left unchanged.

    Args:
        callable_: Function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to homogeneous [tuple][]s wrapped
            in a [trcks.Success][] according to the given function and
            leaves [trcks.SuccessTuple][] values unchanged.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple, SuccessTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _recover_from_not_found(description: str) -> tuple[int, ...]:
        ...     if description == "not found":
        ...         return (0,)
        ...     return ()
        ...
        >>> recover_from_not_found: Callable[
        ...     [ResultTuple[str, int]], SuccessTuple[int]
        ... ] = rt.map_failure_to_iterable(_recover_from_not_found)
        >>> recover_from_not_found(("failure", "not found"))
        ('success', (0,))
        >>> recover_from_not_found(("failure", "not authorized"))
        ('success', ())
        >>> recover_from_not_found(("success", (1, 2)))
        ('success', (1, 2))
    """

    def mapped_callable(
        r_tpl: ResultTuple[_F1, _S1],
    ) -> SuccessTuple[_S1] | SuccessTuple[_S2]:
        match r_tpl:
            case ("failure", value):
                return "success", tuple(callable_(value, *args, **kwargs))
            case ("success", _):
                return r_tpl
            case _:  # pragma: no cover
                assert_type(r_tpl, Never)  # type: ignore[unreachable]  # pyright: ignore[reportUnreachable]
                msg = f"{type(r_tpl).__name__!r} is not a valid ResultTuple"
                raise TypeError(msg)

    return mapped_callable

def map_failure_to_result(
    callable_: Callable[Concatenate[_F1, _P], Result[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], Result[_F2, tuple[_S1, ...] | tuple[_S2, ...]]]:
    """Create function that maps [trcks.Failure][] values
    to [trcks.Failure][] and [trcks.Success][] values.

    [trcks.SuccessTuple][] values are left unchanged.

    Args:
        callable_: Function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to new [trcks.Failure][] and [trcks.Success][]
            values according to the given function and
            leaves [trcks.SuccessTuple][] values unchanged.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _recover_from_not_found(description: str) -> Result[str, int]:
        ...     if description == "not found":
        ...         return "success", 0
        ...     return "failure", description
        ...
        >>> recover_from_not_found: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_failure_to_result(_recover_from_not_found)
        >>> recover_from_not_found(("failure", "not found"))
        ('success', (0,))
        >>> recover_from_not_found(("failure", "not authorized"))
        ('failure', 'not authorized')
        >>> recover_from_not_found(("success", (1, 2)))
        ('success', (1, 2))
    """
    return map_failure_to_result_iterable(
        compose(callable_, construct_from_result), *args, **kwargs
    )

def map_failure_to_result_iterable(
    callable_: Callable[Concatenate[_F1, _P], ResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], Result[_F2, tuple[_S1, ...] | tuple[_S2, ...]]]:
    """Create function that maps [trcks.Failure][] values
    to new [trcks.ResultTuple][] values.

    [trcks.SuccessTuple][] values are left unchanged.

    Args:
        callable_: Function to apply to the [trcks.Failure][] values.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.Failure][] values to new [trcks.ResultTuple][] values
            according to the given function and
            leaves [trcks.SuccessTuple][] values unchanged.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _recover_from_not_found(description: str) -> ResultTuple[str, int]:
        ...     if description == "not found":
        ...         return "success", (0,)
        ...     return "failure", description
        ...
        >>> recover_from_not_found: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_failure_to_result_iterable(_recover_from_not_found)
        >>> recover_from_not_found(("failure", "not found"))
        ('success', (0,))
        >>> recover_from_not_found(("failure", "not authorized"))
        ('failure', 'not authorized')
        >>> recover_from_not_found(("success", (1, 2)))
        ('success', (1, 2))
    """
    return r.map_failure_to_result(
        compose(callable_, construct_from_result_iterable), *args, **kwargs
    )

@deprecated("Use map_failure_to_result_iterable instead")
def map_failure_to_result_tuple(
    callable_: Callable[Concatenate[_F1, _P], ResultTuple[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], Result[_F2, tuple[_S1, ...] | tuple[_S2, ...]]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_failure_to_result_iterable][].
    """
    return map_failure_to_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_failure_to_iterable instead")
def map_failure_to_tuple(
    callable_: Callable[Concatenate[_F1, _P], tuple[_S2, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], SuccessTuple[_S1] | SuccessTuple[_S2]]:
    """Deprecated alias for [trcks.fp.monads.result_tuple.map_failure_to_iterable][]."""
    return map_failure_to_iterable(callable_, *args, **kwargs)  # pragma: no cover

def map_successes(
    callable_: Callable[Concatenate[_S1, _P], _S2],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1, _S2]]:
    """Create function that maps each element of a [trcks.SuccessTuple][]
    to a new element.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Function to apply to each element of the [trcks.SuccessTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps each element of a [trcks.SuccessTuple][] to a new element
            according to the given function.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _double_integer(n: int) -> int:
        ...     return n * 2
        ...
        >>> double_integers: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_successes(_double_integer)
        >>> double_integers(("success", (1, 2, 3)))
        ('success', (2, 4, 6))
        >>> double_integers(("failure", "not found"))
        ('failure', 'not found')
    """
    return r.map_success(t.map_(callable_, *args, **kwargs))

def map_successes_to_awaitable(
    callable_: Callable[Concatenate[_S1, _P], Awaitable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1, _S2]]:
    """Create function that maps [trcks.Success][] values
    to [trcks.AwaitableSuccess][] values.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to each success element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps [trcks.Success][] values to new [trcks.AwaitableSuccess][]
            values according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def double_slowly(n: int) -> int:
        ...     await asyncio.sleep(0.001)
        ...     return n * 2
        ...
        >>> double_successes = rt.map_successes_to_awaitable(double_slowly)
        >>> a_r_tpl_1 = double_successes(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = double_successes(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (2, 4))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_successes_to_awaitable(callable_, *args, **kwargs),
    )

def map_successes_to_awaitable_iterable(
    callable_: Callable[Concatenate[_S1, _P], AwaitableIterable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1, _S2]]:
    """Create function that maps [trcks.Success][] values to homogeneous [tuple][]s
    and flattens the result.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to each success element,
            returning an [trcks.AwaitableIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps [trcks.Success][] values to flattened
            [trcks.AwaitableSuccessTuple][] values
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def slowly_duplicate_integer(n: int) -> tuple[int, int]:
        ...     await asyncio.sleep(0.001)
        ...     return n, n
        ...
        >>> duplicate_successes = rt.map_successes_to_awaitable_iterable(
        ...     slowly_duplicate_integer
        ... )
        >>> a_r_tpl_1 = duplicate_successes(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 1, 2, 2))
        >>> a_r_tpl_2 = duplicate_successes(("failure", "oops"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'oops')
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_successes_to_awaitable_iterable(callable_, *args, **kwargs),
    )

def map_successes_to_awaitable_result(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResult[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1 | _F2, _S2]]:
    """Create function that maps [trcks.Success][] values
    to [trcks.AwaitableResult][] values.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to each success element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps [trcks.Success][] values
            to [trcks.AwaitableFailure][] and [trcks.AwaitableSuccess][] values
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def slowly_double_if_positive(n: int) -> Result[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", n * 2
        ...     return "failure", "negative"
        ...
        >>> double_successes = rt.map_successes_to_awaitable_result(
        ...     slowly_double_if_positive
        ... )
        >>> a_r_tpl_1 = double_successes(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = double_successes(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (2, 4))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_successes_to_awaitable_result(callable_, *args, **kwargs),
    )

def map_successes_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1 | _F2, _S2]]:
    """Create function that maps [trcks.Success][] values
    to [trcks.AwaitableResultTuple][] values.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Asynchronous function to apply to each success element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps [trcks.Success][] values to new [trcks.AwaitableResultTuple][]
            values according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result_tuple as rt
        >>> async def slowly_expand(n: int) -> AwaitableResultTuple[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", (n, -n)
        ...     return "failure", "negative"
        ...
        >>> expand_successes = rt.map_successes_to_awaitable_result_iterable(
        ...     slowly_expand
        ... )
        >>> a_r_tpl_1 = expand_successes(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = expand_successes(("success", (1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (1, -1, 2, -2))
    """
    return compose(
        art.construct_from_result_iterable,
        art.map_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )

@deprecated("Use map_successes_to_awaitable_result_iterable instead")
def map_successes_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResultTuple[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1 | _F2, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_successes_to_awaitable_result_iterable][].
    """
    return map_successes_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_successes_to_awaitable_iterable instead")
def map_successes_to_awaitable_tuple(
    callable_: Callable[Concatenate[_S1, _P], AwaitableTuple[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], AwaitableResultTuple[_F1, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_successes_to_awaitable_iterable][].
    """
    return map_successes_to_awaitable_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

def map_successes_to_iterable(
    callable_: Callable[Concatenate[_S1, _P], Iterable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1, _S2]]:
    """Create function that maps each element of a [trcks.SuccessTuple][]
    to a [collections.abc.Iterable][].

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Function to apply to each element of the [trcks.SuccessTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            flat-maps each element of a [trcks.SuccessTuple][] to a
            [collections.abc.Iterable][] according to the given function.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _duplicate_integer(n: int) -> tuple[int, int]:
        ...     return n, n
        ...
        >>> duplicate_integers: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_successes_to_iterable(_duplicate_integer)
        >>> duplicate_integers(("success", (1, 2)))
        ('success', (1, 1, 2, 2))
        >>> duplicate_integers(("failure", "not found"))
        ('failure', 'not found')
    """
    return r.map_success(t.map_to_iterable(callable_, *args, **kwargs))

def map_successes_to_result(
    callable_: Callable[Concatenate[_S1, _P], Result[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1 | _F2, _S2]]:
    """Create function that maps each element of a [trcks.SuccessTuple][]
    to [trcks.Failure][] and [trcks.Success][] values.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Function to apply to each element of the [trcks.SuccessTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps each element of a [trcks.SuccessTuple][] to
            [trcks.Failure][] and [trcks.Success][] values according to the given
            function, returning the first [trcks.Failure][] encountered, if any.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import Result, ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _double_if_positive(n: int) -> Result[str, int]:
        ...     if n > 0:
        ...         return "success", n * 2
        ...     return "failure", "not positive"
        ...
        >>> double_if_positive: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_successes_to_result(_double_if_positive)
        >>> double_if_positive(("success", (1, 2)))
        ('success', (2, 4))
        >>> double_if_positive(("success", (1, -1, 2)))
        ('failure', 'not positive')
        >>> double_if_positive(("failure", "oops"))
        ('failure', 'oops')
    """
    return map_successes_to_result_iterable(
        compose(callable_, construct_from_result), *args, **kwargs
    )

def map_successes_to_result_iterable(
    callable_: Callable[Concatenate[_S1, _P], ResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1 | _F2, _S2]]:
    """Create function that maps each element of a [trcks.SuccessTuple][]
    to new [trcks.ResultTuple][] values.

    [trcks.Failure][] values are left unchanged.

    Args:
        callable_: Function to apply to each element of the [trcks.SuccessTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Leaves [trcks.Failure][] values unchanged and
            maps each element of a [trcks.SuccessTuple][] to new
            [trcks.ResultTuple][] values according to the given function,
            returning the first [trcks.Failure][] returned by `callable_`, if any.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result_tuple as rt
        >>> def _duplicate_if_positive(n: int) -> ResultTuple[str, int]:
        ...     if n > 0:
        ...         return "success", (n, n)
        ...     return "failure", "not positive"
        ...
        >>> duplicate_if_positive: Callable[
        ...     [ResultTuple[str, int]], ResultTuple[str, int]
        ... ] = rt.map_successes_to_result_iterable(_duplicate_if_positive)
        >>> duplicate_if_positive(("success", (1, 2)))
        ('success', (1, 1, 2, 2))
        >>> duplicate_if_positive(("success", (1, -1, 2)))
        ('failure', 'not positive')
        >>> duplicate_if_positive(("failure", "oops"))
        ('failure', 'oops')
    """

    def partially_mapped_callable(s1s: tuple[_S1, ...]) -> ResultTuple[_F2, _S2]:
        s2s = list[_S2]()
        for s1 in s1s:
            match callable_(s1, *args, **kwargs):
                case ("failure", _) as r_it:
                    return r_it
                case ("success", additional_s2s):
                    s2s.extend(additional_s2s)
                case _ as r_it:  # pragma: no cover
                    assert_type(r_it, Never)  # type: ignore[unreachable]  # pyright: ignore[reportUnreachable]
                    msg = f"{type(r_it).__name__!r} is not a valid ResultIterable"
                    raise TypeError(msg)
        return "success", tuple(s2s)

    def mapped_callable(r_tpl: ResultTuple[_F1, _S1]) -> ResultTuple[_F1 | _F2, _S2]:
        match r_tpl:
            case ("failure", _):
                return r_tpl
            case ("success", s1s):
                return partially_mapped_callable(s1s)
            case _:  # pragma: no cover
                assert_type(r_tpl, Never)  # type: ignore[unreachable]  # pyright: ignore[reportUnreachable]
                msg = f"{type(r_tpl).__name__!r} is not a valid ResultTuple"
                raise TypeError(msg)

    return mapped_callable

@deprecated("Use map_successes_to_result_iterable instead")
def map_successes_to_result_tuple(
    callable_: Callable[Concatenate[_S1, _P], ResultTuple[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1 | _F2, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_successes_to_result_iterable][].
    """
    return map_successes_to_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_successes_to_iterable instead")
def map_successes_to_tuple(
    callable_: Callable[Concatenate[_S1, _P], tuple[_S2, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result_tuple.map_successes_to_iterable][].
    """
    return map_successes_to_iterable(callable_, *args, **kwargs)  # pragma: no cover