Lesson 3 of the deep-module course · export control, barrel files, types as interface · ~18 minutes
export keyword (your gatekeeper), barrel files
(index.ts, your front door), and types (your interface contract). Today you use all
three to build a real deep module — a metrics client — and feel how they keep complexity inside.
We build on the logging module from Lessons 1–2, using a new example: a
metrics client that counts HTTP status codes. The caller just calls
record(200) and summary(). Everything — the counts map, the formatting,
the sorting — stays inside.
exportIn TypeScript, every file is its own module. Nothing in it is visible outside unless
you say export. That makes export your gatekeeper: it is the only tool that
decides what callers can see. Everything else stays private — automatically.
// internal.ts — nothing is exported → invisible to callers
function formatCounts(counts: Map<number, number>): string {
/* … */
}
type StatusCount = { status: number; count: number };
// (these are private — no export)
// public.ts — only what is exported reaches callers
export function makeMetricsClient(prefix: string) {
const counts = new Map<number, number>();
return {
record: (s) => counts.set(s, (counts.get(s) ?? 0) + 1),
summary: () => formatCounts(counts),
};
}
Notice: formatCounts and StatusCount have no export. They
exist only inside this file. Not exporting is how you keep a module deep. The caller
never sees the formatting logic, the type, or the counts map. Only makeMetricsClient is
visible — and that is the whole interface.
A real deep module usually spans several files. TypeScript projects use a barrel file to create a single front door — callers import from the folder, not from the internal files:
metrics/
├── index.ts ← the barrel: the ONLY thing callers see
├── metrics.ts ← main logic (makeMetricsClient lives here)
└── types.ts ← internal helpers — NOT re-exported by the barrel
Inside the barrel:
// metrics/index.ts — this is the front door
export { makeMetricsClient } from "./metrics";
// NOTE: nothing from ./types.ts is re-exported → it stays internal
Callers do import { makeMetricsClient } from "./metrics" and get exactly one function.
If they try to import from ./metrics/types directly, TypeScript warns them — "this is an
internal file, you should not be here." The barrel is your guardrail.
export in it is a promise to callers; every missing export is something
callers will never depend on, so you can change it freely later.
TypeScript types are not erased — they are documentation that the compiler checks. A deep module's interface includes not just the functions, but the types of what those functions accept and return:
// The interface callers see — simple, typed, complete
export function makeMetricsClient(prefix: string): MetricsClient;
export type MetricsClient = {
record(status: number): void;
summary(): string;
};
The caller sees exactly two methods, typed precisely. They do not need to read a single internal file to know how to use the module — the type is the documentation.
export type for type-only re-exports so the compiler knows there is no
runtime cost. (3) If an internal file is imported by the barrel's implementation but not re-exported,
it is still private — that is the whole point.
Implement makeMetricsClient(prefix). It returns an object with two methods:
record(status) adds a status code to an internal count, and summary()
returns a string. The caller never sees the counts map or the formatting logic — they live inside.
The TypeScript structure would be a barrel + internal files; this playground checks the runtime logic
and result shape.
Answer from memory — that effort is the point. Do not scroll back up first.
You now have three tools: export as gatekeeper, barrel files as front doors, and types as
interface contracts. To keep building depth, you will eventually face harder questions — "what if a
module needs to talk to a database?" (that is the imperative shell), "what if two modules share
a type?" (that is a shared kernel), and "where should my boundaries sit?" (that is
bounded contexts). Those live in the architecture course — the DDD curriculum.
import/export, barrel files,
and module resolution. The deep-module idea is Ousterhout's (Chapter 10); these are the
TypeScript tools that make it concrete.