Prototype Manipulation and Monkey-Patching
You'll learn how to safely type code that modifies built-in prototypes or extends third-party objects at runtime.
What Is Prototype Manipulation?
In JavaScript, you can modify built-in prototypes (like Array.prototype or String.prototype) or extend third-party library objects at runtime. This practice—often called monkey-patching—lets you add methods or properties to existing types after they're defined.
The problem? TypeScript doesn't know about these runtime additions by default. If you call a custom method you've added to Array.prototype, TypeScript throws an error saying the property doesn't exist—even though it works perfectly at runtime.
The Runtime vs Compile-Time Gap
Imagine you add a helper method to all arrays:
// Runtime JavaScript
Array.prototype.sum = function() {
return this.reduce((a, b) => a + b, 0);
};
// TypeScript doesn't know about .sum() yet
const nums = [1, 2, 3];
nums.sum(); // ❌ Property 'sum' does not exist on type 'number[]'
The code runs fine, but TypeScript can't type-check it without help.
Typing Prototype Extensions with Declaration Merging
You solve this using global augmentation and interface merging. Declare the new member in the appropriate global interface:
// Tell TypeScript about your prototype addition
declare global {
interface Array<T> {
sum(this: number[]): number;
}
}
// Now implement it
Array.prototype.sum = function(this: number[]) {
return this.reduce((a, b) => a + b, 0);
};
// Now TypeScript understands
const nums = [1, 2, 3];
const total = nums.sum(); // ✅ number
Notice the this parameter constraint—it ensures you can only call .sum() on numeric arrays.
Typing Third-Party Object Extensions
Sometimes libraries expose global objects you want to extend:
// Imagine a third-party library exposes a global config
declare global {
interface Window {
myAppConfig: {
apiUrl: string;
debug: boolean;
};
}
}
// Now you can safely access it
window.myAppConfig = {
apiUrl: 'https://api.example.com',
debug: true
};
console.log(window.myAppConfig.apiUrl); // ✅ string
When Monkey-Patching Happens
Common scenarios include:
- Polyfills: Adding missing browser APIs
- Framework extensions: Adding methods to jQuery objects or Express request objects
- Debugging utilities: Adding
.inspect()or.log()to built-ins during development - Legacy code migration: Maintaining compatibility with old code patterns
The Risks and Best Practices
Prototype manipulation is powerful but dangerous:
- Collisions: Your method might conflict with future standard additions
- Maintainability: Other developers won't expect modified prototypes
- Testing: Pollutes the global environment
Best practice: Only use prototype manipulation when absolutely necessary (polyfills, framework requirements). Always document extensions clearly, and prefer composition over modification when possible.
Key Takeaway: Use declare global with interface merging to type runtime prototype modifications, but treat monkey-patching as a last resort reserved for polyfills and framework integration requirements.