Ports and adapters in TypeScript

The previous article left one rule. Inner code does not import outer code. The practical part is still missing. A use case has to store an order and charge for it, and both are I/O. This article builds those two edges in TypeScript, with the full code of each piece and the decisions I made in each one.

What a port is and what an adapter is

A port is an interface that the application defines, in the application’s vocabulary. An adapter is a concrete implementation of that port that talks to a technology. The use case knows the port. The adapter knows the port and the technology. The composition root knows both and wires them.

This example has two outbound ports, OrderRepository and PaymentGateway. The HTTP controller that invokes the use case is also an adapter, an inbound one, but it needs no interface of its own. It calls PlaceOrder directly.

The domain, a bit more complete

The Order from the first article gains a status and two methods to move in and out of persistence as plain data.

export type OrderLine = { sku: string; quantity: number; unitPriceCents: number };
export type OrderStatus = 'pending' | 'paid' | 'payment-failed';
export type OrderSnapshot = {
  id: string;
  customerId: string;
  lines: OrderLine[];
  status: OrderStatus;
  chargeId: string | null;
};

export class Order {
  private constructor(private state: OrderSnapshot) {}

  static create(id: string, customerId: string, lines: readonly OrderLine[]): Order {
    if (lines.length === 0) throw new Error('An order needs at least one line');
    return new Order({ id, customerId, lines: [...lines], status: 'pending', chargeId: null });
  }

  static fromSnapshot(snapshot: OrderSnapshot): Order {
    return new Order(structuredClone(snapshot));
  }

  toSnapshot(): OrderSnapshot {
    return structuredClone(this.state);
  }

  get id(): string { return this.state.id; }
  get status(): OrderStatus { return this.state.status; }

  totalCents(): number {
    return this.state.lines.reduce((sum, l) => sum + l.quantity * l.unitPriceCents, 0);
  }

  markPaid(chargeId: string): void {
    this.assertPending();
    this.state = { ...this.state, status: 'paid', chargeId };
  }

  markPaymentFailed(): void {
    this.assertPending();
    this.state = { ...this.state, status: 'payment-failed' };
  }

  private assertPending(): void {
    if (this.state.status !== 'pending') {
      throw new Error(`Order ${this.state.id} is already ${this.state.status}`);
    }
  }
}

OrderSnapshot is the contract between the domain and any persistence adapter. Both methods clone, so nothing outside can mutate an order’s internal state.

The ports

Each port lives in src/application/ports/ and exposes only what the use case needs.

import type { Order } from '../../domain/order.js';

export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | undefined>;
}

export type ChargeRequest = { reference: string; amountCents: number; token: string };

export type ChargeResult =
  | { status: 'approved'; chargeId: string }
  | { status: 'declined'; reason: string };

export interface PaymentGateway {
  charge(request: ChargeRequest): Promise<ChargeResult>;
}

A card decline is a business outcome, so it is a value of the return type. A timeout or a 503 from the provider is a technical failure and comes out as an exception. Separating the two in the type forces the use case to handle the decline and frees it from knowing what a 503 is.

The use case

import { Order, type OrderLine } from '../domain/order.js';
import type { OrderRepository } from './ports/order-repository.js';
import type { PaymentGateway } from './ports/payment-gateway.js';

export type PlaceOrderInput = {
  orderId: string;
  customerId: string;
  lines: OrderLine[];
  paymentToken: string;
};

export type PlaceOrderResult =
  | { kind: 'placed'; orderId: string; chargeId: string }
  | { kind: 'payment-declined'; orderId: string; reason: string };

export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
  ) {}

  async execute(input: PlaceOrderInput): Promise<PlaceOrderResult> {
    const order = Order.create(input.orderId, input.customerId, input.lines);
    await this.orders.save(order);

    const charge = await this.payments.charge({
      reference: order.id,
      amountCents: order.totalCents(),
      token: input.paymentToken,
    });

    if (charge.status === 'declined') {
      order.markPaymentFailed();
      await this.orders.save(order);
      return { kind: 'payment-declined', orderId: order.id, reason: charge.reason };
    }

    order.markPaid(charge.chargeId);
    await this.orders.save(order);
    return { kind: 'placed', orderId: order.id, chargeId: charge.chargeId };
  }
}

The orderId arrives in the input instead of being generated inside. That keeps the use case deterministic, the tests do not depend on crypto.randomUUID(), and the client can retry with the same id.

Two adapters for the same port

import { Order, type OrderSnapshot } from '../../domain/order.js';
import type { OrderRepository } from '../../application/ports/order-repository.js';

export class InMemoryOrderRepository implements OrderRepository {
  private readonly rows = new Map<string, OrderSnapshot>();

  async save(order: Order): Promise<void> {
    this.rows.set(order.id, order.toSnapshot());
  }

  async findById(id: string): Promise<Order | undefined> {
    const snapshot = this.rows.get(id);
    return snapshot ? Order.fromSnapshot(snapshot) : undefined;
  }
}

import type { Pool } from 'pg';
import { Order, type OrderSnapshot } from '../../domain/order.js';
import type { OrderRepository } from '../../application/ports/order-repository.js';

type OrderRow = {
  id: string;
  customer_id: string;
  lines: OrderSnapshot['lines'];
  status: OrderSnapshot['status'];
  charge_id: string | null;
};

export class PostgresOrderRepository implements OrderRepository {
  constructor(private readonly pool: Pool) {}

  async save(order: Order): Promise<void> {
    const snapshot = order.toSnapshot();
    await this.pool.query(
      `INSERT INTO orders (id, customer_id, lines, status, charge_id)
       VALUES ($1, $2, $3, $4, $5)
       ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status, charge_id = EXCLUDED.charge_id`,
      [snapshot.id, snapshot.customerId, JSON.stringify(snapshot.lines), snapshot.status, snapshot.chargeId],
    );
  }

  async findById(id: string): Promise<Order | undefined> {
    const { rows } = await this.pool.query<OrderRow>(
      'SELECT id, customer_id, lines, status, charge_id FROM orders WHERE id = $1',
      [id],
    );
    const row = rows[0];
    if (!row) return undefined;
    return Order.fromSnapshot({
      id: row.id,
      customerId: row.customer_id,
      lines: row.lines,
      status: row.status,
      chargeId: row.charge_id,
    });
  }
}

Both adapters satisfy the same interface and the same observable behavior. The compiler does not guarantee the second part. A contract test suite that runs against both does, and it is the topic of the next article.

Wiring it all

I did not use a dependency injection container. With about ten use cases, manual wiring fits on one screen and the compiler tells you when an argument is missing. A container starts to pay off when the graph is large or when you need per-request scopes.

What it costs

The last con is the most dangerous and the least discussed. An in-memory adapter that accepts things Postgres rejects hides errors until production. That is why contract tests are not optional.

Summary

• A port uses the application’s vocabulary. If it exposes SQL or HTTP, it is a driver wrapper.
• Business outcomes go in the return type. Technical failures come out as exceptions.
• The in-memory adapter stores copies. Shared references give tests that pass by accident.
• A hand-wired composition root is enough for most services.
• Every adapter has to pass the same contract suite. That is what comes next in the series.