Do-Notation

Scala-like for-comprehensions for composing monadic operations.

Overview

Do-notation provides generator-based monadic comprehensions inspired by Scala’s for-comprehensions. It makes complex monadic chains readable and maintainable by eliminating nested flatMap calls.

Basic Usage

import { Do, $ } from "functype/do";
import { Option } from "functype/option";

// Instead of nested flatMaps
const nested = Option(1).flatMap((a) =>
  Option(2).flatMap((b) => Option(3).map((c) => a + b + c)),
);

// Use Do-notation
const clean = Do(function* () {
  const a = yield* $(Option(1));
  const b = yield* $(Option(2));
  const c = yield* $(Option(3));
  return a + b + c;
}); // Some(6)

The $ Helper

The $ function enables TypeScript type inference with generators:

import { Do, $ } from "functype/do";

const result = Do(function* () {
  const x = yield* $(Option(42)); // x is number, not unknown
  return x * 2;
});

Short-Circuiting

Do-notation automatically propagates None/Left/Failure:

// Option - stops on None
const result = Do(function* () {
  const a = yield* $(Option(1));
  const b = yield* $(Option.none<number>()); // stops here
  const c = yield* $(Option(3));
  return a + b + c;
}); // None

// Either - stops on Left
const validated = Do(function* () {
  const name = yield* $(validateName(input)); // Left stops chain
  const email = yield* $(validateEmail(input));
  return { name, email };
});

Supported Types

Do-notation works with any monad in functype:

Option

const result = Do(function* () {
  const user = yield* $(findUser(id));
  const profile = yield* $(user.profile);
  const email = yield* $(profile.email);
  return email;
}); // Option<string>

Either

const result = Do(function* () {
  const name = yield* $(validateName(input.name));
  const age = yield* $(validateAge(input.age));
  const email = yield* $(validateEmail(input.email));
  return { name, age, email };
}); // Either<ValidationError, User>

Try

const result = Do(function* () {
  const config = yield* $(Try(() => readConfig()));
  const db = yield* $(Try(() => connectDB(config)));
  const users = yield* $(Try(() => db.query("SELECT * FROM users")));
  return users;
}); // Try<User[]>

List (Cartesian Products)

const combinations = Do(function* () {
  const x = yield* $(List([1, 2, 3]));
  const y = yield* $(List(["a", "b"]));
  return `${x}${y}`;
}); // List(["1a", "1b", "2a", "2b", "3a", "3b"])

Async Do-Notation

For async operations, use DoAsync:

import { DoAsync, $ } from "functype/do";

const result = await DoAsync(async function* () {
  const user = yield* $(Task.async("getUser", () => fetchUser()));
  const posts = yield* $(Task.async("getPosts", () => fetchPosts(user.id)));
  return { user, posts };
});

Performance

Do-notation is highly optimized:

• Option/Either/Try: Near-zero overhead
• List comprehensions: 175x faster than nested flatMaps
• Uses direct iteration instead of creating intermediate structures

Key Features

• Scala-Inspired: Similar syntax to Scala’s for-comprehensions
• Type-Safe: Full TypeScript inference with the $ helper
• Short-Circuiting: None/Left/Failure automatically propagates
• High Performance: Optimized for List comprehensions

When to Use Do-Notation

• Chaining 3+ monadic operations
• List comprehensions (cartesian products)
• Complex validation pipelines
• When readability matters more than micro-optimization

Comparison

// Without Do-notation
const result = getUser(id).flatMap((user) =>
  getProfile(user.profileId).flatMap((profile) =>
    getSettings(profile.settingsId).map((settings) => ({
      user,
      profile,
      settings,
    })),
  ),
);

// With Do-notation
const result = Do(function* () {
  const user = yield* $(getUser(id));
  const profile = yield* $(getProfile(user.profileId));
  const settings = yield* $(getSettings(profile.settingsId));
  return { user, profile, settings };
});

API Reference

See full API documentation at functype API docs