DEV Community: Zach Olivare

How to make your app faster with React's key prop

Zach Olivare — Tue, 11 Apr 2023 17:28:19 +0000

Every React element has a special key prop. It has a single purpose: to uniquely identify a React element.

There are two circumstances in which you as a React developer can use the key prop to your advantage:

to prevent an element from being unnecessarily re-rendered (the most common)
to force an element to be re-rendered (advanced, used only in rare circumstances)

Preventing unnecessary re-renders

Far and away the most common and useful purpose of the key prop is to prevent unnecessary re-renders of a component that is created by mapping over an array.

Using it usually looks something like this:

function MyComponent({items}) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  )
}

👉 But how does using key prevent unnecessary re-renders?

key prevents unnecessary re-renders by allowing React to determine that an element still exists, unchanged from the last render, it just may have moved.

👉 How does that work?

Remember that key's only purpose is to uniquely identify a React element. Every time each one of those <li> elements is rendered, React will do a "diff" (calculate the "difference") between the previous element that was rendered with a particular key and and current element that is being rendered with that key. If there is no difference between the two, React will not modify that element in the DOM. If it does find a difference, React will unmount the previous component instance, create a new component instance, and mount that one instead.

The key prop won't/can't/shouldn't do anything to prevent a component from re-rendering if it has changed. But it can & should prevent a component from re-rendering if it has only moved!

👉 Can you give a more concrete example?

What happens if you reverse the items array from the above snippet? Well, with our current code, React wouldn't create or destroy a single <li> element! It would simply re-arrange the existing <li>s to match the new order of the array. And how does React know where to place each element? Because of it's unique key of course!

Moving existing DOM nodes is much more performant than destroying and re-creating nodes.

The wrong way -- using index as the key

Let's contrast our previous implementation to a very common, yet incorrect one:

<ul>
  {items.map((item, index) => (
    {/* This is bad, don't set key to index */}
    <li key={index}>{item.name}</li>
  ))}
</ul>

You'll see this key={index} in tutorials and production code alike, but its usage is lazy and has negative performance implications.

If you think it's your only solution, scroll down to the last section of this blog post. I promise there's a better way!

The catch is though, that oftentimes those performance implications crop up later, well after the key={index} code was initially written.

👉 But why is key={index} bad?

If the contents of the array that you're mapping over is guaranteed never to change in any way, then there wouldn't be a performance hit caused by setting key to index.

But in my experience, there is almost no array (or code in general) that is guaranteed never to change in any way.

Sure, the code you're writing today has no way for the array to change. But what happens next month when product wants to...

add sort functionality to the UI?
allow the user to add items to the list?
delete items?
drag and drop to re-order items?
filter the list?
search for items in the list?

Every one of those features will be negatively impacted by key={index}.

The developer adding that new feature might be a different member of your team, and they might never have to touch the file that you wrote key={index} in, so they don't know about it. They just trusted you to do the right thing and you let them down 💔.

👉 Why is there a negative performance impact to key={index}?

Consider the scenario where one single item is inserted to the middle of the array.

// before
<li key={0}>Item 0</li>
<li key={1}>Item 1</li>
<li key={2}>Item 2</li>

// after
<li key={0}>Item 0</li>
<li key={1}>---NEW ITEM---</li>
<li key={2}>Item 1</li> // notice this element's key has changed
<li key={3}>Item 2</li> // notice this element's key has changed

With key being set to index, the key of every element after the added element will change. So even though none of those elements have actually changed, they will all be unmounted and have duplicate elements re-created and re-mounted in their place, a process that takes infinitely longer than just leaving the DOM nodes alone and adding the new element ot the middle.

This is equally true for sorting, filtering, searching, and every other type of operation listed in the bullets above.

Force an element to re-render

We've gathered by now that when an React element's key changes, it is unmounted and a brand new component instance is created in its place.

I say "re-render" in the section title, but that is overly simplistic. Changing an element's key will not cause the same component instance to re-render. It will cause the existing component instance to be unmounted and eventually garbage collected. It then causes a brand new component instance to be created, and mounted.

That process of creating a new component instance is definitely slower than a standard re-render, so again, use this pattern of "forceful re-rendering" sparingly and only when there are no better options.

We've also seen that far and away the most common place to use key is inside of a .map() function. But it doesn't have to be inside of a map. key can exist on any React element.

So if you need to force a component to "re-render" in a situation that it otherwise wouldn't one way to approach that problem is to force a change to its key.

// WARNING: This is shitty code and for illustrative purposes only

function MyComponent() {
  const [key, setKey] = useState(0)

  return (
    // Every time onClick() fires, OtherComponent will be replaced
    // with a completely new component instance, resetting any and
    // all state it and any of its children maintain.

    <OtherComponent key={key} onClick={() => setKey(key + 1)} />
  )
}

What makes key so special?

The key prop is special because it is one of only two props that are not accessible from within the component instance (the other being ref).

<MyComponent key="foo" />

function MyComponent(props) {
  // props.key is undefined
}

In fact, if you attempt to access key from within a component instance, you'll get a warning in your console:

But I don't have an id for this object 😭

Inevitably, you'll run into a situation where you need to render a list of objects, but those objects don't come with prepackaged a unique identifier. Maybe they're coming from a third-party API, or maybe they're just a list of strings.

In cases like that, there are still a few options:

Option 1: Generate a random id for each object

If you're fetching a list of objects from an API and they don't have a unique identifier, you can just add one yourself.

async function getMovies() {
  const response = await fetch('http://example.com/movies.json')
  const movies = await response.json()

  // Add a unique id to each movie with Math.random()
  return movies.map((movie) => ({...movie, id: Math.random()}))
}

And just like that, you have a unique identifier for each item!

You can of course use library like nanoid or uuid to generate a unique identifier, but I've found that Math.random() is good enough for most use cases.

Note: It's important that we're doing this process of assigning random ids before we return the array of movies. If we were to do it inside of the .map() function in the component, we'd be generating a new id every time the component re-renders, which would defeat the purpose of having a unique id in the first place.

Option 2: Combine multiple properties into a key

If none of your object's properties are guaranteed to be unique, but combined they are almost certain to be unique, that is usually good enough.

async function getUsers() {
  const response = await fetch('http://example.com/users.json')
  const users = await response.json()

  // Add a psuedo-unique id by combining multiple properties
  return users.map((user) => ({...user, id: `${user.firstName}-${user.lastName}-${user.phone}`}))
}

I quit LastPass and moved to 1Password after 10 years

Zach Olivare — Mon, 06 Mar 2023 14:12:00 +0000

I've been a big advocate for LastPass for the last 10 years. I have encouraged probably around a dozen other people to use it. I even called it out specifically (along with 1password) in my Use a password manager post back in 2020.

But I've been growing increasingly frustrated with LastPass recently so I decided to try out 1Password. tldr I found 1Password to solve many of the issues that I have with LastPass; and even though it's not perfect, overall I think 1Password is a better product.

Please allow me to explain why:

1. LastPass had a major, concerning, data-compromising Hack in 2022

There are a lot of details to this hack. But my cliff note version is that:

URLs and usernames have all been stolen in cleartext (not encrypted)
Passwords and secure notes have also been stolen, but the information was encrypted.
"Unencrypting" one of those passwords would cost the attacker somewhere between $75,000 and $1.5M

So unless you're super famous or work for the government, your passwords at least are reasonably safe. But the attackers now know which sites you use, which would make it easier to perform a phishing attack on you.

2. 1Password is more secure

1Password has a unique security concept they call a Secret Key. You can read this in depth explanation to how the secret key works, but again, here are my cliff notes:

It's a 128-bit (i.e. really long) alpha numeric code
It's combined with your master password to encrypt your data
It makes it so that even if 1Password was hacked in exactly the same way as LastPass was in 2022, the hacker would not be able to crack a single password even if he put every computer on Earth to work on the cracking and ran them for zillions of times the age of the universe

1Password also encrypts your item URLs and titles. So even if 1Password were breached, the hacker would have no valuable information about you.

3. 1Password is a lot easier to use

3a. 1Password has an Archive

When you use a password manager for long enough, you undoubtedly have some passwords that gather dust. Passwords that you think you'll probably never need again; maybe an old job, or maybe you accidentally (or on purpose) created two accounts for the same website.

These are passwords that you don't want to appear in normal searches, and passwords that you don't want suggested to you to sign into stuff. But at the same time, deleting them is scary! It's hard to be certain that you'll never need these passwords for any reason ever again.

I made the mistake of assuming this once when I left a job. I deleted every "old" password related to that job, and thought I was fine. That was until I needed to log into my old HR platform to access tax documents 6 months later.

1Password's Archive gives you an easy place to toss these "old" passwords, with the confidence that if you do ever need them again for any reason, they'll still be there for you to go and find.

3b. 1Password makes sharing passwords with family a lot easier

LastPass conflates the concepts of item organization and item sharing. With a LastPass family subscription, the way you share passwords to other family members is to move the password from whatever folder you wanted it in into a special "Shared-" folder.

So if you have a folder in LastPass where you normally put all passwords of a certain type, e.g. Streaming, in order to share that password with your family you have to move it into a different folder, Shared-Streaming. So your streaming passwords are now split up between two different folders. That's kind of annoying.

In 1Password, you share with family members by creating different "Vaults". Conceptually, a "Vault" is similar to a "Shared-Folder"; but for me there are some meaningful differences:

Vaults are not the primary tool for password organization in 1Password (that's where favorites and tags come in). A vault's primary purpose is for sharing (think of having different safes in your house and giving different people the combination to different safes).
LastPass "Shared-" folders inter-mingle too easily with regular folders. Vaults are distinct; you only have a few of them and they are not intermingled with Tags.
You can name vaults whatever you want, they don't have to begin with "Shared-" (the detail oriented folks out there will understand)

3c. Tags are better than Folders

LastPass uses folders for organization, 1Password uses tags.

Any users of Gmail will immediately recognize the concept of tags and why they're inherently superior to folders: an item can only be in one folder, but it can have any number of tags.

By eliminating folders, 1Password also eliminated the dreaded LastPass (none) folder. This is the place in your LastPass vault that all items that don't have a folder specified go. I'm pretty sure its intended purpose is strictly to shame you for having an unorganized LastPass vault.

I had dozens of folders and subfolders in LastPass (> 50). But when I moved over to 1Password I realized that most of those folders served no purpose whatsoever. Or said another way, looking at those items together as a group provided no benefit. The only reason the folders existed was to get them out of (none). I currently have 9 1Password tags.

3d. 1Password has built in "2FA codes"

You know your Authenticator app, right? The app on your phone that generates Time-based One Time Passwords (TOTP). You might use Google Authenticator or Authy, or even LastPass Authenticator.

1Password (mostly) replaces the need for that app. When you sign into an app that has 2FA configured in 1Password, the 2FA code will automatically be copied to your clipboard, so that without a single extra click or even picking up your phone, you can just paste the code right into the site and go.

Isn't not involving your cell phone (a 2nd device) less secure?

Short answer: No. If you keep passwords on the same phone that you have your Authenticator app on (which most everyone does) then you don't actually have a "2nd factor". You're better off spending your time focusing on keeping your 1Password master password long and secure.

1Password's head of security has a much more in-depth write up on that topic here.

Pro tips for using 1Password as your Authenticator app:

The "Scan QR code" button seems to be broken on the Mac app currently; use the one in the browser extension instead

If the site doesn't give you a QR code, and instead only the "copy this code into your app" function, 1Password supports that too, it's just not as obvious.

Choose Edit on the password you want to save a OTP code for

Choose add another field

One-Time Password

Paste the code you copied from the website

Done! That process is equivalent to scanning the QR code.

3e. 1Password has a native apps for your computer instead of just a browser extension

Using a native app to organize your saved passwords is just a better experience. It also lets 1Password use features like Touch ID and Apple Watch integrations that only native Mac apps have access to!

3f. 1Password supports saving multiple different websites for the same credentials

I've encountered a number of websites over the years that have let you log in at a couple different urls. Or sometimes you need to log into multiple different subsystems of an app that share the same credentials (like corporate SSO for example).

LastPass makes that a real pain to deal with. You have to duplicate the login credentials over multiple LastPass entries, and then LastPass will yell at you for having "duplicate passwords" unless you dig deep into the settings and configure "Equivalent Domains". What a nuisance.

In 1Password, you can just add another website when editing an existing entry. Couldn't be simpler.

3g. 1Password has first class support for multiple accounts

If you use LastPass personally, and your workplace uses LastPass to store shared credentials, you're shit out of luck. You cannot sign into multiple LastPass accounts at the same time.

The only solution is to either never access personal passwords in your work browser, or copy personal/work passwords to the other vault.

1Password lets you sign into multiple accounts at the same time and easily switch between them.

3h. 1Password has customizable fields on every entry

A LastPass entry has a set number of fields depending on its type. A password type entry will have a name, url, username, password, and notes. And that's it. If you want to save any extra information about that site it has to go in the notes field.

1Password entries feel kind of like a "phone contacts" application in that you can add any number of different types of fields to the entry.

4. Things LastPass does better

I have kind of torn LastPass to shreds in this article, and I think rightly so. But there are a couple things that I think they do better than 1Password; features I would like to see 1Password adopt:

4a. LastPass lets you search on the Notes field

The Notes field is a catch all for credential entries. You can put any helpful information in notes for that entry. One common thing I like to include in notes are some aliases to help me find this entry later.

For example the HR software that my company uses is called DayForce. But I can't remember that name for the life of me. So I always search for one of the aliases that I entered in the notes field ("SkySlope HR") and it pops right up in LastPass.

But 1Password doesn't search on the notes fieldddddd!!!!

What the heck, come on guys.

4b. LastPass lets you share passwords with people outside your family subscription

In LastPass you can share any password with any other LastPass user. Doing so frequently is annoying because the share has to be managed inside of that one password, and you have to re-enter the email every time, but nonetheless it's a nice feature to have.

1Password only allows you to share passwords to one of the other people in your family or organization subscription.

4c. LastPass lets you save arbitrary form data

LastPass has a "Save All Entered Data" option for saving all the data you typed into long forms. I personally use this feature for testing websites, but it's useful for any repetitive form-filling.

1Password doesn't appear to have anything similar.

5. A Feature both are lacking

The ability to control which entries are suggested for auto-fill at which time, and easily toggle between them.

Say for example that you only want it to suggest your work passwords when you're at work, and your home passwords when your at home. Or you have a vault/folder that contains family member accounts that you need to have access to to help them do something in once in awhile.

5a. LastPass has Identities

LastPass identities are, in concept, exactly what I'm looking for here. Each identity has certain passwords that are only suggested while you're acting as that identity or when you're acting as the "All" identity.

But it's far from perfect:

The experience of moving sites between identities is frustratingly difficult
The new browser plugin popup doesn't let me switch between identities (without going all the way into my vault). This feature existed before their recent re-skin of the browser plugin popup.
When adding a new site, it gets added to whatever identity you currently have active.
- That makes sense when you first think about it but is frustrating in practice. You never think about which identity is active when saving new credentials, which means that later you have to go figure out where your lost credential ended up and then move it to the correct identity (probably "personal" or the equivalent).
- At least let me choose the default identity that new credentials should always be added under (probably "personal") [1Password does let you choose which vault to add new credentials to by default]
- But preferably, let me choose which identity these credentials are added to in the creation process
- A configurable default would also be nice here

5b. 1Password has nothing of the sort

1Password does not have a way to only auto-fill credentials from a certain "active" vault.

What they should do is (this does not currently exist):

Let me right click on a vault and choose Make active vault, and then only auto-fill credentials from that vault
If I want to auto-fill from all vaults again, I would right click and Remove active vault on that same vault I originally made "active"

Boom, done.

The closest 1Password gets to something like this is the ability to Disable Vaults. If this setting could be toggled more quickly, it might be an acceptable solution to the problem.

How to test TypeScript type definitions with Jest

Zach Olivare — Sun, 22 Jan 2023 23:26:21 +0000

Have you ever toiled to get the TypeScript types just right on a particular function and thought to yourself, "I wish I could write a test to make sure that I don't break this type definition next time I edit this function"? Me too! In this post I'll give you thorough instructions on how you can do just that.

Setup

The library we're going to use to execute these static type tests is one that I made called jest-tsd. It's a wrapper around tsd to make it really easy to use with Jest.

Install jest-tsd and its peer dependency.

   # With yarn
   yarn add --dev jest-tsd @tsd/typescript
   # Or with npm
   npm i -D jest-tsd @tsd/typescript
   # Or with pnpm
   pnpm i -D jest-tsd @tsd/typescript

Exclude .test-d.ts files from your TypeScript compiler build.

This is important because your type definition test files will intentionally add tests that throw TS compiler errors
In your tsconfig.json, add:

   "exclude": ["**/*.test-d.ts"],

Add a new Jest test for your type definitions

   // src/init-translation.test.js

   import {expectTypeTestsToPass} from 'jest-tsd'

   it('should not produce static type errors', async () => {
     await expectTypeTestsToPassAsync(__filename)
   })

The Function Under Test

I want to use a non-trivial example type definition in this post so that I can write some non-trivial type tests. The rest of this section is explaining how that function works, feel free to skip if you don't care.

The function I've chosen here, initTranslation takes 1 or 2 arguments. Its purpose is to return a translate function that can be called to map a translation key to text that can be shown on a UI for a particular language or region. The optional second parameter provides a way to avoid defining the same UI string multiple times.

// src/init-translation.ts

// Function type overload 1
export function initTranslation<G extends Record<string, string>>(
  genericDict: G,
): (key: keyof G) => string

// Function type overload 2
export function initTranslation<G extends Record<string, string>, P extends Record<string, string>>(
  genericDict: G,
  createPageSpecificDict?: (link: (key: keyof G) => string) => P,
): (key: keyof G | keyof P) => string

// Actual function implementation that is generic enough to satisfy
// the type constraints of all function type overloads.
export function initTranslation(
  genericDict: Record<string, string>,
  createPageSpecificDict?: (link: (key: any) => string) => Record<string, string>,
): (key: string) => string {
  /* implementation */
}

The first argument is a dictionary object whose keys & values are all strings.
The second argument is a function with a link() param that returns a similar dictionary.
- The difference is that this second object can invoke the link() function as a value of the object.
- link() gets passed a key from the first parameter of initTranslation in order to reuse that already defined UI string.
- In the actual implementation, link() is secretly an identity function. Its only purpose is to provide strong typing of translation keys. Changing a linked key should throw a type error.

Here's a simple example of how it might be used:

let translate = initTranslation(
  {'foo.bar': 'Foobar'},
  (link) => ({
    'foo.baz': link('foo.bar'),
    'one.two': '1 2',
  }),
)

Here is the full implementation of the initTranslation function in case it's helpful to aid in understanding:

// src/init-translation.ts

export function initTranslation(
  genericDict: Record<string, string>,
  createPageSpecificDict?: (link: (key: any) => string) => Record<string, string>,
): (key: string) => string {
  const pageSpecificDict = createPageSpecificDict?.((key) => key)
  const fullDict = { ...genericDict, ...pageSpecificDict }

  function translate(key: string): string {
    const val = fullDict[key] ?? ''
    const isLinkedKey = !!genericDict[val]
    return isLinkedKey ? translate(val) : val
  }

  // Give access to raw dictionary if desired for unit tests
  translate.dictionary = fullDict
  translate.keys = Object.keys(fullDict)

  return translate
}

Writing a Type Definition test

jest-tsd has a variety of different assertions available to you. Here we'll make use of expectType and expectError.

// src/init-translation.test-d.ts

import {expectType, expectError} from 'jest-tsd'
import {initTranslation} from './init-translation'

First a series of tests for the single parameter version of initTranslation:

let translate1 = initTranslation({'foo.bar': 'Foobar'})

// It should accept key defined in first param dictionary
expectType<(key: 'foo.bar') => string>(translate1)

// It should throw error for key not included in dictionary
// TS Error - Argument of type '"123"' is not assignable to parameter of type '"foo.bar"'
expectError(translate1('123'))

And then similar tests for the two param version:

let translate2 = initTranslation(
  {'foo.bar': 'Foobar'},
  (link) => ({
    'foo.baz': link('foo.bar'),
    'one.two': '1 2',
  }),
)

// It should accept keys defined in either first or second param dictionary
expectType<(key: 'foo.bar' | 'foo.baz' | 'one.two') => string>(translate2)

// It should throw error for key not included in either dictionary
// TS Error - Argument of type '"123"' is not assignable to parameter of type '"foo.bar" | "foo.baz" | "one.two"'
expectError(translate2('123'))

Finally test to ensure that the link() function will only accept keys previously defined in the first param dictionary:

// Link function should only accept keys defined in first param dictionary
expectError(initTranslation(
  { 'foo.bar': 'Foobar' }, 
  // TS Error - Argument of type '"one.one"' is not assignable to parameter of type '"foo.bar"'
  (link) => ({ 'one.two': link('one.one') })
))

// Link function should not accept keys defined in second param dictionary
expectError(
  initTranslation({ 'foo.bar': 'Foobar' }, 
  (link) => ({
    'one.one': 'One',
    // TS Error - Argument of type '"one.one"' is not assignable to parameter of type '"foo.bar"'
    'one.two': link('one.one'),
  })),
)

Tests in TypeScript?

I can hear you saying, "but Zach, you made a big deal in your post on Jest testing mistakes saying that tests should always be written in JavaScript, not TypeScript!".

And I absolutely stand by that. Writing tests in TS makes them harder to maintain over time and adds no value to the tests.

The actual Jest test file described above is still written in JavaScript!

Conclusion

Next time you take the time to write complicated generic types for some utility function in your shared code, I hope you'll also take a little time to write tests for those types!

5 JavaScript Testing Mistakes to Avoid

Zach Olivare — Wed, 27 Apr 2022 13:45:04 +0000

Mistake #1: Excessive mocking

I've heard it said before that mocks are a code smell, but I disagree with that. Mocks are great, in moderation. It makes a lot of sense to mock out things like network calls or responses from a 3rd party library. Sometimes it also makes sense to mock your own modules in order to isolate the unit you're trying to test.

But when a particular test starts requiring you to mock out multiple other modules, or when the amount of code dedicated to mocking rivals or exceeds the amount of code actually dedicated to testing in that file, something has gone wrong. Those tests have now become much, much harder to maintain than they otherwise would be.

To fix this you either need to restructure your code to make it more testable, or write end-to-end tests to cover this module because it's not suitable for unit tests.

Mistake #2: Using enzyme

Enzyme is dead.

tldr; it was a bumpy road for them to create a React 16 enzyme adapter, they never actually released an official React 17 adapter, and it is not possible to create a React 18 enzyme adapter without major changes to the code base that are not going to happen.

Even before Enzyme died, React Testing Library was already well on its way to becoming the community standard (it is supported out of the box with Create React App) because unlike enzyme, Testing Library's API encourages you to avoid including component implementation details in your tests.

Mistake #3: Snapshot testing entire components

Snapshot tests are very alluring because they give you a lot of output while requiring you to write very little code. Jest says that:

Snapshot tests are a very useful tool whenever you want to make sure your UI does not change unexpectedly.

But unfortunately, that sense of security is a lie.

First and foremost, jest is wrong to say that snapshots "make sure your UI does not change"; what they actually do is let you know when your markup changes. And it's not necessarily problematic that the markup of your component changed. There are an infinite number of changes that I can make to your markup without changing your UI at all. You know how else I can determine if your markup is going to change? By actually reading the source code.

The other biggest problem with snapshots is that in real world applications they end up changing very frequently and quite dramatically. The diffs of snapshot files end up being so long that the people reviewing your code are 90% of the time going to completely ignore them, removing 100% of their value. And even when people do take the time to attempt to read your massive snapshot diff, what are they supposed to be looking for? It is an exercise in futility.

I made the title of this section about "entire components" instead of just "snapshot testing" because there is a newer way to use snapshots that I think is really neat and very effective; inline snapshots. They are inline because the snapshot is written directly into the source file instead of into a separate file. Basically it gives you the ability to write expect().toBe() tests without manually entering the expected result, and also gives you the ability to easily update those expected results if your code changes.

They look something like this:
it('formats integer', () => {
  expect(format.currency(1)).toMatchInlineSnapshot(`"$1"`)
  expect(format.currency(12)).toMatchInlineSnapshot(`"$12"`)
  expect(format.currency(123)).toMatchInlineSnapshot(`"$123"`)
})

it('formats decimal', () => {
  expect(format.currency(0.12)).toMatchInlineSnapshot(`"$0.12"`)
  expect(format.currency(0.123)).toMatchInlineSnapshot(`"$0.12"`)
  expect(format.currency(0.129)).toMatchInlineSnapshot(`"$0.13"`)
})
The toMatchInlineSnapshot() function starts out blank and is automatically filled in with that string template when the test is executed.

Mistake #4: Writing tests in TypeScript

TypeScript is great. Every single project that I create professionally or personally (my personal website included) is written in TypeScript. However, writing your tests in TypeScript provides little to no value.

In fact, more often than not your TypeScript test files end up having to define custom types of their own or do a bunch of funky typecasting in order to tell the TypeScript compiler to calm down and accept my fake data. Doing this makes the tests more difficult to maintain, harder to read, and simply creates cruft that does not add any value and has no reason to be there.

This is a minor point, but TypeScript tests also usually require more work to setup because they have to be compiled, and you always have to tell typescript to add all the global functions that your tests reference. It's not that these things are difficult, they're just more setup to do that again...adds no value to your project.

Mistake #5: Having a describe() that wraps the entire test module

I admit that this final point is more just annoying than anything else.

If you've ever worked with me you already know that I really hate repeating myself. I try quite hard to make my code as DRY as reasonably possible. So when I see duplication for the sake of duplication, I need to put a stop to it immediately.

Here's an example:

// get-link.test.js

describe('get link handler', () => {
  it('should do this', () => {})
  it('should do that', () => {})
})

What possible purpose could that describe() serve? When the test is run, this is the output

PASS  get-link.test.ts
  get link handler
    ✓ should do this (4 ms)
    ✓ should do that (4 ms)

The exact same information is repeated on lines 1 and 2! For Pete's sake, just remove the pointless describe().

The only defense of this tactic that I've heard is that it makes the code consistent if you later add a second describe() in the file. But it would not make sense for get-link.test.js to have any tests in it that didn't test "get link"; so the only way it could have another describe() would be inside of the root one, in which case you can STILL remove the root one. 🙃

New git commands to replace 'checkout'

Zach Olivare — Wed, 16 Feb 2022 20:36:04 +0000

Git somewhat recently introduced two new commands, switch and restore. Together, these commands split up the functionality of the git checkout command.

Don't worry, checkout isn't going anywhere and you don't have to change your current workflows if you don't want to.

People who are new to git may have an easier time understanding the purpose of these new commands than they would learning all the uses of checkout though, so it might still be worth your time to learn these new commands if you spend much time mentoring new devs.

The old way

At first glance it might seem odd that these new commands aren't introducing any new functionality. But consider all the different types of things that the checkout command can do:

# Switch to an existing branch
git checkout <branch>

# Create a new branch (and switch to it)
git checkout -b newBranch

# Discard changes to a file
git checkout -- <file>

# Replace the contents of a file (with whatever's in main)
git checkout main -- <file>

There are two categories of functionality happening in those examples:

The first two commands switch which branch you're on (git switch)
The second two commands replace the contents of files in your working directory (git restore)

The new way

Here's how you would perform those same tasks using switch and restore:

# Switch to an existing branch
git switch <branch>

# Create a new branch (and switch to it)
# -c is short for --create
git switch --create newBranch

# Discard changes to a file
git restore <file>

# Replace the contents of a file (with whatever's in main)
git restore <file> --source main

Bonus Tip

The restore command also provides a (potentially more logical) new way to unstage files.

# The old way
git reset HEAD <file>

# The new way
git restore --staged <file>

The old way used the reset command to copy from HEAD (your last commit) to the index (staging area). Because the HEAD and index now match, the change you made to the file only exists in your working directory, meaning the file is "unstaged".

The reset command defaults to the --mixed mode, which affects your HEAD and index. There is also reset --soft which only affects the HEAD (and leaves the index and working directory untouched), and reset --hard which moves the HEAD, index, and working directory.

reset --hard is potentially destructive because it changes the working directory without committing or stashing it.

For more on the reset command, there is a fantastic section of the git book on the topic.

With the new way, you're stating that you want to "restore staged files" and by default, if --staged is given, the contents are restored from HEAD. The effect is the same as the old way, copying from HEAD to the index, "unstaging" the file.

I've always felt that the old way was a roundabout way to accomplish unstaging a file, made extra confusing by the implied --mixed. The new way is still not the most clear thing in the world, but in my opinion it's in incremental improvement.

To clear that up, you should create a git alias!

git config --global alias.unstage "restore --staged"

And then you can use it like this:

git unstage <file>

How to manipulate a Gremlin Cosmos DB from inside a Node.js Azure Function

Zach Olivare — Wed, 22 Jul 2020 15:34:09 +0000

This post assumes that you've already got an Azure Functions project set up and running locally on your computer. If not, please see to my previous post about how to do exactly that.

So you've got a Functions project, and you've created a Cosmos DB in the azure portal, now how do you connect them?

The way it's supposed to work (but doesn't)

The way that the interaction of writing to a database from within an Azure Function is supposed to work is via a binding.

You create an entry in your function.json file for an output binding to Cosmos DB:

{
  "name": "employeeDocument",
  "type": "cosmosDB",
  "databaseName": "my-database",
  "collectionName": "myCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyAccount_COSMOSDB",
  "direction": "out"
}

And then you use the context.bindings object to write to the property you specified in the name field above:

export default async function(context) {
  let document = {
    id: 4,
    name: 'Zach',
    employeeId: '004',
    address: '221b Baker St',
  }

  context.bindings.employeeDocument = document
}

But that DOES NOT WORK!

All that happens when this code runs is a vertex with no data is created in the Cosmos DB.

Why is that? Because Microsoft does not currently support binding to a Cosmos DB using the Gremlin API.

All of their examples (those are three separate links) use the SQL API, without anywhere saying that these bindings are only supported in the SQL API, and not in the Gremlin API.

I'm guessing that the SQL API came out before the Gremlin API, and was at the time this documentation was written the only available API. So the Microsoft MVPs that wrote these "documentation" articles weren't aware that they should state that what they were doing was specific to SQL.

It still confuses me how this binding that supposedly does not exist manages to write anything at all to the DB, even if that is only an empty vertex. Perhaps the SQL code is still running behind the scenes and by some coincidence still has some effect on the Gremlin graph?

The way it actually works

Now that I've hopefully helped you avoid the pitfall that stole hours of my life, what we're actually going to do is make use of the gremlin NPM package.

Because of current limitations of Cosmos DB's Gremlin API, we'll see in this post that using the base gremlin NPM package is somewhat awkward and difficult. I've created a new library called gremlin-cosmos to make the interface between Gremlin and Cosmos more developer friendly.

Remember that because we're developing our functions locally, we can install NPM packages and then the node_modules directory automatically gets pushed into Azure with your function code so that everything continues to work in the cloud.

npm i gremlin

After installing the NPM package, first thing you need to do is define some configuration variables about your database. At the root of your project create a SharedCode directory and inside of that create a gremlinConfig.ts file.

Note: My examples are going to assume you're using typescript. If you're not, you'll have to change the file names to .js, remove any typing information, and change the import / export syntax to use require / module.exports

// SharedCode/gremlinConfig.ts

export default {
  endpoint: 'wss://my-cosmos-db.gremlin.cosmos.azure.com:443',
  primaryKey: 'superSuperSecretKey==',
  database: 'my-database',
  collection: 'myCollection',
}

You can find each of these data in your Cosmos DB on the Azure portal:

endpoint can be found on the Overview tab
primaryKey can be found on the Keys tab
database can be found on the Data Explorer tab, it is the top level item in the DATA section
collection can be found by expanding the (just described) database to show its collections

Once you have the configuration down, you can then use that information to create a Gremlin client that you'll use to communicate with the database:

// MyFunction/index.ts

import config from '../SharedCode/gremlinConfig'

export default async function(context) {
  const authenticator = new Gremlin.driver.auth.PlainTextSaslAuthenticator(
    `/dbs/${config.database}/colls/${config.collection}`,
    config.primaryKey,
  )

  let client = new Gremlin.driver.Client(config.endpoint, {
    authenticator,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json',
  })
}

After the Client has been crated, you can finally create your first vertex!

// MyFunction/index.ts

let query = `g.addV(label).property('pk', partitionKey).property('name', name)`

await client.submit(query, {
  label: 'person',
  name: 'Zach',
  partitionKey: 'pk',
})

Note: If it is not passed explicitly, the id field will be auto assigned to a GUID that does not exist as a key in the database

As you can see, the syntax here is quite unfortunate. You have to craft this query as a string. Values with quotes around them get treated as strings, and values without quotes get interpreted as keys in the object that you pass as the second argument to client.submit().

Gremlin is not supposed to be written like that, but has to be when working with Cosmos DB's Gremlin API because Cosmos does not support Gremlin's nicer bytecode syntax.

In Conclusion

In this post, we've seen that Microsoft doesn't exactly make it easy to work with Cosmos DB's Gremlin API inside of an Azure Function. It doesn't have any bindings, and doesn't support the backend features necessary to make it easy to work with the gremlin NPM package either.

As I hinted at earlier, I've created a wrapper around the gremlin NPM package to make it easier to work with Cosmos' Gremlin API; it's called gremlin-cosmos.

How to get started with Azure Functions in Node.js

Zach Olivare — Tue, 14 Jul 2020 17:33:25 +0000

I was asked to write several Azure Functions in JavaScript that modified a Cosmos DB via its Gremlin API. When I was asked to do that, I had only a vague idea of what an Azure Function was, I had never touched Cosmos DB before and I couldn't begin to imagine what the hell a Gremlin API was.

But after hours spent sorting through the confusing, incomplete assortment of Microsoft documentation on the topic, I did manage to produce some nice functions and gain an understanding of the various aspects of Azure Functions.

In this post, I hope to help your getting started experience move along faster than mine did.

Note: There are a number of different languages that you can write Azure Functions in, in this article I will only be referencing the JavaScript (and TypeScript) languages specifically.

Why would you want to use an Azure Function?

Jamstack is growing in popularity, and for good reason! Jamstack sites are serverless. Instead of storing source files on a dedicated server, the source files are instead served over a CDN for better (potentially global) performance.

But if there's no server, then how do you interact with a database or any other backend service? That's where Azure Functions (or something like it) comes in.

The idea behind Azure Functions is to have a blob of code that you can push to the cloud, without having to worry about ecosystem in which it runs. You don't have to create (for example) an express server and then figure out how to publish and run that server in the cloud. Instead, you just give Azure a blob of code and set some configuration options about when that code is run.

A quick overview of how they work

There are 4 pieces that make up an Azure Function, as illustrated well by the Azure Portal:

Trigger
Inputs
The actual function code
Outputs

Trigger

The function trigger is the condition that tells the function to run. Azure supports a wide variety of triggers; additions or mutations of Blob Storage, a change to a Cosmos DB, and an HTTP request to name a few.

The trigger is passed as the second argument to your function, the first being the context object.

module.exports = async function(context, myTrigger, myInput, myOtherInput) { ... }

For HTTP triggers for example, the HTTP request object will be passed.

Inputs

Inputs are passed as arguments to your function. The first input will be the third argument, the first being the context object and the second being the trigger.

There are other ways to access the inputs too.

The actual function code

One confusing thing about the function is the first argument that's always passed to it, the context object.

The context is basically just an object jam-packed with everything that Microsoft wants to give your function access to.

For example you can call context.log() to write trace output to the console. You can also call context.log.warn(), context.log.error() and context.log.verbose().

The context is also where you'll access the bindings you've configured via context.bindings. HTTP request triggers and HTTP response outputs are so common, that in addition to being able to access theme via context.bindings.req and context.bindings.res respectively, they also exist directly on the context object as context.req and context.res. That's in addition to the req being injected as the second argument to your function. They give you plenty of rope to hang yourself with here, but just pick your favorite and be consistent.

Outputs

Outputs are the side effects that your function produces, like creating or updating an entry in your database.

When the Microsoft documentation talks about outputs, they're exclusively referencing their available output bindings.

A binding is basically a way of interacting with some other system that Microsoft has baked into the Azure function for you. But because you have access to NPM packages (I talk about how to install them below), you're not limited to just those bindings.

For example, Microsoft does not currently support binding to a Cosmos DB using the Gremlin API. To do this, I had to make use of the gremlin NPM package.

Where to start

Before I talk about how to get started, I wanted to clarify something that confused me initially.

Your goal is to set up a Functions project (the Azure portal calls it a Function App), not a singular function. So if you use the portal to create a Function, you're creating one Function inside of a Functions project. If you use an IDE, you're creating the structure of the project first and then individual functions inside of that project.

Probably don't use the portal

It's possible to develop Azure Functions without ever leaving the Azure portal. But it sucks. Their online code editor is frustrating for even the simplest of changes, and while using the portal it's not possible to also use any NPM library.

Additionally, and perhaps most importantly, writing your Functions in the portal prevents you from storing them in version control! One accidental click and all the work you've done can be deleted.

Using the portal can be a nice way to just write something up there and see it run quick, but even for that use case I think you would be better off...

Using VS Code

VS Code has an Azure Functions extension that is incredibly easy to use and makes the whole process of setting up a Functions project much easier.

I would suggest just following the steps laid out on the extension's home page. They walk you through creating a project and creating your first Function. Keep in mind that if you've messed around on the portal, you can use the Function project that you've already created to save on paying for additional resources.

One other area you might deviate from their walkthough is in how you run your Function project locally. They suggest using the integrated VS Code debugger. You can definitely do that if you want to, but I prefer running scripts in my own terminal outside of VS Code.

To do so, from the root of the project run npm start in your terminal. This does the same thing that the VS Code integrated debugger would do; using the pre-installed @azure/functions NPM package to watch your code and restart the server when you make changes.

When I used the VS Code native debugger, it would crash every time I made changes to the source files, forcing me to re-run it each time, which was really annoying. That bug could very well be fixed by the time you're reading this though.

Installing NPM packages

You can bolster the power of Azure Functions by installing and using libraries from NPM.

Doing so is as simple as running npm install in the root of the project (as you would expect) and then requireing or importing them exactly as you normally would.

When you deploy your functions to azure, your node_modules directory will be deployed as well so that everything continues to run the same once deployed as it ran locally.

JavaScript vs TypeScript

When you use the VS Code extension to initialize your Functions project, you get to choose between JavaScript and TypeScript for your project.

This choice is largely preference based, but I feel that TypeScript has two big advantages here:

Strong typing is extremely useful when you're working with a database.
- It's just too easy to mess up your data-structure when writing a different query and then have to annoyingly go back and fix it.
Using TypeScript also allows you to use the ES6 module syntax for imports and exports instead of NPM's module.exports syntax, which I strongly prefer.

The only disadvantage that I've found is that sourcemaps don't see seem to work, so your errors don't point to your original source code, but it's generally pretty easy to figure that out for yourself.

Additional Resources

On the whole, I found Microsoft's documentation around Azure Functions rather confusing and disappointing. Perhaps they do have some great docs somewhere, but it's really hard to find the one you're looking for when you're not sure what that is.

The piece of documentation that helped me the most though (and the one that I linked to several times in this post) was definitely their Azure Functions JavaScript developer guide. It explains the nitty-gritty details of a lot of what I talked about in this post, and is a good place to reference when you're trying to do something specific that's not working.

If you're looking for more information on how to work with the Gremlin API of a Cosmos DB, I should have another post about that specifically coming soon!