traits

Traits in Effect

Overview

Effect provides trait-based abstractions for:

• Equal - Structural equality comparison
• Hash - Hash code generation
• Equivalence - Custom equality relations
• Order - Ordering and comparison

These enable consistent behavior across Effect's data structures.

Equal - Structural Equality

The Equal Interface

import { Equal } from "effect";

Equal.equals(a, b);

import { Data } from "effect";

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

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

Equal.equals(p1, p2);
p1 === p2;

Implementing Equal (Recommended: Use Data.Class)

PREFER Data.Class which provides Equal and Hash automatically:

import { Data, Equal } from "effect";

// Data.Class provides Equal and Hash automatically
class Point extends Data.Class<{ readonly x: number; readonly y: number }> {}

const p1 = new Point({ x: 1, y: 2 });
const p2 = new Point({ x: 1, y: 2 });

Equal.equals(p1, p2);

For Schema types, use Schema.Class which also provides Equal:

import { Schema, Equal } from "effect";

class Point extends Schema.Class<Point>("Point")({
  x: Schema.Number,
  y: Schema.Number,
}) {}

const p1 = new Point({ x: 1, y: 2 });
const p2 = new Point({ x: 1, y: 2 });

Equal.equals(p1, p2); // true

Why Equal Matters

Effect's collections (HashMap, HashSet) use Equal for lookups:

import { HashMap, Data } from "effect";

class UserId extends Data.Class<{ id: string }> {}

const map = HashMap.make([
  [new UserId({ id: "1" }), "Alice"],
  [new UserId({ id: "2" }), "Bob"],
]);

// Works because UserId implements Equal
HashMap.get(map, new UserId({ id: "1" })); // Option.some("Alice")

Hash - Hash Code Generation

The Hash Interface

import { Hash } from "effect";

Hash.hash(value);

Hash.string("hello");
Hash.number(42);
Hash.combine(h1)(h2);
Hash.array([1, 2, 3]);

Hash Contract

Objects that are Equal MUST have the same hash:

// If Equal.equals(a, b) === true
// Then Hash.hash(a) === Hash.hash(b)

// The reverse is NOT required:
// Same hash does NOT mean equal (hash collisions are allowed)

Hash with Data.Class (Recommended)

Data.Class provides both Equal and Hash automatically:

import { Data, Hash, Equal } from "effect";

class Rectangle extends Data.Class<{
  readonly width: number;
  readonly height: number;
}> {}

const r1 = new Rectangle({ width: 10, height: 5 });
const r2 = new Rectangle({ width: 10, height: 5 });

Equal.equals(r1, r2);
Hash.hash(r1) === Hash.hash(r2);

Equivalence - Custom Equality Relations

Creating Equivalences

import { Equivalence } from "effect";

const caseInsensitive = Equivalence.make<string>((a, b) => a.toLowerCase() === b.toLowerCase());

caseInsensitive("Hello", "hello");
caseInsensitive("Hello", "HELLO");

Equivalence.string;
Equivalence.number;
Equivalence.boolean;
Equivalence.strict;

Transforming Equivalences

// Map to compare by derived value
const byLength = Equivalence.string.pipe(Equivalence.mapInput((s: string) => s.length.toString()));

// Actually, better approach:
const byLength = Equivalence.make<string>((a, b) => a.length === b.length);

// Combine equivalences
const userEquivalence = Equivalence.make<User>(
  (a, b) => Equivalence.string(a.name, b.name) && Equivalence.number(a.age, b.age),
);

Using with Collections

import { Array as Arr } from "effect";

const users = [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 },
  { name: "alice", age: 30 }, // Same as Alice?
];

// Dedupe with custom equivalence
const byNameIgnoreCase = Equivalence.make<User>((a, b) => a.name.toLowerCase() === b.name.toLowerCase());

const unique = Arr.dedupe(users); // Uses default equality
const uniqueByName = Arr.dedupeWith(users, byNameIgnoreCase);

Order - Comparison and Sorting

The Order Interface

import { Order } from "effect";

Order.string("a", "b");
Order.string("b", "a");
Order.string("a", "a");

Order.lessThan(Order.number)(5, 10);
Order.greaterThan(Order.number)(5, 10);
Order.lessThanOrEqualTo(Order.number)(5, 5);
Order.between(Order.number)({ minimum: 0, maximum: 10 })(5);

Order.min(Order.number)(3, 7);
Order.max(Order.number)(3, 7);

Order.clamp(Order.number)({ minimum: 0, maximum: 100 })(150);

Built-in Orders

Order.string;
Order.number;
Order.boolean;
Order.bigint;
Order.Date;

Creating Custom Orders

const byAge = Order.make<Person>((a, b) => (a.age < b.age ? -1 : a.age > b.age ? 1 : 0));

const byName = Order.mapInput(Order.string, (p: Person) => p.name);
const byAge = Order.mapInput(Order.number, (p: Person) => p.age);

Combining Orders

const byAgeThenName = Order.combine(byAge, byName);

const byAgeDesc = Order.reverse(byAge);

const sortUsers = Order.combine(
  Order.mapInput(Order.string, (u: User) => u.department),
  Order.combine(
    Order.reverse(Order.mapInput(Order.number, (u: User) => u.salary)),
    Order.mapInput(Order.string, (u: User) => u.name),
  ),
);

Sorting with Order

import { Array as Arr } from "effect";

const people = [
  { name: "Charlie", age: 35 },
  { name: "Alice", age: 30 },
  { name: "Bob", age: 30 },
];

const byAge = Arr.sort(
  people,
  Order.mapInput(Order.number, (p) => p.age),
);

const sorted = Arr.sort(
  people,
  Order.combine(
    Order.mapInput(Order.number, (p) => p.age),
    Order.mapInput(Order.string, (p) => p.name),
  ),
);

Data.Class - Automatic Implementation

Using Data.Class automatically implements Equal and Hash:

import { Data, Equal, Hash } from "effect";

class User extends Data.Class<{
  id: string;
  name: string;
  email: string;
}> {}

const u1 = new User({ id: "1", name: "Alice", email: "a@example.com" });
const u2 = new User({ id: "1", name: "Alice", email: "a@example.com" });

Equal.equals(u1, u2); // true
Hash.hash(u1) === Hash.hash(u2); // true

Best Practices

1. Use Data.Class for value objects - Automatic Equal/Hash
2. Implement both Equal and Hash together - Required for collections
3. Use Order.mapInput for simple ordering - Cleaner than manual comparison
4. Combine orders for complex sorting - More composable than custom compare
5. Consider Equivalence for custom equality - When default equality isn't enough

Additional Resources

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

Search for these sections:

• "Equal" for equality comparison
• "Hash" for hash code generation
• "Equivalence" for custom equality relations
• "Order" for ordering and comparison