Dependency inversion

DIP has two halves, and the second is the one everyone forgets. The principle states: (a) high-level modules should not depend on low-level modules — both should depend on abstractions; and (b) abstractions should not depend on details — details should depend on abstractions. Most people remember half (a) — “code to an interface” — and stop. Half (b) is what gives DIP its teeth: the abstraction is shaped by what the policy needs, not by what some concrete class happens to offer.

// high-level policy (stable: changes when the business changes)
class OrderService { /* what an order is, pricing, placement rules */ }

// low-level detail (volatile: changes when infra/vendors change)
class MySQLDatabase { /* connection pools, SQL, driver quirks */ }

The question DIP answers is: which way does the import go between these two?

Naively, the arrow points from policy to detail — and that is the bug. The default, the thing you write without thinking, is for the high-level service to import the low-level driver directly. Now compile-time and run-time dependencies both flow from stable → volatile.

import { MySQLDatabase } from "../infra/mysql";

class OrderService {
  private db = new MySQLDatabase();          // policy nailed to a vendor
  place(order: Order) {
    this.db.query("INSERT INTO orders ...");  // SQL leaking into business code
  }
}

The cost is concrete: you can’t unit-test place() without MySQL; swapping to Postgres edits the class that holds your rules; and a driver upgrade can break business logic. The most valuable code in the system is hostage to the least valuable. That is exactly the dependency direction we want to reverse.

Invert it: define an interface the policy needs, owned by the policy. Instead of OrderService → MySQLDatabase, define OrderRepository — an interface phrased in the domain’s language (save(order), findById(id)), not the database’s (query, exec). The service depends on that interface. The concrete MySqlOrderRepository implements it. Crucially, the interface lives with the high-level module, in its package, as part of its contract.

// owned by the policy layer — phrased in domain terms
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: OrderId): Promise<Order | null>;
}

class OrderService {
  constructor(private orders: OrderRepository) {}   // depends on the abstraction
  async place(order: Order) {
    /* business rules */ await this.orders.save(order);
  }
}

Now both the service and the driver depend on OrderRepository. The arrow from the detail points up toward the policy’s abstraction. That ownership is what makes this “inversion” and not just “an interface somewhere.”

The detail now depends on the policy — the arrow is genuinely flipped. MySqlOrderRepository imports OrderRepository (which belongs to the domain) and bends itself to the domain’s vocabulary. The compile-time dependency runs from infrastructure to domain. The volatile thing depends on the stable thing, which is what you want, because stable things make good dependency targets.

import type { OrderRepository } from "../domain/OrderRepository";

export class MySqlOrderRepository implements OrderRepository {
  constructor(private db: MySQLDatabase) {}
  async save(order: Order) {
    await this.db.query("INSERT INTO orders ...", toRow(order));
  }
  async findById(id: OrderId) { /* SQL → Order */ }
}

// composition root wires the volatile detail into the stable policy
const service = new OrderService(new MySqlOrderRepository(mysql));

Tests inject a fake; production injects MySQL; a migration to Postgres is one new class implementing the same interface, with OrderService untouched. Testability and swappability fall out of the inverted arrow.