Course contentsShow
← TypeScript
Lesson 160 of 1,7964. Type InferenceFree lesson

Inference Across Module Boundaries

Why exported functions and public APIs benefit from explicit annotations to create stable contracts.

Inference Across Module Boundaries

What you'll learn: Why exported functions need explicit type annotations to create stable, predictable contracts between modules.

The Core Idea

When your function stays inside a single file, TypeScript can infer its return type from what you return. That works fine locally. But when you export that function for other modules to use, you're creating a public API — a promise to other parts of your codebase (or other developers) about what your function accepts and returns.

Without explicit annotations on exported functions, you're relying on inference to define your contract. If you change the implementation later, the inferred type changes automatically. Other modules using your function might break silently, or worse, accept the new type without anyone noticing the API changed.

The Boundary Problem

Think of module boundaries like property lines between neighbors. Inside your yard (your module), you can rearrange things freely. But the fence (your exported API) should be stable and clearly marked. If the fence moves every time you plant a tree, your neighbor never knows where they stand.

When you export a function without explicit parameter and return types, the "fence" moves whenever your implementation changes. Inference is wonderful for internal logic, but creates instability across module boundaries.

The Solution

Always annotate:

  • Function parameters that are exported
  • Return types of exported functions

This creates a stable contract. Even if you refactor the implementation, the type signature stays fixed. TypeScript will warn you if your new code violates the contract you promised.

Key Takeaway: Explicit type annotations on exported functions turn inference from a convenience into a commitment, protecting your module boundaries from unintended breaking changes.