Spec<T> class abstract base

The Specification Pattern: compose business rules as reusable, testable predicates.

A Spec represents a single business rule that an object either satisfies or doesn't. Instead of embedding validation logic directly in methods, specifications are first-class objects that can be created, combined, tested, and reused independently.

This pattern is ideal for:

• Domain rules: Business rules, filtering, and search criteria
• Reusability: The same rule applies in multiple contexts without duplication
• Testability: Each rule is isolated and easy to unit test
• Composability: Combine simple rules into complex business logic
• Readability: Express business intent clearly through method names

Compose specs using:

• & / and — Both must be satisfied (AND logic)
• | / or — At least one must be satisfied (OR logic)
• ^ / xor — Exactly one must be satisfied, not both (XOR logic)
• nand — At least one must not be satisfied (NAND logic)
• nor — Neither must be satisfied (NOR logic)
• xnor — Both must have the same satisfaction state (XNOR logic)
• negated or ~ — Inverts the rule (NOT logic)

AND, OR, NAND, and NOR use left-to-right short-circuit evaluation. XOR and XNOR evaluate both operands because both results are needed.

Creating a Spec:

/// Business rule: person is old enough to vote
final class IsEligibleVoter extends Spec<Person> {
  @override
  bool isSatisfiedBy(Person person) => person.age >= 18;
}

/// Business rule: person has valid contact info
final class HasValidEmail extends Spec<Person> {
  @override
  bool isSatisfiedBy(Person person) => person.email.contains('@');
}

Using a Spec:

// Single rule
final isVoter = IsEligibleVoter();
if (isVoter.isSatisfiedBy(person)) {
  registerToVote(person);
}

// Composed rules
final validVoter = IsEligibleVoter() & HasValidEmail();
final voters = people.where((p) => validVoter.isSatisfiedBy(p)).toList();

// Complex compositions
final canReceiveNewsletter = HasValidEmail() & (IsEligibleVoter() | HasOptedIn());