Package-level declarations

Types

Link copied to clipboard
interface Effect<out R>

A request that expects a response of type R. Effect families are the open union of everything a Program can ask its handlers to do. Handlers match on the erased class, so declare a family as a sealed interface and handle it star-projected (handle<MyEffect<*>, A>).

Link copied to clipboard
sealed class Program<out A>

A pure, reusable description of a computation producing A. Build one with program or perform/flatMap, then apply handlers (handle, intercept, handleS, interpret) and extract the value with runOrThrow or run.

Link copied to clipboard
sealed class ProgramScope

Receiver scope of program blocks: sequence sub-programs, and effects, with bind. Suspension is restricted, so only binds — not arbitrary suspend calls — can occur inside.

Functions

Link copied to clipboard
fun <A, B> Program<A>.flatMap(f: (A) -> Program<B>): Program<B>

Sequence f after this program. Evaluation timing follows the receiver: on a Program.Done value, f runs immediately at construction; on a suspended or deferred program it is queued and runs during interpretation.

Link copied to clipboard
inline fun <E : Effect<*>, A> Program<A>.handle(noinline rule: suspend ProgramScope.(E) -> Any?): Program<A>

Interpret with auto-resume: the block's return value is the effect's response. For an effect that returns Unit, do the work; for one that returns a value, return it. The block may bind other programs, which run in place of the effect as in a program block, so a rule that translates its effect into I/O binds a performIO { }. The block is a one-shot coroutine: under a multi-shot handler such as collectAll, a block that binds the choice fails when resumed a second time, while one that returns without suspending is fine.

Link copied to clipboard
inline fun <E : Effect<*>, S, A> Program<A>.handleS(initialState: S, noinline rule: suspend ProgramScope.(S, E) -> Pair<S, Any?>): Program<A>

Stateful handle: the block receives the current state and returns newState to response. Mind the pair order when the state and the response share a type — response to newState is equally well-typed and silently swaps the two. The state is threaded by value, so each interpretation starts from initialState and shares nothing with another; a rule that mutates the initial state in place instead of returning a new one shares it between every interpretation of the program.

Link copied to clipboard
inline fun <E : Effect<*>, A> Program<A>.intercept(noinline rule: suspend ProgramScope.(effect: E, proceed: suspend ProgramScope.() -> Any?) -> Any?): Program<A>

Middleware: observe an effect without consuming it. proceed() re-emits the effect to the handler downstream and returns its response, so the rule decides where the effect executes and may inspect, rewrite or replace the result; a rule that answers without calling proceed() consumes the effect. Effects the rule performs itself are seen only by the handlers applied after this one, so a middleware that logs needs the log handler downstream of it.

Link copied to clipboard
inline fun <E : Effect<*>, A> Program<A>.interpret(noinline rule: (E, (Any?) -> Program<A>) -> Program<A>): Program<A>

Handle and remove every effect of family E. rule receives the effect and a resume continuation: resume(response) is the rest of the program with response as the effect's result, as a program that nothing has run yet. Return it to continue, transform it with flatMap or map or bind it in a program { } block to work on the rest's result, call it more than once to resume the same continuation more than once, or leave it uncalled to cut the program short. Every form runs on a constant stack. Applied lazily, when the program is run.

inline fun <E : Effect<*>, A, B> Program<A>.interpret(noinline transformDone: (A) -> Program<B>, noinline rule: (E, (Any?) -> Program<B>) -> Program<B>): Program<B>

Handle and remove every effect of family E, mapping the final value with transformDone. rule receives the effect and a resume continuation: resume(response) is the rest of the program with response as the effect's result, as a program that nothing has run yet. Return it to continue, transform it with flatMap or map or bind it in a program { } block to work on the rest's result, call it more than once to resume the same continuation more than once, or leave it uncalled to cut the program short. Every form runs on a constant stack. Applied lazily, when the program is run.

Link copied to clipboard
inline fun <E : Effect<*>, S, A> Program<A>.interpretS(initialState: S, noinline rule: (S, E, (S, Any?) -> Program<A>) -> Program<A>): Program<A>

Handle and remove every effect of family E, threading state S from initialState; resume takes the next state and the response, and is the rest of the program as in interpret, with the same forms and the same lazy application.

inline fun <E : Effect<*>, S, A, B> Program<A>.interpretS(initialState: S, noinline transformDone: (S, A) -> Program<B>, noinline rule: (S, E, (S, Any?) -> Program<B>) -> Program<B>): Program<B>

Handle and remove every effect of family E, threading state S from initialState through every step; transformDone sees the final state and value. resume takes the next state and the response, and is the rest of the program as in interpret, with the same forms and the same lazy application.

Link copied to clipboard
fun <A, B> Program<A>.map(f: (A) -> B): Program<B>

Transform this program's final value with f. Like flatMap, f runs immediately on a Program.Done value and during interpretation otherwise.

Link copied to clipboard
fun <R> perform(effect: Effect<R>): Program<R>

Perform an effect: a one-step program that suspends on effect and produces its response.

Link copied to clipboard
fun <A> program(block: suspend ProgramScope.() -> A): Program<A>

Build a Program in direct style: .bind() each sub-program, or each effect, instead of chaining flatMap. The block is captured, not run — each interpretation forces it afresh, so program{} values are pure, replayable descriptions that can be interpreted any number of times, under different handler stacks.

Link copied to clipboard
fun <A> Program<A>.run(): Result<A>

Run a fully handled program, capturing the outcome as a Result: the final value on success, or an IllegalStateException naming the unhandled effect on failure.

Link copied to clipboard
fun <A> Program<A>.runOrThrow(): A

Extract the final value of a fully handled program, or throw naming the unhandled effect.