trcks.fp.monads.awaitable_tuple

def construct(value: _T, /) -> AwaitableTuple[_T]:
    """Create a [trcks.AwaitableTuple][] from a value.

    Args:
        value: The value to create the [trcks.AwaitableTuple][] from.

    Returns:
        The [trcks.AwaitableTuple][] created from the value.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> a_tpl: AwaitableTuple[int] = at.construct(42)
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (42,)
    """
    return a.construct(t.construct(value))

def construct_from_awaitable(awtbl: Awaitable[_T], /) -> AwaitableTuple[_T]:
    """Create a [trcks.AwaitableTuple][] from an awaitable value.

    Args:
        awtbl: The awaitable value to create the [trcks.AwaitableTuple][] from.

    Returns:
        The [trcks.AwaitableTuple][] created from the awaitable value.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> awtbl: Awaitable[int] = a.construct(7)
        >>> a_tpl: AwaitableTuple[int] = at.construct_from_awaitable(awtbl)
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (7,)
    """
    return a.map_(t.construct)(awtbl)

def construct_from_awaitable_iterable(
    a_it: AwaitableIterable[_T],
    /,
) -> AwaitableTuple[_T]:
    """Create a [trcks.AwaitableTuple][] from a [trcks.AwaitableIterable][].

    Args:
        a_it: The [trcks.AwaitableIterable][] to create
            the [trcks.AwaitableTuple][] from.

    Returns:
        The [trcks.AwaitableTuple][] created from the [trcks.AwaitableIterable][].

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableIterable, AwaitableTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> a_it: AwaitableIterable[int] = a.construct([1, 2])
        >>> a_tpl: AwaitableTuple[int] = at.construct_from_awaitable_iterable(a_it)
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 2)
    """
    return a.map_(tuple)(a_it)

@deprecated("Use construct_from_awaitable_iterable instead")
def construct_from_awaitable_tuple(
    a_tpl: AwaitableTuple[_T],
    /,
) -> AwaitableTuple[_T]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.construct_from_awaitable_iterable][].
    """
    return construct_from_awaitable_iterable(a_tpl)  # pragma: no cover

def construct_from_iterable(it: Iterable[_T], /) -> AwaitableTuple[_T]:
    """Create a [trcks.AwaitableTuple][] from an iterable.

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

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

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> a_tpl: AwaitableTuple[int] = at.construct_from_iterable((1, 2))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 2)
    """
    return a.construct(tuple(it))

@deprecated("Use construct_from_iterable instead")
def construct_from_tuple(tpl: tuple[_T, ...], /) -> AwaitableTuple[_T]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.construct_from_iterable][].
    """
    return construct_from_iterable(tpl)  # pragma: no cover

def map_(
    callable_: Callable[Concatenate[_T1, _P], _T2],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Turn synchronous function into a function
    expecting and returning [trcks.AwaitableTuple][]s
    of the same length.

    Args:
        callable_:
            The synchronous function to be transformed into
            a function expecting and returning
            [trcks.AwaitableTuple][]s of the same length.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning
            [trcks.AwaitableTuple][]s of the same length.

    Note:
        The underscore in the function name helps to avoid collisions
        with the built-in function [map][].

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def double_integer(n: int) -> int:
        ...     return n * 2
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2, 3)),
        ...     at.map_(double_integer),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (2, 4, 6)
    """
    return a.map_(t.map_(callable_, *args, **kwargs))

def map_to_awaitable(
    callable_: Callable[Concatenate[_T1, _P], Awaitable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Turn [collections.abc.Awaitable][]-returning function into a function
    expecting and returning [trcks.AwaitableTuple][]s
    of the same length.

    Args:
        callable_:
            The [collections.abc.Awaitable][]-returning function to be transformed
            into a function expecting and returning
            [trcks.AwaitableTuple][]s of the same length.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning
            [trcks.AwaitableTuple][]s of the same length.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_add_one(n: int) -> int:
        ...     await asyncio.sleep(0.001)
        ...     return n + 1
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2)),
        ...     at.map_to_awaitable(slowly_add_one),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (2, 3)
    """
    return map_to_awaitable_iterable(
        compose(callable_, construct_from_awaitable), *args, **kwargs
    )

def map_to_awaitable_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableIterable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Turn [trcks.AwaitableIterable][]-returning function into a function
    expecting and returning [trcks.AwaitableTuple][]s
    of varying length.

    Args:
        callable_:
            The [trcks.AwaitableIterable][]-returning function to be transformed
            into a function expecting and returning
            [trcks.AwaitableTuple][]s of varying length.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning
            [trcks.AwaitableTuple][]s of varying length.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_duplicate_integer(n: int) -> tuple[int, int]:
        ...     await asyncio.sleep(0.001)
        ...     return n, n
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2)),
        ...     at.map_to_awaitable_iterable(slowly_duplicate_integer),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 1, 2, 2)
    """

    async def mapped_callable(a_t1s: AwaitableTuple[_T1]) -> tuple[_T2, ...]:
        # `tuple` does not support asynchronous generators.
        # Therefore, we need to use a list comprehension and then convert it to a tuple:
        t2s = [t2 for t1 in await a_t1s for t2 in await callable_(t1, *args, **kwargs)]
        return tuple(t2s)

    return mapped_callable

def map_to_awaitable_result(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResult[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a [trcks.AwaitableTuple][]
    to a [trcks.AwaitableResult][] value.

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

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] if the function returns [trcks.Success][]
                for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> 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_if_positive = (
        ...     at.map_to_awaitable_result(slowly_double_if_positive)
        ... )
        >>> a_r_tpl_1 = double_if_positive(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (2, 4))
        >>> a_r_tpl_2 = double_if_positive(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.map_successes_to_awaitable_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def map_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultIterable[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a [trcks.AwaitableTuple][]
    to a [trcks.AwaitableResultIterable][] and flattens the result.

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

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a flattened [trcks.SuccessTuple][] if the function returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_expand_if_positive(n: int) -> ResultTuple[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", (n, -n)
        ...     return "failure", "negative"
        ...
        >>> expand_if_positive = (
        ...     at.map_to_awaitable_result_iterable(slowly_expand_if_positive)
        ... )
        >>> a_r_tpl_1 = expand_if_positive(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, -1, 2, -2))
        >>> a_r_tpl_2 = expand_if_positive(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.map_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use map_to_awaitable_result_iterable instead")
def map_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultTuple[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.map_to_awaitable_result_iterable][].
    """
    return map_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_to_awaitable_iterable instead")
def map_to_awaitable_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableTuple[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.map_to_awaitable_iterable][].
    """
    return map_to_awaitable_iterable(callable_, *args, **kwargs)  # pragma: no cover

def map_to_iterable(
    callable_: Callable[Concatenate[_T1, _P], Iterable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Turn [collections.abc.Iterable][]-returning function into a function
    expecting and returning [trcks.AwaitableTuple][]s
    of varying length.

    Args:
        callable_:
            The [collections.abc.Iterable][]-returning function to be transformed
            into a function expecting and returning
            [trcks.AwaitableTuple][]s of varying length.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning
            [trcks.AwaitableTuple][]s of varying length.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def add_negative(n: int) -> tuple[int, int]:
        ...     return n, -n
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2)),
        ...     at.map_to_iterable(add_negative),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, -1, 2, -2)
    """
    return a.map_(t.map_to_iterable(callable_, *args, **kwargs))

def map_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a [trcks.AwaitableTuple][]
    to a [trcks.Result][] value.

    Args:
        callable_: Synchronous function to apply to each element,
            returning a [trcks.Result][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] with all transformed elements if the
                function returns [trcks.Success][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def double_if_positive(n: int) -> Result[str, int]:
        ...     if n > 0:
        ...         return "success", n * 2
        ...     return "failure", "negative"
        ...
        >>> double_result = at.map_to_result(double_if_positive)
        >>> a_r_tpl_1 = double_result(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (2, 4))
        >>> a_r_tpl_2 = double_result(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.map_successes_to_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def map_to_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], ResultIterable[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a [trcks.AwaitableTuple][]
    to a [trcks.ResultIterable][] and flattens the result.

    Args:
        callable_: Synchronous function to apply to each element,
            returning a [trcks.ResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a flattened [trcks.SuccessTuple][] if the function returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def expand_if_positive(n: int) -> ResultTuple[str, int]:
        ...     if n > 0:
        ...         return "success", (n, -n)
        ...     return "failure", "negative"
        ...
        >>> expand_result = at.map_to_result_iterable(expand_if_positive)
        >>> a_r_tpl_1 = expand_result(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, -1, 2, -2))
        >>> a_r_tpl_2 = expand_result(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.map_successes_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use map_to_result_iterable instead")
def map_to_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], ResultTuple[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _S]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.map_to_result_iterable][].
    """
    return map_to_result_iterable(callable_, *args, **kwargs)  # pragma: no cover

@deprecated("Use map_to_iterable instead")
def map_to_tuple(
    callable_: Callable[Concatenate[_T1, _P], tuple[_T2, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T2]]:
    """Deprecated alias for [trcks.fp.monads.awaitable_tuple.map_to_iterable][]."""
    return map_to_iterable(callable_, *args, **kwargs)  # pragma: no cover

def tap(
    callable_: Callable[Concatenate[_T1, _P], object],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Turn synchronous function into a function
    expecting a [trcks.AwaitableTuple][] and
    returning the same [trcks.AwaitableTuple][].

    Args:
        callable_:
            The synchronous function to be transformed into a function
            expecting a [trcks.AwaitableTuple][] and
            returning the same [trcks.AwaitableTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [trcks.AwaitableTuple][] and
            returning the same [trcks.AwaitableTuple][].

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def log_integer(n: int) -> None:
        ...     print(f"Received: {n}")
        ...
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2)),
        ...     at.tap(log_integer),
        ... )
        >>> tpl = asyncio.run(at.to_coroutine_tuple(a_tpl))
        Received: 1
        Received: 2
        >>> tpl
        (1, 2)
    """
    return a.map_(t.tap(callable_, *args, **kwargs))

def tap_to_awaitable(
    callable_: Callable[Concatenate[_T1, _P], Awaitable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Turn [collections.abc.Awaitable][]-returning function into a function
    expecting a [trcks.AwaitableTuple][] and
    returning the same [trcks.AwaitableTuple][].

    Args:
        callable_:
            The [collections.abc.Awaitable][]-returning function to be transformed
            into a function expecting a [trcks.AwaitableTuple][] and
            returning the same [trcks.AwaitableTuple][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [trcks.AwaitableTuple][] and
            returning the same [trcks.AwaitableTuple][].

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_log_integer(n: int) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Received: {n}")
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2)),
        ...     at.tap_to_awaitable(slowly_log_integer),
        ... )
        >>> tpl = asyncio.run(at.to_coroutine_tuple(a_tpl))
        Received: 1
        Received: 2
        >>> tpl
        (1, 2)
    """

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

    return map_to_awaitable(bypassed_callable)

def tap_to_awaitable_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableIterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Turn a [trcks.AwaitableIterable][]-returning side effect into a function
    expecting a [trcks.AwaitableTuple][] and returning a [trcks.AwaitableTuple][]
    where each original element is repeated once per element returned by
    the side effect.

    Args:
        callable_:
            The [trcks.AwaitableIterable][]-returning function to be transformed
            into a function expecting a [trcks.AwaitableTuple][] and
            returning a [trcks.AwaitableTuple][] where each original element is
            repeated once per element returned by the side effect.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [trcks.AwaitableTuple][] and
            returning a [trcks.AwaitableTuple][] where each original element is
            repeated once per element returned by the side effect.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_get_divisors(n: int) -> tuple[int, ...]:
        ...     await asyncio.sleep(0.001)
        ...     candidates = range(1, n + 1)
        ...     return tuple(c for c in candidates if n % c == 0)
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2, 3, 4)),
        ...     at.tap_to_awaitable_iterable(slowly_get_divisors),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 2, 2, 3, 3, 4, 4, 4)
    """

    async def bypassed_callable(t1: _T1) -> tuple[_T1, ...]:
        objs = await callable_(t1, *args, **kwargs)
        return tuple(t1 for _ in objs)

    return map_to_awaitable_iterable(bypassed_callable)

def tap_to_awaitable_result(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResult[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResult][]
    to each element of a [trcks.AwaitableTuple][].

    Args:
        callable_: Asynchronous side effect to apply to each element,
            returning a [trcks.AwaitableResult][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* elements if the applied side effect returns
                [trcks.Success][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_check_if_positive(n: int) -> Result[str, None]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", None
        ...     return "failure", "negative"
        ...
        >>> check_if_positive = at.tap_to_awaitable_result(slowly_check_if_positive)
        >>> a_r_tpl_1 = check_if_positive(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 2))
        >>> a_r_tpl_2 = check_if_positive(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.tap_successes_to_awaitable_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def tap_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultIterable[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResultIterable][]
    to each element of a [trcks.AwaitableTuple][].

    Args:
        callable_: Asynchronous side effect to apply to each element,
            returning a [trcks.AwaitableResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* elements with each element repeated once
                per side effect output element if the applied side effect returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_audit(n: int) -> ResultTuple[str, None]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", (None, None)
        ...     return "failure", "negative"
        ...
        >>> audit_successes = at.tap_to_awaitable_result_iterable(slowly_audit)
        >>> a_r_tpl_1 = audit_successes(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 1, 2, 2))
        >>> a_r_tpl_2 = audit_successes(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.tap_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use tap_to_awaitable_result_iterable instead")
def tap_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultTuple[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.tap_to_awaitable_result_iterable][].
    """
    return tap_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use tap_to_awaitable_iterable instead")
def tap_to_awaitable_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableTuple[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.tap_to_awaitable_iterable][].
    """
    return tap_to_awaitable_iterable(callable_, *args, **kwargs)  # pragma: no cover

def tap_to_iterable(
    callable_: Callable[Concatenate[_T1, _P], Iterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Turn a [collections.abc.Iterable][]-returning side effect into a function
    expecting a [trcks.AwaitableTuple][] and returning a [trcks.AwaitableTuple][]
    where each original element is repeated once per element returned by
    the side effect.

    Args:
        callable_:
            The [collections.abc.Iterable][]-returning function to be transformed
            into a function expecting a [trcks.AwaitableTuple][] and
            returning a [trcks.AwaitableTuple][] where each original element is
            repeated once per element returned by the side effect.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [trcks.AwaitableTuple][] and
            returning a [trcks.AwaitableTuple][] where each original element is
            repeated once per element returned by the side effect.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableTuple
        >>> from trcks.fp.composition import pipe
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def get_divisors(n: int) -> tuple[int, ...]:
        ...     candidates = range(1, n + 1)
        ...     return tuple(c for c in candidates if n % c == 0)
        >>> a_tpl: AwaitableTuple[int] = pipe(
        ...     at.construct_from_iterable((1, 2, 3, 4)),
        ...     at.tap_to_iterable(get_divisors),
        ... )
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 2, 2, 3, 3, 4, 4, 4)
    """
    return a.map_(t.tap_to_iterable(callable_, *args, **kwargs))

def tap_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.Result][]
    to each element of a [trcks.AwaitableTuple][].

    Args:
        callable_: Synchronous side effect to apply to each element,
            returning a [trcks.Result][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* elements if the applied side effect returns
                [trcks.Success][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def check_if_positive(n: int) -> Result[str, None]:
        ...     if n > 0:
        ...         return "success", None
        ...     return "failure", "negative"
        ...
        >>> check_if_positive_sync = at.tap_to_result(check_if_positive)
        >>> a_r_tpl_1 = check_if_positive_sync(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 2))
        >>> a_r_tpl_2 = check_if_positive_sync(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.tap_successes_to_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def tap_to_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], ResultIterable[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.ResultIterable][]
    to each element of a [trcks.AwaitableTuple][].

    Args:
        callable_: Synchronous side effect to apply to each element,
            returning a [trcks.ResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [trcks.AwaitableTuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* elements with each element repeated once
                per side effect output element if the applied side effect returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def audit(n: int) -> ResultTuple[str, None]:
        ...     if n > 0:
        ...         return "success", (None, None)
        ...     return "failure", "negative"
        ...
        >>> audit_successes_sync = at.tap_to_result_iterable(audit)
        >>> a_r_tpl_1 = audit_successes_sync(at.construct_from_iterable((1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 1, 2, 2))
        >>> a_r_tpl_2 = audit_successes_sync(at.construct_from_iterable((1, -1, 2)))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [AwaitableTuple[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable_iterable,
        art.tap_successes_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use tap_to_result_iterable instead")
def tap_to_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], ResultTuple[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable_tuple.tap_to_result_iterable][].
    """
    return tap_to_result_iterable(callable_, *args, **kwargs)  # pragma: no cover

@deprecated("Use tap_to_iterable instead")
def tap_to_tuple(
    callable_: Callable[Concatenate[_T1, _P], tuple[object, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[AwaitableTuple[_T1]], AwaitableTuple[_T1]]:
    """Deprecated alias for [trcks.fp.monads.awaitable_tuple.tap_to_iterable][]."""
    return tap_to_iterable(callable_, *args, **kwargs)  # pragma: no cover