DEV Community: Anthony Frehner

Composing JavaScript Decorators

Anthony Frehner — Wed, 10 Jul 2024 01:33:34 +0000

A walkthrough and best practices guide on how to compose JavaScript decorators that use auto-accessors.

Consider skipping straight to Best Practices!

Context and Specification
Preface
Composing Decorators
- Non-Functional Chaining Example
- Writing Composable Decorators
- Order Matters
- Best Practices

Context and Specification

The Decorators Proposal on GitHub and my previous article on decorators already do a great job of breaking down the basic use-cases of decorators. My goal isn't to recreate those examples there, but instead to highlight some lesser-known features and interactions. Additionally, I'll highlight how to compose or chain multiple decorators on a single class property.

Preface

Each code sample will come with a link to an interactive Babel REPL playground, so you can try it for yourself without needing to set up a polyfill or spin up a repo. The "Evaluate" option in the top left (under Settings) should be checked in all my examples, which means that you will be able to see the code, edit it, open your browser's dev console, and see the logs / results there.

You don't need to pay attention to the transpiled code on the right-hand side of the Babel REPL, unless you want to dig into the polyfill for decorators. The left-hand side of the Babel REPL is where you can edit and write code to try out for yourself.

To emphasize, your developer tools' console should show console logs. If it doesn't, make sure that Evaluate is checked in the top left.

Composing Decorators

One important use-case that the proposal doesn't show is how to compose (or combine multiple) decorators on a single property. This is a powerful tool which helps keep your decorators clean and reusable, so let's dig into it.

In my previous article on decorators, it's was annoying to have to manually console.log after changing the value, so let's make a decorator that does that automatically for us - all while keeping the evensOrOdds decorator there, too!

Non-Functional Chaining Example

My first impression when working with chaining decorators is that it would be as simple as adding the decorator and things would "Just Work". Unfortunately, that isn't the case; in this example below, I've added the logOnSet decorator before and after a property in order to demonstrate the issue. Babel REPL

// THIS DOES NOT WORK CORRECTLY, DO NOT USE

// code collapsed from previous examples
function evensOrOdds(){}

function logOnSet(prefix = 'autologger') {
  return function decorator(value, context) {
    return {
      set(val) {
        console.log(prefix, val)
        return val
      }
    }
  }
}

class MyClass {
  @evensOrOdds(true)
  @logOnSet('even-logger:')
  accessor myEvenNumber

  @logOnSet('odd-logger:')
  @evensOrOdds(false)
  accessor myOddNumber
}

If you open the Babel REPL and look at the console logs, you may notice a couple of things:

even-logger never shows up 🤔
myOddNumber is always 0, even though the odd-logger shows that there's a different value that's trying to be set 🤔

Despite the order we place the decorators in, nothing seems to be working as we expect it to. What's going on?

Writing Composable Decorators

There's an important line in the decorators proposal that affects how multiple decorators work:

Accessor decorators receive the original underlying getter/setter function as the first value, and can optionally return a new getter/setter function to replace it. Like method decorators, this new function is placed on the prototype in place of the original (or on the class for static accessors), and if any other type of value is returned, an error will be thrown.

In other words, the last-applied decorator's setter/getter methods win out, and none of the other decorators setters/getters are applied.

Since only one setter/getter is ever applied, how would we chain decorators?

Fortunately, our decorator is passed the previous decorator's setter/getter methods (or the native getter/setters if there are no others), so we can call them ourselves! Let's update the logOnSet decorator to do this, using the value parameter that the decorator is passed: Babel REPL

function logOnSet(prefix = 'autologger') {
  return function decorator(value, context) {
    return {
      set(val) {
        const previousSetterValue = value.set.call(this, val) ?? val
        console.log(prefix, previousSetterValue)
        return previousSetterValue
      }
    }
  }
}

That fixes the myOddNumber property and logger, but myEvenNumber still isn't working correctly; we need to do the same thing in the evensOrOdds decorator, too! Babel REPL

function evensOrOdds(onlyEvens = true) {
  return function decorator(value, context) {
    let internalNumber = 0
    return {
      get() {
        // invoke the previous getter, but only return our valid number
        value.get.call(this)
        return internalNumber
      },
      set(val) {
        const previousSetterValue = value.set.call(this, val) ?? val
        const num = Number(previousSetterValue)
        if(isNaN(num)) {
            // don't set the value if it's not a number
            return internalNumber
        }
        if(num % 2 !== (onlyEvens ? 0 : 1)) {
            return internalNumber
        }
        internalNumber = val
        return internalNumber
      }
    }
  }
}

Note how we're calling the previous getter/setter with .call(this, val), which helps ensure that the this value is consistent. Importantly, we're also using the nullish coalescing operator ?? val at the end to ensure that, if the previous setter/getter doesn't return anything, we keep the original val and use that.

Order Matters

Now that it's all working, let's take another close look at the logs. You may note that the even-logger logs the value before it is validated by our evensOrOdds decorator, while the odd-logger logs the value after the value has been validated.

It's important to note that the order of our chained decorators is different for each property:

// weird ordering on decorators
class MyClass {
  @evensOrOdds(true)
  @logOnSet('even-logger:')
  accessor myEvenNumber

  @logOnSet('odd-logger:')
  @evensOrOdds(false)
  accessor myOddNumber
}

Decorators are executed from bottom-to-top, just like normal JavaScript functions are executed right-to-left: last(first()). We want our logger to be logging values after validation, so let's reorder the decorators on myEvenNumber (and finally remove all the other console logs): Babel REPL

// better ordering on decorators
class MyClass {
  @logOnSet('even-logger:')
  @evensOrOdds(true)
  accessor myEvenNumber

  @logOnSet('odd-logger:')
  @evensOrOdds(false)
  accessor myOddNumber
}

Those logs look better, and we've only had to write our console log logic once, too!

Best Practices

A TLDR of the "Writing Composable Decorators" section.

Call the the previous decorator's setter/getter: value.set.call(this, val) to enable chaining
Fall back to the original value if the previous decorator's setter/getter doesn't return anything: value.set.call(this, val) ?? val
Return a value in your setter/getter, so that other decorators can easily chain it: return internalNumber
Ensure the order is correct - decorators execute from bottom-to-top!

JavaScript Decorators and Auto-Accessors

Anthony Frehner — Wed, 10 Jul 2024 01:30:30 +0000

A walkthrough of how to create JavaScript decorators and how using auto-accessors helps improve your developer experience.

Context and Specification
Preface
Auto-Accessors
Creating Decorators
- A Simple Decorator
- Validation With Decorators
- Decorator Options
Metadata

Context and Specification

The Decorators Proposal on GitHub already does a great job of breaking down the basic use-cases of decorators. My goal isn't to recreate those examples there, but instead to highlight some lesser-known features and interactions. Additionally, in the next article in this series I'll highlight how to compose or chain multiple decorators on a single class property.

Preface

To emphasize, your developer tools' console should show console logs. If it doesn't, make sure that Evaluate is checked in the top left.

Auto-Accessors

An important feature of the Decorators spec are auto-accessors. We'll start with learning what they are and how using auto-accessor will make writing decorators easier.

The the Decorators Proposal outlines auto-accessor here. But ultimately it's a simple feature; let's look at a basic working example: Babel REPL.

class MyClass {
  accessor myBoolean = false
}

In this class definition the accessor keyword goes before the property name. However, this hasn't really changed anything about the property yet - next, we'll see how useful auto-accessors are when combined with decorators.

(Note that you can also use static with auto-accessors, such as static accessor myBoolean = false)

Creating Decorators

To better understand why we're using an auto-accessor, let's build some decorators.

A Simple Decorator

We'll start by combining auto-accessors with a decorator that doesn't actually do much, in order to get an idea of the syntax.

Here's a functional decorator that keeps an internal variable, and allows you to get and set that variable through the property on the class: Babel REPL

function simpleDecorator(value, context) {
  let internalValue = false
  return {
    get() {
      return internalValue
    },
    set(val) {
      internalValue = val
      return internalValue
    }
  }
}

class MyClass {
  @simpleDecorator
  accessor myBoolean
}

This decorator returns an object with two methods: get() and set(). This is how a decorator for an auto-accessor can "decorate" or wrap both the setter and the getter for a property in a single place; we don't have to create a simpleGetterDecorator and simpleSetterDecorator. Instead, we've combined them into a single definition with auto-accessors, which is easier.

In the end, this looks like a fairly normal function so far - which is great for an introduction!

Validation With Decorators

To set us up for the rest of the article, let's update our decorator so that it actually does some sort of validation. We'll make a decorator that only allows you to set even numbers and nothing else. Here's what that would look like: Babel REPL

function onlyEvenNumbers(value, context) {
  let internalNumber = 0
  return {
    get() {
      return internalNumber
    },
    set(val) {
      const num = Number(val)
      if(isNaN(num)) {
        // don't set the value if it's not a number or coerced to a number
        return internalNumber
      }
      if(num % 2 !== 0) {
        // don't allow odd numbers
        return internalNumber
      }
      internalNumber = val
      return internalNumber
    }
  }
}

class MyClass {
  @onlyEvenNumbers
  accessor myEvenNumber
}

So we add logic to the set() method and now anyone trying to set the myEvenNumber property on our class will go through that validation logic. Nice.

Decorator Options

Now that we have a nice only-evens decorator, let's make it handle both even and odd numbers with an option to configure which type of number we want!

Fortunately, because this is fairly-normal-looking JavaScript we're writing here, it's not too hard to configure it to work this way. We wrap the original decorator with a function that takes in an option, and then return the decorator. Babel REPL

function evensOrOdds(onlyEvens = true) {
  return function decorator(value, context) {
    let internalNumber = 0
    return {
      get() {
        return internalNumber
      },
      set(val) {
        const num = Number(val)
        if(isNaN(num)) {
            // don't set the value if it's not a number
            return internalNumber
        }
        if(num % 2 !== (onlyEvens ? 0 : 1)) {
            return internalNumber
        }
        internalNumber = val
        return internalNumber
      }
    }
  }
}

class MyClass {
  @evensOrOdds(true)
  accessor myEvenNumber

  @evensOrOdds(false)
  accessor myOddNumber
}

We've now configured our decorator to take in arbitrary options, which allows users of our decorator to customize its behavior. Yay.

Metadata

One additional tool your decorators can utilize is context.metadata. This object is passed to each decorator and you could use it for a variety of things, but you need to be careful because the metadata object is the same for all invocations of every decorator.

Continue Learning

Continue to the next post in the series to learn how to compose (or apply multiple) decorators to a single property!

The Modern Guide to Packaging Your JavaScript Library

Anthony Frehner — Wed, 31 Aug 2022 19:17:12 +0000

I had a lot of questions when it came to packaging up my JavaScript library, such as:

minify?
output to single file or maintain file/folder structure?
have an esm build (or cjs)?
transpile or not? (e.g. jsx -> createElement)
package.exports setup?
other package.json settings? (e.g. type)
multiple outputs - dev/prod?
what is "double bundling"?

With the hope of answering these questions, and more, I created the Modern Guide to Packaging Your JavaScript Library.

I created it on GitHub so that, as time goes on, it will (hopefully) remain fresh and updated - if I had written it as an article, then no one else could have contributed as easily, and it may have gone stale.

Hopefully this guide is helpful to you, too.

The Case for Browser Devtools to Emulate Mobile Viewport Changes

Anthony Frehner — Thu, 18 Nov 2021 18:25:48 +0000

When working on responsive components or websites, I frequently find myself wishing that my desktop browser could better emulate how a mobile browser actually behaves - specifically, when it comes to resizing the viewport as you scroll up and down.

And yes, it's true that nothing beats using an actual mobile device to test your code, that doesn't mean that we can't make the desktop developer experience better.

These following cases are only some of the examples of where the desktop's "Responsive Design Mode" experience doesn't actually match how mobile browsers behave:

CSS Viewport Units

I've been working with viewport units, like vh, for a long time. I've even helped resolve some of the issues with them, and it's exciting to see Safari Technical Preview release 135 with support for the new *vh units such as lvh, svh, and dvh.

These units can subtly or even quite drastically change how your website looks and behaves - especially the dvh unit (which behaves as vh used to behave when it was first implemented, until it was determined that in most cases that's actually pretty bad behavior).

However, if you play around with the new units on your desktop browser (assuming you use a browser that supports them), nothing happens - even if you're in responsive design mode!

That's because your desktop browser doesn't change the viewport size, while the mobile version of your browser does. So the only solution is to have an actual mobile browser open to test your component or website. (Again, ideally you're doing this already. But it can slow things down if this is your only option to test.)

Window Resize Events

If you have an event listener for window resize events, you may not have realized that mobile browsers fire those events quite frequently as you scroll around - because your desktop browser doesn't change the viewport, even in responsive design mode. Test out this codesandbox on your phone and on your desktop to see the difference. (Source code found here)

Proposal

I think it would be a great improvement if desktop browsers' mobile responsive design mode had the ability to emulate the viewport changing sizes as you scroll.

Additional thoughts:

Perhaps it could be turned on and off with a preference toggle?
You (probably?) don't need to add the actual browser chrome to the emulator, you could just resize the window. At least for an initial first release
Maybe it should only work when you have an actual device selected in the Device picker dropdown?

If you also think this would be helpful, please:

Add a star to the Chrome issue
Add a vote for the Firefox request
Add a vote for the Safari request

Please refrain from commenting things like "+1" :)

CSS vh (dvh, lvh, svh) and vw units

Anthony Frehner — Mon, 01 Nov 2021 17:23:21 +0000

Background

This background section is large; here's a handy link to the new unit section if you would like to skip ahead.

However, I think it can be useful to understand how we got where we are. Additionally, this information will be useful to understand when talking about the dvh and dvw units later.

Note: while I'll focus mainly on the vh unit, please know that the vw unit had the same issues. It's just easier to talk about one of them.

History of `vh`

The vh unit, as it originally existed, was defined as

Equal to 1% of the height of the initial containing block.

Expand for more info about the initial containing block

The initial containing block (ICB) definition can be found here, but I think the first bullet point summarizes it well (emphasis mine):

The containing block in which the root element lives is a rectangle called the initial containing block. For continuous media, it has the dimensions of the viewport and is anchored at the canvas origin;

In other words, it's the same size as the viewport; or the same size as the content of your website that you can see without scrolling.

Which is very useful and good... that is, until mobile browsers started doing some tricks to maximize your phone's screen space. To see these tricks, open any webpage on your phone and scroll around some bit, while paying attention not to the content of the webpage but the browser's UI itself.

You may have noticed that the browser's UI changes size as you scroll. And if the browser's UI and viewport changes size, then the question regarding vh became:

If vh is 1% of the initial containing block (ICB), but the ICB changes sizes as a user scrolls, what does vh really equal?

First Solution, First Problem

The first and simplest answer to that question was "vh changes as the ICB changes." Logically, it would seem like that should be the final answer, too.

However, there's a problem with this solution:

Let's say you have a phone that has 100px of screen space. When you load up a page, the browser UI takes up 15px which leaves 85px left for your website's content.

However, your browser is Super Cool, so when you scroll down the browser UI only takes up 10px, which leaves your website content with 90px. Or, in table form:

Browser UI State	Browser UI	`100vh` in pixels
See everything / maximized / first page load / on scroll upward	`15px`	`85px`
Small / minimized / on scroll downward	`10px`	`90px`

On your Fancy Website™, you have 5 <section style="height: 100vh"> elements on your page. When someone first loads the page, each <section> is 85px tall. But as they begin to scroll down, the browser UI begins to change size which causes those section elements to grow by 5 pixels, to a total of 90px!

Now, let's say the user's now at the bottom of the page looking at the 5th section element. They decide they want to scroll up, which has the side effect of changing the browser UI to the maximum size. That causes vh to shrink, and your sections are now all 5px smaller; when you're at the bottom of the page, that's a total of 20px of difference (4 sections with 5px each).

Just by scrolling upwards a tiny bit, the content of your page has jumped upwards 1/5 of your total screen space (100px total / 20px smaller)! That is a very jarring experience, and honestly it sucked.

Imagine if you had used vh for things like font-size, and how that would look!

Second Solution, Second Problem

With this problem in mind, in 2015 Safari / Webkit engineers decided to change the behavior of vh units:

Dynamically updating the height was not working, we had a few choices: drop viewport units on iOS, match the document size like before iOS 8, use the small view size, use the large view size.

From the data we had, using the larger view size was the best compromise.

In other words, a dynamic vh unit was not great, so they changed it to be a static unit equal to the size of the viewport when the browser UI was its smallest (and the content / "view size" was the largest).

About a year later Chrome / Blink engineers agreed and also updated vh units to do the same.

Which is where we are now (as of the time of this writing) with vh.

One of the problems with vh being the "largest view size" is that anything that is height: 100vh is now larger or overflows the screen when you first load a page. It's pretty difficult, using just CSS, to get content to fit the page exactly.

And so, in 2019, a new CSS proposal was born. And in 2021, that proposal, with feedback and improvements, was accepted in the CSS spec as several new units!

The New CSS Units

The large, small, dynamic, and traditional vh units.

Large Viewport Units

The lvh & lvw units are defined as:

The large viewport-percentage units (lv*) are defined with respect to the large viewport size: the viewport sized assuming any UA interfaces that are dynamically expanded and retracted to be retracted.

In other words, the size when the browser UI is the smallest and the website content is the largest. lvh is essentially how the vh unit currently (at the time of this writing) acts.

Small Viewport Units

The svh & svw units are defined as:

The small viewport-percentage units (sv*) are defined with respect to the small viewport size: the viewport sized assuming any UA interfaces that are dynamically expanded and retracted to be expanded.

Essentially, svh gives you units that you can use to fill the screen when the browser UI is at its largest, and the website content is at its smallest.

Dynamic Viewport Units

The dvh & dvw units are defined as (with emphasis mine):

The dynamic viewport-percentage units (dv*) are defined with respect to the dynamic viewport size: the viewport sized with dynamic consideration of any UA interfaces that are dynamically expanded and retracted. This allows authors to size content such that it can exactly fit within the viewport whether or not such interfaces are present.

The sizes of the dynamic viewport-percentage units are not stable even while the viewport itself is unchanged. Using these units can cause content to resize e.g. while the user scrolls the page. Depending on usage, this can be disturbing to the user and/or costly in terms of performance.

While the dvh & dvw units may sound good on paper, the caveats noted in the definition above (and in the first problem & solution section above) actually lead me to believe that you should only use them in very rare and specific situations.

Traditional Viewport Units

With these new units, where does vh and vw sit? Interestingly enough, they are currently defined as:

The UA-default viewport-percentage units (v*) are defined with respect to a UA-defined UA-default viewport size, which for any given document should be equivalent to the large viewport size, small viewport size, or some intermediary size.

Personally, I find this definition to be too vague, and I have concerns about how this will affect users and developers. I guess we'll see where it goes!

Polymorphic React Button Component in Typescript

Anthony Frehner — Mon, 13 Sep 2021 22:16:33 +0000

[Edited Oct 6 2021 with improved code due to feedback. See implementation section for details]

Polymorphic?

The goal of this article is to create a component that can be either a button OR a react-router Link component OR a native <a> (anchor) tag.

But first, let's define the word "polymorphic." From Dictionary.com:

having more than one form or type

So when we call something a "polymorphic" component, it means that we can use the same component and it will have more than one form under the hood.

In this case, designers usually want a consistent look for interactive elements such as buttons and links, and developers want an easy interface to use these common styles, while also maintaining semantic and accessible HTML.

Use Cases / Examples

So we're going to make a component called <Button /> that will allow someone to choose whether to use it as a button, a react-router Link component, or as an anchor for external links. And we want to have Typescript enforce and validate the correct props for each one.

For example, we want to be able to do the following:

Button / Default

<Button
  as='button'
  styleType='primary'
  onClick={(evt) => {
    // evt should be of type React.MouseEvent<HTMLButtonElement, MouseEvent>
    console.log(evt)
  }}
>
  hello!
</Button>

<Button
  // 'as' is optional, and will default to 'button'
  styleType='secondary'
  // allow other button attributes, such as 'type'
  type='button'
>
  hello!
</Button>

Link

<Button
  as='link'
  // 'to' is required since it's required in the Link component
  to='/test'
  styleType='primary'
  onClick={(evt) => {
    // evt should be of type React.MouseEvent<HTMLAnchorElement, MouseEvent>
    console.log(evt)
  }}
>
  hello!
</Button>

External Link / Anchor Tag

<Button
  as='externalLink'
  styleType='primary'
  onClick={(evt) => {
    // evt should be of type React.MouseEvent<HTMLAnchorElement, MouseEvent>
    console.log(evt)
  }}
  // href and other anchor attributes should be allowed
  href='/someurl'
  target='_blank'
  rel='noopener noreferrer'
>
  Link
</Button>

Unstyled button

An unstyled button is occasionally used in designs where a designer wants some clickable text but without all the pomp and circumstance. Shouldn't be used very often.

<Button as='unstyled'>Unstyled</Button>

Implementation Notes:

Hopefully the use-cases above show how we want our component to be polymorphic. When it comes to the implementation, I originally started by referring to these wonderful articles by Ben Ilegbodu and Iskander Samatov. However, I kept running into issues with certain things like the rest parameters / props not being correctly typed or the to prop not being correctly recognized for link type Buttons. It was frustrating and I spent several days and iterations on it.

Finally, I took a step back, tried to simplify as much as I could, and got it to work. It's not as clean as I had hoped, but it's working and that's what matters, right? Anyway, some takeaways:

I had to use type-predicate narrowing to get the rest params to be correctly typed. There's probably room to improve them there, but see the functions isLinkProps, isButtonProps, and isAnchorProps. Apparently it isn't enough for Typescript for us to key off of the as prop? 🤷
The anchor tag must explicitly have the {rest.children} part; the jsx-a11y/anchor-has-content ESLint plugin doesn't like it when you keep children as part of the {...rest} spread.
It took me awhile to figure out that I wanted JSX.IntrinsicElements['button'] as the prop type definition; I had tried other things like React.ComponentPropsWithoutRef<> and React.ElementType<> combinations without much success for some reason - they would fail one of the test cases I outlined above. One day I'll understand Typescript better to tell you why.

Implementation

Edited; thanks to this wonderful comment from Mae Capozzi below, the typing for this component can be simplified! I can remove the type-predicate narrowing issues I described above by not destructuring the as prop. Apparently TS likes that a lot more!

import * as React from 'react'
import { Link } from 'react-router-dom'
import type { LinkProps } from 'react-router-dom'

type BaseProps = {
  children: React.ReactNode
  className?: string
  styleType: 'primary' | 'secondary' | 'tertiary'
}

type ButtonAsButton = BaseProps &
  Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof BaseProps> & {
    as?: 'button'
  }

type ButtonAsUnstyled = Omit<ButtonAsButton, 'as' | 'styleType'> & {
  as: 'unstyled'
  styleType?: BaseProps['styleType']
}

type ButtonAsLink = BaseProps &
  Omit<LinkProps, keyof BaseProps> & {
    as: 'link'
  }

type ButtonAsExternal = BaseProps &
  Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof BaseProps> & {
    as: 'externalLink'
  }

type ButtonProps =
  | ButtonAsButton
  | ButtonAsExternal
  | ButtonAsLink
  | ButtonAsUnstyled

export function Button(props: ButtonProps): JSX.Element {
  const allClassNames = `${props.styleType ? props.styleType : ''} ${
    props.className ? props.className : ''
  }`

  if (props.as === 'link') {
    // don't pass unnecessary props to component
    const {className, styleType, as, ...rest} = props
    return <Link className={allClassNames} {...rest} />
  } else if (props.as === 'externalLink') {
    const {className, styleType, as, ...rest} = props
    return (
      <a
        className={allClassNames}
        // provide good + secure defaults while still allowing them to be overwritten
        target='_blank'
        rel='noopener noreferrer'
        {...rest}
      >
        {props.children}
      </a>
    )
  } else if (props.as === 'unstyled') {
    const {className, styleType, as, ...rest} = props
    return <button className={className} {...rest} />
  } else {
    const {className, styleType, as, ...rest} = props
    return <button className={allClassNames} {...rest} />
  }
}

Javascript AWS SDK v3 S3 guide

Anthony Frehner — Fri, 20 Aug 2021 16:35:44 +0000

That is way too many acronyms in the title, yet they almost seem necessary. I promise I'm not trying to out-SEO you.

With the new v3 update to the Javascript AWS-SDK, you can use the sdk quite a bit differently. You don't have to, but the new way can reduce the amount of code you import at runtime, and thus can be "more performant." At the moment of writing this article, there aren't a lot of docs on it either. So this article is just as much for me as is it for you!

The major difference is that you now import/require a very bare "client", and send your commands through that client.

// The "old" way
const { S3 } = require('awk-sdk')
const s3 = new S3(s3Config)
const object = await s3.getObject(objConfig).promise()

// The "new" way
const { S3Client, GetObjectCommand } = require('@aws-sdk/client-s3')
const s3Client = new S3Client(s3Config)
const object = await s3Client.send(new GetObjectCommand(objConfig))

So, some things to point out:

Note that you can install only the client you need, not the whole AWS SDK library. In this case, you only have to npm install @aws-sdk/client-s3. This reduces the space on disk and the install time 👍
You only need to import/require the exact functions you need from the client, e.g. GetObjectCommand. This reduces the amount of code you need at runtime 👍
You send the command you want through the client, and a promise is returned by default instead of needing to call .promise() 👍

Here's the v3 documentation homepage if you want to explore it as well. I wouldn't say it's bad, per se, but I wouldn't say it's good either. It does seem extensive though.

A closer look at Javascript event listeners & objects

Anthony Frehner — Fri, 19 Feb 2021 17:15:31 +0000

This post isn't meant to be an introduction to Javascript event listeners and the event object; instead it's meant to answer some random questions I had while working on my own event listener system (since I was unable to use domNode.dispatchEvent). --edit-- I just discovered EventTarget! See the section below

Questions:

If there are multiple event listeners, do they receive the same event object or different objects?

They receive the same event object.

var button = document.createElement('button')

var temp1, temp2

button.addEventListener('click', (evt) => temp1 = evt)

button.addEventListener('click', (evt) => temp2 = evt)

button.click()

console.log(temp1 === temp2) // true

If an event is `preventDefault()`-ed, do other listeners still receive that event?

Yes; preventDefault() is a signal that the event's action shouldn't happen, but other listeners will still get called. stopPropagation() and stopImmediatePropagation() is what's used to prevent other listeners from being called. (See questions below)

The Event interface's preventDefault() method tells the user agent that if the event does not get explicitly handled, its default action should not be taken as it normally would be. The event continues to propagate as usual

MDN Source

If there are multiple event listeners added to the same DOM element, and the first listener calls `stopPropagation()`, do the other listeners receive the event?

Yes. stopPropagation() prevents the event from bubbling up to higher-up listeners, but it does not prevent listeners from being fired on the same DOM node.

When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.

DOM Standards spec

And that's why stopImmediatePropagation() exists; it will prevent ALL other event listeners from being fired.

Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.

DOM Standards spec

EventTarget

If you ever think about implementing your own event listener system, you should consider using EventTarget instead! Here's an example:

const target = new EventTarget()

target.addEventListener('myEvent', (evt) => {console.log(evt)})

target.dispatchEvent(new Event('myEvent'))

EventTarget works in all modern browsers and NodeJS >14.5. That's a lot easier than doing it yourself! :)

Interactions with the history stack

Anthony Frehner — Mon, 15 Feb 2021 21:23:38 +0000

JS Trivia time: given the following code, what is logged?

window.history.pushState(null, null, "/temp1");
window.history.pushState(null, null, "/temp2");
window.history.pushState(null, null, "/temp3");

console.log("before go", window.history.length);
window.history.go(-3);

console.log("after go", window.history.length);
window.history.pushState(null, null, "/temp4");

console.log("after go after pushState", window.history.length);

Answer (click to see)

before go 4
after go 4
after go after pushState 2

Followup question!

window.history.pushState(null, null, "/temp1");
window.history.pushState(null, null, "/temp2");
window.history.pushState(null, null, "/temp3");

console.log("before go", window.history.length);
window.history.go(-3);

console.log("after go", window.history.length);
window.history.replaceState(null, null, "/temp4");

console.log("after go after replaceState", window.history.length);

Answer (click to see)

before go 4
after go 4
after go after replaceState 4

What's going on?

The history stack allows you to navigate through it, and it will maintain the stack as it was through your navigation. However, when you push onto the stack, you erase any future navigations from your current location in the stack.

A simplified demonstration:

window.history.pushState(null, null, "/temp1");
// history.stack looks like ['', '/temp1']
// current entry is '/temp1'

window.history.pushState(null, null, "/temp2");
// history.stack looks like ['', '/temp1', '/temp2']
// current entry is '/temp2'

window.history.pushState(null, null, "/temp3");
// history.stack looks like ['', '/temp1', '/temp2', '/temp3']
// current entry is '/temp3'

console.log("before go", window.history.length);
// before go 4

window.history.go(-3);
// history.stack looks like ['', '/temp1', '/temp2', '/temp3']
// current entry is ''

console.log("after go", window.history.length);
// after go 4

window.history.pushState(null, null, "/temp4");
// history.stack looks like ['', '/temp4']
// current entry is '/temp4'

console.log("after go after pushState", window.history.length);
// after go after pushState 2

and if we were only to change the pushState call above with replaceState, here's what it would look like:

window.history.replaceState(null, null, "/temp4");
// history.stack looks like ['/temp4', '/temp1', '/temp2', '/temp3']
// current entry is '/temp4'

Spec talk

Here's a link to the WHATWG HTML spec for history update steps.

The key thing to pay attention to here is step 2:

2 If isPush is true, then:

2.1 Remove all the entries in browsingContext's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

isPush is true for pushState and false for replaceState, which can be found here for pushState and here for replaceState - paying attention to the last words in those sentences.

The 'discarded' page lifecycle state

Anthony Frehner — Tue, 10 Nov 2020 21:23:43 +0000

Background

Browsers don't like the reputation of being resource hogs, even if you have 100+ tabs open. To help reduce CPU + memory demands while still allowing you to keep those tabs around, browsers came up with the Page Lifecycle - a way to reduce resource usage while still providing a good user experience.

This article does a great job of further explaining the different states and what happens in them, as well as APIs you can use to check which state your page was or is in.

Discarded State

Let's focus on the discarded state. The article above defines that state as

A page is in the discarded state when it is unloaded by the browser in order to conserve resources. No tasks, event callbacks, or JavaScript of any kind can run in this state, as discards typically occur under resource constraints, where starting new processes is impossible.

In the discarded state the tab itself (including the tab title and favicon ) is usually visible to the user even though the page is gone.

Or in other words - the page hasn't been used for awhile, and the browser wants to free up resources, so it's going to "close the page" while still showing the tab for the page. That's pretty cool and useful.

However, what isn't detailed in that article (at the time of writing) is: what exactly happens when the page is loaded up again?

The answer (again, for the moment) appears to be: it's up to each browser to determine that. (To be clear, there's nothing wrong with that!)

What actually happens

From my testing, let me tell you what appears to happens in Chrome - and how it caused a bug in my application:

The page is loaded
After some time, Chrome determines that it needs to go into the discarded state
Chrome appears to cache the original HTML of the page that you're on
The page goes into discarded state and all resources (CPU, memory) are removed for that tab
Now you open that tab/page again, and Chrome needs it to be in the active state
It pulls the cached HTML and re-parses + re-executes it - (which means that it refetches any CSS or Javascript referenced by the HTML)
The page is now loaded

The problem I ran into lies in that second-to-last step: it is using a cached version of the HTML but downloading a new version of the JS.

Is that a problem?

But why would that cause a problem?

Well, in any case where you need a change to happen in both your HTML and your JS in order to work, and there's some place where you don't have versioned assets.

In my case, it's because of how the infrastructure is set up:

We're using import-maps with SystemJS
I have one import-map that is not versioned and is not cached; the JS assets it links to are though
I have another import-map that is inlined into the HTML page; this import-map is for things like shared dependencies that don't change very often (e.g. react, react-dom, etc.)

So in this situation, I had put a new shared library into the inlined import-map, and also updated all the JS assets to look for the shared version of that library instead of the bundled one. However, for those people that had a cached version of the HTML (for example, the people that had their page go into the discarded state), they never downloaded the new HTML but did download the new JS - and that broke the page!

A solution

Fortunately, the solution for users is simple enough - just a page refresh will cause them to download the latest HTML and all is good again.

For me, it also means that I can handle the situation where the app is being started from the discarded state by checking document.wasDiscarded, and if that's true, then force a full-page refresh which should resolve the bug before it happens.

if(document.wasDiscarded) {
  window.location.reload(true);
}

Making CSS vars with SCSS vars

Anthony Frehner — Tue, 06 Oct 2020 17:15:15 +0000

SASS treats CSS variables (also known as custom properties) in a special way, which means it's a little difficult to create CSS vars dynamically:

Sass parses custom property declarations differently than other property declarations. All tokens, including those that look like SassScript, are passed through to CSS as-is.

SASS docs

Which can cause problems, especially for my situation where I want to

Keep the SASS variables around because they're used in a lot of existing code, but also
Add CSS variables for new code

So here's how I've worked around this. It's not ideal, because it still duplicates the name of the SASS variable, but it works for my situation. 🤷

$primary-color: #30dbb4;

@mixin add-css-variable($name, $color) {
  --#{$name}: $color;
}

:root {
  // repeat as necessary for all your vars
  @include add-css-variable('primary-color', $primary-color);
}

You can test this out in the wonderful SassMeister playground

The Order of Javascript Object Keys

Anthony Frehner — Wed, 02 Sep 2020 17:33:46 +0000

Trivia time! What does the following array look like?

Object.keys({
  2: true, 
  1: true,
  '00': true,
  'b': true,
  'a': true,
  '3': true,
})

Answer (click to see)

[ "1", "2", "3", "00", "b", "a" ]

So what exactly is going on?? Here are the ordering rules:

Numbers are ordered first, and they are ordered within themselves from smallest to largest as long as they are >=0 (see below for more details)
Strings come second, and they are ordered within themselves by insertion order
Symbols come last, and they are ordered within themselves by insertion order (note that we didn't use symbols in this example)

But wait, why did '3' come before '00' if strings are ordered within themselves by insertion order?

Well, turns out that JS will see if your string can be converted to a number - if it can, then it will order it with the numbers and not the strings.

And what about '00'? Apparently it converts it to a new number, then does something similar to toString() on new number, and compares that new string with the original string.

If they match, then it can be lumped in with the numbers. If it doesn't match, then it's a string.

const originalString = '00'
const stringToNumber = Number(originalString)
const matchesOriginalString = stringToNumber.toString() === originalString // false: '0' !== '00'

Pretty clear, huh? :P

Thanks to this article for helping https://www.stefanjudis.com/today-i-learned/property-order-is-predictable-in-javascript-objects-since-es2015/

Here's the wording from the spec:

Numbers

For each own property key P of O such that P is an array index, in ascending numeric index order, Add P as the last element of keys.

i.e. insert numerical keys first in ascending order

Strings

For each own property key P of O such that Type(P) is String and P is not an array index, in ascending chronological order of property creation, Add P as the last element of keys.

i.e. insert string keys in order of creation as long as they're not an array index. So what's that?

An integer index is a String-valued property key that is a canonical numeric String (see 7.1.21) and whose numeric value is either +0 or a positive integer ≤ 2⁵³ - 1. An array index is an integer index whose numeric value i is in the range +0 ≤ i < 2³² - 1.

source for array index

i.e. a string key that is a canonical numeric string and greater than +0

so... what's a canonical numeric string?

[A canonical numeric string is an] argument converted to a Number value if it is a String representation of a Number that would be produced by ToString, or the string "-0".

source for canonical numeric string
i.e. if that string is the same as any number that is toString()

Symbols

For each own property key P of O such that Type(P) is Symbol, in ascending chronological order of property creation, Add P as the last element of keys.

i.e. insert symbol keys in order of creation

DEV Community: Anthony Frehner

Composing JavaScript Decorators

Table of Contents

Context and Specification

Preface

Composing Decorators

Non-Functional Chaining Example

Writing Composable Decorators

Order Matters

Best Practices

JavaScript Decorators and Auto-Accessors

Table of Contents

Context and Specification

Preface

Auto-Accessors

Creating Decorators

A Simple Decorator

Validation With Decorators

Decorator Options

Metadata

Continue Learning

The Modern Guide to Packaging Your JavaScript Library

The Case for Browser Devtools to Emulate Mobile Viewport Changes

CSS Viewport Units

Window Resize Events

Proposal

CSS *vh (dvh, lvh, svh) and *vw units

Background

History of vh

First Solution, First Problem

Second Solution, Second Problem

The New CSS Units

Large Viewport Units

Small Viewport Units

Dynamic Viewport Units

Traditional Viewport Units

Polymorphic React Button Component in Typescript

Polymorphic?

Use Cases / Examples

Button / Default

Link

External Link / Anchor Tag

Unstyled button

Implementation Notes:

Implementation

Javascript AWS SDK v3 S3 guide

A closer look at Javascript event listeners & objects

Questions:

If there are multiple event listeners, do they receive the same event object or different objects?

If an event is preventDefault()-ed, do other listeners still receive that event?

If there are multiple event listeners added to the same DOM element, and the first listener calls stopPropagation(), do the other listeners receive the event?

EventTarget

Interactions with the history stack

Followup question!

What's going on?

Spec talk

The 'discarded' page lifecycle state

Background

Discarded State

What actually happens

Is that a problem?

A solution

Making CSS vars with SCSS vars

The Order of Javascript Object Keys

Numbers

Strings

Symbols

CSS vh (dvh, lvh, svh) and vw units

History of `vh`

If an event is `preventDefault()`-ed, do other listeners still receive that event?

If there are multiple event listeners added to the same DOM element, and the first listener calls `stopPropagation()`, do the other listeners receive the event?