Building Deep Modules in TypeScript

Lesson 3 of the deep-module course · export control, barrel files, types as interface · ~18 minutes

1 · What are deep modules? 2 · When to use them 3 · TypeScript module design
Why this matters for your mission The deep-module idea is language-agnostic — but TypeScript gives you concrete tools to make a module deep: the 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.

1 · The TypeScript tool that makes modules deep: export

In 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.

2 · Barrel files: the front door

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.

The principle One barrel, one interface. The barrel file is the only door. Every 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.

3 · Types as part of the interface

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.

Gotchas (1) Don't export internal types "just in case" — each export is a promise you cannot break. (2) Prefer 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.

4 · Practice: build the metrics client

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.

5 · Retrieval check

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

6 · Where this goes next

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.

Your teacher is the agent Questions about export control, barrel file layout, or "should I export this type?" — ask in chat. If you are unsure whether a file is internal or public, send it and I will tell you which side of the barrel it belongs on.
Primary source for this lesson TypeScript Handbook: "Modules" — for the mechanics of 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.
← Lesson 2 Glossary →