Course contentsShow
← TypeScript
Lesson 1629 of 1,79637. Migrating JavaScript to TypeScriptFree lesson

Prototype Manipulation and Monkey-Patching

Typing code that extends built-in prototypes or third-party objects at runtime.

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.