[[TypeScript Declaration Files (.d.ts) Design]]

📌 Brief Summary
TypeScript declaration files (`.d.ts`) serve as the structural blueprint for type information in a JavaScript ecosystem, providing ambient declarations that describe the shape of existing code without containing implementation logic. Designing these files requires a sophisticated approach to "Ambient Type Definition," focusing on maintaining type safety across module boundaries while managing the complexity of declaration merging and global scope pollution.

📖 Core Content
The design of `.d.ts` files is centered around the concept of **Ambient Declarations**, which allow TypeScript to understand the existence of variables, functions, and classes that are defined in JavaScript or other compiled TypeScript files. Effective design involves several critical architectural patterns:

*   **Module Augmentation and Declaration Merging**: One of the most powerful features in `.d.rypt` design is declaration merging. This allows developers to extend existing interfaces or namespaces by defining them again in a `.d.ts` file. In professional interface design, this is used to "patch" third-party library types (e.g., adding a new property to `Express.Request`) without modifying the original source code.
*   **Ambient Module Declarations (`declare module`)**: When consuming non-module JavaScript libraries (like those using CommonJS or global scripts), `.d.ts` design relies on `declare module "library-name"` syntax. The challenge here lies in accurately mapping the dynamic nature of JS objects to static TypeScript interfaces, often requiring the use of `any` sparingly and preferring `unknown` or specific structural types to preserve type integrity.
*   **Type Definition Granularity**: High-quality declaration design distinguishes between **Internal Types** (used only within the `.d.ts` for complex logic) and **Public API Types**. A well-designed file exports minimal, high-level interfaces while hiding implementation-specific complexity through private or unexported type aliases, reducing the cognitive load on the consumer of the library.
*   **Global vs. Module Scoped Declarations**: Design decisions must strictly govern whether types are placed in the global namespace (using `declare global`) or within a module scope. Overuse of the global namespace can lead to "Namespace Pollution," where name collisions occur across different libraries, undermining the predictability of the type system.
*   **Handling Side Effects and Ambient Imports**: Professional `.d.ts` design must account for files that contain top-level `import` or `export` statements. Once a file contains an `import`, it becomes a module, and all declarations within it are no longer global unless explicitly wrapped in `declare global`. This distinction is critical when designing type definitions for polyfills or environment-specific globals (like `window` or `process`).

🔗 Knowledge Connections
* Related Topics: [[Declaration Merging]], [[Module Augmentation]], [[Ambient Contexts]]
* Projects/Contexts: [[DefinitelyTyped]], [[TypeScript Compiler API]]
* Contradictions/Notes: While declaration merging provides flexibility, it can lead to "hidden" type changes that make debugging difficult; therefore, architectural preference is given to explicit interface extensions over implicit global overrides.

Last updated: 2026-04-17