trcks.fp.monads.result

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][] object.

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

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> r.construct_failure(42)
        ('failure', 42)
    """
    return "failure", value

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

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

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

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> r.construct_success(42)
        ('success', 42)
    """
    return "success", value

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

    [trcks.Success][] 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.Success][] values unchanged.

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> add_prefix_to_failure = r.map_failure(lambda s: f"Prefix: {s}")
        >>> add_prefix_to_failure(("failure", "negative value"))
        ('failure', 'Prefix: negative value')
        >>> add_prefix_to_failure(("success", 25.0))
        ('success', 25.0)
    """
    return map_failure_to_result(compose(callable_, construct_failure), *args, **kwargs)

def map_failure_to_awaitable(
    callable_: Callable[Concatenate[_F1, _P], Awaitable[_F2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], AwaitableResult[_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 as ar
        >>> from trcks.fp.monads import result as r
        >>> async def add_prefix_slowly(s: str) -> str:
        ...     await asyncio.sleep(0.001)
        ...     return f"Prefix: {s}"
        ...
        >>> add_prefix_to_failure = r.map_failure_to_awaitable(add_prefix_slowly)
        >>> a_rslt_1 = add_prefix_to_failure(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'Prefix: not found')
        >>> a_rslt_2 = add_prefix_to_failure(("success", 42))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 42)
    """
    return compose(
        ar.construct_from_result,
        ar.map_failure_to_awaitable(callable_, *args, **kwargs),
    )

def map_failure_to_awaitable_result(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResult[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], AwaitableResult[_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 as ar
        >>> from trcks.fp.monads import result as r
        >>> 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
        ...
        >>> replace_not_found = r.map_failure_to_awaitable_result(
        ...     slowly_replace_not_found
        ... )
        >>> a_rslt_1 = replace_not_found(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('success', 0.0)
        >>> a_rslt_2 = replace_not_found(("failure", "other failure"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('failure', 'other failure')
        >>> a_rslt_3 = replace_not_found(("success", 25.0))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_3))
        ('success', 25.0)
    """
    return compose(
        ar.construct_from_result,
        ar.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[[Result[_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 as r
        >>> 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_result = r.map_failure_to_awaitable_result_iterable(recover)
        >>> a_r_tpl_1 = recover_from_result(("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_result(("success", 25.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (25.0,))
    """
    return compose(
        art.construct_from_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[[Result[_F1, _S1]], AwaitableResultTuple[_F2, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.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[[Result[_F1, _S1]], SuccessTuple[_S1] | SuccessTuple[_S2]]:
    """Create function that maps [trcks.Failure][] values to homogeneous [tuple][]s.

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

    Args:
        callable_: 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 a [trcks.Success][] according to the given function and
            leaves [trcks.Success][] values (wrapped as a tuple) unchanged.

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> def recover(s: str) -> tuple[float, ...]:
        ...     if s == "not found":
        ...         return (0.0, 1.0)
        ...     return ()
        ...
        >>> recover_from_result = r.map_failure_to_iterable(recover)
        >>> recover_from_result(("failure", "not found"))
        ('success', (0.0, 1.0))
        >>> recover_from_result(("failure", "other error"))
        ('success', ())
        >>> recover_from_result(("success", 42))
        ('success', (42,))
    """
    c: tuple[
        Callable[[Result[_F1, _S1]], ResultTuple[_F1, _S1]],
        Callable[[ResultTuple[_F1, _S1]], SuccessTuple[_S1] | SuccessTuple[_S2]],
    ] = (
        rt.construct_from_result,
        rt.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[[Result[_F1, _S1]], Result[_F2, _S1 | _S2]]:
    """Create function that maps [trcks.Failure][] values
    to [trcks.Failure][] and [trcks.Success][] values.

    [trcks.Success][] 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 [trcks.Failure][] and [trcks.Success][] values
            according to the given function and
            leaves [trcks.Success][] values unchanged.

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> replace_not_found_failure_by_default_value = r.map_failure_to_result(
        ...     lambda s: ("success", 0.0) if s == "not found" else ("failure", s)
        ... )
        >>> replace_not_found_failure_by_default_value(("failure", "not found"))
        ('success', 0.0)
        >>> replace_not_found_failure_by_default_value(("failure", "other failure"))
        ('failure', 'other failure')
        >>> replace_not_found_failure_by_default_value(("success", 25.0))
        ('success', 25.0)
    """

    def mapped_callable(rslt: Result[_F1, _S1]) -> Result[_F2, _S1 | _S2]:
        match rslt:
            case ("failure", value):
                return 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 mapped_callable

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

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

    Examples:
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result as r
        >>> def expand_error(s: str) -> ResultTuple[str, float]:
        ...     if s == "not found":
        ...         return "success", (0.0, 1.0)
        ...     return "failure", s
        ...
        >>> expand_error_from_result = r.map_failure_to_result_iterable(expand_error)
        >>> expand_error_from_result(("failure", "not found"))
        ('success', (0.0, 1.0))
        >>> expand_error_from_result(("failure", "other error"))
        ('failure', 'other error')
        >>> expand_error_from_result(("success", 42))
        ('success', (42,))
    """
    c: tuple[
        Callable[[Result[_F1, _S1]], ResultTuple[_F1, _S1]],
        Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F2, _S1 | _S2]],
    ] = (
        rt.construct_from_result,
        rt.map_failure_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@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[[Result[_F1, _S1]], ResultTuple[_F2, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.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[[Result[_F1, _S1]], SuccessTuple[_S1] | SuccessTuple[_S2]]:
    """Deprecated alias for [trcks.fp.monads.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[[Result[_F1, _S1]], Result[_F1, _S2]]:
    """Create function that maps [trcks.Success][] values to [trcks.Success][] values.

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

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

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> def increase(n: int) -> int:
        ...     return n + 1
        ...
        >>> increase_success = r.map_success(increase)
        >>> increase_success(("failure", "not found"))
        ('failure', 'not found')
        >>> increase_success(("success", 42))
        ('success', 43)
    """
    return map_success_to_result(compose(callable_, construct_success), *args, **kwargs)

def map_success_to_awaitable(
    callable_: Callable[Concatenate[_S1, _P], Awaitable[_S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], AwaitableResult[_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 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.AwaitableSuccess][] values
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import result as r
        >>> async def increment_slowly(n: int) -> int:
        ...     await asyncio.sleep(0.001)
        ...     return n + 1
        ...
        >>> increase_success = r.map_success_to_awaitable(increment_slowly)
        >>> a_rslt_1 = increase_success(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>> a_rslt_2 = increase_success(("success", 42))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 43)
    """
    return compose(
        ar.construct_from_result,
        ar.map_success_to_awaitable(callable_, *args, **kwargs),
    )

def map_success_to_awaitable_result(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResult[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], AwaitableResult[_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 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 [trcks.AwaitableFailure][] and [trcks.AwaitableSuccess][] values
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> import math
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import result as r
        >>> 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 = r.map_success_to_awaitable_result(get_square_root_slowly)
        >>> a_rslt_1 = get_square_root(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not found')
        >>> a_rslt_2 = get_square_root(("success", -25.0))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('failure', 'negative value')
        >>> a_rslt_3 = get_square_root(("success", 25.0))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_3))
        ('success', 5.0)
    """
    return compose(
        ar.construct_from_result,
        ar.map_success_to_awaitable_result(callable_, *args, **kwargs),
    )

def map_success_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_S1, _P], AwaitableResultIterable[_F2, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_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_tuple as art
        >>> from trcks.fp.monads import result as r
        >>> 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 = r.map_success_to_awaitable_result_iterable(slowly_expand)
        >>> a_r_tpl_1 = expand_success(("failure", "not found"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('failure', 'not found')
        >>> a_r_tpl_2 = expand_success(("success", 5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (5.0, 10.0))
    """
    return compose(
        art.construct_from_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[[Result[_F1, _S1]], AwaitableResultTuple[_F1 | _F2, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.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[[Result[_F1, _S1]], ResultTuple[_F1, _S2]]:
    """Create function that maps [trcks.Success][] values to homogeneous [tuple][]s.

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

    Args:
        callable_: 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 (wrapped as a tuple) unchanged and
            maps [trcks.Success][] values to homogeneous [tuple][]s
            according to the given function.

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> def duplicate(x: float) -> tuple[float, ...]:
        ...     return (x, x)
        ...
        >>> duplicate_success = r.map_success_to_iterable(duplicate)
        >>> duplicate_success(("failure", "not found"))
        ('failure', 'not found')
        >>> duplicate_success(("success", 5.0))
        ('success', (5.0, 5.0))
    """
    c: tuple[
        Callable[[Result[_F1, _S1]], ResultTuple[_F1, _S1]],
        Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1, _S2]],
    ] = (
        rt.construct_from_result,
        rt.map_successes_to_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

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

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

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

    Examples:
        >>> import math
        >>> from trcks import Result
        >>> from trcks.fp.monads import result as r
        >>> def _get_square_root(x: float) -> Result[str, float]:
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", math.sqrt(x)
        ...
        >>> get_square_root = r.map_success_to_result(_get_square_root)
        >>> get_square_root(("failure", "not found"))
        ('failure', 'not found')
        >>> get_square_root(("success", -25.0))
        ('failure', 'negative value')
        >>> get_square_root(("success", 25.0))
        ('success', 5.0)
    """

    def mapped_callable(rslt: Result[_F1, _S1]) -> Result[_F1 | _F2, _S2]:
        match rslt:
            case ("failure", _):
                return rslt
            case ("success", value):
                return 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 mapped_callable

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

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

    Args:
        callable_: 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 (wrapped as a tuple) unchanged and
            maps [trcks.Success][] values to new [trcks.ResultTuple][] values
            according to the given function.

    Examples:
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import result as r
        >>> def expand(x: float) -> ResultTuple[str, float]:
        ...     if x < 0:
        ...         return "failure", "negative"
        ...     return "success", (x, x * 2)
        ...
        >>> expand_success = r.map_success_to_result_iterable(expand)
        >>> expand_success(("failure", "not found"))
        ('failure', 'not found')
        >>> expand_success(("success", 5.0))
        ('success', (5.0, 10.0))
        >>> expand_success(("success", -5.0))
        ('failure', 'negative')
    """
    c: tuple[
        Callable[[Result[_F1, _S1]], ResultTuple[_F1, _S1]],
        Callable[[ResultTuple[_F1, _S1]], ResultTuple[_F1 | _F2, _S2]],
    ] = (
        rt.construct_from_result,
        rt.map_successes_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@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[[Result[_F1, _S1]], ResultTuple[_F1 | _F2, _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.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[[Result[_F1, _S1]], ResultTuple[_F1, _S2]]:
    """Deprecated alias for [trcks.fp.monads.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[[Result[_F1, _S1]], Result[_F1, _S1]]:
    """Create function that applies a side effect to [trcks.Failure][] values.

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

    Args:
        callable_: Side effect to apply to the [trcks.Failure][] 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.Failure][] values and
            returns the original [trcks.Failure][] value.
            Passes on [trcks.Success][] values without side effects.
    """
    return map_failure(i.tap(callable_, *args, **kwargs))

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

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

    Args:
        callable_: Asynchronous side effect to apply to the [trcks.Failure][] 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.Failure][] values and
            returns the original [trcks.Failure][] value.
            Passes on [trcks.Success][] values without side effects.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import result as r
        >>> async def write_to_disk(output: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{output}' to disk.")
        ...
        >>> write_failure_to_disk = r.tap_failure_to_awaitable(write_to_disk)
        >>> a_rslt_1 = write_failure_to_disk(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        Wrote 'not found' to disk.
        ('failure', 'not found')
        >>> a_rslt_2 = write_failure_to_disk(("success", 42))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('success', 42)
    """
    return compose(
        ar.construct_from_result,
        ar.tap_failure_to_awaitable(callable_, *args, **kwargs),
    )

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

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

    Args:
        callable_: Asynchronous side effect to apply to the [trcks.Failure][] 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.Failure][] values.
            If the given side effect returns a [trcks.Failure][],
            *the original* [trcks.Failure][] is returned.
            If the given side effect returns a [trcks.Success][],
            *this* [trcks.Success][] is returned.
            Passes on [trcks.Success][] values without side effects.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> from trcks.fp.monads import result as r
        >>> async def replace_not_found_with_default(
        ...     s: str,
        ... ) -> Result[object, float]:
        ...     await asyncio.sleep(0.001)
        ...     if s == "not found":
        ...         return "success", 0.0
        ...     return "failure", s
        ...
        >>> recover_from_failure = r.tap_failure_to_awaitable_result(
        ...     replace_not_found_with_default
        ... )
        >>> a_rslt_1 = recover_from_failure(("failure", "not found"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('success', 0.0)
        >>> a_rslt_2 = recover_from_failure(("failure", "other error"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        ('failure', 'other error')
        >>> a_rslt_3 = recover_from_failure(("success", 42))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_3))
        ('success', 42)
    """
    return compose(
        ar.construct_from_result,
        ar.tap_failure_to_awaitable_result(callable_, *args, **kwargs),
    )

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

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

    Args:
        callable_: Asynchronous side effect to apply to the [trcks.Failure][] 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.Failure][] values.
            If the given side effect returns a [trcks.Failure][],
            *the original* [trcks.Failure][] is returned.
            If the given side effect returns a [trcks.SuccessIterable][],
            *this* [trcks.SuccessIterable][] is returned.
            Passes on [trcks.Success][] values (wrapped as a tuple)
            without side effects.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import result as r
        >>> async def recover(e: str) -> AwaitableResultTuple[object, float]:
        ...     await asyncio.sleep(0.001)
        ...     if e == "not found":
        ...         return "success", (0.0, 1.0)
        ...     return "failure", e
        ...
        >>> recover_from_failure = r.tap_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.0, 1.0))
        >>> a_r_tpl_2 = recover_from_failure(("success", 42))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('success', (42,))
    """
    return compose(
        art.construct_from_result,
        art.tap_failure_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )

@deprecated("Use tap_failure_to_awaitable_result_iterable instead")
def tap_failure_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_F1, _P], AwaitableResultTuple[object, _S2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], AwaitableResultTuple[_F1, _S1 | _S2]]:
    """Deprecated alias for
    [trcks.fp.monads.result.tap_failure_to_awaitable_result_iterable][].
    """
    return tap_failure_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

def tap_failure_to_iterable(
    callable_: Callable[Concatenate[_F1, _P], Iterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Result[_F1, _S1]], SuccessTuple[_F1] | SuccessTuple[_S1]]:
    """Create function that applies a [collections.abc.Iterable][]-returning
    side effect to [trcks.Failure][] values.

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

    Args:
        callable_: Side effect to apply to the [trcks.Failure][] value,
            returning an [collections.abc.Iterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to [trcks.Failure][] values and converts them
            to [trcks.SuccessTuple][] values containing the original failure
            repeated once per element in the [collections.abc.Iterable][] returned
            by the side effect.
            Passes on [trcks.Success][] values (wrapped as a tuple)
            without side effects.

    Examples:
        >>> from trcks.fp.monads import result as r
        >>> def log_err(e: str) -> tuple[None, ...]:
        ...     print(f"Error logged: {e}")
        ...     print(f"Alert sent: {e}")
        ...     return (None, None)
        ...
        >>> log_failure = r.tap_failure_to_iterable(log_err)
        >>> log_failure(("failure", "critical"))
        Error logged: critical
        Alert sent: critical
        ('success', ('critical', 'critical'))
        >>> log_failure(("success", 42))
        ('success', (42,))
    """
    c: tuple[
        Callable[[Result[_F1, _S1]], ResultTuple[_F1, _S1]],
        Callable[[ResultTuple[_F1, _S1]], SuccessTuple[_F1] | SuccessTuple[_S1]],
    ] = (
        rt.construct_from_result,
        rt.tap_failure_to_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)