Pattern Matching in Effect

Overview

Pattern matching replaces complex control flow in Effect code. Simple if/else (no nesting, no else if) is allowed, but else if chains, nested conditionals, and ternary operators must use pattern matching.

Effect's Match module provides:

• Exhaustive matching - Compiler ensures all cases handled
• Type narrowing - Automatic type inference in each branch
• Composable matchers - Build complex patterns from simple ones
• Predicate support - Match on conditions, not just values

What to Use Instead of Imperative Code

When you encounter imperative control flow, refactor it to pattern matching immediately.

Basic Matching

Match.value - Match a Value

import { Match } from "effect";

const result = Match.value(input).pipe(
  Match.when("admin", () => "Full access"),
  Match.when("user", () => "Limited access"),
  Match.when("guest", () => "Read only"),
  Match.exhaustive,
);

Match.type - Create Reusable Matcher

const rolePermissions = Match.type<"admin" | "user" | "guest">().pipe(
  Match.when("admin", () => "Full access"),
  Match.when("user", () => "Limited access"),
  Match.when("guest", () => "Read only"),
  Match.exhaustive,
);

// Use multiple times
const perm1 = rolePermissions("admin");
const perm2 = rolePermissions("guest");

Matching Discriminated Unions

Match.tag - Match by _tag

type Shape =
  | { _tag: "Circle"; radius: number }
  | { _tag: "Rectangle"; width: number; height: number }
  | { _tag: "Triangle"; base: number; height: number };

const area = Match.type<Shape>().pipe(
  Match.tag("Circle", ({ radius }) => Math.PI * radius ** 2),
  Match.tag("Rectangle", ({ width, height }) => width * height),
  Match.tag("Triangle", ({ base, height }) => (base * height) / 2),
  Match.exhaustive,
);

area({ _tag: "Circle", radius: 5 }); // 78.54...

Handling Effect Errors

type AppError =
  | { _tag: "NetworkError"; url: string }
  | { _tag: "ValidationError"; field: string; message: string }
  | { _tag: "AuthError"; reason: string };

const handleError = Match.type<AppError>().pipe(
  Match.tag("NetworkError", (e) => `Failed to fetch ${e.url}`),
  Match.tag("ValidationError", (e) => `${e.field}: ${e.message}`),
  Match.tag("AuthError", (e) => `Auth failed: ${e.reason}`),
  Match.exhaustive,
);

Conditional Matching

Match.when - Match with Predicate

const describeNumber = Match.type<number>().pipe(
  Match.when(
    (n) => n < 0,
    () => "negative",
  ),
  Match.when(
    (n) => n === 0,
    () => "zero",
  ),
  Match.when(
    (n) => n > 0 && n < 10,
    () => "small positive",
  ),
  Match.when(
    (n) => n >= 10,
    () => "large positive",
  ),
  Match.exhaustive,
);

Match.when with Refinement

const processInput = Match.type<string | number | boolean>().pipe(
  Match.when(
    (x): x is string => typeof x === "string",
    (s) => `String: ${s.toUpperCase()}`,
  ),
  Match.when(
    (x): x is number => typeof x === "number",
    (n) => `Number: ${n * 2}`,
  ),
  Match.when(
    (x): x is boolean => typeof x === "boolean",
    (b) => `Boolean: ${!b}`,
  ),
  Match.exhaustive,
);

Non-Exhaustive Matching

Match.orElse - Provide Default

const greet = Match.type<string>().pipe(
  Match.when("morning", () => "Good morning!"),
  Match.when("evening", () => "Good evening!"),
  Match.orElse(() => "Hello!"),
);

greet("morning"); // "Good morning!"
greet("afternoon"); // "Hello!"

Match.orElseAbsurd - Assert Exhaustive

// Use when you believe all cases are covered
// Throws at runtime if unhandled case reached
const handle = Match.type<"a" | "b">().pipe(
  Match.when("a", () => 1),
  Match.when("b", () => 2),
  Match.orElseAbsurd,
);

Advanced Patterns

Match.not - Negative Matching

const classify = Match.type<number>().pipe(
  Match.when(
    (n) => n === 0,
    () => "zero",
  ),
  Match.not(
    (n) => n > 0,
    () => "negative",
  ), // Matches when NOT positive
  Match.orElse(() => "positive"),
);

Match.whenOr - Multiple Patterns

const isWeekend = Match.type<string>().pipe(
  Match.whenOr("Saturday", "Sunday", () => true),
  Match.orElse(() => false),
);

Match.whenAnd - Combined Conditions

interface User {
  role: "admin" | "user";
  verified: boolean;
}

const canDelete = Match.type<User>().pipe(
  Match.whenAnd(
    { role: "admin" },
    (u) => u.verified,
    () => true,
  ),
  Match.orElse(() => false),
);

Pattern Objects

Matching Object Shapes

const processEvent = Match.type<Event>().pipe(
  Match.when({ type: "click" }, (e) => handleClick(e)),
  Match.when({ type: "keydown" }, (e) => handleKeydown(e)),
  Match.when({ type: "submit" }, (e) => handleSubmit(e)),
  Match.orElse(() => {
    /* unknown event */
  }),
);

Nested Pattern Matching

interface Response {
  status: number;
  data: { type: string; value: unknown };
}

const handleResponse = Match.type<Response>().pipe(
  Match.when({ status: 200, data: { type: "user" } }, (r) => `User: ${r.data.value}`),
  Match.when({ status: 200, data: { type: "product" } }, (r) => `Product: ${r.data.value}`),
  Match.when({ status: 404 }, () => "Not found"),
  Match.when({ status: 500 }, () => "Server error"),
  Match.orElse(() => "Unknown response"),
);

Converting from if/else

Before (if/else)

function processStatus(status: Status): string {
  if (status === "pending") {
    return "Waiting...";
  } else if (status === "active") {
    return "In progress";
  } else if (status === "completed") {
    return "Done!";
  } else if (status === "failed") {
    return "Error occurred";
  } else {
    return "Unknown";
  }
}

After (Match)

const processStatus = Match.type<Status>().pipe(
  Match.when("pending", () => "Waiting..."),
  Match.when("active", () => "In progress"),
  Match.when("completed", () => "Done!"),
  Match.when("failed", () => "Error occurred"),
  Match.exhaustive, // Compile error if status type changes!
);

Converting from switch

Before (switch)

function getDiscount(userType: UserType): number {
  switch (userType) {
    case "regular":
      return 0;
    case "premium":
      return 10;
    case "vip":
      return 20;
    default:
      return 0;
  }
}

After (Match)

const getDiscount = Match.type<UserType>().pipe(
  Match.when("regular", () => 0),
  Match.when("premium", () => 10),
  Match.when("vip", () => 20),
  Match.exhaustive,
);

With Effects

const handleError = (error: AppError) =>
  Match.value(error).pipe(
    Match.tag("NetworkError", (e) =>
      Effect.gen(function* () {
        yield* Effect.logError("Network failure", { url: e.url });
        return yield* Effect.fail(e);
      }),
    ),
    Match.tag("ValidationError", (e) => Effect.succeed({ field: e.field, message: e.message })),
    Match.tag("AuthError", () => Effect.redirect("/login")),
    Match.exhaustive,
  );

Schema.is() with Match (For Schema Types Only)

Use Schema.is() in Match.when patterns to combine Schema validation with pattern matching. This works with Schema.TaggedClass and other Schema types.

Use Schema.TaggedError for domain errors - they work with Schema.is(), Effect.catchTag, and Match.tag:

• Use Schema.is(ErrorClass) for type guards on errors
• Use Effect.catchTag("ErrorName", ...) for error handling
• Use Match.tag("ErrorName", ...) when matching on errors (including predicates)

Schema.is() as Type Guard

import { Schema, Match } from "effect";

// Define schemas with TaggedClass for methods
class Circle extends Schema.TaggedClass<Circle>()("Circle", {
  radius: Schema.Number,
}) {
  get area() {
    return Math.PI * this.radius ** 2;
  }
  get circumference() {
    return 2 * Math.PI * this.radius;
  }
}

class Rectangle extends Schema.TaggedClass<Rectangle>()("Rectangle", {
  width: Schema.Number,
  height: Schema.Number,
}) {
  get area() {
    return this.width * this.height;
  }
  get perimeter() {
    return 2 * (this.width + this.height);
  }
}

const Shape = Schema.Union(Circle, Rectangle);
type Shape = Schema.Schema.Type<typeof Shape>;

// Schema.is() provides type guard + access to class methods
const describeShape = (shape: Shape) =>
  Match.value(shape).pipe(
    Match.when(
      Schema.is(Circle),
      (c) => `Circle: area=${c.area.toFixed(2)}, circumference=${c.circumference.toFixed(2)}`,
    ),
    Match.when(Schema.is(Rectangle), (r) => `Rectangle: area=${r.area}, perimeter=${r.perimeter}`),
    Match.exhaustive,
  );

Schema.is() vs Match.tag

// Match.tag - simpler, when you just need the data
const getShapeName = (shape: Shape) =>
  Match.value(shape).pipe(
    Match.tag("Circle", () => "circle"),
    Match.tag("Rectangle", () => "rectangle"),
    Match.exhaustive,
  );

// Schema.is() - when you need class methods or type narrowing
const processShape = (shape: Shape) =>
  Match.value(shape).pipe(
    Match.when(Schema.is(Circle), (c) => c.area), // Can use .area method
    Match.when(Schema.is(Rectangle), (r) => r.area), // Can use .area method
    Match.exhaustive,
  );

Validating Unknown Data with Schema.is()

// Schema.is() also works for runtime validation of unknown data
const handleUnknown = (input: unknown) =>
  Match.value(input).pipe(
    Match.when(Schema.is(Circle), (c) => `Valid circle with radius ${c.radius}`),
    Match.when(Schema.is(Rectangle), (r) => `Valid rectangle ${r.width}x${r.height}`),
    Match.orElse(() => "Invalid shape"),
  );

// Or use for type narrowing
const processInput = (input: unknown) => {
  if (Schema.is(Circle)(input)) {
    console.log(`Circle area: ${input.area}`); // Type is Circle, has methods
  }
};

Complete Example: State Machine

import { Schema, Match, Effect } from "effect";

// Define states with TaggedClass
class Draft extends Schema.TaggedClass<Draft>()("Draft", {
  content: Schema.String,
}) {
  get isEmpty() {
    return this.content.trim().length === 0;
  }
}

class Published extends Schema.TaggedClass<Published>()("Published", {
  content: Schema.String,
  publishedAt: Schema.Date,
}) {
  get daysSincePublish() {
    return Math.floor((Date.now() - this.publishedAt.getTime()) / 86400000);
  }
}

class Archived extends Schema.TaggedClass<Archived>()("Archived", {
  content: Schema.String,
  archivedReason: Schema.String,
}) {}

const Article = Schema.Union(Draft, Published, Archived);
type Article = Schema.Schema.Type<typeof Article>;

// Process with Schema.is() to access class methods
const getArticleStatus = (article: Article) =>
  Match.value(article).pipe(
    Match.when(Schema.is(Draft), (d) => (d.isEmpty ? "Empty draft" : "Draft with content")),
    Match.when(Schema.is(Published), (p) => `Published ${p.daysSincePublish} days ago`),
    Match.when(Schema.is(Archived), (a) => `Archived: ${a.archivedReason}`),
    Match.exhaustive,
  );

Option.match vs Option.flatMap

Option.match is for single Option-to-value conversion. For chaining multiple optional operations, use Option.flatMap:

// ✅ GOOD: Single Option.match (converting Option to different type)
const greeting = Option.match(maybeUser, {
  onNone: () => "Hello, guest!",
  onSome: (user) => `Hello, ${user.name}!`,
});

// ❌ BAD: Nested Option.match (every onNone returns same default)
const result = Option.match(maybeA, {
  onNone: () => fallback,
  onSome: (a) =>
    Option.match(maybeB(a), {
      onNone: () => fallback,
      onSome: (b) => transform(b),
    }),
});

// ✅ GOOD: Option.flatMap chain (flat, readable, single fallback)
const result = pipe(
  maybeA,
  Option.flatMap(maybeB),
  Option.map(transform),
  Option.getOrElse(() => fallback),
);

Rule: When every onNone branch returns the same value, that's a signal to flatten with Option.flatMap + Option.getOrElse.

Best Practices

CRITICAL: No Imperative Code

1. NEVER use else if - Replace with Match.value + Match.when
2. NEVER nest if statements - Flatten or replace with Match
3. Prefer Match over switch/case - But switch is acceptable as last resort
4. NEVER use ternary operators - Replace with Match or simple if/else
5. NEVER use if (x != null) - Replace with Option.match
6. NEVER check error flags - Replace with Either.match or Effect.match
7. NEVER access ._tag directly - Replace with Match.tag or Schema.is()
8. Refactor imperative code immediately - This is mandatory, not optional
9. NEVER nest Option.match calls - Use Option.flatMap chains with Option.getOrElse when all onNone branches share the same fallback

General Best Practices

1. Use Schema.is() in Match.when - Access class methods with proper type narrowing
2. Use Schema.TaggedClass with Match - Define unions with classes, match with Schema.is()
3. Prefer Match.exhaustive - Catch missing cases at compile time
4. Use Match.tag for simple cases - When you don't need class methods
5. Create reusable matchers - Use Match.type() for repeated patterns
6. Handle edge cases with Match.when - Predicates for complex logic

Additional Resources

For comprehensive pattern matching documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Pattern Matching" for full API reference