Living With Ports and Adapters

Hexagonal, clean and onion architecture are not competitors and choosing between them is largely a vocabulary decision. All three put technology-free business logic at the centre and push technology to the edge behind interfaces the centre owns. What differs is emphasis, and knowing which emphasis you need is more useful than picking a name.

What the pattern does not decide for you

• **How to model the domain.** Hexagonal will happily host an anaemic domain. It tells you where the business logic goes, not how to write it — that is the subject of the domain-driven design module later in this chapter.
• **Where transactions belong.** A driven port that returns a transaction handle leaks infrastructure; one that hides transactions makes multi-repository operations impossible to compose. Most teams settle on an application-layer transaction that repositories join, and it is worth deciding explicitly rather than discovering the answer.
• **How to keep fakes faithful.** An in-memory adapter that behaves differently from the real one under concurrency or ordering will let broken code pass. Contract tests — the same test suite run against both the fake and the real adapter — are the usual answer and they are extra work.
• **Whether a port is worth having.** The pattern gives no stopping rule, which is why over-porting is its characteristic failure. The stopping rule has to come from outside: a namable second implementation, or a fake you actually need.

// One suite, two subjects. If the in-memory adapter diverges from Postgres,
// this fails rather than a production incident revealing it later.
export function enrolmentRepositoryContract(
  name: string,
  makeRepository: () => Promise<EnrolmentRepository>,
) {
  describe(name, () => {
    it('counts only active enrolments', async () => {
      const repository = await makeRepository();
      await repository.save(activeEnrolment('l-1'));
      await repository.save(cancelledEnrolment('l-1'));
      expect(await repository.activeEnrolmentCount(LearnerId.parse('l-1'))).toBe(1);
    });

    it('is idempotent on save of the same enrolment', async () => {
      const repository = await makeRepository();
      const enrolment = activeEnrolment('l-2');
      await repository.save(enrolment);
      await repository.save(enrolment);
      expect(await repository.activeEnrolmentCount(LearnerId.parse('l-2'))).toBe(1);
    });
  });
}

enrolmentRepositoryContract('in-memory', async () => new InMemoryEnrolmentRepository());
enrolmentRepositoryContract('postgres', async () => new PostgresEnrolmentRepository(await testDb()));