API Quick Reference

A condensed reference for the most commonly used types and functions in id_effect. For full documentation, use cargo doc --open -p id_effect.

Core Types

Type	Description
`Effect<A, E, R>`	A computation that produces `A`, can fail with `E`, and requires environment `R`
`Stream<A, E, R>`	A sequence of `A` values that can fail with `E` and requires environment `R`
`Stm<A>`	A transactional computation that produces `A`
`Exit<A, E>`	The result of running an effect: `Success(A)` or `Failure(Cause<E>)`
`Cause<E>`	`Fail(E)`, `Die(Box<dyn Any>)`, or `Interrupt`
`Context<R>`	A heterogeneous map of services, the `R` at runtime
`Layer<Out, In, E>`	A recipe for building `Out` from `In`, can fail with `E`
`Chunk<A>`	A contiguous, reference-counted batch of `A` values
`Unknown`	Unvalidated wire data; input type for schemas
`ParseErrors`	Accumulated parse failures with paths

Constructors

Function	Type	Notes
`succeed(a)`	`Effect<A, E, R>`	Always succeeds with `a`
`fail(e)`	`Effect<A, E, R>`	Always fails with typed error `e`
`pure(a)`	`Effect<A, Never, ()>`	Alias for `succeed`; `E = Never`
`from_async(f)`	`Effect<A, E, R>`	Lift an async closure
`effect!(…)`	`Effect<A, E, R>`	Do-notation macro
`commit(stm)`	`Effect<A, Never, ()>`	Run an STM transaction
`Stream::from_iter(i)`	`Stream<A, Never, ()>`	Stream from an iterator
`Stream::from_effect(e)`	`Stream<A, E, R>`	Single-element stream
`Stream::unfold_effect(s, f)`	`Stream<A, E, R>`	Generate stream from state

Effect Combinators

Method	Notes
`.map(f)`	Transform success value
`.flat_map(f)`	Chain effects
`.map_err(f)`	Transform error
`.catch(f)`	Handle typed failure
`.catch_all(f)`	Handle any `Cause`
`.fold(on_e, on_a)`	Both paths to success
`.or_else(f)`	Try alternative on failure
`.ignore_error()`	Convert failure to `Option`
`.zip(other)`	Run two effects, tuple result
`.zip_left(other)`	Run two effects, keep left
`.zip_right(other)`	Run two effects, keep right
`.retry(schedule)`	Retry on failure
`.repeat(schedule)`	Repeat on success
`.timeout(dur)`	Fail with `Timeout` if too slow

Concurrency

Function/Method	Notes
`run_fork(rt, f)`	Spawn a fiber
`handle.join()`	`Effect` that waits for the fiber
`handle.interrupt()`	Cancel a fiber
`FiberRef::new(initial)`	Fiber-scoped dynamic variable
`fiber_ref.get()`	Read current fiber's value
`fiber_ref.set(v)`	Set current fiber's value
`with_fiber_id(id, f)`	Run `f` with a specific fiber id

STM

Function	Notes
`TRef::new(v)`	Create a transactional cell
`tref.read_stm()`	Read inside `stm!`
`tref.write_stm(v)`	Write inside `stm!`
`tref.modify_stm(f)`	Modify inside `stm!`
`commit(stm)`	Lift `Stm<A>` into `Effect<A, Never, ()>`
`atomically(stm)`	Execute `Stm` synchronously
`stm::retry()`	Block until any read `TRef` changes
`stm::fail(e)`	Abort transaction with error
`TQueue::bounded(n)`	Transactional FIFO queue
`TMap::new()`	Transactional hash map
`TSemaphore::new(n)`	Transactional semaphore

Resources

Function	Notes
`scope.acquire(res, f)`	Use a resource, run finalizer on exit
`acquire_release(acq, rel)`	Bracket-style resource management
`Pool::new(size, factory)`	Reusable resource pool
`pool.get()`	`Effect` that borrows one resource
`Cache::new(loader)`	Cache backed by an effect

Scheduling

Function	Notes
`Schedule::fixed(d)`	Repeat every `d`
`Schedule::exponential(base)`	Exponential backoff
`Schedule::linear(step)`	Linear backoff
`Schedule::immediate()`	No delay
`.take(n)`	At most `n` repetitions
`.until(pred)`	Stop when predicate holds
`eff.retry(sched)`	Retry with a schedule
`eff.repeat(sched)`	Repeat with a schedule

Running Effects

Function	Notes
`run_blocking(eff, env)`	Synchronous runner (main/binaries)
`run_async(eff, env)`	Async runner (tokio integration)
`run_test(eff)`	Test harness; detects leaks
`run_test_and_unwrap(eff)`	Test harness; panics on failure
`run_test_with_env(eff, env)`	Test with custom environment
`run_test_with_clock(f)`	Test with controlled `TestClock`

Schema

Function	Notes
`string()`	`Schema<String>`
`i64()`	`Schema<i64>`
`f64()`	`Schema<f64>`
`boolean()`	`Schema<bool>`
`optional(s)`	`Schema<Option<T>>`
`array(s)`	`Schema<Vec<T>>`
`struct_!(Type { … })`	Struct schema via macro
`refine(s, pred, msg)`	Add a predicate constraint
`parse(schema, unknown)`	Run schema; returns `Result<T, ParseErrors>`
`Unknown::from_json_str(s)`	Parse JSON into `Unknown`
`Unknown::from_serde_json(v)`	Convert `serde_json::Value`

Macros

Macro	Notes
`effect!(…)`	Do-notation for effects; use `~expr` to bind
`ctx!(Key => value, …)`	Build a `Context` from key-value pairs
`service_key!(Name: Type)`	Declare a service key
`pipe!(v, f, g, …)`	Pipeline for pure values