Your team proposes augmenting a third-party library's exported interface in TypeScript so a field it does not declare becomes visible everywhere. What do you weigh before accepting that over defining a local type?

## What you are actually proposing A module augmentation reopens another package's declaration space and merges members into one of its interfaces. It is the same mechanism as any interface merge — powerful precisely because it is not scoped. Understanding it as "editing the library's types for the entire program" rather than "adding a field in my file" is the whole of the judgment call. ## Blast radius Once the augmenting file is part of the compilation, the added member exists for every file in it. There is no import required, no way to restrict it to one directory, and no per-consumer opt-out. Consequences worth naming: - **Discoverability inverts.** A reader hovering the property sees a member that does not appear in the package's own declarations, and there is no local clue about who added it or under what conditions it is populated. - **It travels.** If you publish a library whose own declarations carry a global augmentation, every consumer of your package inherits it whether they wanted it or not. Imposing a change on downstream programs is a decision, not a detail. - **It cannot be staged.** You cannot roll it out to one team first; the compilation is all-or-nothing. ## Collision risk Merging has no precedence rule for properties: two declarations of the same member name with different types is an error, full stop. Three ways that bites in real programs: 1. Two dependencies both augment a popular interface and both pick the obvious name. Neither is wrong, neither can be un-applied, and the build stops. 2. Your augmentation and a colleague's, in the same monorepo, differ on required-versus-optional or on the exact shape. 3. The library itself later ships that member with its own type, and a routine version bump breaks compilation with an error that points at your file rather than at the change that caused it. The cheap mitigations are conventions, not mechanisms: give the added member an owner-specific name rather than a generic noun, or add a single namespaced member holding everything your feature needs, so the surface you occupy is one name you control. ## The honesty problem Everything in the type layer is erased. An augmentation emits nothing and verifies nothing; it changes only what the checker believes. Declaring a required field asserts a guarantee that some code, somewhere, always ran before this value was observed — and nothing enforces it. Handlers reached by a path that skips the setup read `undefined` through a type that says it cannot be. So if the field's presence is conditional, declare it optional. That pushes the uncertainty into the type where callers must handle it, at the cost of a check at each use — which is the correct cost, because the uncertainty is real. If you want the checked-once, non-optional experience, express it as a *distinct type* the code passes through a validating boundary, so something at runtime actually establishes the guarantee before the type asserts it. ## The alternatives, and what each costs - **Local intersection at the call site** — `LibType & { tenantId: string }`. Visible, scoped, and requires a cast or a narrowing step at the boundary. Best when a handful of sites need it. - **A wrapper type of your own** that holds the library value plus your data. Fully honest and fully local, at the cost of unwrapping. - **A typed accessor** — a function that takes the library value and returns your enriched type, throwing or narrowing if the data is absent. This is the option that makes the runtime check and the type claim agree, and it is usually the right answer when the field comes from middleware or setup that may not have run. - **The augmentation** — the only option when third-party or framework code, which you cannot edit, must itself see the enriched type. Plugin ecosystems designed around "packages contribute fields" are the legitimate case: the library's own design anticipates augmentation and documents the member names. ## How I would decide Ask who needs to see the type. If the answer is "only our code", use a local type — it keeps provenance obvious and can be deleted in one place. If the answer is "the framework, at call sites we do not own", augmentation is the right tool, and I would then insist on: an owner-specific or namespaced member name; optional unless a runtime boundary genuinely guarantees presence; the augmentation living beside the code that populates the field, not in a shared types dump; and a note in the module explaining what sets it. If we publish libraries, I would additionally treat any augmentation reaching consumers as a public API decision reviewed like any other breaking-change surface — because for the consumer, that is exactly what it is.