Struct IO 

pub struct IO<A> { /* private fields */ }

A lazy, composable IO effect type.

IO<A> represents a computation that, when executed, performs side effects and produces a value of type A (or fails with an error).

Nothing executes until .run() is called — this gives referential transparency, deferred execution, and composable effect descriptions.

Design

• One type parameter: IO<A> keeps signatures clean. Errors are type-erased via anyhow::Error and surfaced at .run() boundaries. For typed errors, use IO<Result<A, E>> — opt-in, not mandatory.
• Send + 'static: Compatible with tokio and thread pools.
• FnOnce: Consumed exactly once.

Examples

use functype_io::IO;

let io = IO::succeed(42);
assert_eq!(io.run().unwrap(), 42);

let io = IO::effect(|| 1 + 2).map(|x| x * 10);
assert_eq!(io.run().unwrap(), 30);

Implementations

impl<A> IO<A>

where A: Send + 'static,

pub fn succeed(a: A) -> IO<A>

Creates an IO that succeeds with the given value.

pub fn fail(e: impl Into<Error> + Send + 'static) -> IO<A>

Creates an IO that fails with the given error.

pub fn effect(f: impl FnOnce() -> A + Send + 'static) -> IO<A>

Creates an IO from an infallible side effect.

pub fn effect_result( f: impl FnOnce() -> Result<A, Error> + Send + 'static, ) -> IO<A>

Creates an IO from a fallible side effect (primary constructor).

pub fn from_result( result: Result<A, impl Into<Error> + Send + 'static>, ) -> IO<A>

Lifts a Result into an IO.

pub fn from_option( option: Option<A>, on_none: impl FnOnce() -> Error + Send + 'static, ) -> IO<A>

Lifts an Option into an IO, using the provided closure for the None case.

pub fn from_either( either: Either<impl Into<Error> + Send + 'static, A>, ) -> IO<A>

Lifts an Either into an IO. Left becomes the error, Right becomes the value.

impl<A> IO<A>

pub fn run(self) -> Result<A, Error>

Consumes and executes this IO, returning the result.

pub fn run_or_panic(self) -> A

where A: Debug,

Executes this IO, panicking on error.

impl<A> IO<A>

where A: Send + 'static,

pub fn map<B>(self, f: impl FnOnce(A) -> B + Send + 'static) -> IO<B>

where B: Send + 'static,

Transforms the success value.

pub fn flat_map<B>(self, f: impl FnOnce(A) -> IO<B> + Send + 'static) -> IO<B>

where B: Send + 'static,

Chains a computation that depends on the success value.

pub fn and_then<B>(self, f: impl FnOnce(A) -> IO<B> + Send + 'static) -> IO<B>

where B: Send + 'static,

Alias for flat_map (for fdo! macro compatibility).

pub fn zip<B>(self, other: IO<B>) -> IO<(A, B)>

where B: Send + 'static,

Combines two IOs into a tuple.

pub fn zip_with<B, C>( self, other: IO<B>, f: impl FnOnce(A, B) -> C + Send + 'static, ) -> IO<C>

where B: Send + 'static, C: Send + 'static,

Combines two IOs with a function.

pub fn then<B>(self, other: IO<B>) -> IO<B>

where B: Send + 'static,

Sequences two IOs, discarding the first result.

pub fn tap(self, f: impl FnOnce(&A) + Send + 'static) -> IO<A>

Runs a side effect on the success value, returning the original value.

impl<A> IO<A>

where A: Send + 'static,

pub fn map_error(self, f: impl FnOnce(Error) -> Error + Send + 'static) -> IO<A>

Transforms the error.

pub fn catch(self, f: impl FnOnce(Error) -> IO<A> + Send + 'static) -> IO<A>

Recovers from an error by producing a new IO.

pub fn or_else(self, other: IO<A>) -> IO<A>

Falls back to another IO on error.

pub fn either(self) -> IO<Either<Error, A>>

Makes this IO infallible by wrapping the result in Either. Errors become Left, successes become Right.

pub fn retry(factory: impl Fn() -> IO<A> + Send + 'static, n: usize) -> IO<A>

Retries a factory function up to n times on failure.

This is an associated function (not a method) because IO is FnOnce — the factory creates a fresh IO on each attempt.

impl IO<()>

pub fn bracket<R, B>( acquire: IO<R>, use_fn: impl FnOnce(&R) -> IO<B> + Send + 'static, release: impl FnOnce(&R) + Send + 'static, ) -> IO<B>

where R: Send + 'static, B: Send + 'static,

Acquires a resource, uses it, and guarantees release even on failure.

• acquire: IO that produces the resource
• use_fn: Function that uses the resource (receives a reference)
• release: Cleanup function that always runs after use_fn (on both success and error)

If acquire fails, neither use_fn nor release run.

impl<A> IO<A>

where A: Send + 'static,

pub fn ensuring(self, finalizer: impl FnOnce() + Send + 'static) -> IO<A>

Guarantees that the finalizer runs after this IO, regardless of success or failure.

impl<A> IO<A>

where A: Send + 'static,

pub fn from_future( future: impl Future<Output = Result<A, Error>> + Send + 'static, ) -> IO<A>

Creates an IO from a future. Blocks on the current tokio runtime.

Must be called from within a tokio runtime context. Uses block_in_place to avoid panicking when called from an async context (requires multi-thread runtime).

pub async fn to_future(self) -> Result<A, Error>

Converts this IO into a future.

Trait Implementations

impl<A> Debug for IO<A>

where A: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<A> Pure<A> for IO<A>

where A: Send + 'static,

fn pure(a: A) -> IO<A>