🇺🇸English

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.

UseSchema.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 useelse if - Replace with Match.value + Match.when
2. NEVER nestif statements - Flatten or replace with Match
3. Prefer Match overswitch/case - But switch is acceptable as last resort
4. NEVER use ternary operators - Replace with Match or simple if/else
5. NEVER useif (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 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

Weekly Installs

0

Repository

andrueandersonc…ffect-ts

GitHub Stars

5

First Seen

Jan 1, 1970

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass