trcks.fp.monads.awaitable_result

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

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

    Returns:
        A new [trcks.AwaitableFailure][] instance containing the given value.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> a_rslt = ar.construct_failure("not found")
        >>> isinstance(a_rslt, Awaitable)
        True
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('failure', 'not found')
    """
    return a.construct(r.construct_failure(value))

def construct_failure_from_awaitable(awtbl: Awaitable[_F], /) -> AwaitableFailure[_F]:
    """Create a [trcks.AwaitableFailure][] object
    from a [collections.abc.Awaitable][] object.

    Args:
        awtbl: [collections.abc.Awaitable][] object to be wrapped
            in a [trcks.AwaitableFailure][] object.

    Returns:
        A new [trcks.AwaitableFailure][] instance containing
            the value of the given [collections.abc.Awaitable][] object.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from http import HTTPStatus
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def get_status() -> HTTPStatus:
        ...     await asyncio.sleep(0.001)
        ...     return HTTPStatus.NOT_FOUND
        ...
        >>> awaitable_status = get_status()
        >>> isinstance(awaitable_status, Awaitable)
        True
        >>> a_rslt = ar.construct_failure_from_awaitable(awaitable_status)
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('failure', <HTTPStatus.NOT_FOUND: 404>)
    """
    return a.map_(r.construct_failure)(awtbl)

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

    Args:
        rslt: [trcks.Result][] object to be wrapped
            in a [trcks.AwaitableResult][] object.

    Returns:
        A new [trcks.AwaitableResult][] instance containing
            the value of the given [trcks.Result][] object.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> a_rslt = ar.construct_from_result(("failure", "not found"))
        >>> isinstance(a_rslt, Awaitable)
        True
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('failure', 'not found')
    """
    return a.construct(rslt)

def construct_success(value: _S, /) -> AwaitableSuccess[_S]:
    """Create a [trcks.AwaitableSuccess][] object from a value.

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

    Returns:
        A new [trcks.AwaitableSuccess][] instance containing the given value.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> a_rslt = ar.construct_success(42)
        >>> isinstance(a_rslt, Awaitable)
        True
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('success', 42)
    """
    return a.construct(r.construct_success(value))

def construct_success_from_awaitable(awtbl: Awaitable[_S], /) -> AwaitableSuccess[_S]:
    """Create a [trcks.AwaitableSuccess][] object
    from a [collections.abc.Awaitable][] object.

    Args:
        awtbl: [collections.abc.Awaitable][] object to be wrapped
            in a [trcks.AwaitableSuccess][] object.

    Returns:
        A new [trcks.AwaitableSuccess][] instance containing
            the value of the given [collections.abc.Awaitable][] object.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def read_from_disk() -> str:
        ...     await asyncio.sleep(0.001)
        ...     return "Hello, world!"
        ...
        >>> awaitable_str = read_from_disk()
        >>> isinstance(awaitable_str, Awaitable)
        True
        >>> a_rslt = ar.construct_success_from_awaitable(awaitable_str)
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('success', 'Hello, world!')
    """
    return a.map_(r.construct_success)(awtbl)

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

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

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResult
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> add_prefix_to_failure = ar.map_failure(lambda s: f"Prefix: {s}")
        >>> a_rslt_1: AwaitableResult[str, float] = add_prefix_to_failure(
        ...     ar.construct_failure("negative value")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'Prefix: negative value')
        >>> a_rslt_2: AwaitableResult[str, float] = add_prefix_to_failure(
        ...     ar.construct_success(25.0)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 25.0)
    """
    return a.map_(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[[AwaitableResult[_F1, _S1]], AwaitableResult[_F2, _S1]]:
    """Create function that maps [trcks.AwaitableFailure][]
    to [trcks.AwaitableFailure][] values.

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

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResult
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def slowly_add_prefix(s: str) -> str:
        ...     await asyncio.sleep(0.001)
        ...     return f"Prefix: {s}"
        ...
        >>> slowly_add_prefix_to_failure = ar.map_failure_to_awaitable(
        ...     slowly_add_prefix
        ... )
        >>> a_rslt_1: AwaitableResult[str, float] = slowly_add_prefix_to_failure(
        ...     ar.construct_failure("negative value")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'Prefix: negative value')
        >>> a_rslt_2: AwaitableResult[str, float] = slowly_add_prefix_to_failure(
        ...     ar.construct_success(25.0)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 25.0)
    """
    return map_failure_to_awaitable_result(
        compose(callable_, construct_failure_from_awaitable), *args, **kwargs
    )

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

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

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def _slowly_replace_not_found(s: str) -> Result[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if s == "not found":
        ...         return "success", 0.0
        ...     return "failure", s
        ...
        >>> slowly_replace_not_found = ar.map_failure_to_awaitable_result(
        ...     _slowly_replace_not_found
        ... )
        >>>
        >>> a_rslt_1 = slowly_replace_not_found(ar.construct_failure("not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('success', 0.0)
        >>> a_rslt_2 = slowly_replace_not_found(ar.construct_failure("other failure"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('failure', 'other failure')
        >>> a_rslt_3 = slowly_replace_not_found(ar.construct_success(25.0))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_3))
        ('success', 25.0)
    """

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

    return a.map_to_awaitable(partially_mapped_callable)

def map_failure_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_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 as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> async def recover(e: str) -> AwaitableResultTuple[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if e == "not found":
        ...         return "success", (0.0, 1.0)
        ...     return "failure", e
        ...
        >>> recover_from_failure = ar.map_failure_to_awaitable_result_iterable(
        ...     recover
        ... )
        >>> a_r_tpl_1 = recover_from_failure(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0.0, 1.0))
        >>> a_r_tpl_2 = recover_from_failure(ar.construct_success(25.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (25.0,))
    """
    return compose(
        art.construct_from_awaitable_result,
        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[[AwaitableResult[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_result.map_failure_to_awaitable_result_iterable][].
    """
    return map_failure_to_awaitable_result_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[
    [AwaitableResult[_F1, _S1]],
    Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
]:
    """Create function that maps [trcks.Failure][] values to homogeneous [tuple][]s.

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

    Args:
        callable_: Synchronous function to apply to the [trcks.Failure][] values,
            returning an [collections.abc.Iterable][].
        *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 [trcks.AwaitableSuccessTuple][] values
            according to the given function and
            leaves [trcks.Success][] values unchanged (wrapped as a tuple).

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def recover(e: str) -> tuple[float, ...]:
        ...     if e == "not found":
        ...         return (0.0, 1.0)
        ...     return ()
        ...
        >>> recover_from_failure = ar.map_failure_to_iterable(recover)
        >>> a_r_tpl_1 = recover_from_failure(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0.0, 1.0))
        >>> a_r_tpl_2 = recover_from_failure(ar.construct_success(25.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (25.0,))
    """
    c: tuple[
        Callable[[AwaitableResult[_F1, _S1]], AwaitableResultTuple[_F1, _S1]],
        Callable[
            [AwaitableResultTuple[_F1, _S1]],
            Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
        ],
    ] = (
        art.construct_from_awaitable_result,
        art.map_failure_to_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

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

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

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResult
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> replace_not_found_by_default_value = ar.map_failure_to_result(
        ...     lambda s: ("success", 0.0) if s == "not found" else ("failure", s)
        ... )
        >>> a_rslt_1: AwaitableResult[str, float] = replace_not_found_by_default_value(
        ...     ar.construct_failure("not found")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('success', 0.0)
        >>> a_rslt_2: AwaitableResult[str, float] = replace_not_found_by_default_value(
        ...     ar.construct_failure("other failure")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('failure', 'other failure')
        >>> a_rslt_3: AwaitableResult[str, float] = replace_not_found_by_default_value(
        ...     ar.construct_success(25.0)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_3))
        ('success', 25.0)
    """
    return a.map_(r.map_failure_to_result(callable_, *args, **kwargs))

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

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

    Args:
        callable_: Synchronous 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.Success][] values unchanged (wrapped as a tuple).

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def recover(e: str) -> ResultTuple[str, float]:
        ...     if e == "not found":
        ...         return "success", (0.0, 1.0)
        ...     return "failure", e
        ...
        >>> recover_from_failure = ar.map_failure_to_result_iterable(recover)
        >>> a_r_tpl_1 = recover_from_failure(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (0.0, 1.0))
        >>> a_r_tpl_2 = recover_from_failure(ar.construct_success(25.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (25.0,))
    """
    return compose(
        art.construct_from_awaitable_result,
        art.map_failure_to_result_iterable(callable_, *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[[AwaitableResult[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_result.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[
    [AwaitableResult[_F1, _S1]],
    Awaitable[SuccessTuple[_S1] | SuccessTuple[_S2]],
]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_result.map_failure_to_iterable][].
    """
    return map_failure_to_iterable(callable_, *args, **kwargs)  # pragma: no cover

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

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

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResult
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> def increase(n: int) -> int:
        ...     return n + 1
        ...
        >>> increase_success = ar.map_success(increase)
        >>> a_rslt_1: AwaitableResult[str, int] = increase_success(
        ...     ar.construct_failure("not found")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>> a_rslt_2: AwaitableResult[str, int] = increase_success(
        ...     ar.construct_success(42)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 43)
    """
    return a.map_(r.map_success(callable_, *args, **kwargs))

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

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

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

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

    Examples:
        >>> import asyncio
        >>>
        >>> from trcks import AwaitableResult
        >>> from trcks.fp.monads import awaitable_result as ar
        >>>
        >>>
        >>> async def increment_slowly(n: int) -> int:
        ...     return n + 1
        ...
        >>> increase_success = ar.map_success_to_awaitable(increment_slowly)
        >>>
        >>> a_rslt_1: AwaitableResult[str, int] = increase_success(
        ...     ar.construct_failure("not found")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>>
        >>> a_rslt_2: AwaitableResult[str, int] = increase_success(
        ...     ar.construct_success(42)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 43)
    """
    return map_success_to_awaitable_result(
        compose(callable_, construct_success_from_awaitable), *args, **kwargs
    )

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

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

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

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

    Examples:
        >>> import asyncio
        >>> import math
        >>> from trcks import AwaitableResult, Result
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def _get_square_root_slowly(x: float) -> Result[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", math.sqrt(x)
        ...
        >>> get_square_root_slowly = ar.map_success_to_awaitable_result(
        ...     _get_square_root_slowly
        ... )
        >>> a_rslt_1: AwaitableResult[str, float] = get_square_root_slowly(
        ...     ar.construct_failure("not found")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>> a_rslt_2: AwaitableResult[str, float] = get_square_root_slowly(
        ...     ar.construct_success(25.0)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 5.0)
    """

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

    return a.map_to_awaitable(partially_mapped_callable)

def map_success_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_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 the [trcks.Success][] values.
        *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 as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> async def slowly_expand(x: float) -> AwaitableResultTuple[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if x < 0:
        ...         return "failure", "negative"
        ...     return "success", (x, x * 2)
        ...
        >>> expand_success = ar.map_success_to_awaitable_result_iterable(
        ...     slowly_expand
        ... )
        >>> a_r_tpl_1 = expand_success(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = expand_success(ar.construct_success(5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (5.0, 10.0))
    """
    return compose(
        art.construct_from_awaitable_result,
        art.map_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )

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

def map_success_to_iterable(
    callable_: Callable[Concatenate[_S1, _P], Iterable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_F1, _S1]], AwaitableResultTuple[_F1, _S2]]:
    """Create function that maps [trcks.Success][] values to homogeneous [tuple][]s.

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

    Args:
        callable_: Synchronous function to apply to the [trcks.Success][] values,
            returning an [collections.abc.Iterable][].
        *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 homogeneous [tuple][]s
            according to the given function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def duplicate(x: float) -> tuple[float, ...]:
        ...     return (x, x)
        ...
        >>> duplicate_success = ar.map_success_to_iterable(duplicate)
        >>> a_r_tpl_1 = duplicate_success(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = duplicate_success(ar.construct_success(5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (5.0, 5.0))
    """
    return compose(
        art.construct_from_awaitable_result,
        art.map_successes_to_iterable(callable_, *args, **kwargs),
    )

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

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

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

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

    Examples:
        >>> import asyncio
        >>> import math
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> def _get_square_root_slowly(x: float) -> Result[str, float]:
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", math.sqrt(x)
        ...
        >>> get_square_root_slowly = ar.map_success_to_result(
        ...     _get_square_root_slowly
        ... )
        >>> a_rslt_1 = get_square_root_slowly(
        ...     ar.construct_failure("not found")
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>> a_rslt_2 = get_square_root_slowly(
        ...     ar.construct_success(25.0)
        ... )
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 5.0)
    """
    return a.map_(r.map_success_to_result(callable_, *args, **kwargs))

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

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

    Args:
        callable_: Synchronous function to apply to the [trcks.Success][] values.
        *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.ResultTuple][] values
            according to the given function.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def expand(x: float) -> ResultTuple[str, float]:
        ...     if x < 0:
        ...         return "failure", "negative"
        ...     return "success", (x, x * 2)
        ...
        >>> expand_success = ar.map_success_to_result_iterable(expand)
        >>> a_r_tpl_1 = expand_success(ar.construct_failure("not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = expand_success(ar.construct_success(5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (5.0, 10.0))
    """
    return compose(
        art.construct_from_awaitable_result,
        art.map_successes_to_result_iterable(callable_, *args, **kwargs),
    )

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

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

def tap_failure(
    callable_: Callable[Concatenate[_F1, _P], object],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_F1, _S1]], AwaitableResult[_F1, _S1]]:
    """Create function that applies a synchronous side effect
    to [trcks.AwaitableFailure][] values.

    [trcks.AwaitableSuccess][] values are passed on without side effects.

    Args:
        callable_: Synchronous side effect to apply
            to the [trcks.AwaitableFailure][] value.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to [trcks.AwaitableFailure][] values and
            returns the original [trcks.AwaitableFailure][] value.
            Passes on [trcks.AwaitableSuccess][] values without side effects.
    """
    return a.map_(r.tap_failure(callable_, *args, **kwargs))

def tap_failure_to_awaitable(
    callable_: Callable[Concatenate[_F1, _P], Awaitable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_F1, _S1]], AwaitableResult[_F1, _S1]]:
    """Create function that applies an asynchronous side effect
    to [trcks.AwaitableFailure][] values.

    [trcks.AwaitableSuccess][] values are passed on without side effects.

    Args:
        callable_: Asynchronous side effect to apply
            to the [trcks.AwaitableFailure][] value.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to [trcks.AwaitableFailure][] values and
            returns the original [trcks.AwaitableFailure][] value.
            Passes on [trcks.AwaitableSuccess][] values without side effects.
    """

    async def bypassed_callable(value: _F1) -> _F1:
        _ = await callable_(value, *args, **kwargs)
        return value

    return map_failure_to_awaitable(bypassed_callable)

def tap_failure_to_awaitable_result(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResult[object, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableResult[_F1, _S1]], AwaitableResult[_F1, _S1 | _S2]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResult][] to [trcks.AwaitableFailure][] values.

    [trcks.AwaitableSuccess][] values are passed on without side effects.

    Args:
        callable_: Asynchronous side effect to apply
            to the [trcks.AwaitableFailure][] value.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to [trcks.AwaitableFailure][] values.
            If the given side effect returns a [trcks.AwaitableFailure][],
            *the original* [trcks.AwaitableFailure][] value is returned.
            If the given side effect returns a [trcks.AwaitableSuccess][],
            *this* [trcks.AwaitableSuccess][] is returned.
            Passes on [trcks.AwaitableSuccess][] values without side effects.
    """

    async def bypassed_callable(value: _F1) -> Result[_F1, _S2]:
        match await callable_(value, *args, **kwargs):
            case ("failure", _):
                return r.construct_failure(value)
            case ("success", _) as rslt:
                return rslt
            case _ as rslt:  # pragma: no cover
                assert_type(rslt, Never)  # type: ignore[unreachable]  # pyright: ignore[reportUnreachable]
                msg = f"{type(rslt).__name__!r} is not a valid Result"
                raise TypeError(msg)

    return map_failure_to_awaitable_result(bypassed_callable)