Lesson 1 of the deep-module course · What a deep module is, what a shallow one is, the depth idea · ~15 minutes
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.
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.
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.
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.
| Shallow module | Deep 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 |
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.
Answer from memory — that effort is the point. Do not scroll back up first.
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.
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.