DEV Community: Thomas Beverley

How we used JSDoc & Webpack to write some custom JavaScript decorators & annotations

Thomas Beverley — Thu, 19 May 2022 14:24:22 +0000

This article was originally posted on the Wavebox blog

At Wavebox, we use JavaScript for some of our code and we came across an interesting problem (and solution) this week when trying to export some data.

We encapsulate a lot of our data in JavaScript classes/models, this means we can store sparse data and access it through the models, with the models automatically substituting defaults and creating more complex getters for us. As part of a new feature, we want to be able to share of some this data, but not all of it... and this is where we came up with an interesting solution that involves JSDoc decorators & annotations...

The models

We store most of our data structures in classes that wrap the raw data, a simple model looks something like this...

class App {
  constructor (data) {
    this.__data__ = data
  }

  get id () { return this.__data__.id }

  get name () { return this.__data__.name || 'Untitled' }

  get nameIsCustom () { return Boolean(this.__data__.name) }

  get lastAccessed () { return this.__data__.lastAccessed || 0 }
}

const app = new App({ id: 123, name: 'test', lastAccessed: 1000 })

The __data__ variable holds the raw JavaScript object and when accessing something in the model, we normally use a getter that provides the value.

In the above example, we've got some basic getters that just return some data like id. We've also got some getters that return a default if the value doesn't exist like name and lastAccessed.

These models form the a core part of how we manage data and ensure that we don't need to check for undefined's throughout the code, substitute default values and so forth.

Exporting some of the data

We've been working on a new feature that will allow you to share some of your models, but there's a problem. We only want to share some of the data. In our simple App example above, there are some fields we want to share and some we don't...

id & name these are good to share 👍
nameIsCustom this just works by reading the name field, don't share 🚫
lastAccessed we don't want to share this 🙅‍♂️

So lets looks at the most basic example, we can drop nameIsCustom by just reading the raw __data__ object...

console.log(app.__data__)
// { id: 123, name: 'test', lastAccessed: 1000 }

...but this still gives us the lastAccessed field that we don't want. So we went around writing an export function that looks more like this...

class App {
  ...
  getExportData () {
    const { lastAccessed, ...exportData } = this.__data__
    return exportData
  }
}

...looks great. It works! But I predict a problem...

Keeping the code maintainable

The getExportData() function works great, but there's a problem. Some of our models are quite large, and these models will have new fields added in the future. Future me, or future anyone else working on the code is guaranteed to forget to add another exclude to that function and we're going to get a bug. Not so great. So I started thinking about ways we could make this a little bit more maintainable.

Big changes to the models were out of the question, we started with this pattern quite some ago and there are tens of thousands of uses of the models through the code, so whatever we come up with needs to have minimal impact everywhere.

This got me thinking about decorators. I was thinking about a way that I could generate a list of properties to export in the same place that they're defined. This would improve maintainability going forwards.

I came up with some pseudo code in my head that looked something like this...

const exportProps = new Set()
function exportProp () {
  return (fn, descriptor) => {
    exportProps.add(descriptor.name)
  }
}

class App {
  @exportProp()
  get id () { return this.__data__.id }

  @exportProp()
  get name () { return this.__data__.name || 'Untitled' }

  get nameIsCustom () { return Boolean(this.__data__.name) }

  get lastAccessed () { return this.__data__.lastAccessed || 0 }
}

const app = new App({})
Object.keys(app).forEach((key) => { app[key })

console.log(Array.from(exportProps))
// [id, name]

...you can decorate each getter with @exportProp which is nice, but the implementation is far from ideal. In fact it's the sort of code that gives me nauseous 🤢. To begin with, the exported properties now need to run through a decorator before being accessed, there's going to be a performance hit for this. Also to generate the list, you need to create an empty object and iterate over it, although there's nothing wrong with this, it didn't feel particularly nice.

So I started to think about how else we could achieve a similar pattern...

Using JSDoc

This is when I started to think, could we use JSDoc to write some annotations at build time? Doing this would remove the need to generate anything at runtime, keeping the getters performant and allowing us to add an annotation to each property in-situ as required.

I started to play around and came up with this...

class App {
  /**
  * @export_prop
  */
  get id () { return this.__data__.id }

  /**
  * @export_prop
  */
  get name () { return this.__data__.name || 'Untitled' }

  get nameIsCustom () { return Boolean(this.__data__.name) }

  get lastAccessed () { return this.__data__.lastAccessed || 0 }
}

Okay, the comments now span a few more lines, but if it satisfies all the other requirements I can live with that. If we run JSDoc over the file, we get something like this...

[{
  "comment": "/**\n   * @export_prop\n   */",
  "meta": {
    "filename": "App.js",
    "lineno": 61,
    "columnno": 2,
    "path": "/src/demo",
    "code": {
      "id": "astnode100000128",
      "name": "App#id",
      "type": "MethodDefinition",
      "paramnames": []
    },
    "vars": { "": null }
  },
  "tags": [{
    "originalTitle": "export_prop",
    "title": "export_prop",
    "text": ""
  }],
  "name": "id",
  "longname": "App#id",
  "kind": "member",
  "memberof": "App",
  "scope": "instance",
  "params": []
}, ...]

...and hey presto! We get the getter name, and in the list of tags is the export_prop annotation we added. A little bit of looping around on this and we can generate a nice list of property names to export.

Mixing JSDoc & Webpack

You could write a pre-build script to write the docs into a file and then read that in at compile time, but where's the fun in that? We use Webpack for our bundling needs, which means we can write a custom loader. This will run JSDoc over the file for us, play around with the data a little bit and give us a nice output. We can use this output to configure which data comes out the model.

So our Webpack loader can look something a little bit like this, it just runs JSDoc over the input file, strips out everything we don't need and writes the output as a JSON object...

const path = require('path')
const jsdoc = require('jsdoc-api')

module.exports = async function () {
  const callback = this.async()

  try {
    const exportProps = new Set()
    const docs = await jsdoc.explain({ files: this.resourcePath })

    for (const entry of docs) {
      if (entry.kind === 'member' && entry.scope === 'instance' && entry.params && entry.tags) {
        for (const tag of tags) {
          if (tag.title === 'export_prop') {
            exportProps.add(entry.name)
            break
          }
        }
      }
    }
    callback(null, 'export default ' + JSON.stringify(Array.from(exportProps)))
  } catch (ex) {
    callback(ex)
  }
}
...and we just need to update our webpack config to use the loader...

config.resolveLoader.alias['export-props'] = 'export-props-loader.js' 
config.module.rules.push({
  test: /\*/,
  use: {
    loader: 'export-props'
  }
})

...great! That's all the hard work done. Now we can add this to our App model and see what we get out!

import exportProps from 'export-props!./App.js'

class App {
  /**
  * @export_prop
  */
  get id () { return this.__data__.id }

  /**
  * @export_prop
  */
  get name () { return this.__data__.name || 'Untitled' }

  get nameIsCustom () { return Boolean(this.__data__.name) }

  get lastAccessed () { return this.__data__.lastAccessed || 0 }

  getExportData () {
    return exportProps.reduce((acc, key) => {
      if (this.__data__[key] !== undefined) {
        acc[key] = this.__data__[key]
      }
      return acc
    }, {})
  }
}

const app = new App({ id: 123, name: 'test', lastAccessed: 1000 }) 
console.log(app.getExportData())
// { id: 123, name: 'test' }

Hey presto! There it is! Using JSDoc we can generate the list of properties to export at compile time, serialise those into an array and read that out at runtime. We can then use that list to only include what we want in the exported data 👍.

The really great thing is, that we can define which properties are exported next to where they are declared in the hope a future dev will be able to continue along with with pattern.

Taking it one step further

Maybe you've got some properties that need more configuration, or some special behaviours... You can change some of the annotations to look something like this...

class App {
  /**
  * @export_prop isSpecial=true
  */
  get id () { return this.__data__.id }
}

...and then in your loader use...

if (tag.title === 'export_prop') {
  if (tag.value === 'isSpecial=true') {
    // Do something special
  } else {
    exportProps.add(entry.name)
  }
  break
}

If you need it, this gives a way to configure what each one does.

Wrapping up

I thought I'd share this neat little trick, because once you've got the pattern setup it's trivially easy to use. I mean sure, it's a complete mis-use of JSDoc, comments and Webpack loaders, but it works flawlessly, runs at compile time and helps keep our code maintainable. It's a win win!

A 55% Performance Improvement Upgrading Material-UI from v4 to v5

Thomas Beverley — Thu, 14 Oct 2021 13:40:38 +0000

This article was originally posted on the Wavebox blog

A big part of our browser Wavebox, is the user interface and for some of this we utilize React & Material-UI. We've been a heavy user of Material-UI since 2016 and started out using version 0.14.2. Since then we've seen some big changes to the library and a few big migrations. Material-UI 5 recently launched and we wanted to share some of our experiences in upgrading from version 4.

From figuring out what needed to be done, to actually doing it across our entire codebase took us about 3 days, but in doing so we were able to grab a 55% performance improvement. Here's how we did it...

📘 Start with the Migration Guide

Migrating from v4 to v5, you're going to be spending some time here, but the guide covers all the basics and more. There's something to be said for just diving and ignoring the instructions and our takeaway from the migration guide was "update and run codemodes". So we did...

npm install @mui/material @mui/styles @mui/lab @mui/icons-material @emotion/react @emotion/styled
npm uninstall @material-ui/core @material-ui/icons @material-ui/lab
npx @mui/codemod v5.0.0/preset-safe .

...this gives us a starting point. All be it a non-compiling starting point, but still a starting point.

🕶️ Styling

This was the biggest chunk of work for us. We've gone through a styling change before with Material-UI when they moved from inline styles to JSS, but this time Material-UI 5 moves away from JSS as the default styling solution to emotion. We've been relying heavily on JSS for the majority of our components, so lots of them looked something like this...

const styles = (theme) => ({
  root: {
    padding: 8,
    overflow: 'hidden'
  },
  item: {
    margin: 12,
    display: 'inline-block',
    backgroundColor: theme.palette.primary.main
  }
})

@withStyles(styles, { withTheme: true })
class MyComponent extends React.PureComponent {
  render () {
    const { className, classes, theme, ...passProps } = this.props

    return (
      <div className={clsx(className, classes.root)} {...passProps}>
        <div className={classes.item}>1</div>
        <div className={classes.item}>2</div>
        <div className={classes.item}>3</div>
      </div>
    )
  }
}

We had a few options readily available to us in migrating. Either using the styled component api, or using the system. So lets convert this simple component to both to see what it looks like.

Option 1: Using Styled Components

Styled components wrap another component with a set of styles, and from there you just add the component to your react tree. At first glance it looked comfortably familiar, however this is now the legacy solution for styling and isn't compatible with React.StrictMode or React 18 which means we're going to need to revisit this at some point.

const Root = styled('div')(
  ({ theme }) => `
  padding: 8px;
  overflow: hidden;
`);
const Item = styled('div')(
  ({ theme }) => `
  margin: 12px;
  display: inline-block;
  background-color: ${theme.palette.primary.main};
`);
class MyComponent extends React.PureComponent {
  render () {
    const { classes, theme, ...passProps } = this.props

    return (
      <Root {...passProps}>
        <Item>1</Item>
        <Item>2</Item>
        <Item>3</Item>
      </Root>
    )
  }
}

Option 2: Using the System

The system lets you define your styles inline alongside the element as a prop. This almost feels like going back to the old inline-styles of React 0.14, but behind the scenes a whole load of clever bits happen, these styles get placed in a stylesheet so they can be re-used. There is a tradeoff using this approach and that is performance. According to Material-ui's own benchmark rendering 1000 Box components takes 370ms vs just 160ms for styled components.

const Item = function (props) {
  return (
    <Box
      sx={{
        margin: 12,
        display: 'inline-block',
        backgroundColor: 'palette.primary.main'
      }}
      {...props} />
  )
}

class MyComponent extends React.PureComponent {
  render () {
    const { classes, theme, ...passProps } = this.props

    return (
      <Box
        sx={{
          padding: 8,
          overflow: 'hidden'
        }}
        {...passProps}
      >
        <Item>1</Item>
        <Item>2</Item>
        <Item>3</Item>
      </Box>
    )
  }
}

🤔 Option 3: Erm...

Okay, I'll be honest here, we stopped for a minute to consider our options. Performance is a big thing for us and more than doubling the render time isn't something that's overly appealing. We've been using Material-ui long enough to remember the performance boost in moving from inline-styles to JSS and all those little performance boosts really make a difference.

We were also looking for some kind of shortcut, we've got a lot of components and having to go through each one by hand takes time. We couldn't see any easy method to automate (either at runtime, or during development) the migration.

We then looked at re-implementing "withStyles" so that we could consume our current styles and output something that we can use with MUI5, but this just felt like a band-aid that we'd be picking off at a later date.

So we went back to the drawing board and looked at other options. After a bit of playing around we settled on something completely different. Something that could potentially give us a free performance boost and some semi-automated migration.

🤩 Introducing CSS! Yeah, okay, a little anticlimactic. Our thinking was that by dropping the whole CSS in JS approach we'd drop a bunch of processing work that needs to be done in JavaScript and grab some free CPU cycles along the way. We're already using LESS for a few styles around the app, so everything is already setup in our build scripts. This didn't seem like all that much of a jump.

With a bit of (cool 😎) scripting, we thought we could semi-automate most of the migration. Our style definitions normally start with "const styles =" so it wouldn't be too hard to pull those out, convert them from JSS into CSS and write them into a file. Here's what our new component looks like...

MyComponent.module.less

.root {
  padding: 8px;
  overflow: hidden;
}
.item {
  margin: 12px;
  display: inline-block;
  background-color: "__TODO__"
}

MyComponent.js

import classes from './MyComponent.module.less'
class MyComponent extends React.PureComponent {
  render () {
    const { className, theme, ...passProps } = this.props

    return (
      <div className={clsx(className, classes.root)} {...passProps}>
        <div className={classes.item}>1</div>
        <div className={classes.item}>2</div>
        <div className={classes.item}>3</div>
      </div>
    )
  }
}

As you can see, not too much of a jump. The only bit missing is that pesky theme property for the background color, we came up with a couple of options here...

Just define the property twice, once in JavaScript and other time using LESS
Use CSS variables and write this out to the document from JavaScript

...we decided we could use both. We split our theme properties into two categories, those that don't change ("palette.primary.main" is one of those, it's always blue) and those that do change ("palette.background.paper" depends on the users preference for dark or light mode). Using both approaches gives us the best of both worlds. By extending our theme provider, we could push out what we need to CSS pretty quickly...

class ThemeProvider extends React.PureComponent {
  constructor (props) {
    super(props)

    this.state = {
      theme: createTheme({ ... })
    }
    this.stylesheet = document.createElement('style')
    document.head.prepend(this.stylesheet)
  }
  render () {
    const { theme } = this.state

    document.body.className = `theme-${theme.palette.mode}`
    this.stylesheet.innerHTML = `
      :root {
        --theme-primary-main: ${theme.palette.primary.main};
      }
    `

    return (
      <StyledEngineProvider injectFirst>
        <ThemeProvider theme={theme}>
          {children}
        </ThemeProvider>
      </StyledEngineProvider>
    )
  }
}

LESS variables

As mentioned above, we tend to use LESS variables for colors that don't change, but if you need to customize them depending on the theme you can read the class from the document body. It's a little bit more code, but everything is setup at compile time.

@theme-primary-main-light: #0277BD;
@theme-primary-main-dark: #4FC3F7;

.item {
  :global(body.theme-light) {
    background-color: @theme-primary-main-light;
  }
  :global(body.theme-dark) {
    background-color: @theme-primary-main-dark;
  }
}

CSS Variables

If the color is completely undetermined or it's something that we know will change, then we can use CSS variables. Once the theme provider is up and running the colors are set and component looks as it should.

.item {
  background-color: var(--theme-primary-main);
}

🚀🚀🚀 Performance. Yes!

As we suspected, we managed to pick up some free performance, but what we weren't expecting is how much. We used our settings screen as a benchmark, taking 3 sets of measurements using the performance tab in Chromium.

Material-UI 4

CPU Time: 1191ms, 1200ms, 1163ms (Average 1185ms)
Blocking time: 740ms, 859ms, 792ms (Average 797ms)
Peak JS Heap: 36.1mb, 35.9mb, 36.2mb (Average 36mb)

Material-UI 5

CPU Time: 558ms, 758ms, 559ms (625ms)
Blocking time: 316ms, 447ms, 314ms (359ms)
Peak JS Heap: 34.5mb, 35.2mb, 34.6mb (34.7mb)

Yep, that's a whopping 55% reduction in blocking time. Down from 797ms to 359ms. That saving deserves some cake to celebrate 🎂.

Alongside that we saw an equally impressive 48% reduction in CPU time and a slight drop in memory (1.3mb). All these big (and small) improvements help keep Wavebox running fast and smoothly.

We're working to roll this update out to our beta channel over the next week or so in Wavebox version 10.95.