The Actual Lost-Update Bug#

A lost update occurs when two requests read the same aggregate state and an unconditional later write overwrites the earlier change. This repository is fine for a demo and unsafe under concurrent updates:

1
async save(order: Order): Promise<Result<void, string>> {
2
  this.orders.set(order.getId().getValue(), order);
3
  return ok(undefined);
4
}

Two requests can load version 4 of the same order. One adds a line, the other cancels it. Both call save(). The second write replaces the first without either request learning that it worked from stale state.

The bug is the missing concurrency contract. A version-aware write is commonly called save().

There are two common repository contracts:

A serializable transaction is an isolation level, not a third repository API. Use it when an invariant depends on conflicting reads beyond the locked aggregate; it can abort transactions, so callers must retry.

I use the update closure when the application service can express the change as one short operation on one aggregate. It makes the repository own the read, lock, mutation, and write as one unit.

A Transactional Update Closure#

Three Dots Labs uses this shape in Go:

1
type Repository interface {
2
  UpdateHour(
3
    ctx context.Context,
4
    hourTime time.Time,
5
    updateFn func(h *Hour) (*Hour, error),
6
  ) error
7
}
8

9
UpdateHour(ctx, hourTime, func(hour *Hour) (*Hour, error) {
10
  return hour.MakeAvailable(), nil
11
})

Its MySQL adapter starts a transaction, loads the row with SELECT ... FOR UPDATE, runs the function, saves the result, then commits. The row lock is pessimistic: a competing writer waits until the first transaction commits or rolls back.

Here is the TypeScript contract:

1
type UpdateOrder = (order: Order) => Result<Order, OrderError>;
2

3
interface OrderRepository {
4
  add(order: Order): Promise<Result<void, OrderError>>;
5
  getById(id: OrderId): Promise<Result<Order, OrderError>>;
6
  update(id: OrderId, change: UpdateOrder): Promise<Result<Order, OrderError>>;
7
}

The application service states the business operation. It neither opens a transaction nor persists an intermediate aggregate.

1
class SubmitOrder {
2
  constructor(private readonly orders: OrderRepository) {}
3

4
  execute(orderId: OrderId): Promise<Result<Order, OrderError>> {
5
    return this.orders.update(orderId, (order) => {
6
      const submitted = order.submit();
7
      if (!submitted.ok) return submitted;
8
      return ok(order);
9
    });
10
  }
11
}

The closure must remain short and local. Do not call payment APIs, publish messages, or acquire another aggregate lock inside it.

How Should a PostgreSQL Repository Update an Aggregate Safely?#

The adapter starts a transaction, loads the order with SELECT ... FOR UPDATE, rehydrates the order and its lines, runs the closure, persists the changed aggregate, and commits. The lock is the detail that matters; the interface name is incidental.

Returning an error from a transaction callback does not necessarily roll back; the transaction library decides that. When a closure returns Result.err, the repository must signal rollback to its transaction helper, then convert that rollback signal back to the same error for the caller.

Production code also needs a transaction helper whose rollback behavior is tested. Do not assume a wrapper rolls back because its callback returned { ok: false }.

Optimistic Concurrency with a Version-Aware Save#

When a request loads an aggregate, lets a user think for ten minutes, then submits a form, holding a row lock is the wrong design. Optimistic concurrency is the match for detached aggregates. Load a version with the aggregate and condition the write on that version instead:

This scalar-only sketch updates fields stored on orders. A complete save writes changed order lines in the same transaction before it advances the version.

1
UPDATE orders
2
SET status = $2,
3
    total_cents = $3,
4
    version = version + 1
5
WHERE id = $1
6
  AND version = $4

If the affected-row count is zero, the repository returns ConcurrencyConflict. The UI can reload the order and ask the user to reconcile the change.

1
async save(order: Order): Promise<Result<Order, OrderError>> {
2
  const updated = await this.database.execute(
3
    `UPDATE orders
4
     SET status = $2,
5
         total_cents = $3,
6
         version = version + 1
7
     WHERE id = $1 AND version = $4`,
8
    [
9
      order.getId().getValue(),
10
      order.getStatus(),
11
      order.getTotalCents(),
12
      order.getVersion(),
13
    ]
14
  );
15

16
  if (updated.rowCount === 0) {
17
    return err({ type: "concurrency-conflict", id: order.getId().getValue() });
18
  }
19

20
  return ok(order.withVersion(order.getVersion() + 1));
21
}

This is a valid save() method. The caller owns the load-modify-save window; the database detects whether that window became stale.

Pick one model per use case. A closure that locks the row does not need a version check to prevent concurrent writes. A detached aggregate needs one because it has no lock.

A Fake That Can Prove Rollback#

The Three Dots in-memory repository stores values rather than pointers. That detail matters. A fake that gives the callback its stored object lets mutations escape before the update succeeds.

The smallest honest fake stores snapshots and reconstitutes a new aggregate for every operation:

1
class InMemoryOrderRepository implements OrderRepository {
2
  private readonly orders = new Map<string, OrderSnapshot>();
3

4
  async add(order: Order): Promise<Result<void, OrderError>> {
5
    const id = order.getId().getValue();
6
    if (this.orders.has(id)) return err({ type: "already-exists", id });
7

8
    this.orders.set(id, structuredClone(order.toSnapshot()));
9
    return ok(undefined);
10
  }
11

12
  async getById(id: OrderId): Promise<Result<Order, OrderError>> {
13
    const snapshot = this.orders.get(id.getValue());
14
    if (!snapshot) return err({ type: "not-found", id: id.getValue() });
15
    return Order.reconstitute(structuredClone(snapshot));
16
  }
17

18
  async update(
19
    id: OrderId,
20
    change: UpdateOrder
21
  ): Promise<Result<Order, OrderError>> {
22
    const snapshot = this.orders.get(id.getValue());
23
    if (!snapshot) return err({ type: "not-found", id: id.getValue() });
24

25
    const loaded = Order.reconstitute(structuredClone(snapshot));
26
    if (!loaded.ok) return loaded;
27

28
    const changed = change(loaded.value);
29
    if (!changed.ok) return changed;
30

31
    this.orders.set(id.getValue(), structuredClone(changed.value.toSnapshot()));
32
    return changed;
33
  }
34
}

This fake’s read-modify-write block does not yield. JavaScript does not need a mutex around it. If production locking matters, test that behavior against PostgreSQL, where locks and transaction isolation actually exist.

The fake proves domain behavior and rollback. The integration test proves database concurrency.

How Do You Test Rollback in an In-Memory Repository?#

This test only proves rollback if the aggregate changes before the closure rejects:

1
it("does not commit changes when the closure rejects after mutating", async () => {
2
  const result = await orders.update(orderId, (order) => {
3
    const added = order.addLine("widget", 1, 5_000);
4
    if (!added.ok) return added;
5

6
    return err({ type: "cannot-submit-cancelled-order" });
7
  });
8

9
  expect(result).toEqual(err({ type: "cannot-submit-cancelled-order" }));
10

11
  const reloaded = await orders.getById(orderId);
12
  expect(reloaded.ok && reloaded.value.getLineCount()).toBe(0);
13
});

The error is deliberately arbitrary. The contract under test is mutate, reject, then reload from storage. If the fake stores references, this test catches it.

1
it("serializes two updates without losing either", async () => {
2
  const first = repository.update(orderId, (order) => {
3
    const result = order.submit();
4
    return result.ok ? ok(order) : result;
5
  });
6
  const second = repository.update(orderId, (order) => {
7
    const result = order.cancel();
8
    return result.ok ? ok(order) : result;
9
  });
10

11
  const [left, right] = await Promise.all([first, second]);
12

13
  // Pessimistic FOR UPDATE serializes the closures. Both observe the
14
  // latest committed state; one wins submit, the other sees the
15
  // submitted order and accepts the cancel.
16
  expect(left.ok).toBe(true);
17
  expect(right.ok).toBe(true);
18

19
  const reloaded = await repository.getById(orderId);
20
  expect(reloaded.ok && reloaded.value.getStatus()).toBe("cancelled");
21
});

What Happens When the Use Case Touches More Than One Aggregate?#

An aggregate is a transactional consistency boundary. The boundary guides the design while still allowing a local transaction that deliberately writes several tables.

Start with the business requirement:

• If Order and Inventory must be atomically consistent and share one database, a local transaction may be the right cost.
• If they can converge later, record an integration event in an outbox in the same transaction as Order; publish it after commit.
• If they live in separate services or databases, a database transaction cannot coordinate them. Use an asynchronous process and make its failure modes explicit.

The next article covers aggregate boundaries, mappings, database foreign keys, and the workflow choices for work that crosses those boundaries.

Sources#

• Eric Evans, Domain-Driven Design, chapters on entities, aggregates, and repositories for the consistency-boundary framing throughout.
• Vaughn Vernon, Implementing Domain-Driven Design, on optimistic concurrency and detached-aggregate persistence.
• Martin Fowler, Repository, for the domain-access-versus-storage-mechanics separation.
• Three Dots Labs, Repository pattern in Go, for the transactional update closure shape adapted in this article.

Continue the TDD & Software Design Series#

1. TDD Isn’t Just for Catching Bugs - It’s Your Permission Slip
2. Value Objects & Entities - Building Blocks That Can’t Break
3. Aggregates & Repositories in TypeScript - Refactoring Without Fear
4. Repository Updates in TypeScript: Locks and Optimistic Concurrency
5. DDD Aggregate Boundaries and Persistence in TypeScript
6. I Stopped Mocking Everything in TDD
7. The Result Pattern: Why I Stopped Throwing Exceptions
8. TDD in the Age of AI: Who Tests the Tests?
9. TDD for Legacy Code: Start With Seams, Not Ideology