data-types

Data Types in Effect

Overview

Effect provides immutable, type-safe data structures:

• Option - Represents optional values (Some/None)
• Either - Represents success/failure (Right/Left)
• Cause - Detailed failure information
• Exit - Effect execution result
• Data - Value equality for classes
• Chunk - Immutable indexed sequence
• Duration - Time spans
• DateTime - Date/time handling

Option

Represents a value that may or may not exist:

import { Option } from "effect";

const some = Option.some(42);
const none = Option.none();

const fromNull = Option.fromNullable(maybeNull);

const result = Option.match(option, {
  onNone: () => "No value",
  onSome: (value) => `Got: ${value}`,
});

const value = Option.getOrElse(option, () => defaultValue);

const doubled = Option.map(option, (n) => n * 2);

const chained = Option.flatMap(option, (n) => (n > 0 ? Option.some(n) : Option.none()));

const positive = Option.filter(option, (n) => n > 0);

Option with Effect

const program = Effect.gen(function* () {
  const maybeUser = yield* findUser(id);

  // Convert Option to Effect
  const user = yield* Option.match(maybeUser, {
    onNone: () => Effect.fail(new UserNotFound()),
    onSome: Effect.succeed,
  });

  // Or use Effect.fromOption
  const user = yield* maybeUser.pipe(
    Effect.fromOption,
    Effect.mapError(() => new UserNotFound()),
  );
});

Option Chaining - flatMap over Nested match

NEVER nest Option.match calls. When chaining multiple optional operations that share the same fallback, use Option.flatMap with a single Option.getOrElse:

// ❌ FORBIDDEN: Nested Option.match (pyramid of doom)
// Every onNone returns the same default — this is the signal to use flatMap
const result = pipe(
  users,
  Array.findFirst((u) => u.role === "admin"),
  Option.match({
    onNone: () => defaultName,
    onSome: (admin) =>
      Option.match(admin.department, {
        onNone: () => defaultName,
        onSome: (dept) =>
          pipe(
            departments,
            Array.findFirst((d) => d.id === dept),
            Option.match({
              onNone: () => defaultName,
              onSome: (d) => d.name,
            }),
          ),
      }),
  }),
);

// ✅ REQUIRED: Option.flatMap chain with single getOrElse
const result = pipe(
  users,
  Array.findFirst((u) => u.role === "admin"),
  Option.flatMap((admin) => admin.department),
  Option.flatMap((dept) =>
    pipe(
      departments,
      Array.findFirst((d) => d.id === dept),
    ),
  ),
  Option.map((d) => d.name),
  Option.getOrElse(() => defaultName),
);

When to use which:

Pattern	Use When
Option.match	Converting Option to a different type (single use)
Option.flatMap chain	Chaining multiple optional operations with same fallback
Option.map	Transforming the inner value without changing Option wrapper
Option.getOrElse	Extracting the value with a default at the end of a chain
Option.filter	Adding a condition that may turn Some into None

Either

Represents a value that is either Left (failure) or Right (success):

import { Either } from "effect";

const right = Either.right(42);
const left = Either.left("error");

const result = Either.match(either, {
  onLeft: (error) => `Error: ${error}`,
  onRight: (value) => `Success: ${value}`,
});

const doubled = Either.map(either, (n) => n * 2);

const mapped = Either.mapLeft(either, (e) => new Error(e));

const both = Either.mapBoth(either, {
  onLeft: (e) => new Error(e),
  onRight: (n) => n * 2,
});

const chained = Either.flatMap(either, (n) => (n > 0 ? Either.right(n) : Either.left("negative")));

const value = Either.getOrThrow(either);

Cause

Complete failure information for an Effect:

import { Cause } from "effect";

Cause.fail(error);
Cause.die(defect);
Cause.interrupt(id);
Cause.empty;
Cause.sequential(c1, c2);
Cause.parallel(c1, c2);

Cause.isFailure(cause);
Cause.isDie(cause);
Cause.isInterrupt(cause);

const failures = Cause.failures(cause);
const defects = Cause.defects(cause);

const message = Cause.pretty(cause);

Exit

The result of running an Effect:

import { Exit } from "effect";

Exit.succeed(value);
Exit.fail(cause);

const result = Exit.match(exit, {
  onFailure: (cause) => `Failed: ${Cause.pretty(cause)}`,
  onSuccess: (value) => `Succeeded: ${value}`,
});

Exit.isSuccess(exit);
Exit.isFailure(exit);

const value = Exit.getOrElse(exit, () => defaultValue);

const mapped = Exit.map(exit, (a) => a * 2);

Data - Value Equality

Create classes with structural equality:

import { Data, Schema } from "effect";

// Tagged class
class Person extends Data.Class<{
  readonly name: string;
  readonly age: number;
}> {}

const alice1 = new Person({ name: "Alice", age: 30 });
const alice2 = new Person({ name: "Alice", age: 30 });

alice1 === alice2; // false (reference)
Equal.equals(alice1, alice2); // true (structural)

// Tagged errors (used with Effect.fail)
// Use Schema.TaggedError for domain errors - works with Schema.is(), catchTag, and Match.tag
class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", { userId: Schema.String }) {}

// Tagged enum
type Shape = Data.TaggedEnum<{
  Circle: { radius: number };
  Rectangle: { width: number; height: number };
}>;
const { Circle, Rectangle } = Data.taggedEnum<Shape>();

const circle = Circle({ radius: 10 });
const rect = Rectangle({ width: 5, height: 3 });

Chunk

Immutable indexed sequence optimized for Effect:

import { Chunk } from "effect";

const chunk = Chunk.make(1, 2, 3, 4, 5);
const fromArray = Chunk.fromIterable([1, 2, 3]);
const empty = Chunk.empty<number>();

const head = Chunk.head(chunk);
const tail = Chunk.tail(chunk);
const take = Chunk.take(chunk, 2);
const drop = Chunk.drop(chunk, 2);

const doubled = Chunk.map(chunk, (n) => n * 2);
const filtered = Chunk.filter(chunk, (n) => n > 2);
const sum = Chunk.reduce(chunk, 0, (acc, n) => acc + n);

const array = Chunk.toArray(chunk);
const readonlyArray = Chunk.toReadonlyArray(chunk);

Duration

Represent time spans:

import { Duration } from "effect";

const ms = Duration.millis(100);
const secs = Duration.seconds(5);
const mins = Duration.minutes(10);
const hours = Duration.hours(2);
const days = Duration.days(1);

const fromString = Duration.decode("5 seconds");

const total = Duration.sum(duration1, duration2);
const remaining = Duration.subtract(total, elapsed);

Duration.greaterThan(a, b);
Duration.lessThanOrEqualTo(a, b);

const milliseconds = Duration.toMillis(duration);
const seconds = Duration.toSeconds(duration);

DateTime

Date and time handling:

import { DateTime } from "effect";

const now = DateTime.now;

const fromDate = DateTime.fromDate(new Date());

const specific = DateTime.make({
  year: 2024,
  month: 1,
  day: 15,
  hours: 10,
  minutes: 30,
});

const tomorrow = DateTime.add(now, { days: 1 });
const lastWeek = DateTime.subtract(now, { weeks: 1 });

const formatted = DateTime.format(now, "yyyy-MM-dd");

const utc = DateTime.setZone(now, "UTC");
const local = DateTime.setZone(now, DateTime.zoneLocal);

HashMap & HashSet

Immutable hash-based collections:

import { HashMap, HashSet } from "effect";

const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]);

const value = HashMap.get(map, "a");
const updated = HashMap.set(map, "d", 4);
const removed = HashMap.remove(map, "a");

const set = HashSet.make(1, 2, 3, 4, 5);

const has = HashSet.has(set, 3);
const added = HashSet.add(set, 6);
const removed = HashSet.remove(set, 1);
const union = HashSet.union(set1, set2);
const intersection = HashSet.intersection(set1, set2);

Redacted

Protect sensitive values from logging:

import { Redacted } from "effect";

const apiKey = Redacted.make("sk-secret-key-123");

console.log(apiKey);
console.log(`Key: ${apiKey}`);

const actual = Redacted.value(apiKey);

Best Practices

1. Use Option for nullable values - Explicit handling required
2. Use Either for validation - Accumulate errors
3. Use Schema.TaggedError for Effect errors - Enables catchTag and Schema.is()
4. Use Chunk in streaming - Optimized for Effect operations
5. Use Redacted for secrets - Prevents accidental exposure
6. Use Duration for time - Type-safe time operations

Additional Resources

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

Search for these sections:

• "Option" for optional values
• "Either" for success/failure
• "Cause" for error details
• "Exit" for execution results
• "Data" for value equality
• "Chunk" for sequences
• "DateTime" for date handling