Extending built-ins & instanceof

The idea: customize a standard tool without changing everyone’s

JavaScript’s built-ins are already powerful. Array knows about numeric indexes and length. Map stores any value as a key. Classes let you build a specialized version of those tools with extends instead of changing the global tool for every file on the page.

That distinction matters because an earlier lesson warned you not to modify built-in prototypes. Adding Array.prototype.sum changes every array in the program. Creating class NumberList extends Array changes only the lists you intentionally create.

This lesson covers four connected tools: extending Array and Map, Symbol.species, ordinary instanceof , and Symbol.hasInstance. Custom errors use the same inheritance idea, but Throwing & custom errors gets its own lesson later.

An Array subclass is still an array: numeric indexes, length, push, pop, iteration, and methods like map still work. You add names that make sense for your domain.

1class TodoList extends Array {2  d = new Set();3  add(t) {4    this.push(t);5    return this.length;6  }7  complete(t) {8    this.d.add(t);9  }10  open() {11    return this.filter(Boolean);12  }13}14 15const todos = new TodoList("a", "b");16todos.add("c");17todos.complete("b");18const open = todos.open();19const up = todos.map(String);20console.log(todos.length);21console.log(open instanceof TodoList);22console.log(up.constructor.name);

The TodoList example has a custom add method and a complete method, but it still grows with push, shrinks with pop, and reports length. That makes a subclass feel natural when the object really is a list with a few extra rules.

Map subclasses are often calmer because a map’s surface is smaller. The example below changes one behavior: a missing key returns a default value instead of undefined. The important line is super(entries), which lets Map initialize its real internal storage before the subclass adds its own field.

1class DefaultMap extends Map {2  constructor(fallback, entries) {3    super(entries);4    this.fallback = fallback;5  }6  get(key) {7    return super.has(key) ? super.get(key) : this.fallback;8  }9}10 11const scores = new DefaultMap(0, [["Ada", 10]]);Run12console.log(scores.get("Ada"));13console.log(scores.get("Lin"));14console.log(scores instanceof Map);

Here is the subtle part. Some built-in methods create a new collection. todos.map(...) does not mutate todos; it makes another array-like result. For an Array subclass, JavaScript asks a well-known symbol: “Which constructor should I use for the new result?”

1class TodoList extends Array {2  d = new Set();3  add(t) {4    this.push(t);5    return this.length;6  }7  complete(t) {8    this.d.add(t);9  }10  open() {11    return this.filter(Boolean);12  }13}14 15const todos = new TodoList("a", "b");Run16todos.add("c");17todos.complete("b");18const open = todos.open();19const up = todos.map(String);20console.log(todos.length);21console.log(open instanceof TodoList);22console.log(up.constructor.name);

The default is real: map and filter on an array subclass return the subclass. If that would confuse callers, add static get [Symbol.species]() { return Array; } so derived arrays are plain arrays. That trade-off is about API design: do result arrays need your custom methods, or should they be ordinary data?

value instanceof Constructor is not a type-name check. In the ordinary case it looks for Constructor.prototype somewhere on value’s prototype chain. If it finds that object, the answer is true; otherwise it is false.

1class Collection {}2class Stack extends Collection {}3 4const stack = new Stack();Run5console.log(stack instanceof Stack);6console.log(stack instanceof Collection);7console.log(stack instanceof Object);8console.log(3 instanceof Number);9Object.setPrototypeOf(stack, Collection.prototype);10console.log(stack instanceof Stack);11console.log(stack instanceof Collection);

That explains three common surprises. First, subclass instances also count as instances of their base class. Second, primitives like 3 are not instances of wrapper constructors like Number. Third, changing an object’s prototype chain can change future instanceof answers. You rarely call Object.setPrototypeOf in production because it can hurt performance, but it is a great microscope for this rule.

A class can intercept instanceof by defining a static method named with Symbol.hasInstance. JavaScript calls that method with the left-hand value and trusts the boolean it returns. This is metaprogramming, so use it sparingly and document the rule clearly.

1class Duck {Run2  static [Symbol.hasInstance](value) {3    return typeof value?.quack === "function";4  }5}6 7const toy = { quack() { return "squeak"; } };8const rock = { sound: "thud" };9console.log(toy instanceof Duck);10console.log(rock instanceof Duck);

The Duck example is duck typing: “If it quacks like a duck, treat it like a duck.” It accepts any object with a callable quack method, even if that object was never constructed by Duck. That can be elegant for small capability checks, but surprising if readers expect instanceof to mean “built by this class.”

Where you’ll use this

Most application code does not need many built-in subclasses. Reach for them when the phrase “is a kind of array/map” stays true after you add behavior. Good examples include a fixed vocabulary list with helper methods, a DefaultMap for counters, or a domain list that prints itself nicely in debugging tools.

class CounterMap extends Map {
  add(key, amount = 1) {
    const next = (this.get(key) ?? 0) + amount;
    this.set(key, next);
    return next;
  }
}

const views = new CounterMap();
views.add("/home");
views.add("/home", 2);
console.log(views.get("/home")); // 3

Notice that this example does not need Symbol.species because Map.prototype.set mutates and returns the same map. Species matters most when methods create new collections.

Pitfalls & trade-offs

Subclassing is safer than mutating built-in prototypes, but it is not free. Constructors, species, cross-realm values, and reader expectations all matter.

class BadList extends Array {
  constructor(items) {
    super(items);
  }
}

class GoodList extends Array {
  constructor(...items) {
    super();
    this.push(...items);
  }
}

console.log(new BadList(3).length);
console.log(new BadList(["a", "b"]).length);
console.log(new GoodList(3).length);

Prefer rest parameters when you mean “these are the items”: constructor(...items) { super(); this.push(...items); }. If you mean “an initial capacity,” say so clearly and test the empty-slot behavior.

Common misconceptions

• “Subclassing Array changes all arrays.” No. Editing Array.prototype changes all arrays; subclassing creates a separate class.
• “Array methods always return plain arrays.” Not for subclasses. map and filter return the subclass by default unless species says otherwise.
• “instanceof checks the class name.” It checks prototype-chain identity, not a string name.
• “instanceof is a perfect type check.” Cross-realm objects, changed prototypes, primitives, and Symbol.hasInstance can all surprise you. Use Array.isArray when you specifically need arrays.
• “Symbol.hasInstance is just syntax decoration.” It fully controls the right-hand class’s instanceof result.

Key takeaways

• Subclass built-ins when your object really is a specialized built-in, and avoid changing global prototypes.
• Array subclass methods such as map and filter return the subclass by default.
• Symbol.species lets a subclass choose the constructor used for derived results.
• Ordinary instanceof searches the prototype chain for Constructor.prototype.
• Symbol.hasInstance lets a class replace that search with a custom boolean test.

One-line definition: Extending built-ins creates a specialized version of a standard JavaScript object, while instanceof answers membership by prototype chain unless a class defines a custom has-instance hook.

Up next: Mixins & composition.