Deep Modules

Lesson 1 of the deep-module course · What a deep module is, what a shallow one is, the depth idea · ~15 minutes

1 · What are deep modules? 2 · When to use them 3 · TypeScript module design
Why this matters for your mission You write TypeScript apps that grow. The single habit that makes code stay manageable as it grows is building modules whose interface is small and clean while the complexity stays inside. That habit is exactly what "deep module" means. Master the idea today and you will start spotting shallow modules everywhere — and know how to fix them.

Working example: a logging module for your web app. Every part of your app needs to log things. The job seems simple — "just save a line" — but the real work (timestamps, log levels, output format, error handling) is fiddly. Watch how much of good design hides in that sentence.

1 · The smell: using a module feels heavy

Here is how a lot of TypeScript code starts — a logging import that makes you think hard:

import { Logger } from "./logger";

const logger = new Logger({
  level: "info",
  format: "json",
  destination: "stdout",
  prefix: "orders",
  timestamp: true,
});

logger.log("Order placed", "info", "stdout", "orders");
logger.log("Retry failed", "warn", "stdout", "orders");

Every call repeats the same noise — level, destination, prefix — even though it never changes. The module made you carry the complexity instead of carrying it itself. If you swap the format from JSON to text, you touch every call site. That is a shallow module.

2 · The idea: a deep module

John Ousterhout, in A Philosophy of Software Design, defines a deep module as one that does a lot of useful work behind a small, simple interface. [Ousterhout, book]

The depth of a module is roughly:

depth = functionality provided  ÷  complexity of the interface

In plain words: the more the module does, and the less you have to think about to use it, the deeper it is. A deep module is heavy inside, light outside. A shallow module is light inside, heavy outside — it pushes the work onto whoever calls it.

3 · The fix: let the module do the work

Here is the same logging need, but the module absorbs the complexity:

import { logger } from "./logger";

// the module chose the level, format, prefix, destination — once, inside
logger.info("Order placed");
logger.warn("Retry failed");

One word per call. The caller never sees the level names, the output format, or the file path. Those are inside the module, and only the people maintaining the logger need to know them. Change the format? Edit ./logger/index.ts — one file, not every call site.

The rule — cite this A deep module is heavy inside, light outside. It takes the real work of your problem and hides it behind as small an interface as you can manage. The complexity does not disappear — it moves to where it belongs: inside the module, out of every caller's head.

4 · How you recognise a deep module in practice

Shallow moduleDeep module
Many parameters per call Few parameters per call
You must know internal names (levels, formats, destinations) You only know the public method names
Changing the internals means touching callers Changing the internals changes nothing for callers
Import many helpers to do one job Import one thing and call it

5 · Practice: write the deep logger

Build the makeLogger function. It returns an object with info, warn, and error methods. Each method takes a message and returns a formatted string: "[LEVEL] 2024-01-15 message". The caller does not pass the level, the date, or the format — the module owns those. TypeScript types are your job to write in your head; this playground checks the runtime logic and result shape.

6 · Retrieval check

Answer from memory — that effort is the point. Do not scroll back up first.

7 · Where this goes next

You can now spot shallow modules and sketch a deep replacement. But "deep" is not always right — sometimes the cost outweighs the benefit. Next lesson: when to use deep modules, including the advantages and the hidden costs.

Your teacher is the agent Anything unclear — why info beats passing "info" as a string, or how the date stays inside the module, or whether deep modules are ever the wrong choice — just ask in the chat. That is what I am here for. No question is too basic.
Primary source for this lesson Read Chapter 10 of A Philosophy of Software Design — John Ousterhout (2019). It is the source of the deep-module idea and the depth formula. Free sample chapters are available on the publisher's site.
Glossary — today's terms →