Why does any of this matter?

Having worked on a few large scale applications over my career, one of the most common runtime errors I have seen is something along the lines of Uncaught TypeError: Cannot read property 'foo' of undefined. One of the nice features enabled by TypeScript --strict mode is that it also enables all the checks that come with the --strictNullCheck option, which will result in compiler errors anytime you try to access a property on an object that may be null or undefined. Here’s an example:

• The getStringLengthError function would result in a compiler error when --strictNullChecks are enabled, but no error when the checks are off, which could lead to runtime errors.
• The second function, getStringLengthNoError, demonstrates that checking maybeUndefined is not undefined before trying to access the length property, doesn’t result in an error. Once we make that undefined check, TypeScript knows the type of maybeUndefined is no longer string | undefined, but instead a string in the context of the if block.
• The process by which we introduce a type check here to reduce the possible types of a variable in TypeScript is commonly referred to as “narrowing”.

While --strict mode does make it harder for us to write code that results in runtime type errors, it does not completely eliminate them.

TypeScript is not C#

One of the things that often confuses experienced developers when they first start using TypeScript is how it’s type system differs from that of other languages. TypeScript’s type system is very powerful (more on that later), but it has one key difference from other languages: the types do not exist at runtime. One of TypeScript’s key features is that TypeScript programs can be translated into JavaScript code that can be run in a browser. The TypeScript playground is a great place where you can see what JavaScript is generated for a given TypeScript program. In the example below, all evidence of our AwesomeInterface is gone in the generated JavaScript code.

The fact that types do not exist at runtime is very important to know. One particular source of confusion is the existence of the as keyword in both TypeScript and C#. In C#, the as operator tries to do a type conversion and returns null when the conversion is not possible. This causes many developers coming from a C# to expect the code snippet below to only enter the if block if arg is an implementation of AwesomeInterface. If you take a look at the generated code below, you can see the as keyword simply gets compiled away, causing us to go into the if block for any value of arg that is not falsy!

Type casting via as AwesomeInterfaceor <AwesomeInterface> in TypeScript simply tells the compiler to treat the variable as if it were an AwesomeInterface rather than doing any work to see if the object actually has the shape defined by AwesomeInterface. Type casts can sometimes be helpful when you have more context than the TypeScript compiler in a certain situation, but in general you should avoid using type casts in favor of other techniques we will cover in this article.

Ok, so how do I check the type of something at runtime?

There are many scenarios where you may want to identify the type of something at runtime in a TypeScript application. One example could be you have a function that takes in an argument that could have multiple types and you want to have different behavior for each of these types. Take a look at the example below, where we define a hypothetical function that takes in an argument that can be a number, string, or number array.

In this example, we used type “narrowing” to determine what the exact type of arg is before using the value.

• The first if statement uses the typeof operator to check if the input is a string. This enables the compiler to know that the value of arg on line 3 is a string.
• The second if statement uses the Array.isArray function to determine if arg is a number array.
• By the time we get to line 10, if the type of arg was string or number[], we would have already returned. This means the TypeScript compiler knows the only possible type for argis number at this point, so we don’t to do an additional check here.

This technique also works for more complex types as well. Consider the example below where we have a function that takes in an argument of type Person or CityLocation.

Here we use the in keyword to check if arg has a firstName property. If it does, we know that it must be a Person type since CityLocation has no firstName property.

There is a caveat with this kind of a check that can be demonstrated with this sample code.

In this example myLocation implements the CityLocation contract, but also adds an additional firstName property. In this case, our code would see that the object passed in has a firstName property on it and goes down the path for an argument of the Person type, even though myLocation does not have the lastName property we’d expect a Person type to have. This could be addressed by also including a check for 'lastName' in arg.

As another example, let’s change the type of CityLocation from an interface to a class. When the type of an object is a class, we have the option of using instanceof keyword in addition to the is operator.

Can I trust the inputs to my function are what they say they are?

One thing we are taking for granted in the examples shown previously is that we trust the input values we are working with at runtime actually match the type signature declaration at compile time. That is, we are trusting that a function with the signature (param: string | number) always is called with an argument that is of type string or number. Often times, this assumption holds. For example, if your APIs are only called by other TypeScript code using — strictmode, then this is a safe assumption, since the callers would get a compiler error if they violated the type signature (assuming they didn’t use a type cast).

However, there are many situations where you cannot trust the data you are being given has a particular shape. One example would be data obtained from an API call or read from local storage.

Let’s say we have a function that we expect to provide a string argument, but it is possible the caller will give us a non-string value. We certainly don’t want our code to throw an exception when we are given an unexpected input value. The temptation here may be to define this value with the any type, but that would cause us to lose all type safety. To demonstrate why any is a bad fit, look at the example below.

Despite the fact that this example is certainly going to throw an exception, the compiler does not give us an error due to the fact that x has the type of any.

For these kinds of scenarios, the TypeScript language has the unknown keyword. The TypeScript team refers to unknown as the type-safe counter part to any. In practice, this means that TypeScript will make sure that you have done the right type assertions before accessing any properties on a variable of unknown type. Below we have an example of a getLength function that is expected to be called with an array or string, but we can’t know for sure.

The use of unknown ensures that we do not call the length property on input unless we have narrowed it down to a type that is known to have a length property on it.

Tips and tricks for type system pros

Now that you are motivated to and using the any and as keywords, here are some concepts you may find useful in your codebases.

Type predicates enable you to avoid duplicating type checks throughout a codebase.

Discriminated unions are a useful pattern for defining union types that can be differentiated easily at runtime.

Exhaustive switch statements are useful for ensuring that all possible values for a union type are covered by your code.

1. Define a location to be your work space — This one can be tough since many people live in apartments, but try to identify an area of your home where you will be able to focus. Define this area as your “work space” and try not to use this area for other activities like eating, watching TV, or browsing social media.
2. Set expectations for those around you — Often times when working from home, you will be surrounded by other people. Try to make it clear to other folks when you are working and set expectations for when you can be interrupted. For deep focus activities, like coding, folks who aren’t in the tech industry have a hard time understanding how disruptive an interruption could be. Try to have a conversation up front about your expectations when you are working from home. What worked well for me was to tell the folks around me to get a hold of me using asynchronous communication (text messages work really well for this), especially when I am on a call. This is more complicated if you have children in the house, so hopefully some of the parents reading this can share some tips specific to this scenario!
3. Use your webcam — When calling into meetings while working remote use your webcam. It makes a huge difference. I also recommend having a good webcam and lighting where you will be working. I personally use the Logitech C920 s and a ring light. Scott Hanselman has a great writeup about this that inspired my set up.
4. The mic on your laptop is probably terrible — Some folks prefer to use headphones or a dedicated mic for better call quality. Most laptop microphones are typically highly directional so they don’t work well if you are not directly in front of the laptop. I personally use a Blue Yeti Nano.
5. Take breaks and make sure to move around — It’s very easy to fall into the trap of doing deep work for several hours. I find it very helpful to intentionally take breaks to move around the house or neighborhood a bit. I also find disconnecting during work completely during lunch to be super helpful. I have a “no eating around my work computer” rule.
6. Favor public asynchronous communication — This is something we typically should always be doing, but try to avoid direct IM for communication with others since it can be disruptive and doesn’t offer the transparency and inclusion we value at Microsoft. In general, I recommend using public Teams channel as your primary communication tool over email and direct IM.
7. Avoid the temptation to do other work while on a video call — I found it super difficult to stay focused in meetings when I first started working remotely. I was often coding or checking emails. I eventually had to resort to the measure of moving my keyboard out of reach while I am on a Teams call. Turning on your webcam also has the nice side effect of keeping you honest.

As part of a recent performance push, we decided to dive deeper into the dependency graph generated by webpack-bundle-analyzer to make sure that all the code in our main bundle was indeed required on the boot path. To our surprise, we discovered that a large portion of our bundle was taken up by an internal package @ms/office-web-platform. This package contains a lot of the common infrastructure shared by various Office web experiences, such as logging, authentication, and common utilities. Over time, this package has become quite large, but often times only a small percentage of the code in the package is on the critical boot path of an application. Upon closer inspection, it appeared as if tree shaking was not enabled at all for the package.

We first expected this to be a configuration issue, so we verified that @ms/office-web-platform was meeting the tree-shaking requirements. We made sure the package was exporting ECMA Script Modules, had a module entry in package.json, and properly set the sideEffects flag in package.json. We also confirmed that another application using @ms/office-web-platform was seeing the correct tree shaking behavior.

We then scanned the modules in our main bundle to find all the static imports of @ms/office-web-platform. We only found usages of the logger, with imports of the form:

import { logger } from '@ms/office-web-platform';

This logging module is very small and does not have dependencies on many other modules. The @ms/office-web-platform package has a structure that is roughly like this:

/lib
  /authentication
    auth.js
    index.js
  /telemetry
    index.js
    logger.js
  ...
index.js

All index.js files simply re-export other modules. As an exercise, we tried changing the path of the imports from the root index.js file to instead be pointing at the /telemetry/index.js module. Our imports then look like this:

import { logger } from '@ms/office-web-platform/lib/telemetry';

This change dramatically reduced the bundle size, which was great! However, this change would force us to take a dependency on the internal package structure of the @ms/office-web-platform package and there was a concern that this bundle would easily regress the next time some adds an import to something from the @ms/office-web-platform. We needed to understand what was actually going on here.

The webpack stats files weren’t providing us with any clues, so we went ahead and started removing imports and eventually got to a state where were able to get a minimal reproduction of the issue by removing all app code except for this:

import { logger } from '@ms/office-web-platform';
import { getAuthService } from './AuthService';

export function boot() {
  logger.loadFull();

return getAuthService();
}

Removing either import in this case cause the bundle size to dramatically drop. We eventually went into getAuthServiceand started removing code until we saw the desired bundle output. We tracked the issue to this line of code ingetAuthService:

// IMPORTANT: Dynamically load dependency on office-web-platform  
// package to ensure that it is not included inside initial app 
// bundle. This method is not called on app boot up so delay loading 
// makes sense.
const platform = await import('@ms/office-web-platform');

This code had good intentions, it meant to delay load some code that isn’t needed on the initial render. When this line of code was first added we didn’t have any telemetry in the boot slice, so we didn’t have any code from @ms/office-web-platform in the main chunk. When we added logging to the main slice, we introduced a static import of the index.js module at the root of the @ms/office-web-platform. A static require isn't a problem since webpack tree shaking will only include the bits we care about, which we were able to confirm by removing the dynamic import. The problem comes with the dynamic import of that same index.js module.

import('@ms/office-web-platform');

When you dynamically import a module, it automatically makes that module ineligible for tree shaking. The result of the dynamic import is an object with all the exports of the module. Due to the dynamic nature of JavaScript, webpack can’t easily determine which exports will be used, so webpack can’t do any tree shaking. For more details on tree shaking behavior for dynamic imports, checkout this great description from the webpack team.

This discovery revealed why we weren’t tree shaking the @ms/office-web-platform module, but it was still unclear why all of the code from that package was in the main slice rather than just the telemetry module we were statically importing. The spec for ECMA script modules defines that modules that can only be evaluated once, so we cannot evaluate the index.js module once in the boot slice and then once again later in the delay loaded slice. Since we have a static import @ms/office-web-platform/lib/index.js module in the boot path, we expect the evaluation of the index.js module to happen in the boot chunk. Since this exact index.js module is also required in a dynamic import, this module is no longer eligible for tree shaking, meaning we will pull in everything that is re-exported by that module in the boot slice!

The fix here was to switch all the dynamic imports of @ms/office-web-platform to be scoped to specific modules that were being required, meaning we would update our imports from import('@ms/office-web-platform') to import('@ms/office-web-platform/lib/expensiveModule')This has the downside of making the application dependent on the internal package structure of @ms/office-web-platform, meaning we would run into issues if the logger.js module was moved to different location in the package. In the end we felt this trade off worth making to improve our boot performance. Going forward, we are going to evaluate all our dynamic imports and ensure we are not pulling in too much code. We’re also considering splitting larger packages like @ms/office-web-platform into smaller modules so that we can go back to importing from the index.js file at the root of the module.

Edit August 2020:

Since publishing this article, we recently moved to a different pattern for dynamic imports that does not cause dependencies on the internal package structure of an external package. Rather than having a reference import('@ms/office-web-platform/lib/expensiveModule') inside of our package, we create a module in the package consuming @ms/office-web-platform that has a static import to the expensive modules we need and dynamically import that module. For example, we would create a file officeWebPlatformLazy.js inside the package that wishes to delay load @ms/office-web-platform. The contents of officeWebPlatformLazy.js would look something like this:

export{ expensiveModule } from '@ms/office-web-platform';

Now, we replace all the import('@ms/office-web-platform/lib/expensiveModule') statements with statements like import('../officeWebPlatformLazy'). With this approach, we still get the expected bundle output, but removed the dependency on the internal structure of the external package @ms/office-web-platform.

Building a standalone component

To help us ensure that our new architecture was not influenced by the structure of the existing Office Online applications, we decided that we would build the UX platform as a standalone NPM package. This NPM package would live in a new git repository and it would have its own test application that would enable us to render parts of the UX platform in isolation. This contrasts with our existing UX platform, where things like the Ribbon can only be rendered inside an application like Word Online. The hope was that this test application would be a place where developers making UI changes could see their changes in seconds instead the minutes it takes with our current stack.

There was some initial concern here that this approach would make it more difficult for developers working on bug fixes to test their changes end to end. After all, there are some bugs in Word Online that only appear when the UX platform is integrated within the larger application. In practice, we found that this isolated test app enabled us to easily separate bugs in the UX platform from bugs in the integration of the UX platform into an Office Online application. We also invested in tooling to enable developers to be able to validate changes in the UX platform inside a larger application without deploying a new version of the NPM package. A side effect of this development approach is that we did not have Office Online specific implementation details inside the UX platform, which has enabled us to share our code with other web applications within Microsoft.

Design considerations

To fully understand the design decisions we made when building up a new UX platform, it is important to understand some of the functionality we need to support in our applications. While our initial UX platform rewrite was only targeting the Ribbon, we plan to eventually port all our UX surfaces to React and TypeScript. It was very important for us to have a forward looking mindset here to enable us to scale out to more developers as the project matured.

Responsive layout

The Single Line Ribbon has a responsive design where controls can be rendered in an overflow menu to fit in narrower browser windows. This means we need to support rendering any control type in an overflow menu. We also needed to figure out a clean way for application teams to author the contents of their Ribbons and order in which controls go into an overflow. The implementation of Ribbon scaling was actually one of the more challenging parts of this rewrite and likely merits a blog post of its own.

Tell Me

Another interesting aspect of our UX platform is the “Tell Me” control. This is a feature that enables users to search for a command in Word Online. The Tell Me control needs to be able to query for all controls in the Ribbon to determine what results should be presented to the user. The Tell Me control was implemented years after our legacy Script# UX platform, which resulted in some clunky mechanisms for interacting with the Ribbon to identify and invoke commands. We wanted to improve the architecture in the new UX platform to ensure we were exposing the right APIs from our UX platform to prevent tight coupling between the Ribbon and Tell Me code.

Add Ins

Office Online’s extensibility platform allows for third party developers to develop features and have their own buttons in the Ribbon. Like “Tell Me”, this functionality came to Word Online a long time after the initial implementation of the UX platform. The legacy Ribbon was originally built under the assumption that all controls could be statically defined at build time. We did not have APIs for adding or removing controls at run time, so this meant that we had to write new code for add ins to support this scenario rather than leveraging the same mechanism for constructing the first party controls in the Ribbon. It was a goal of the rewrite to consolidate the ways in which controls are added to the Ribbon.

Synchronizing state across multiple UI surfaces

Controls that appear in the Ribbon might also appear in other UI surfaces, such as context menus, floaties, and Tell Me search results. Many of these controls also have some state associated with them. An example of this can be seen with “toggle buttons” like the “bold” button in Word Online. Whenever the user’s selection contains bold text, the control has a darker background color than it does when the selection does not contain bolded text.

This state needs to be consistent across all the UI surfaces in which the “bold” button appears. Today, each of these UI surfaces has its own “bold” button whose state needs to be kept up to date, resulting in each application having code that needs to know about all these UI surfaces. For the new UX platform, we wanted to eliminate this duplication and reduce some of this coupling between core application logic and the UX platform.

The UX Store

One of the key design decisions we made was to introduce the concept of a “UX Store”. Each control in our UI would have an associated JavaScript object known as a “control model” that represents all the metadata about that control. This includes things like the icon, label text, and tooltip for the control. The control models would also include any state that a control may have, such as the “toggled” state of the bold button. These models would not contain details about how a control should appear, enabling us to have a single model for a control that can be shared across UI surfaces.

The UX store would also have the definitions of the Ribbon contents for a given application. This is where we would define the controls that would appear in each Ribbon tab, as well as specifying the order in which controls would be dropped into the overflow menu as the window width decreases.

The UX store was implemented using Redux. We had actually written three versions of the UX store using various open source state management libraries. We wrote one version using React’s setState API, another using Redux, and another version using MobX. We were actually very happy with all three versions of the store and I think we would have been successful with any of these approaches. We decided against React setState because we did not want our UX store to be React-specific and we liked how cleanly our Redux and MobX implementations separated our state from the React components. We ended up choosing Redux because we really liked the organization of the store into actions/reducers/selectors. We also liked working with immutable data structures, since we were easily able to leverage reselect and React Pure Components to get great update performance for our UI.

App Integration

To ensure that we were creating a UX platform that was truly a standalone component, we built up the majority of the UX store well before we ever tried to integrate it into the existing Word Online application. The extraction of the UX platform into an external NPM package forced us to come up with a well-defined API for communication with the UX platform. This API needed to work across all Office Online applications, not just Word Online.

There is a very large set of interactions that need to happen between the UX platform and the application, but we can break it down into two large categories.

Communication from UX platform to the application

The first category is communication from the UX platform to the application. This includes the scenario where the user clicks on the bold button in the Ribbon and the application needs to respond to that by updating the formatting of the user’s selection.

The application is responsible for registering a function, known as the command handler, that will be invoked whenever the user executes a Ribbon command. When the user interacts with a control in the Ribbon, the command handler is invoked with an object that contains information about the command that was just invoked. This payload contains the name of the command that was invoked (e.g. “Bold”) as well as any other data associated with this control execution. For toggle buttons, this will include the current toggle state of the control. For things like the font name drop down, this will include the name of the font that the user selected. The application then uses the data in the payload to execute the requested user action within the command handler.

Communication from the application to the UX Platform

There are also scenarios when the application needs to update some state in the UX platform. An example of this is when a user invokes a keyboard shortcut to apply bold formatting to the current selection. In this scenario, the application needs to update the “toggled” state of the bold button in the Ribbon to reflect the new state of the user’s selection in the document.

The UX platform exposes an API to enable the application to update the Ribbon in response to a user action. These APIs are mostly just exposing a subset of the Redux actions available in the UX store. The platform has APIs like ‘setButtonToggleState’ which enables the application to set the toggle state of the bold button when the user’s selection changes. These APIs would make the appropriate updates in the UX store and then trigger a rerender of the Ribbon with the React props derived from the updated UX state.

Looking back

We took a lot of inspiration from the open source community when building up our UX platform. This was most evident in our decision to create the UX platform as a standalone NPM package. This packaging strategy ended up being a forcing function for us to implement good contracts between our application and UX platform, which we expect will make our code easier to maintain going forward. The biggest difference from our previous UX platform architecture was the creation of a UX store. This design ended up solving many of the pain points of our existing UX platform.

• We are now able to use the same APIs for the insertion of first party controls and third party controls.
• We have eliminated the state duplication for controls that appear in multiple UI surfaces, reducing the amount of work we will have to do as we convert the remainder of our UI surfaces to React.
• We now have a nice set of APIs that the Tell Me control can interact with to get control metadata rather than digging into implementation details of the Ribbon.

A new architecture for Word Online’s UX Platform was originally published in Web Dev @ Microsoft on Medium, where people are continuing the conversation by highlighting and responding to this story.

Early in 2017, our design team proposed a pretty significant visual refresh of Word Online. While many of these changes were quick CSS tweaks to change some colors and padding, there were also some significant visual updates that would require core changes to the code in our UX framework. The most prominent of these visual changes were targeted at the primary commanding surface at the top of Word Online, commonly referred to as the Ribbon.

The goal of this visual update was to allocate more visual real estate to the user’s document by moving from a “Multi Line Ribbon” to a “Single Line Ribbon”. In order to make all these commands fit into a single row, we needed to be able to render some of the less frequently used commands in an “overflow menu”. This is not a behavior that we supported in the Multi Line Ribbon, so we would have to do some work in our UX platform to ensure we could support rendering all our control types in menus.

The Single Line Ribbon was also designed to be more responsive than the Multi Line Ribbon. As the window width decreases, commands will move from the top level into the overflow well.

Time for a rewrite?

The Word Online codebase is over 11 years old. At that time, the JavaScript ecosystem was also not as mature it as it is today, with a growing sentiment that raw JavaScript did not scale to large applications. This led to a rise in the use of Script# (a transpiler from C# to JavaScript) for large web applications within Microsoft. Script# was a vital tool that helped our code base scale to our growing engineering team and played a key role in getting us to the point where we are able to confidently ship new versions of Word Online multiple times per week. Over the past few years TypeScript has emerged as Microsoft’s public facing solution to large scale JavaScript development. This has led to Script# usage declining across the company, as the developer experience offered in TypeScript is far superior to that experienced by Script# developers.

On the Office Online team, we have been trying to write some new features in TypeScript to help improve our engineering velocity. This approach proved to be very successful for isolated features, but it had the tendency of being a very frustrating experience for developers that were working on features that tightly integrated with the large Script# code base. It became clear that we would have to eventually rewrite a core piece of Word Online in TypeScript to reduce the friction for developers trying to write new features in TypeScript.

The proposed updates to the Word Online Ribbon would require extensive refactoring of the UX platform in order to enable the new responsive design, making it an ideal candidate for a rewrite on a more modern tech stack. After some initial prototyping, it became pretty clear that taking the additional time now to rewrite our UX platform would have significant long term improvements to the workflow of our development team. We decided that we would write the Single Line Ribbon from scratch in TypeScript. To make sure we were able to deliver the UX refresh in a timely fashion, we would not rewrite the entire UX platform at this time and instead just focus on rewriting the Ribbon. This meant we would still need to support the Multi Line Ribbon and other UX surfaces from our existing UX platform, such as context menus and task panes, alongside the new UX platform.

Building a new UX platform

Since many teams at Microsoft were already using TypeScript, we saw this as a great opportunity to connect with other web app teams to learn from their experiences. We reached out to our friends on the Outlook Web team, who at the time had just started an effort to move a significant portion of their Script# code base to TypeScript. During these conversations we learned that they, like many other popular web applications, were using React for their user interfaces. Our initial prototype of the Single Line Ribbon was written in React, so we were very eager to use some of the components that they had built for our real implementation. After getting more details on Outlook’s UX platform, we found out Outlook wasn’t the only team at Microsoft using React and that many teams had started building their app using components from a Microsoft owned open source library called Fabric React.

We started to build the new Ribbon on top of Fabric React, enabling us to reduce overall development time by leveraging the components that other teams at Microsoft had already contributed to the project. We even added some new components to the project that are now being used in other products of Microsoft. Overall, we were amazed to see how the open source mindset around Fabric React enabled us to collaborate with product teams at Microsoft that were outside of the Office organization.

The move to TypeScript made it much easier for us to leverage open source software, enabling us to spend more time writing product code and lest time writing code for build tools and general infrastructure. In addition to React, we ended up leveraging popular open source libraries like Redux, Webpack, and Jest to provide a modern development experience to our engineering team.

After a year of hard work, we ended up being very happy with our decision to build up a new UX platform. This new UX platform has enabled to deliver features that leveraged modern browser functionality, such as the use of SVGs to deliver more crisp looking icons on the new UX platform.

The rewrite has already had the anticipated impact on developer efficiency and our ability to write more features in Typescript. We will be leveraging the efficiency of the new platform to respond to user feedback and continue to improve the experience. The move to a more modern platform also had some surprising effects, as we saw it encourage us to work more closely with other web app teams within Microsoft and in the broader open source community.

Try it out today!

The new visuals are enabled by default for Word documents hosted on OneDrive. Please try it out today and let us know your thoughts on the new experience by leaving feedback in the app!

This is just an introduction to the work we’ve done over the past year. We’ll be publishing some more detailed articles on our architecture and some of the work we did to improve the performance of our UX platform. Feel free to reach out on twitter with suggestions on what you’d like to hear more about in future blog posts!

• A new architecture for Word Online’s UX Platform

Modernizing Word Online’s UX platform was originally published in Web Dev @ Microsoft on Medium, where people are continuing the conversation by highlighting and responding to this story.

You might not need a class

Developers with a background in Object Oriented programming languages are used to encapsulating code within classes. An example we see regularly from new developers is the creation of utility classes that contains some static methods. Consider this example:

While this is a perfectly reasonable way to organize your code, you could instead create a module that exports a set of utility functions:

While it is nice that the utility function is less verbose and generates less JavaScript when transpiled to ES5, this isn’t the primary reason why we prefer to use functions over classes in many situations. By favoring functions over classes, developers will naturally be writing code that adheres to the principle of Composition over Inheritance, which we’ve found makes it easier for us to write components that are testable and loosely coupled.

An interface might not be what you expect it to be

A common source of confusion for developers new to TypeScript is the concept of interfaces. Developers coming from a C# or Java background are familiar with the concept of interfaces used in a context like this:

While this is perfectly valid TypeScript, we rarely ever write code that looks like this inside the Office Online codebase. If you read the TypeScript documentation for interfaces, you’ll see them described as a way to define the types of a JavaScript object rather than something that should be implemented by a class. This means we could actually write code that looks like this:

Now, this code is fundamentally different than the code in the previous example. The prior example created an instance of a class, which has a constructor and could also have methods, and assigned it to a person variable. The second example simply created a plain JavaScript object and assigned it to the person variable. When following the second approach, developers will typically use pure functions to manipulate these plain JavaScript objects rather than having methods to manipulate the state contained within the person object. This approach allows for a clean separation of data and the code that manipulates data, which is something I’ve found makes code easier to reason about and unit test.

You may have noticed that these first two guidelines have recommended that you avoid using classes. While I personally prefer plain JavaScript objects manipulated by pure functions over classes with methods, this does not mean I think you shouldn’t use classes at all in TypeScript. In fact, I actually encourage them to be used for things like stateful React components. These recommendations are mostly about demonstrating the new possibilities a developer has for structuring their code when introduced to a language that has first-class functions.

The types don’t exist at run time

The types provided by TypeScript allow some bugs to be identified through the static analysis performed by the compiler. TypeScript is ultimately transpiled into JavaScript that is executed by the browser. Since JavaScript does not have a type system as strong as the one provided by TypeScript, the type information from TypeScript code will be stripped from a program as a result of the transpilation process. The end result is that you do not have access to the types of an object at run time like you do in some other languages like C#.

While the inability to access type information at run time may seem like a deal-breaking constraint, TypeScript supports Discriminated Unions as a mechanism for differentiating objects of different types at run time. To better understand how discriminated unions work, let’s consider an application that displays a number to the user and supports a set of actions that manipulates that number.

In this example, we have a function getNextState that takes in an Action and the current state and returns the next state. Action is a union type of the Add and Decrement interfaces. Both of these interfaces have a type property, referred to as the discriminant, that allows us to determine which Action type was passed in to the getNextState function.The TypeScript compiler is able to leverage this type property within each clause of the switch statement to narrow down the set of valid properties to just those that correspond to the interface with that type value. For example, the compiler knows that the action inside the ‘Add’ case has a numberToAdd property and it knows that any reference to numberToAdd inside of the ‘Decrement’ block is a compiler error. The use of a discriminant allows us to differentiate objects of different types at runtime while also providing us with stronger type checking and an improved intellisense experience. When discriminated unions are combined with TypeScript strict mode, the compiler is able to do exhaustiveness checking on the switch statement inside the getNextState function, which is helpful to ensure that developers update that function as new Action types are added.

Use undefined instead of null

As Douglas Crockford has said many times, one of the annoying things in JavaScript is that it has two bottom values: null and undefined. Developers coming from other programming languages are probably familiar with the null keyword and are likely to favor the usage of the null keyword over undefined. While there is nothing wrong with this approach, there are often scenarios where a variable might have a value of undefined, such as optional parameters, for a function. This would result in variables that can have a real value, null, or undefined, which means developers need to remember to check for both null and undefined. Of course you can get around this by replacing instances of

with

Since both null and undefined are falsy values. However, this approach won’t work if the type of foo also had valid falsy values (such as 0 for a number or “” for a string) that you don’t want to handle in the same fashion as null and undefined. As a result, we found it preferable on the Office Online team to avoid using null in our codebase, instead encouraging the use of undefined (almost) everywhere.

Conclusions

TypeScript has emerged as a powerful tool for writing large scale web applications. The static type checking provides familiarity to experienced programmers coming from languages like C# and Java without reducing the ability for your programs to leverage the large library of open source JavaScript libraries. Experienced developers should find the syntax of TypeScript to be very familiar, but I hope these tips help these developers reach out of their comfort zones to fully leverage the capabilities of the language.

Thinking in TypeScript was originally published in Web Dev @ Microsoft on Medium, where people are continuing the conversation by highlighting and responding to this story.

One way we’ve achieved this is by minifying all the JavaScript we send down to the browser. At first we used Microsoft’s Ajax Minifier, which reduces the size of JavaScript files by performing optimizations such as removing whitespace and renaming local variables to have shorter names. We then implemented a tool that would leverage knowledge of the entire application to rename functions and remove unused functions from the output JavaScript. This tool worked well for many years, but it was tightly coupled to our internal build system and eventually was no longer being actively maintained. This caused us to look to the open source community for a more modern solution for JavaScript minification.

We recently replaced our internal minification tool with Closure Compiler. Like our previous minification tool, Closure Compiler in Advanced Mode supports global function renaming and dead code removal. It also has additional features like function inlining and dynamic moving of code between JavaScript files. When running our JavaScript code through Closure Compiler, the size of our main JavaScript file after Gzip compression was 15% smaller than it was with our old minification tool. We found that most of these file size savings came from the compiler’s ability to move code from our main JavaScript file into one of our “delay-loaded” JavaScript files that were also fed as inputs to the compiler.

The JavaScript download time isn’t the only factor that contributes to the boot time of our applications. The browser also needs to parse the JavaScript, run our app initialization code, and render content once available. To get a better understanding of how these file size reductions would translate into boot time improvements, we ran a controlled A/B test in production for Word Online users. In the control group of this experiment, users were served JavaScript files that come from our old minification pipeline. In the treatment group, users saw JavaScript files that were minified with Closure Compiler. Our experiment showed that there was an 8% improvement in boot time across all browsers. We also saw that the “gap to interactive”, which measures the time between the document being visible to the user to the time it is editable, improved by 14% across all browsers.

After analyzing the results of this experiment in Word Online, we started moving other Office Online applications to also use Closure Compiler and saw similar performance improvements. We also did some work to make our JavaScript exception logging code compatible with Closure Compiler by creating a tool that turns minified method names in a stack trace back into their human readable form. For more info on that, check out this blog post.

Performance gains from switching to Closure Compiler was originally published in Web Dev @ Microsoft on Medium, where people are continuing the conversation by highlighting and responding to this story.

Since our JavaScript is aggressively minified with the closure compiler, it can be a bit difficult to track down the code that caused the exception since the method names have all been changed in an effort to reduce the number of bytes sent over the wire.

As an example, consider this JavaScript snippet which will cause a crash when the user clicks a button on the page.

After running it through a minifier, the output becomes something like the snippet below. This is pretty printed for clarity. In production you’d likely see all the line breaks and spaces stripped out.

I created a jsfiddle hosting this script and some basic HTML to allow the user to force a crash on the page by calling the ‘causeCrash’ function. When the user clicks the “crash button”, the stack property on the error object passed to the window.onerror handler will be something like this:

TypeError: Cannot read property 'length' of undefined
    at https://fiddle.jshell.net/_display/:62:26
    at t (https://fiddle.jshell.net/_display/:63:10)
    at e (https://fiddle.jshell.net/_display/:56:17)
    at n (https://fiddle.jshell.net/_display/:52:17)
    at causeCrash (https://fiddle.jshell.net/_display/:67:8)
    at HTMLButtonElement.<anonymous> (https://fiddle.jshell.net/_display/:70:9)

It’s not very easy to determine what happened from this stack trace alone. In an effort to improve our app’s reliability, we developed an open source .NET library that parses the stack string and determines the original function names for the code that appears in the stack trace. This tool works with any code generated by a JavaScript minifier that produces source maps, including Closure Compiler, UglifyJS2 and AjaxMin.

For each function call that appears in the minfied stack trace, the library looks up the relevant mapping entry in the source map that corresponds to the location information for that function call. In the previous example, the call to function i in the minified stack frame has a corresponding deminified stack frame with the following information:

FilePath: "crashcauser.js"
    MethodName: "level1"
    SourcePosition.ZeroBasedColumnNumber: 8
    SourcePosition.ZeroBasedLineNumber: 5

We bucket our exceptions by these deminified stack frame entries. This means that the same exception occurring on multiple browsers would be be in the same bucket. Bucketing by deminified stack frames also allows for us to track exceptions across multiple deployments, even though the minified method names might have changed between the two different versions of the application. This analysis has provided us with the necessary information to assign bugs to the right developers for our top unexpected JavaScript exceptions in Office Online.

Deminifying JavaScript call stacks was originally published in Web Dev @ Microsoft on Medium, where people are continuing the conversation by highlighting and responding to this story.