Glossary

Key terms used throughout this book, in alphabetical order.

~ (bind operator) The prefix operator inside effect! that runs an inner effect and binds its success value to a variable. let x = ~eff runs eff and assigns the result to x; ~eff runs eff and discards the result.

Backpressure The mechanism by which a slow consumer signals to a fast producer to slow down or drop data. In id_effect, expressed via BackpressurePolicy: Block, DropLatest, DropOldest, or Unbounded. See Backpressure Policies.

Brand A zero-cost newtype wrapper that creates a distinct type from a primitive. Brand<String, EmailMarker> and Brand<String, NameMarker> are different types even though both wrap String, preventing accidental mixing. See Validation and Refinement.

Cause<E> The reason an effect failed. Three variants: Cause::Fail(E) (expected error), Cause::Die(Box<dyn Any>) (panic or defect), Cause::Interrupt (cancelled). See Exit.

Chunk<A> A contiguous, reference-counted batch of A values. The unit of data in Stream pipelines. Cheap to clone; efficient to process in bulk. See Chunks.

Clock A trait abstracting time. LiveClock uses real system time; TestClock advances only when told to. Inject Clock through the environment so scheduling logic is testable. See Clock Injection.

commit The function that lifts a Stm<A> into an Effect<A, Never, ()>. Executing the effect runs the STM transaction and retries on conflict. See Stm and commit.

Env The runtime capability map. Values are keyed by capability services (Database, EffectLogger, …) and looked up in O(1). Built with build_env([provide!(…), …]), run_with, or manual Env::insert. See The Environment.

Effect<A, E, R> The central type. A description of a computation that: succeeds with a value of type A, can fail with a typed error of type E, and requires environment R. Effects are lazy: nothing runs until you call a runtime function. See What Even Is an Effect?.

effect! macro The do-notation macro for writing effect programs. Converts ~expr into flat bind chains so you can write sequential effect code without nested closures. See The effect! Macro.

Exit<A, E> The result of running an effect: Exit::Success(A) or Exit::Failure(Cause<E>). Returned by run_test and accessible via FiberHandle::join. See Exit.

Fiber A lightweight, independently-scheduled unit of concurrent work. Fibers are cheaper than OS threads and support structured cancellation. Spawn with run_fork; join with handle.join(). See What Are Fibers?.

FiberRef A fiber-scoped dynamic variable. Each fiber has its own copy; changes don't leak to parent or sibling fibers. Use for request IDs, trace contexts, and other per-fiber state. See FiberRef.

from_async A constructor that lifts an async closure into an Effect. Use when wrapping third-party library futures that return Future rather than Effect. See Creating Effects.

caps!(K1, K2, …) A macro that names the required capability set for Effect<A, E, caps!(…)> at compile time. At runtime this is a CapList<(K1, K2, …)> backed by Env. Prefer caps!(…) over bare Env in public APIs that need multiple capabilities. See The R Parameter.

HasSchema A trait that attaches a canonical Schema<Self> to a type. Implement it when a type should always be parsed the same way and you want schema-driven tooling to work automatically. See Validation and Refinement.

id_effect_axum Workspace crate bridging Axum handlers to Effect: State<R>, routing::*, execute, JSON + schema helpers. See Axum host.

id_effect_cli Workspace crate for CLI entrypoints: optional clap, run_main, and mapping Exit / Cause to process exit codes. See CLI with clap.

id_effect_config Workspace crate for configuration: Config<T> descriptors, Figment/serde extraction, and effectful reads from a provider in R. See Configuration.

id_effect_logger Workspace crate for an injectable EffectLogger service and pluggable log backends. See Logging.

id_effect_platform Workspace crate providing @effect/platform-style HTTP, filesystem, and process traits plus Tokio-backed implementations (HttpClient, FileSystem, ProcessRuntime, …). See Platform I/O.

id_effect_platform::http::reqwest Workspace crate: reqwest::Client as a keyed service, send / JSON helpers, optional pools; complements portable HTTP via id_effect_platform. See HTTP via reqwest.

id_effect_tokio Workspace crate: Tokio-backed Runtime integration, re-exports run_async / run_blocking / run_fork, and patterns for non-Send async graphs (spawn_blocking_run_async). See Tokio bridge.

id_effect_tower Workspace crate: tower::Service implementations over effects, with optional concurrency limits and request metrics. See Tower service.

id_effect_lint Custom rustc lint crate for id_effect-specific rules; excluded from the default workspace members list. See Workspace tooling.

effect! macro crates (id_effect_macro, id_effect_proc_macro) The effect! do-notation is split between a proc-macro crate and a user-facing macro crate. See Workspace tooling.

ProviderSpec A type that declares how to build one capability value. Providers list dependencies in requires() and are wired with provide!(P), build_env, or run_with. CapabilityGraph plans build order. See Providers and Wiring.

Needs<K> trait A bound on the environment type parameter that expresses "this computation requires capability K." Prefer caps!(Database, EffectLogger) on the Effect type; use where R: Needs<Database> only for generic library functions (still use require! inside effect!). See Widening and Narrowing.

Never The uninhabited type. Effect<A, Never, R> cannot fail with a typed error (but may still Die or Interrupt). Eliminate Err(never) branches with absurd(never). See Error Handling.

ParseErrors An accumulated collection of ParseError values, each with a path and message. Returned by parse(schema, unknown). Reports all validation failures at once, not just the first. See ParseErrors.

R (environment type parameter) The third type parameter of Effect<A, E, R>. Encodes which capabilities the computation needs — often caps!(K1, K2) for multi-cap public APIs, or () when none are required. Binaries and tests supply a concrete Env. See The R Parameter.

run_blocking The synchronous effect runner. Use in main and integration tests where you want a blocking call. Do not call from within library functions — return Effect instead. See Laziness as a Superpower.

run_test The test-aware effect runner. Like run_blocking but also detects fiber leaks and uses deterministic scheduling. Use in all #[test] functions. See run_test.

Schedule A value describing how to space out repeated or retried operations. Combinators: fixed, exponential, linear, .take(n), .until(pred). Used with .retry() and .repeat(). See Schedule.

Schema A value of type Schema<T> that describes how to parse an Unknown into a T. Schemas are composable: build complex schemas from primitive ones. See Schema Combinators.

Scope A resource lifetime boundary. Finalizers registered with a Scope run when the scope exits, whether by success, failure, or cancellation. Use acquire_release for the common bracket pattern. See Scopes and Finalizers.

Cap<T> Universal capability slot. The service type T is what you write in caps!(T), require!(T), and #[provides(T)]. See Capability services.

Sink A consumer of Stream elements. Receives Chunks via on_chunk and a completion signal via on_done. Built-in sinks: collect, fold, for_each, drain. See Sinks.

Stm<A> A transactional computation over TRef values. Compose with stm!; execute with commit or atomically. Retries automatically on conflict; aborts on stm::fail. See Stm and commit.

Stream A lazy, potentially infinite sequence of values of type A. Processes elements in Chunks. Supports all the combinators of Effect plus streaming-specific operators like flat_map, merge, and take_until. See Streams.

Capability service A Rust type naming a dependency in Env (for example Counter or HttpClientService). Cap<T> implements CapabilityKey with Value = T. See Capability services.

TestClock A Clock implementation for tests. Starts at Unix epoch and advances only when you call .advance(dur) or .set_time(t). Sleep effects complete instantly when the clock passes their wake time. See TestClock.

TRef<T> A transactional cell: a mutable T that can be read and written inside Stm transactions. Multiple TRefs can be read and written atomically. See TRef.

Unknown The type for unvalidated wire data. All external data enters your program as Unknown and is converted to typed values by running it through a Schema. See The Unknown Type.