DEV Community: Bugsnag

Anatomy of a JavaScript Error

Christian Schlensker — Wed, 28 Mar 2018 00:00:00 +0000

This blog is the second part in a two-part series on JavaScript debugging. Read part one to learn about the inner workings of JavaScript source maps with code examples.

It’s not a pretty sight when an application dies. Error messages can be difficult to understand, and we sometimes have to put our investigator hats on to solve the mystery and find the culprit.

Most software developers spend all their time avoiding errors, but here at Bugsnag, our entire product is built around capturing and managing errors. As such, we deal a lot with the ins and outs of JavaScript errors and their related APIs. In this blog, we’ll take a look at the different types of JavaScript errors, why they happen, and how to handle them in your application.

Automatically generated errors and why they happen

The first step to understanding JavaScript errors is to understand where they come from. Most JavaScript errors that occur in the wild are automatically generated from the JavaScript engine. There are many types of errors but they typically fall into one of 3 classes.

`TypeError`

One of the most common classes of error, this occurs when some value is not the type it’s expected to be. Frequently this happens when calling something like a function that actually isn’t a function because it is “undefined” or some other value.

window.foo()
  // => TypeError: window.foo is not a function
[].length
  // => 0
[].length()
  // => TypeError: array.length is not a function

Another common occurrence of TypeError is when trying to access a property on an undefined value.

window.foo.bar
  // => TypeError: Cannot read property 'bar' of undefined

`SyntaxError`

These errors occur when the JavaScript engine is parsing a script and encounters syntactically invalid code. If a JavaScript file contains a syntax error, none of the code in the file will execute.

console.log('hello')
    notValid(

Not only will this code produce an error, but the console.log before the invalid syntax won’t even run.

`ReferenceError`

These occur when code refers to a value that does not exist in the current scope. For example:

console.log(somethingMadeUp)
  // => ReferenceError: somethingMadeUp is not defined

Manually throwing errors

Not all errors are accidental. They can also be triggered intentionally. When an application isn’t functioning correctly, it is preferable to fail loudly, explicitly, and clearly. Otherwise the cause of the problem could be unclear or, worse yet, not noticed by the developer at all.

The simplest way to manually trigger an error is by using a throw statement:

throw 'Invalid input';

This will automatically create an instance of an Error object with the message “Invalid input”, but the error instance can also be created manually and passed around.

let error = new Error('Invalid input')
// later
throw error;

Manually throwing errors is especially helpful for library authors as they can inform a developer using their library how they made a mistake. For example, when a function is called with an invalid argument.

function sayName(name) {
  if(typeof name !== 'string') {
    throw new Error('name must be a string, received:' + typeof name);
  }
}

Intercepting errors using try/catch

If you know that a particular bit of code is risky and might throw an error it can be wrapped in a try/catch statement.

try {
  someCrashyFunction()
} catch(error) {
  // display it to the user maybe
  // and report it to Bugsnag
  Bugsnag.notify(error);
}

Try catch blocks can also be nested inside each other. Once the error is handled, if it is desirable to pass the error higher up the call stack, it can be re-thrown.

try {
  someCrashyFunction()
} catch(error) {
  // Handle the error here:
  // ...
  // then pass it up the chain
  throw error;
}

Gotta catch ‘em all with global error handling

Even with the most diligently written code, errors can sometimes still slip through. It’s okay. Mistakes happen. When they do, it’s important to know about it quickly. That’s where error reporting tools like Bugsnag fit in.

How global error handling works

To catch and handle all errors that might happen in a browser session, we can hook into the window.onerror event handler. This allows setting up a global handler for any unhandled errors that might pop up. This is what the Bugsnag error reporting library hooks into for reporting uncaught errors from browser based JavaScript applications.

In a Node environment, there is no window object so the equivalent approach is to use process.on('unhandledException, callback).

Global error handling is not a replacement for the fine grained control that can be achieved from try/catch statements. Instead, it serves as a safety net for exceptions that make it through the earlier lines of defense. By placing the error handling closer to the source of the potential problem, we will likely have a better idea of how best to deal with it and possibly recover before the user even notices a problem. And for everything that does slip through the cracks, we have peace of mind knowing our global error handler will surface the issues to us.

Broken promises

With the advent of ES2015, we were given first class support for Promises in JavaScript which greatly improves the clarity of asynchronous code. One drawback of Promises is they have the tendency to swallow errors that occur in their .then() method. If there is an error generated in this method it will never bubble up to the global error handler and thus will not be reported to Bugsnag.

fetch('https://my-api.endpoint')
.then((response) => {
  response.thisMethodDoesNotExist() // this error will be swallowed

  doSomethingElse() // this code will never run
})

This is why it’s always best practice to add a catch statement for all promise chains so any errors can be handled.

fetch('https://my-api.endpoint')
  .then((response) => {
      response.thisMethodDoesNotExist()
    doSomethingElse() // this code will never run
  })
  .catch((error) => {
    console.error(error)
    // # => response.thisMethodDoesNotExist is not a function
    Bugsnag.notify(error)
    // show the error to the user
  });

This solves the problem of invisible errors, but it has a couple of drawbacks. First of all, it is cumbersome to write this error handling code for every promise we use. Secondly, if an error occurs in the catch statement, it will be swallowed as well and we are right back where we started. In order to get around this, we can hook into a global unhandled promise rejection handler.

window.addEventListener("unhandledrejection", (event) => {
  console.error(event.reason);
  // report the error here
});

Now any promise that fails and does not have an explicit catch handler will trigger the unhandledrejection event.

If you are using the bugsnag-js notifier, then unhandled promise rejections will automatically be caught and logged to Bugsnag so you don’t have to worry about missing them.

Properties of an error

Once an error has been captured, it can be inspected in order to pull useful information out of it. Most important are the name , message , and stack properties.

The first bits of useful information are the error’s name and message. These fields are what get displayed for error listings in the Bugsnag inbox as well as what gets printed to the browser console.

The message of an error is set when it is initialized.

let error = new Error('This is my message')
    console.log(error.message)
    // => This is my message

By default the error’s name is the same as its constructor function so when an error is created using new Error('oh no!') or throw('oh no!' its name will be “Error”. If you create an error using new TypeError('oh no!') its name would be “TypeError”. The name of an error can be overridden simply by setting it.

let myError = new Error('some message');
    myError.name = 'ValidationError';
    throw myError;

Here we’ve changed the error name to ValidationError, and this will be reflected in the Bugsnag dashboard; however, in some browsers (e.g. Chrome), it will still be printed to the console as “Error”. To get around this, custom error classes can be used which we’ll talk about a little later in this article.

Stacktraces

The Error.prototype.stack property contains the stacktrace for the error. The stacktrace is stored on the error as a simple string where each function in the stack is separated by newline characters. In the bugsnag-js library, we use a utility called error-stack-parser to parse the stacktrace into a useful data structure.

It is important to note that the stacktrace is determined by where the error was initialized, not where it was thrown. This means that if an error is created and returned from functionA and then thrown in functionB, the top of the stacktrace will be functionA.

It’s likely that you’ll minify your JavaScript code, and when you do, the lines in the stacktrace will not match up with the original source files. In order to find the original source, we use source maps to look up and translate the stacktrace. Learn more about how source maps work in our other blog in this series the Anatomy of source maps.

Creating custom error types

Sometimes it is useful to create custom error types in addition to the ones that are already built into the JavaScript language. One possible use case for this is an application could be set up to handle different types of errors in different ways.

For example, in a Node application, perhaps we would have a special error class for validation errors in API requests. If a validation error is caught, the application would know to respond with an HTTP 400 status.

Custom errors also allow capturing additional custom data with an error that is specific to that error class.

ES6 classes make the task of defining custom error types extremely trivial. For example, if we wanted to throw a specific type of error for invalid fields, we could define it like this.

class ValidationError extends Error {
  constructor(field, reason) {
    super(reason);
    this.field = field;
    this.reason = reason;
    // the next line is important so that the ValidationError constructor is not part
    // of the resulting stacktrace
    Error.captureStackTrace(this, ValidationError);
  }

  // we can also define custom methods on this class
  prettyMessage() {
     return `ValidationError: [${this.fields}] reason: ${this.reason}`;
     // ex: "ValidationError: [age] reason: Must be a number"
  }
}

Then the error handling code can make use of instanceof to determine what type of error was thrown and respond appropriately. In an Express.js application for example, custom middleware can be set up to accomplish this.

app.use(function errorHandler (err, req, res, next) {
 if (error instanceof ValidationError) {
   // respond with 400 status and include relevant error details
   return res.status(400).json({
      type: error.name,
      message: error.prettyMessage(),
      field: error.field,
    });
  } else {
    // This is some other kind of error, let the default error handler deal with it
    next(error)
  }
})

Although this example is using Express.js middleware, a similar approach can be taken in other types of JavaScript applications using a simple try/catch.

try {
  submitForm();
} catch (error) {
  if (error instanceof ValidationError) {
    // show the error to the user
    displayErrorMessage(error.prettyMessage());
  } else {
    // pass it to the default error handler
    throw error;
  }
}

Without custom error classes, this kind of specialized error handling would be much more difficult. It would require doing something hacky, like comparing the error message or some custom property. Luckily, using the error class for comparison is much more explicit.

Wrapping up

When applications fail, ideally they provide a smooth experience for the user, but for the developer, they should fail loudly and clearly so the problem can be quickly analyzed. Properly utilizing the tools the JavaScript language provides for error handling can help to clarify the opaque anomalies in an application so they can be understood quickly and addressed.

Try Bugsnag’s JavaScript error reporting, free for 14-days.

Anatomy of source maps

Ben Gourley — Mon, 26 Mar 2018 00:00:00 +0000

This blog is first in a two-part series on JavaScript debugging. Learn about the inner workings of JavaScript source maps with code examples. Or, check out part two and read about the Anatomy of a JavaScript error.

Source maps are a cornerstone of modern JS and CSS development. When things are ticking along smoothly, it’s easy to overlook how crucial a role they play. If you’ve ever had a source map go wrong on you, it quickly exposes the complexity that, most of a time, they keep a lid on.

Have you ever wondered what they are for or how they work? What the content of a source map looks like? And – if you’ve opened one up – what on Earth the "…GACxB,IAAMC,GAAUD,EAAGE,SAInB…" mappings mean? If so, hold on to your hats!

The many transformations of JavaScript

These days, it’s rare that the code you read and write in your editor is what makes it into a browser. Transformations can include:

Concatenation and minification

Concatenating assets – joining the contents of multiple files into one – reduces the number of network requests required to serve the content.

The process of minifying, also known as “uglification”, reduces the number of bytes required to transfer the content over the network. This process can involve renaming local variables to shorter identifiers, replacing constant expressions with their calculated result, stripping all whitespace, and other complex optimizations.

People typically use Uglify for minification.

Module resolution

Separating code into manageable chunks is a technique that has been available to most respectable languages since their inception. JS, however, doesn’t provide a way (yet) to import code from other places, so this problem is solved by tooling.

Browserify led the way on this front, mimicking Node.js’s commonjs-ish require() functionality, and more recently Webpack arrived, which supports node-style require() along with the new ES module import spec.

Using new (or extended) JS features

As the JS spec has evolved, using a more modern version of JS than is supported by your audience’s browsers has become commonplace. Newer features of the language allow more robust, terse, and reasonable solutions so engineers are understandably keen to use them, but this requires a transformation.

Likewise, Facebook’s JSX extension – adding syntax for constructing DOM-like structures in React applications – is a widely used feature that no browser supports.

Babel is the most commonly used tool for transforming different “flavours” of JS into a more compatible form.

Writing in a totally different language

Finally, there’s a whole genre of program languages whose raison d’être is to compile to JS – Elm, CoffeeScript, TypeScript, PureScript, to name a few.

Debugging JavaScript errors using source maps

All of these transformations facilitate better ways of writing code. But what happens when you run it, and something doesn’t go as expected? What happens when you’re tasked with investigating some erroneous condition, or worse, in code you’re not 100% familiar with?

An example error:

The location points somewhere inside this file:

😩

When faced with a wall of minified code that bears little resemblance to anything in your editor, the task of stepping through or finding the cause of anything can be overwhelmingly tricky…

Here’s where source maps come in. Essentially a source map allows you to answer the question:

Given the line/col location in this generated code, in which file and at what line/col did it originate?

What’s in a source map?

The first iteration of the source map format was created for use in Closure Inspector, to aid with the debugging of obfuscated JS output from Closure Compiler. Now, the format is on its third major revision, jointly authored by representatives from Google and Mozilla.

The file’s format is JSON. Here’s a trimmed, annotated, real example from the bugsnag-js package:

# This is an example source map. Note that source maps are JSON, so comments *aren't* usually allowed!
{
   # "version"
   # Declares which version of the source map spec is being used, like a <!DOCTYPE> in html.
  "version": 3,

  # "sources"
  # A list of input source files that were used to generate the output.
  "sources": [
    "base/lib/es-utils.js",
    "node_modules/stackframe/stackframe.js",
    "base/client.js",
    "base/plugins/throttle.js",
    "browser/plugins/device.js",
    "browser/plugins/inline-script-content.js",
    # … the actual list is a lot longer than this, but the rest is omitted for brevity…
  ],

  # "names"
  # A list of identifiers used in the source code which were changed in or removed from the output.
  "names": [
    "schema", "apiKey", "defaultValue", "message", "validate" #…
  ],

  # "mappings"
  # This is the clever bit! These comma and semi-colon separated values are base64-encoded VLQ
  # values that point from every position in the output back to positions in the input sources.
  "mappings": "CAAA,SAAAA,GAAA,GAAA,iBAAAC,SAAA,…",

  # "sourcesContent"
  # This optional field can include the original source content for each file in
  # the "sources" property. This option should only be omitted if the tool using
  # the source map can retrieve the sources via url or from the filesystem.
  "sourcesContent": [
    "(function(f){if(typeof exports===\"object\"&&typeof…",
    "/*\n * Leaves breadcrumbs when the user interacts…",
    "module.exports = stringify\nstringify.default…",
    "// minimal implementations of useful ES functionality…",
    "const { isoDate } = require('./lib/es-utils')…",
    "const { filter, reduce, keys, isArray } =…",
    "module.exports = client =>\n client.app &&…",
    "(function(root, factory) {\n 'use strict';…",
    "const ErrorStackParser = require('error-stack-parser')…",
    "/**\n * cuid.js\n * Collision-resistant UID generator…",
    "const config = require('./config')\nconst BugsnagReport…",
    "const positiveIntIfDefined = require('../lib/positive-int-check')…",
    "module.exports = {\n releaseStage: {\n…",
    # ……
  ],

  # Some optional fields that are not used in this example…

  # "sourceRoot"
  # A prefix to add to each entry in the "sources" property when looking them up
  # on the network/disk.
  "sourceRoot": "/path/to/static/assets",

  # "file"
  # The name of the file this source map is for.
  "file": "bugsnag.min.js"
}

Hopefully, most aspects of the file make a lot of sense. Obviously, if it’s being sent over the network, there’ll be no pretty whitespace and there definitely wouldn’t be any comments, but the JSON has some sensibly named properties that don’t require a ton of head-scratching – except, that is, for the "mappings" key.

In short, "mappings" is a list of pointers to entries in the "sources" and "names" arrays for every “segment” in every line of the generated file. Each segment is separated by a comma , and each line is separated by a semi-colon ;. “Segment” – a rather vague term – refers to any parts of the line that can be mapped back to some original source: identifiers, operators, function calls, etc.

As you might imagine, this information can take up a lot of space; in previous versions of source maps, the map file could end up being around 10x the size of the mapped file! So in version 3, a format was introduced – Base64 VLQs – which is heavily optimized for space-saving.

There is an excellent explanation of the Base64 VLQ format on HTML5 Rocks if you want to understand the full strategy behind this encoding, but here we’re going to concentrate on a few examples where the mappings have been decoded and vaguely make sense to humans.

I’ve replaced the "mappings" property with content in the format below:

"mappings": {
  "0": [
   ^
   └── the line number of the output file

    "231 => source.js 5:64 foo"
      ^ ^ ^ ^
      │ │ │ └── the symbol name from the source file
      │ │ │
      │ │ └── the line:column position in the source file
      │ │
      │ └── the name of the source file
      │
      └── the column number of the output file

  ]
}

Here’s the code I used to do this.

Examining a source map from minification (UglifyJS)

First up we need some code. Here’s a function I wrote as part of a library that maintains the score during a tennis match:

function incrementSet (state, scorer, nonScorer) {
  scorer.games++
  var currentSet = state.players[PLAYER].sets + state.players[OPPONENT].sets
  if (!state.completedSets[currentSet]) state.completedSets[currentSet] = []
  state.completedSets[currentSet][PLAYER] = scorer.isPlayer ? scorer.games : nonScorer.games
  state.completedSets[currentSet][OPPONENT] = scorer.isPlayer ? nonScorer.games : scorer.games
  scorer.games = 0
  nonScorer.games = 0
  scorer.sets = scorer.sets + 1
  state.isFinalSet = scorer.sets + nonScorer.sets === state.config.numSets - 1
  if (scorer.sets > state.config.numSets - scorer.sets) state.isComplete = true
}

When you compress this function using Uglify, you get the following minified code and the accompanying source map:

function incrementSet(e,s,t){s.games++;var m=e.players[PLAYER].sets+e.players[OPPONENT].sets;e.completedSets[m]||(e.completedSets[m]=[]),e.completedSets[m][PLAYER]=s.isPlayer?s.games:t.games,e.completedSets[m][OPPONENT]=s.isPlayer?t.games:s.games,s.games=0,t.games=0,s.sets=s.sets+1,e.isFinalSet=s.sets+t.sets===e.config.numSets-1,s.sets>e.config.numSets-s.sets&&(e.isComplete=!0)}

{
  "version": 3,
  "sources": ["score.js"],
  "names": [
    "incrementSet", "state", "scorer", "nonScorer", "games", "currentSet",
    "players", "PLAYER", "sets", "OPPONENT", "completedSets", "isPlayer",
    "isFinalSet", "config", "numSets", "isComplete"
  ],
  "mappings": {
    "1": [
      "1 => score.js 1:1 incrementSet",
      "10 => score.js 1:10 incrementSet",
      "23 => score.js 1:24 state",
      "25 => score.js 1:31 scorer",
      "27 => score.js 1:39 nonScorer",
      "30 => score.js 2:3 scorer",
      "32 => score.js 2:10 games",
      "40 => score.js 3:3 games",
      "44 => score.js 3:7 currentSet",
      "46 => score.js 3:20 state",
      "48 => score.js 3:26 players",
      "56 => score.js 3:34 PLAYER",
      "64 => score.js 3:42 sets",
      "69 => score.js 3:49 state",
      // SNIP! Truncated for brevity.
    ]
  }
}

Say we load the minified file and call incrementSet() with no arguments, we get an error message like TypeError: Cannot read property 'games' of undefined and the position would be reported as line 1, column 30.

Referencing the decoded mappings, we can see what line 1, column 30 maps to:

"30 => score.js 2:3 scorer"

Comparing the output file versus the original:

# Output file                                 # Original file

function incrementSet(e,s,t){s.games++;var    scorer.games++
                             ^                ^
 This is line 1, column 30  ─┘                └─ This is line 2, column 3

This makes total sense – we’re trying to increment scorer.games but because we didn’t pass in any arguments, scorer is undefined.

As you can see, the positional information from the mappings also includes the original name of the object it was trying to modify – scorer – which we can see was transformed to s.

Examining a source map from compiling TypeScript

Sticking with the tennis-themed examples, (guess what this author’s favourite sport is?), here’s a fledgling TypeScript program:

import { Score, Player, nextState } from './utils';

export class Match {
  public score: Score;

  constructor() {
    this.score = new Score();
  }

  public addPoint(p: Player): Score {
    this.score = nextState(this.score, p);
    return this.score;
  }
}

After the TypeScript is compiled, you get the following JS and its accompanying source map:

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var utils_1 = require("./utils");
var Match = (function () {
    function Match() {
        this.score = new utils_1.Score();
    }
    Match.prototype.addPoint = function (p) {
        this.score = utils_1.nextState(this.score, p);
        return this.score;
    };
    return Match;
}());
exports.Match = Match;

{
  "version": 3,
  "file": "index.js",
  "sources": ["index.ts"],
  "names": [],
  "mappings": {
    "1": [""],
    "2": [""],
    "3": [
      "1 => index.ts 1:1", "34 => index.ts 1:52"
    ],
    "4": [
      "1 => index.ts 3:1"
    ],
    "5": [
      "5 => index.ts 6:3"
    ],
    "6": [
      "9 => index.ts 7:5", "13 => index.ts 7:9", "14 => index.ts 7:10",
      "19 => index.ts 7:15", "22 => index.ts 7:18", "26 => index.ts 7:22",
      "39 => index.ts 7:27", "41 => index.ts 7:29", "42 => index.ts 7:30"
    ],
    "7": [
      "5 => index.ts 8:3", "6 => index.ts 8:4"
    ],
    "8": [
      "5 => index.ts 10:10", "29 => index.ts 10:18", "32 => index.ts 10:3",
      "42 => index.ts 10:19", "43 => index.ts 10:28"
    ],
    "9": [
      "9 => index.ts 11:5", "13 => index.ts 11:9", "14 => index.ts 11:10",
      "19 => index.ts 11:15", "22 => index.ts 11:18", "39 => index.ts 11:27",
      "40 => index.ts 11:28", "44 => index.ts 11:32", "45 => index.ts 11:33",
      "50 => index.ts 11:38", "52 => index.ts 11:40", "53 => index.ts 11:41",
      "54 => index.ts 11:42", "55 => index.ts 11:43"
    ],
    "10": [
      "9 => index.ts 12:5", "15 => index.ts 12:11", "16 => index.ts 12:12",
      "20 => index.ts 12:16", "21 => index.ts 12:17", "26 => index.ts 12:22",
      "27 => index.ts 12:23"
    ],
    "11": [
      "5 => index.ts 13:3", "6 => index.ts 13:4"
    ],
    "12": [
      "5 => index.ts 14:1", "17 => index.ts 14:2"
    ],
    "13": [
      "1 => index.ts 14:1", "2 => index.ts 14:2", "2 => index.ts 3:1",
      "6 => index.ts 14:2"
    ],
    "14": [
      "1 => index.ts 3:14", "23 => index.ts 3:19"
    ]
  }
}

One thing of note here is that the first two lines in the mappings have no location in the original source:

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });

The TypeScript compiler adds these lines of preamble to any module and they bear no relation to anything we wrote, so there’s nothing to map.

Looking at the JS output, where did the last line exports.Match = Match; come from? That doesn’t look like anything we wrote at the end of our .ts file…

"14": [
  "1 => index.ts 3:14", "23 => index.ts 3:19"
]

So it came from near the start of our source file…

export class Match {
             ^
             └── This is line 3, column 14

There we are! TypeScript translates the static import/export statements into imperative node-style require() calls and exports assignments – two entirely different ways of managing modules with different constraints on order, meaning that the exports assignment happens at the end.

This example hints at how powerful source maps can be. In the minification example, the transformed output still roughly resembled the input source, especially in terms of order. In a small example like that, debugging without source maps seems remotely doable.

In this TypeScript example, however, the source map tracked something we wrote near the start of the input which appeared near the end of the output. With lots of source code, transformations like this would quickly get out of hand, and having a tool at our disposal to track it for us is crucial.

Examining a future JS source map

Finally, here’s an example of a JS program written using features from ES6/7 and beyond:

default function parameters
classes
array destructuring
arrow functions
object rest/spread
const/let declarations

In order to make this program run in most browsers, we compile it to ES5 using Babel.

const createScoreboard = (playerA = 'Player A', playerB = 'Player B') => ({
  names: [playerA, playerB],
  games: [0, 0],
  sets: [0, 0],
  points: [0, 0]
})

const nextScoreboard = (score, scoreboard = createScoreboard()) => {
  // all the tricky logic goes here
}

document.querySelector('button#start', () => {
  const renderer = new MatchRenderer()
  let score = [0, 0]
  let scoreboard = nextScoreboard(score)
  renderer.update(scoreboard)

  // When the button to increment player A's point gets pressed,
  // increment their score and then update the scoreboard
  document.querySelector('button#player-a-point', () => {
    const [a, b] = score
    score = [a + 1, b]
    scoreboard = nextScoreboard(score, scoreboard)
    renderer.render()
  })

  // Do the same for player B
  document.querySelector('button#player-b-point', () => {
    const [a, b] = score
    score = [a, b + 1]
    scoreboard = nextScoreboard(score, scoreboard)
    renderer.render(scoreboard)
  })
})

class MatchRenderer {
  constructor () {
    this.viewData = {
      date: new Date(),
      matchId: Math.random(),
      tournament: 'Bugsnag Masters'
    }
  }
  update (state) {
    updateDOM({ ...this.viewData, ...state })
  }
}

Here’s the compiled version:

'use strict';

var _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; };

var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }();

var _slicedToArray = function () { function sliceIterator(arr, i) { var _arr = []; var _n = true; var _d = false; var _e = undefined; try { for (var _i = arr[Symbol.iterator](), _s; !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"]) _i["return"](); } finally { if (_d) throw _e; } } return _arr; } return function (arr, i) { if (Array.isArray(arr)) { return arr; } else if (Symbol.iterator in Object(arr)) { return sliceIterator(arr, i); } else { throw new TypeError("Invalid attempt to destructure non-iterable instance"); } }; }();

function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }

var createScoreboard = function createScoreboard() {
  var playerA = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'Player A';
  var playerB = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'Player B';
  return {
    names: [playerA, playerB],
    games: [0, 0],
    sets: [0, 0],
    points: [0, 0]
  };
};

var nextScoreboard = function nextScoreboard(score) {
  // all the tricky logic goes here

  var scoreboard = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : createScoreboard();
};

document.querySelector('button#start', function () {
  var renderer = new MatchRenderer();
  var score = [0, 0];
  var scoreboard = nextScoreboard(score);
  renderer.update(scoreboard);

  // When the button to increment player A's point gets pressed,
  // increment their score and then update the scoreboard
  document.querySelector('button#player-a-point', function () {
    var _score = score,
        _score2 = _slicedToArray(_score, 2),
        a = _score2[0],
        b = _score2[1];

    score = [a + 1, b];
    scoreboard = nextScoreboard(score, scoreboard);
    renderer.render();
  });

  // Do the same for player B
  document.querySelector('button#player-b-point', function () {
    var _score3 = score,
        _score4 = _slicedToArray(_score3, 2),
        a = _score4[0],
        b = _score4[1];

    score = [a, b + 1];
    scoreboard = nextScoreboard(score, scoreboard);
    renderer.render(scoreboard);
  });
});

var MatchRenderer = function () {
  function MatchRenderer() {
    _classCallCheck(this, MatchRenderer);

    this.viewData = {
      date: new Date(),
      matchId: Math.random(),
      tournament: 'Bugsnag Masters'
    };
  }

  _createClass(MatchRenderer, [{
    key: 'update',
    value: function update(state) {
      updateDOM(_extends({}, this.viewData, state));
    }
  }]);

  return MatchRenderer;
}();

And its accompanying source map:

{
  "version": 3,
  "sources": ["tennis.js"],
  "names": [
    "createScoreboard", "playerA", "playerB", "names", "games", "sets", "points",
    "nextScoreboard", "score", "scoreboard", "document", "querySelector", "renderer",
    "MatchRenderer", "update", "a", "b", "render", "viewData", "date", "Date", "matchId",
    "Math", "random", "tournament", "state", "updateDOM"
  ],
  "mappings": {
    "1": [""],
    "2": [""],
    "3": [""],
    "4": [""],
    "5": [""],
    "6": [""],
    "7": [""],
    "8": [""],
    "9": [""],
    "10": [""],
    "11": [
      "1 => tennis.js 1:1 createScoreboard", "5 => tennis.js 1:7 createScoreboard",
      "24 => tennis.js 1:26 createScoreboard", "33 => tennis.js 1:7 createScoreboard",
      "49 => tennis.js 1:26 createScoreboard"
    ],
    "12": [
      "1 => tennis.js 1:26 createScoreboard", "7 => tennis.js 1:27 playerA",
      "14 => tennis.js 1:26 playerA", "85 => tennis.js 1:37 playerA",
      "95 => tennis.js 1:26 playerA"
    ],
    "13": [
      "1 => tennis.js 1:26 playerA", "7 => tennis.js 1:49 playerB",
      "14 => tennis.js 1:26 playerB", "85 => tennis.js 1:59 playerB",
      "95 => tennis.js 1:26 playerB"
    ],
    "14": [
      "1 => tennis.js 1:26 playerB", "10 => tennis.js 1:75 playerB"
    ],
    "15": [
      "1 => tennis.js 2:3 names", "12 => tennis.js 2:10 names",
      "13 => tennis.js 2:12 playerA", "20 => tennis.js 2:10 playerA",
      "22 => tennis.js 2:21 playerB", "29 => tennis.js 2:10 playerB",
      "30 => tennis.js 1:75 playerB"
    ],
    "16": [
      "1 => tennis.js 3:3 games", "12 => tennis.js 3:10 games",
      "13 => tennis.js 3:12 games", "14 => tennis.js 3:10 games",
      "16 => tennis.js 3:15 games", "17 => tennis.js 3:10 games",
      "18 => tennis.js 1:75 games"
    ],
    "17": [
      "1 => tennis.js 4:3 sets", "11 => tennis.js 4:9 sets",
      "12 => tennis.js 4:11 sets", "13 => tennis.js 4:9 sets",
      "15 => tennis.js 4:14 sets", "16 => tennis.js 4:9 sets",
      "17 => tennis.js 1:75 sets"
    ],
    "18": [
      "1 => tennis.js 5:3 points", "13 => tennis.js 5:11 points",
      "14 => tennis.js 5:13 points", "15 => tennis.js 5:11 points",
      "17 => tennis.js 5:16 points", "18 => tennis.js 5:11 points"
    ],
    "19": [
      "1 => tennis.js 1:75 points", "4 => tennis.js 1:26 points"
    ],
    "20": [
      "1 => tennis.js 1:26 points", "2 => tennis.js 1:1 points"
    ],
    "21": [""],
    "22": [
      "1 => tennis.js 8:1 points", "5 => tennis.js 8:7 nextScoreboard",
      "22 => tennis.js 8:24 nextScoreboard", "31 => tennis.js 8:7 nextScoreboard",
      "45 => tennis.js 8:24 nextScoreboard", "46 => tennis.js 8:25 score",
      "51 => tennis.js 8:24 score", "53 => tennis.js 8:68 score"
    ],
    "23": [
      "1 => tennis.js 9:3 score"
    ],
    "24": [""],
    "25": [
      "1 => tennis.js 8:68 score", "7 => tennis.js 8:32 scoreboard",
      "17 => tennis.js 8:68 scoreboard", "88 => tennis.js 8:45 createScoreboard",
      "106 => tennis.js 8:68 createScoreboard"
    ],
    "26": [
      "1 => tennis.js 10:2 createScoreboard", "2 => tennis.js 8:1 createScoreboard"
    ],
    "27": [""],
    "28": [
      "1 => tennis.js 12:1 document", "10 => tennis.js 12:10 querySelector",
      "23 => tennis.js 12:1 querySelector", "24 => tennis.js 12:24 querySelector",
      "38 => tennis.js 12:1 querySelector", "40 => tennis.js 12:40 querySelector",
      "52 => tennis.js 12:46 querySelector"
    ],
    "29": [
      "1 => tennis.js 13:3 querySelector", "7 => tennis.js 13:9 renderer",
      "18 => tennis.js 13:20 renderer", "22 => tennis.js 13:24 MatchRenderer",
      "35 => tennis.js 13:20 MatchRenderer", "37 => tennis.js 13:3 MatchRenderer"
    ],
    "30": [
      "1 => tennis.js 14:3 MatchRenderer", "7 => tennis.js 14:7 score",
      "15 => tennis.js 14:15 score", "16 => tennis.js 14:17 score",
      "17 => tennis.js 14:15 score", "19 => tennis.js 14:20 score",
      "20 => tennis.js 14:15 score", "21 => tennis.js 14:3 score"
    ],
    "31": [
      "1 => tennis.js 15:3 score", "7 => tennis.js 15:7 scoreboard",
      "20 => tennis.js 15:20 nextScoreboard", "35 => tennis.js 15:35 score",
      "40 => tennis.js 15:20 score", "41 => tennis.js 15:3 score"
    ],
    "32": [
      "1 => tennis.js 16:3 renderer", "12 => tennis.js 16:12 update",
      "18 => tennis.js 16:3 update", "19 => tennis.js 16:19 scoreboard",
      "29 => tennis.js 16:3 scoreboard"
    ],
    "33": [""],
    "34": [
      "1 => tennis.js 18:3 scoreboard"
    ],
    "35": [
      "1 => tennis.js 19:3 scoreboard"
    ],
    "36": [
      "1 => tennis.js 20:3 document", "12 => tennis.js 20:12 querySelector",
      "25 => tennis.js 20:3 querySelector", "26 => tennis.js 20:26 querySelector",
      "49 => tennis.js 20:3 querySelector", "51 => tennis.js 20:51 querySelector",
      "63 => tennis.js 20:57 querySelector"
    ],
    "37": [
      "1 => tennis.js 20:57 querySelector", "18 => tennis.js 21:22 score",
      "23 => tennis.js 20:57 score"
    ],
    "38": [
      "1 => tennis.js 20:57 score"
    ],
    "39": [
      "1 => tennis.js 20:57 score", "9 => tennis.js 21:13 a",
      "10 => tennis.js 20:57 a"
    ],
    "40": [
      "1 => tennis.js 20:57 a", "9 => tennis.js 21:16 b",
      "10 => tennis.js 20:57 b"
    ],
    "41": [""],
    "42": [
      "1 => tennis.js 22:5 score", "13 => tennis.js 22:13 score",
      "14 => tennis.js 22:15 a", "18 => tennis.js 22:19 a",
      "19 => tennis.js 22:13 a", "21 => tennis.js 22:22 b",
      "22 => tennis.js 22:13 b", "23 => tennis.js 22:5 b"
    ],
    "43": [
      "1 => tennis.js 23:5 scoreboard", "18 => tennis.js 23:18 nextScoreboard",
      "33 => tennis.js 23:33 score", "38 => tennis.js 23:18 score",
      "40 => tennis.js 23:40 scoreboard", "50 => tennis.js 23:18 scoreboard",
      "51 => tennis.js 23:5 scoreboard"
    ],
    "44": [
      "1 => tennis.js 24:5 renderer", "14 => tennis.js 24:14 render",
      "20 => tennis.js 24:5 render"
    ],
    "45": [
      "1 => tennis.js 25:4 render", "4 => tennis.js 20:3 render"
    ],
    "46": [""],
    "47": [
      "1 => tennis.js 27:3 render"
    ],
    "48": [
      "1 => tennis.js 28:3 document", "12 => tennis.js 28:12 querySelector",
      "25 => tennis.js 28:3 querySelector", "26 => tennis.js 28:26 querySelector",
      "49 => tennis.js 28:3 querySelector", "51 => tennis.js 28:51 querySelector",
      "63 => tennis.js 28:57 querySelector"
    ],
    "49": [
      "1 => tennis.js 28:57 querySelector", "19 => tennis.js 29:22 score",
      "24 => tennis.js 28:57 score"
    ],
    "50": [
      "1 => tennis.js 28:57 score"
    ],
    "51": [
      "1 => tennis.js 28:57 score", "9 => tennis.js 29:13 a",
      "10 => tennis.js 28:57 a"
    ],
    "52": [
      "1 => tennis.js 28:57 a", "9 => tennis.js 29:16 b",
      "10 => tennis.js 28:57 b"
    ],
    "53": [""],
    "54": [
      "1 => tennis.js 30:5 score", "13 => tennis.js 30:13 score",
      "14 => tennis.js 30:15 a", "15 => tennis.js 30:13 a",
      "17 => tennis.js 30:18 b", "21 => tennis.js 30:22 b",
      "22 => tennis.js 30:13 b", "23 => tennis.js 30:5 b"
    ],
    "55": [
      "1 => tennis.js 31:5 scoreboard", "18 => tennis.js 31:18 nextScoreboard",
      "33 => tennis.js 31:33 score", "38 => tennis.js 31:18 score",
      "40 => tennis.js 31:40 scoreboard", "50 => tennis.js 31:18 scoreboard",
      "51 => tennis.js 31:5 scoreboard"
    ],
    "56": [
      "1 => tennis.js 32:5 renderer", "14 => tennis.js 32:14 render",
      "20 => tennis.js 32:5 render", "21 => tennis.js 32:21 scoreboard",
      "31 => tennis.js 32:5 scoreboard"
    ],
    "57": [
      "1 => tennis.js 33:4 scoreboard", "4 => tennis.js 28:3 scoreboard"
    ],
    "58": [
      "1 => tennis.js 34:2 scoreboard", "2 => tennis.js 12:1 scoreboard"
    ],
    "59": [""],
    "60": [
      "5 => tennis.js 36:7 MatchRenderer", "18 => tennis.js 36:7 MatchRenderer"
    ],
    "61": [
      "1 => tennis.js 37:3 MatchRenderer", "28 => tennis.js 37:18 MatchRenderer"
    ],
    "62": [
      "1 => tennis.js 37:18 MatchRenderer"
    ],
    "63": [
      ""
    ],
    "64": [
      "1 => tennis.js 38:5 MatchRenderer", "10 => tennis.js 38:10 viewData",
      "18 => tennis.js 38:5 viewData", "21 => tennis.js 38:21 viewData"
    ],
    "65": [
      "1 => tennis.js 39:7 date", "13 => tennis.js 39:13 date",
      "17 => tennis.js 39:17 Date", "21 => tennis.js 39:13 Date",
      "23 => tennis.js 38:21 Date"
    ],
    "66": [
      "1 => tennis.js 40:7 matchId", "16 => tennis.js 40:16 Math",
      "21 => tennis.js 40:21 random", "27 => tennis.js 40:16 random",
      "29 => tennis.js 38:21 random"
    ],
    "67": [
      "1 => tennis.js 41:7 tournament", "19 => tennis.js 41:19 tournament"
    ],
    "68": [
      "1 => tennis.js 38:21 tournament", "6 => tennis.js 38:5 tournament"
    ],
    "69": [
      "1 => tennis.js 43:4 tournament"
    ],
    "70": [""],
    "71": [""],
    "72": [""],
    "73": [
      "28 => tennis.js 44:11 state", "33 => tennis.js 44:11 state",
      "35 => tennis.js 44:18 state"
    ],
    "74": [
      "1 => tennis.js 45:5 updateDOM", "30 => tennis.js 45:20 updateDOM",
      "35 => tennis.js 45:25 viewData", "43 => tennis.js 45:5 viewData",
      "45 => tennis.js 45:38 state", "50 => tennis.js 45:5 state"
    ],
    "75": [
      "1 => tennis.js 46:4 state"
    ]
  }
}

Let’s drill down into the interesting bits.

Default parameters

We can see some code on lines 12 and 13 that doesn’t look like anything in the source:

var playerA = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'Player A';
var playerB = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'Player B';

By looking this up in the mappings we can see where it originated:

"12": [
  "1 => tennis.js 1:26 createScoreboard", "7 => tennis.js 1:27 playerA",
  "14 => tennis.js 1:26 playerA", "85 => tennis.js 1:37 playerA",
  "95 => tennis.js 1:26 playerA"
],
"13": [
  "1 => tennis.js 1:26 playerA", "7 => tennis.js 1:49 playerB",
  "14 => tennis.js 1:26 playerB", "85 => tennis.js 1:59 playerB",
  "95 => tennis.js 1:26 playerB"
],

Both of these lines in the output stem from line 1 of our original source:

const createScoreboard = (playerA = 'Player A', playerB = 'Player B') => ({
                         ^^         ^           ^         ^
      columns:        26 ┘└ 27  37 ─┘       49 ─┘     59 ─┘

It’s quite clear from these mappings how the default function parameters have been converted into something that works in environments that don’t support this feature.

Array destructuring, rest/spread, classes

Like the TypeScript example, lines 1-10 are inserted by Babel. Again, these are created during the transformation, but are not directly related to parts of the input source so they do not map anywhere. When we look at what happened when we used array destructuring, the object spread operator and class syntax, we soon see why:

const [ a, b ] = score           =>   var _score = score,
                                          _score2 = _slicedToArray(_score, 2),
                                          a = _score2[0],
                                          b = _score2[1];

{ ...this.viewData, ...state }   =>   _extends({}, this.viewData, state);

class MatchRenderer {            =>   _createClass(MatchRenderer, [{

What Babel does here is a trade-off. It would be possible to map the direct result of each transformation every time it swaps out a feature, as per the default parameters example. However, since that would output a larger file, it creates the helper functions you see in line 1-10 of the output. The usage of these functions can be mapped; for example, here’s the mapping for the _extends(…) call:

"74": [
  "1 => tennis.js 45:5 updateDOM", "30 => tennis.js 45:20 updateDOM",
  "35 => tennis.js 45:25 viewData", "43 => tennis.js 45:5 viewData",
  "45 => tennis.js 45:38 state", "50 => tennis.js 45:5 state"
]

    updateDOM({ ...this.viewData, ...state })
    ^              ^    ^            ^
  5 ┘          20 ─┘    └─ 25        └─ 38

Since many places in the source can end up calling code inside the _extends(), _slicedToArray() or _createClass() helpers, there can be no definitive mapping. This is a limitation of the process.

Source maps + Bugsnag

At Bugsnag, we care deeply about surfacing error reports in the most useful and actionable way. If you’re shipping transformed JS, what use is it to see your stacktraces against that generated code? That’s why we use source maps – to show stacktraces against the code you see in your editor.

The great news about the source map format, is that for the most part it’s language agnostic. We’ve mostly covered JS being the target language here, but it is also commonly used for generated CSS. What this means is if you pick some new esoteric flavour of JS, or even some compile-to-JS language that we’ve never heard of, we’ve already got you*! Using the source map we can show you the original source for an error that happened in your generated JS.

* Okay, you may not see perfect syntax highlighting!

How to tell Bugsnag about your source maps

There are two main routes you can take when you want to get source maps working with Bugsnag:

Self-hosting

The simplest way is to host your source maps alongside your bundled JS, then either:

Include the //# sourceMappingURL= comment in your bundled JS. This is inserted automatically by most tools that generate source maps. We’ll detect this once we’ve loaded the JS and go fetch the map if it exists.
Set the X-SourceMap header when the bundled JS is served. When we receive an error that originates in your JS, we’ll make a request to load it. We’ll detect the X-SourceMap header and go fetch the map if it exists.

We’ll always request the sources and maps from the same IPs, so with either of these options, if making your source maps public is not an option you can whitelist our IPs.

Uploading

You also have the option to upload your source maps directly to us. Depending on the tools you use you can do this at varying levels:

webpack-bugsnag-plugins allows you to upload your source maps directly from Webpack via our BugsnagSourceMapUploaderPlugin plugin.
bugsnag-sourcemaps allows you to upload your source maps from within a node process or via the command line.
Alternatively you can hit our source map API directly.

Fin.

If you made it this far, you’re a veritable source map trooper. Hopefully you’ve a new found appreciation for the humble source map, and at the very least, you’ll be able to impress your friends with your knowledge about "mappings". Happy code transforming!

Try Bugsnag’s JavaScript error reporting or learn more in our documentation.

Replacing npm with Yarn

Christian Schlensker — Thu, 13 Oct 2016 18:32:04 +0000

This post was originally published on the Bugsnag blog. Bugsnag's real-time error monitoring platform is the most practical way to improve software quality for your users. With visibility into production errors alongside diagnostic data for reproducing and fixing, developers can improve customer experiences and code quality.

Hold on to your sweaters. There's a brand new tool hot out of the dryer. On Tuesday Facebook announced a new package manager for Javascript that is meant as a replacement for NPM.

The initial gut reaction may be to get wound up about the notion of forking essential tooling. However, yarn works in a way that is compatible with existing infrastructure. It still uses the existing npm registry and its CLI is mostly identical to that of npm.

The Bugsnag frontend team was on pins and needles to give it a spin, primarily because we have frequently gotten tangled up by dependencies changing between different developers' machines. We often have to delete our node_modules folder and re-install everything to solve mysterious problems. We've tried npm's shrinkwrap feature before, but, like Facebook, there were issues with it getting out of date so we've been itching for an alternative solution for some time.

Yarn solves this problem by using an automatically updated "lockfile" to tie down the dependencies to a specific version. After this file is committed to source control, we should never have to worry about inconsistent dependencies between machines or variations over time.

Moving from npm to Yarn

The migration process was extremely simple. Just run the yarn command and commit the resulting yarn.lock file. Then grep all our docker and deploy scripts for references to npm and replace them with the yarn equivalents.

Performance improvements

Some initial rough benchmarks look very promising. Just so you know the wool hasn't been pulled over your eyes, here are the raw numbers.

command	time (in seconds)
`npm install`	155s
`yarn` (cold cache)	53s
`yarn` (warm cache)	13s

Yarn will cache dependencies so subsequent installs can be done without re-downloading. This even works without an internet connection.

Yarn has threads

Even without caching, Yarn is faster due to parallelization.

I'm especially excited about the impact it will have on the CI server where we start with a fresh node_modules folder for every build.

The API

The API is mostly the same with a few notable exceptions. With NPM the default npm install <some-package> command would not add the dependency to package.json, where as yarn add <package-name> will. I think this is preferable as the default behavior since the alternative makes it too easy to forget to commit a dependency change.

Yarn also adds several bonus features. The yarn why command, which will show you which of your dependencies is causing a package to be downloaded.

Sew much more

These are only some initial impressions of yarn. There are also many features that I didn't get to cover. Check out the official site to learn more, including the security enhancements, performance features, and flat mode.