Don't break the web

Don't break the web: new features must fit old pages

Every year, JavaScript gets new features. But the web is full of old pages that nobody will ever update, and browsers must keep running them. So every new feature has to fit next to all the old code already out there. This rule is called "don't break the web", and it explains some odd names in JavaScript.

var prices = [3, [4, [5]]];
console.log(prices.flat().length);
console.log(typeof prices.flatten);
console.log(typeof prices.includes, typeof prices.contains);

Line 1 makes an array with arrays inside it. Line 2 calls flat, which pulls the inner items up one level, so the array becomes [3, 4, [5]] and line 2 prints 3.

Line 3 prints undefined: there is no flatten method, even though that is the name most people expect. Line 4 prints function undefined: arrays have includes, but not contains.

The obvious names were tried first. In each case, a browser shipped the method for testing, and real websites broke. So the spec picked other names. This lesson shows exactly how that happens, and what it means for the code you write.

Web compatibility: old pages must keep working

Web compatibility means that a browser keeps running the pages that already exist. The Space Jam movie website from 1996 still works in today's browsers, almost exactly as it was built.

Imagine a browser that ships a change and breaks a popular site. Visitors don't know what changed. They only see that the site works in another browser, so they switch. Other browsers then refuse to ship the change. And a spec that browsers won't follow is just a document nobody uses. So the spec follows what browsers can really ship.

Even a famous mistake has to stay. typeof null gives "object", a bug from the first version of JavaScript in 1995.

var nothing = null;
console.log(typeof nothing);
console.log(typeof nothing === "object");

Line 1 stores null, which means "no value". Line 2 prints object, which is wrong: null is not an object. Line 3 prints true.

A proposal once tried to make typeof null give "null". It was turned down, because old code like line 3 counts on the answer "object". The null internals lesson explains where the mistake came from.

New keywords are a problem too. Before 2015, let had no job in JavaScript, so old code could use it as a variable name.

var let = 3;
var async = 4;
var of = 5;
console.log(let + async + of);

Lines 1 to 3 make variables named let, async and of. Each of these words has a job in modern JavaScript, but sloppy code, the code without "use strict", still allows them as names. Line 4 prints 12.

Strict mode was new in 2009, so no old page used it. That made it safe to reserve let there.

"use strict";
var let = 3;
console.log(let);

Line 1 makes the script strict. Line 2 uses let as a name, which strict code doesn't allow, so the whole script is a SyntaxError.

Not every change is risky. Read each row of the table as: "a change of this kind does this to old websites."

New syntax is the safest change: code like a?.b was a SyntaxError before, so no working page contains it. New names are the risky ones, because old code may already use them.

SmooshGate: why flatten became flat

In 2018, a new array method called flatten was almost finished. Firefox turned it on for testing, and some websites broke. The proposal's author joked that it could be renamed smoosh. Many people took the joke seriously, and the fuss got the name SmooshGate.

The broken sites used MooTools, a library that was popular in the late 2000s. To see what went wrong, you need one idea first: enumerable. Every property has an enumerable setting. A for…in loop visits only the enumerable ones.

var methods = {};
methods.flatten = function () {};
Object.defineProperty(methods, "flat", {
  value: function () {},
  enumerable: false,
});
for (var key in methods) {
  console.log(key);
}

Line 2 adds flatten with a plain assignment. A property made this way is enumerable.

Lines 3 to 6 add flat with Object.defineProperty, which lets you choose the settings. Line 5 makes it not enumerable, the way browsers add their built-in methods. Lines 7 to 9 loop over the names, and only flatten is printed.

The second idea is the surprise. Assigning to a property that already exists only changes its value. Its settings stay as they were.

var methods = {};
Object.defineProperty(methods, "flatten", {
  value: function () {},
  enumerable: false,
  writable: true,
});
methods.flatten = function () {};
console.log(Object.keys(methods).length);

Lines 2 to 6 make a flatten property that is not enumerable but can be changed. Line 7 assigns a new function to it. The value changes, but the property stays not enumerable, so Object.keys, which lists enumerable names, finds nothing. Line 8 prints 0.

Now the MooTools pattern. It added its own flatten to every array, then copied all of its array methods to its own list type, Elements, with a for…in loop.

Array.prototype.flatten = function () {
  return "library flatten";
};
var Elements = {};
for (var key in Array.prototype) {
  Elements[key] = Array.prototype[key];
}
console.log(typeof Elements.flatten);

Lines 1 to 3 add the library's flatten to Array.prototype, the object all arrays share their methods from. It is a plain assignment, so the property is enumerable.

Lines 5 to 7 copy every enumerable property into Elements. Built-in methods like map are skipped, but flatten is copied, so line 8 prints function. This is what happens in today's browsers.

Now pretend the browser had shipped a built-in flatten. The program below adds it first, the way a browser would.

Object.defineProperty(Array.prototype, "flatten", {
  value: function () {},
  enumerable: false,
  writable: true,
  configurable: true,
});
Array.prototype.flatten = function () {
  return "library flatten";
};
var Elements = {};
for (var key in Array.prototype) {
  Elements[key] = Array.prototype[key];
}
console.log(typeof Elements.flatten);

Lines 1 to 6 add a built-in flatten, not enumerable. Lines 7 to 9 are the library's assignment. flatten already exists, so only its value changes, and it stays not enumerable.

Lines 11 to 13 copy the enumerable properties. flatten is skipped, so line 14 prints undefined. Every site that called flatten on an Elements list now throws a TypeError.

1Object.defineProperty(Array.prototype, "flatten", {Run2  value: function () {},3  enumerable: false,4  writable: true,5  configurable: true,6});7Array.prototype.flatten = function () {8  return "library flatten";9};10var Elements = {};11for (var key in Array.prototype) {12  Elements[key] = Array.prototype[key];13}14console.log(typeof Elements.flatten);

Press Step and watch the enumerable setting beside line 3. It stays false after line 7. This replays the example code; it isn't a view inside the JavaScript engine. It runs on a stand-in for Array.prototype, so this page's arrays don't change.

Why not make the built-in flatten enumerable? Then every old for…in loop over an array would suddenly visit an extra flatten name, and break different sites. Why not fix MooTools? A fixed version only helps sites that update, and the broken ones are the ones nobody updates. So in May 2018, the committee renamed it.

var prices = [3, [4, [5]]];
console.log(prices.flat().length);
console.log(prices.flat(Infinity).join(" "));
console.log([3, 4].flatMap((p) => [p, p * 2]).join(" "));

Line 2 flattens one level, so the array has 3 items and line 2 prints 3. Line 3 passes Infinity, which flattens every level, and prints 3 4 5.

Line 4 uses flatMap, which runs a function on each item and flattens the results one level. Each price becomes a pair, so it prints 3 6 4 8.

contains became includes, and other renamed features

flatten wasn't the first time. In 2014, arrays were going to get a contains method. MooTools had its own array contains, with the same copy problem. So in November 2014, the committee renamed it to includes, and renamed the string method contains to match.

var menu = ["tea", "cake"];
console.log(menu.includes("tea"));
console.log("teacup".includes("cup"));
console.log(typeof menu.contains, typeof "tea".contains);

Line 2 asks whether the array holds "tea" and prints true. Line 3 asks whether the string holds "cup" and prints true. Line 4 prints undefined undefined: neither has contains.

The page's own objects still use the old word. The list of classes on an element, element.classList, has a contains method, so you will see both names in real code.

Global names can clash too. Browsers call the global object window, and Node.js calls it global. A proposal tried to add global to browsers as a name that works everywhere. Old code like this stopped working.

var place = typeof global !== "undefined" ? "Node.js" : "a browser";
console.log(place);

Line 1 checks whether a name global exists. In a browser it doesn't, so place is "a browser", and line 2 prints a browser.

If browsers added global, the same line would decide it was running in Node.js, and the site would take the wrong path. That broke flickr.com and other sites. So the name became globalThis.

console.log(typeof globalThis);
console.log(globalThis === this);

Line 1 prints object. Line 2 prints true: at the top of a classic script, this is the global object too.

The newest rename was for grouping. The plan was an array method groupBy, but old versions of a library called Sugar added their own groupBy to arrays. The next try, group, clashed with other old code. So the committee moved it off arrays entirely.

var menu = [
  { name: "tea", kind: "drink" },
  { name: "cake", kind: "food" },
  { name: "juice", kind: "drink" },
];
var groups = Object.groupBy(menu, (item) => item.kind);
console.log(groups.drink.length, groups.food.length);
console.log(typeof menu.groupBy, typeof menu.group);

Lines 1 to 5 make a menu. Line 6 calls Object.groupBy, a static method: one that lives on Object itself, not on every array. It sorts the items into groups by the kind the function returns.

Line 7 prints 2 1: two drinks and one food. Line 8 prints undefined undefined: arrays got neither name.

Read each row of the table as: "the first name was this, it couldn't ship for this reason, so this shipped instead."

Symbol.unscopables: hiding new methods from old with blocks

Old code has one more trap: the with statement. Inside with (list) { … }, every plain name is looked up on list first. The with statement lesson explains it.

So every new array method is a new name that with could find first. When 2015 added methods such as values, keys and entries, old with blocks that used variables with those names would have found the methods instead.

The fix is a list called Symbol.unscopables. Names on that list are skipped by with.

var values = [3, 4];
with ([1, 2]) {
  console.log(values.join(" "));
}

Line 1 makes a variable values. Line 2 starts a with block for the array [1, 2]. That array has a values method, but the name is on the list, so line 3 skips it, finds the variable from line 1, and prints 3 4.

Here is what old code would have seen without the list.

var values = [3, 4];
var list = [1, 2];
Object.defineProperty(list, Symbol.unscopables, { value: {} });
with (list) {
  console.log(typeof values);
}

Line 3 gives this one array its own, empty Symbol.unscopables list. Now nothing is skipped. Inside the block, line 5 finds the array's values method before the variable, and prints function.

var hidden = Array.prototype[Symbol.unscopables];
console.log(hidden.values, hidden.flat, hidden.includes);
console.log(hidden.map);

Line 1 reads the list from Array.prototype. Line 2 prints true true true: values, flat and includes are all on it. Line 3 prints undefined: map is older than the list, and old with code already lived with it, so it was never added.

Most new array methods are added to this list as they ship, so old with code keeps working.

Use counters and deprecation: measuring before removing

Before a browser removes or changes anything, it needs to know how many pages would break. Guessing isn't enough. Browsers measure it.

A use counter is a small counter built into the browser. For each page load, it records whether the page used a feature, such as substr. Chrome adds up these counts from many users who allow it, and publishes the share of page loads that use each feature on chromestatus.com. Firefox collects similar numbers.

Here is a tiny model of a use counter, written for this lesson, with four page loads.

var pages = [
  ["substr", "map"],
  ["map"],
  ["escape", "map"],
  ["map", "substr"],
];
var used = {};
for (var page of pages) {
  for (var name of page) {
    used[name] = (used[name] || 0) + 1;
  }
}
for (var name in used) {
  console.log(name + ": " + (used[name] / pages.length) * 100 + "%");
}

Lines 1 to 6 list four page loads, and the features each one used. Line 7 makes an empty object, used, for the counts.

Lines 8 to 12 go through each page, and line 10 adds 1 for each feature that page used. Lines 13 to 15 divide each count by the 4 pages and print substr: 50%, map: 100% and escape: 25%.

1var pages = [2  ["substr", "map"],3  ["map"],4  ["escape", "map"],5  ["map", "substr"],6];7var used = {};Run8for (var page of pages) {9  for (var name of page) {10    used[name] = (used[name] || 0) + 1;11  }12}13for (var name in used) {14  console.log(name + ": " + (used[name] / pages.length) * 100 + "%");15}

Press Step and watch the counts beside line 7 grow, one page at a time. This replays the example code; it isn't a view inside the JavaScript engine.

The real numbers are much smaller. A feature used on even a tiny share of page loads can still mean many thousands of websites. When a browser team does decide to remove a feature, it usually follows these steps:

1. Measure how many page loads use it, with a use counter.
2. Deprecate it: print a warning in the developer console, so the people who run those sites can find out.
3. Wait, and watch the number fall.
4. Remove it, if the number is small enough and the other browsers agree.

Chrome removed Object.observe this way in 2016. For the language itself, removal is rare. More often, the spec is changed to describe what browsers already do. That is how the old features in the Annex B lesson got into the spec.

Writing code that keeps working as JavaScript grows

MooTools did nothing strange for its time. Its mistake was changing objects it didn't own. Your code can avoid that mistake, so it keeps working when JavaScript adds new features.

Adding your own methods to Array.prototype causes trouble even today.

Array.prototype.last = function () {
  return this[this.length - 1];
};
var prices = [3, 4];
for (var key in prices) {
  console.log(key);
}

Lines 1 to 3 add a last method to every array with a plain assignment, so it is enumerable. Lines 5 to 7 loop over an array with for…in, which visits every enumerable name. It prints 0, 1, and then last, which isn't an item at all.

And if JavaScript ever ships its own last, your version would replace it on every page that loads your code.

function last(list) {
  return list[list.length - 1];
}
var prices = [3, 4];
console.log(last(prices));
console.log(prices.at(-1));

Lines 1 to 3 make last a plain function that takes the array as a value. It changes nothing shared, so it can't clash with anything. Line 5 prints 4.

Line 6 uses at(-1), a standard method that counts from the end when given a negative number. It also prints 4.

Sometimes you must support old browsers that lack a standard method. Code that adds a missing standard feature is called a polyfill. A careful polyfill checks first, and adds the method the way a browser would.

if (!Array.prototype.at) {
  Object.defineProperty(Array.prototype, "at", {
    value: function (index) {
      return this[index < 0 ? this.length + index : index];
    },
    writable: true,
    configurable: true,
  });
}
console.log([3, 4].at(-1));

Line 1 checks whether the browser already has at. Every modern browser does, so lines 2 to 8 are skipped. In an old browser, lines 2 to 8 would add at with Object.defineProperty, not enumerable, so for…in loops don't see it.

Line 4 handles a negative index by counting back from the length. Line 10 prints 4 either way.

Now try being the browser. The playground runs an old website with a MooTools-style library. Pick a name and ship a built-in method with it. Guess first: does the old site still work?

Object.defineProperty(Array.prototype, "flatten", {
  value: function () {},
  enumerable: false,
  writable: true,
  configurable: true,
});

Array.prototype.flatten = function () {};
Array.prototype.contains = function () {};
var Elements = {};
for (var key in Array.prototype) {
  Elements[key] = Array.prototype[key];
}
console.log("flatten: " + typeof Elements.flatten);
console.log("contains: " + typeof Elements.contains);

Ship flatten or contains: the library's copy loop skips the clashing name, and the old site breaks. Ship flat or includes: the library never uses those names, and everything keeps working. That is exactly why the committee chose them.

Three habits keep your code safe as JavaScript grows: don't add to objects you don't own, such as Array.prototype; loop over arrays with for…of, not for…in; and check for a feature before you add it.

Common mix-ups

Most mix-ups come from thinking that only removing a feature can break things, or that a broken library is the library's problem alone.

• "Adding a feature can't break old code." No. A new name can clash with a name old code already uses, as flatten, contains and global did.
• "The committee renamed flatten to smoosh." No. That was a joke. The name that shipped is flat.
• "Assigning to a property makes it enumerable." No. Assigning to a property that already exists keeps its settings. Only a new property made by assignment is enumerable.
• "Browsers could just tell old sites to update." No. Many old sites have nobody looking after them, so they never update.
• "let is reserved everywhere." No. Only in strict code. Sloppy code still allows it as a name.
• "typeof null will be fixed one day." No. Too much code depends on "object", so the fix was turned down.
• "A use counter counts every call." No. It records once per page load whether the page used the feature at all.

The table below puts three of these side by side. Read each row as: "people often think this about the topic, but this is true."

Practice exercises

Every program below is a sloppy classic script. For each one, ask which names old code and new code both want, and which properties are enumerable. Guess first, then run it.

var shelf = {};
Object.defineProperty(shelf, "flat", { value: 1, enumerable: false, writable: true });
shelf.flat = 2;
shelf.extra = 3;
console.log(Object.keys(shelf).join(" "), shelf.flat);

var shelf = {};
Object.defineProperty(shelf, "flat", { value: 1, enumerable: false, writable: true });
shelf.flat = 2; // still hidden: the property already existed
shelf.extra = 3; // a new property, so it is enumerable
console.log(Object.keys(shelf).join(" "), shelf.flat);

var let = 1;
var async = 2;
var await = 3;
console.log(let + async + await);

var count = 1;
var total = 2;
var wait = 3;
console.log(count + total + wait);

var keys = "outer";
with ([3, 4]) {
  console.log(typeof keys, length);
}

var keys = "outer";
var list = [3, 4];
console.log(typeof keys, list.length);

Array.prototype.sum = function () {
  return this.reduce((a, b) => a + b, 0);
};
var prices = [3, 4];
var count = 0;
for (var key in prices) {
  count = count + 1;
}
console.log(count);

function sum(list) {
  return list.reduce((a, b) => a + b, 0);
}
var prices = [3, 4];
var count = 0;
for (var price of prices) {
  count = count + 1;
}
console.log(count, sum(prices));

var global = { name: "pretend" };
var place = typeof global !== "undefined" ? "Node.js" : "a browser";
console.log(place);

var global = { name: "pretend" };
var isNode = typeof process !== "undefined" && Boolean(process.versions && process.versions.node);
console.log(isNode ? "Node.js" : "a browser");

var arrayMethods = {};
Object.defineProperty(arrayMethods, "contains", { value: function () {}, writable: true, configurable: true });
arrayMethods.contains = function () { return "library"; };
arrayMethods.flatten = function () { return "library"; };
var Elements = {};
for (var key in arrayMethods) {
  Elements[key] = arrayMethods[key];
}
console.log(typeof Elements.contains, typeof Elements.flatten);

var arrayMethods = {};
Object.defineProperty(arrayMethods, "includes", { value: function () {}, writable: true, configurable: true });
arrayMethods.contains = function () { return "library"; };
arrayMethods.flatten = function () { return "library"; };
var Elements = {};
for (var key in arrayMethods) {
  Elements[key] = arrayMethods[key];
}
console.log(typeof Elements.contains, typeof Elements.flatten);

Check your understanding

For each question, ask what old code already does with a name, and whether a new feature would change that. Each answer explains why it's right or wrong.

Key takeaways

JavaScript grows by adding, carefully, around everything that already exists. Knowing the rule explains odd names, and helps you write code that won't be the next MooTools.

• Browsers must keep old websites working, and the spec follows what browsers can ship.
• New syntax is usually safe. New names are risky, because old code may already use them.
• Assigning to a property that already exists keeps it not enumerable. That is why a built-in flatten broke MooTools' copy loop.
• flatten became flat, contains became includes, global became globalThis, and groupBy became Object.groupBy.
• Symbol.unscopables keeps new array methods out of old with blocks.
• Use counters measure how many page loads use a feature. Removal is rare, and comes after a deprecation warning.
• Don't add to objects you don't own, don't use for…in on arrays, and check before you polyfill.

Coming next: The early editions: ES1 to ES5. It tells how JavaScript was first standardized, and about the edition that almost broke it.