IO<R,E,A>

Lazy, composable effects with typed errors and dependency injection.

Overview

IO represents a lazy effect that:

• Requires environment R (dependencies)
• May fail with error E (typed errors)
• Produces value A on success

Nothing runs until explicitly executed.

Basic Usage

import { IO } from "functype/io";

// Synchronous effect
const sync = IO.sync(() => 42);

// Async effect
const async = IO.async(async () => fetchData());

// Effect that may fail
const safe = IO.tryCatch(
  () => JSON.parse(input),
  (e) => new ParseError(e),
);

// Running effects - safe by default
const either = await sync.run(); // Either<E, A> - never throws
const value = await sync.runOrThrow(); // A - throws on error

// Synchronous execution
const syncEither = sync.runSync(); // Either<E, A> - never throws
const syncValue = sync.runSyncOrThrow(); // A - throws on error

Constructors

Method	Description
IO.succeed(value)	Effect that succeeds with value
IO.fail(error)	Effect that fails with error
IO.sync(() => A)	Wrap synchronous computation
IO.async(async () => A)	Wrap async computation
IO.tryCatch(fn, onError)	Catch exceptions as typed errors
IO.fromPromise(promise, onError)	Convert Promise to IO
IO.unit	Effect that succeeds with void
IO.never	Effect that never completes

Transformations

// Map over success value
io.map((x) => x * 2);

// Chain effects
io.flatMap((x) => IO.succeed(x + 1));

// Handle errors
io.mapError((e) => new WrappedError(e));
io.catchAll((e) => IO.succeed(fallback));
io.recover(defaultValue);

// Provide fallback
io.orElse(fallbackIO);

Combining Effects

// Run in parallel
IO.all([io1, io2, io3]); // All must succeed
IO.race([io1, io2]); // First to complete wins
IO.any([io1, io2, io3]); // First success wins

// Zip effects
io1.zip(io2); // [A, B]
io1.zipWith(io2, (a, b) => c); // C

// Sequential
io1.andThen(io2); // Run io2 after io1

Dependency Injection

IO has built-in dependency injection using Tags, Contexts, and Layers.

import { IO, Tag, Context } from "functype/io";

// Define service interface
interface Logger {
  log(message: string): void;
}

// Create a Tag for the service
const Logger = Tag<Logger>("Logger");

// Use the service
const program = IO.service(Logger).flatMap((logger) =>
  IO.sync(() => logger.log("Hello!")),
);

// Provide implementation
const result = await program
  .provideService(Logger, { log: console.log })
  .runOrThrow();

Context and Layer

// Build context with multiple services
const context = Context.empty()
  .add(Logger, consoleLogger)
  .add(Config, appConfig);

// Provide full context
program.provideContext(context);

// Use Layer for complex dependency graphs
const AppLayer = Layer.succeed(Logger, consoleLogger).merge(
  Layer.succeed(Config, appConfig),
);

program.provideLayer(AppLayer);

Do-Notation

Generator Syntax (IO.gen)

const program = IO.gen(function* () {
  const a = yield* IO.succeed(1);
  const b = yield* IO.succeed(2);
  const c = yield* IO.succeed(3);
  return a + b + c;
});

await program.runOrThrow(); // 6

Builder Syntax (IO.Do)

const program = IO.Do.bind("user", () => getUser("123"))
  .bind("posts", ({ user }) => getPosts(user.id))
  .let("count", ({ posts }) => posts.length)
  .map(({ user, posts, count }) => ({ user, posts, count }));

Resource Management

// Bracket pattern
IO.bracket(
  IO.sync(() => openFile(path)), // acquire
  (file) => IO.sync(() => file.close()), // release
  (file) => IO.sync(() => file.read()), // use
);

// Acquire/Release
IO.acquireRelease(
  IO.sync(() => openConnection()),
  (conn) => IO.sync(() => conn.close()),
);

Error Handling Patterns

// Catch specific errors
io.catch("NotFound", () => IO.succeed(null));

// Fold over success/failure
io.fold(
  (error) => `Failed: ${error}`,
  (value) => `Success: ${value}`,
);

// Ensure cleanup
io.ensuring(IO.sync(() => cleanup()));

// Retry on failure
io.retry(3);
io.retryWithDelay(3, 1000);

IO vs Task

Feature	IO<R,E,A>	Task
Typed Errors	Yes (E parameter)	No
Dependency Injection	Yes (R parameter)	No
Cancellation	Via interrupt	Built-in
Progress Tracking	No	Yes
Best For	Complex apps with DI	Simple async with cancellation

When to Use IO

• Applications with complex dependencies (web servers, CLI tools)
• When you want errors tracked in the type system
• Resource management with guaranteed cleanup
• Building composable, testable programs
• When you need dependency injection without mocking frameworks

API Reference

See full API documentation at functype API docs