Keep side effects at the edges

How to do it

A rule that reads the database, the clock and the mail server at once can only be tested with all three faked. Split it in two. The outer function loads what the rule needs and calls the rule. Then it carries out what the rule returns. The rule now tests with plain values, as Fake the clock and the network in unit tests wants. It also runs the same in a job, an API call or a script. These rules form the inner ring of Point dependencies inward.

Examples

TypeScript example

// The rule: plain data in, a decision out
export function reminderFor(invoice: Invoice, today: Date): Reminder | undefined {
  const daysLate = differenceInDays(today, invoice.dueDate);
  return daysLate >= 14 && !invoice.paid ? { to: invoice.customerEmail, daysLate } : undefined;
}

// The edge: reads, calls the rule, then acts
export async function sendReminders(db: Db, mailer: Mailer, clock: Clock) {
  for (const invoice of await db.unpaidInvoices()) {
    const reminder = reminderFor(invoice, clock.today());
    if (reminder) await mailer.sendReminder(reminder);
  }
}

Python example

# The rule: plain data in, a decision out
def reminder_for(invoice: Invoice, today: date) -> Reminder | None:
    days_late = (today - invoice.due_date).days
    return Reminder(invoice.customer_email, days_late) if days_late >= 14 and not invoice.paid else None

# The edge: reads, calls the rule, then acts
def send_reminders(db: Db, mailer: Mailer, clock: Clock) -> None:
    for invoice in db.unpaid_invoices():
        if reminder := reminder_for(invoice, clock.today()):
            mailer.send_reminder(reminder)

How to check

A dependency rule fails the build when a file in domain/ imports a database driver, an HTTP client or a mail library. It also fails on clock reads there. Examples are dependency-cruiser and import-linter. The unit tests of domain/ use no mocks.

Related rules

• TST-5 Fake the clock and the network in unit tests in Testing
• ARC-63 Point dependencies inward in Clean code and architecture