DEV Community: Lori Baumgartner

One Small TypeScript Import/Export Change That Saved Us

Lori Baumgartner — Tue, 16 Jun 2020 13:38:36 +0000

We added TypeScript (TS) to our React + Ruby on Rails app about 4 months ago now. We have reached a decent tipping point where I'm not the only one who understands how to use TypeScript and other devs are actively converting non-TS files over to TS without much guidance.

One hurdle we've recently faced, is that as we add more types and shared types across multiple directories in our frontend, knowing WHERE a type lives and IF a type already exists has become really challenging. We've run into almost virtual duplicates of types multiple times now.

I said, "I've had enough! This is supposed to be helping us be less confused - not add to our confusion."

How can more structure be added to our storage of types so that it's easier for all of us to know where to check if a type exists already or not?

With some fiddling around, a little reading, and a little battling of our linter and we came to a pretty great solution I'm happy to document here.

The Problem

For some context, we have a frontend that's broken up into three "apps" and then shared helper files kind of like this:

bakery/
├── cookies/
│   ├── Cookie.tsx
│   ├── Biscuit.tsx
│   ├── lib/api.tsx
├── cake/
│   ├── Cake.tsx
│   ├── BirthdayCake.tsx
│   ├── lib/api.tsx
├── pudding/
│   ├── Pudding.tsx
│   ├── lib/api.tsx
└── shared/
    └── types/

So what has organically happened (and what is a little hard to show with his very simple example) is that components inside /cookies for example have some of their types locally defined since only those components need access to those types. So you might have an import statement like:

// bakery/cookies/SomeComponent.tsx

import { ChocolateChipType } from 'bakery/cookies/Cookie'

But what if you wanted a Chocolate Chip Cake? Then you'd have to access the Chocolate Chip type from the cookie directory and that's where things start to get really messy.

For us, as soon as we started to leverage shared types and generics, our organization and structure went out the window.

So, a new day began and I was determined to figure out how to make our types more easily shareable while also reducing the places you had to check for where the type might be defined.

The Solution

Option 1: Namespacing (deprecated)

I'll be honest - this was the first solution I came up with. I liked it - but our linter hated and informed me was a deprecated method 😅 .
We use "react-scripts": "3.4.1",.

🔖 Namespacing and Module TypeScript Documentation

To me, namespacing is a way of grouping similar things together under one umbrella name. So you could have a namespace of Cookies and then nested types of ChocolateChip, Sugar, Overcooked, etc.

A file using this method might look like this:

// bakery/cookie/types.ts

export namespace Cookies {
    export interface ChocolateChip { /* ... */ }
    export class Sugar { /* ... */ }
}

Then, if I want to use the ChocolateChip type, I could import and use it like this:

// bakery/cookies/Oven.tsx

// import full namespace
import { Cookies } from 'bakery/cookie/types'

// access specific type via dot notation
function CookieOven({ cookie }: Cookies.ChocolateChip) {
  return (...)
}

This method has the benefit of great autocomplete for your IDE - as soon as you type Cookies. you should see a list of all the types defined under that namespace.

Again - I personally liked how this looked, how it worked, and it made sense to me. BUT my linter did not like it and I had to start over with a different idea.

Depending on the version of eslint you're using, you might be able to use this method, but honestly I wouldn't recommend it since you'd have to upgrade and adapt eventually.

Option 2: ES6 Modules

This should look familiar to most of you since it's probably the way you import React to each of your components:

import * as React from 'react'

While it's nothing revolutionary, the way we leveraged ES6 modules are what made this solution make sense for us.

So, back to our type definition file, we remove the namespace and individually export all of our types and interfaces:

// bakery/cookie/types.ts

export interface ChocolateChip { /* ... */ }
export class Sugar { /* ... */ }

Because of the structure of our app, we actually have multiple segmented type files in one directory. That looks something like this:

bakery/
├── cookies/
│   ├── Cookie.tsx // No more types defined here
│   ├── Biscuit.tsx
│   ├── lib/api.tsx
├── cake/
│   ├── Cake.tsx
│   ├── BirthdayCake.tsx
│   ├── lib/api.tsx
├── pudding/
│   ├── Pudding.tsx
│   ├── lib/api.tsx
└── shared/
    ├── types/ // all types defined here
        ├── cookie.ts
        ├── cake.ts
        └── pudding.ts

I don't know about you - but when you have an app that uses a lot of modular components that can be put together in a variety of ways for different use cases, you start to get import fatigue.

Even once I moved the types into the shared/types directory, I was still having to import types across multiple files like this:

// bakery/cookie/SomeComponent.tsx

import { ChocolateChip } from 'bakery/shared/types/cookie'
import { Tiramisu, DeathByChocolate } from 'bakery/shared/types/cake'

Not terrible - and this works! - but pretty annoying if you want to use types from multiple modules in one file.

To try to get down to one import statement, you can add a default export file: index.tsx and then the magic starts to happen. So let's add that file:

bakery/
├── cookies/
├── cake/
├── pudding/
└── shared/
    ├── types/
        ├── cookie.ts
        ├── cake.ts
        ├── index.ts // This file is important!
        └── pudding.ts

And update it to be our main source of exporting all types:

// bakery/shared/types/index.ts

import * as Cookie from './cookie'
import * as Cake from './cake'
import * as Pudding from './pudding'

export { Cookie, Cake, Pudding }

So this is saying import everything from those files under the alias as XYZ and then export them as an object literal. The functional behavior of that export statement is similar to:

export {
  Cookie: Cookie, // key is "Cookie" and value is the exported module of Cookie
  Cake: Cake,
  Pudding: Pudding
}

So now! Let's go check out how that changes our import statement in our component:

// bakery/cookie/SomeComponent.tsx

// OLD WAY
// import { ChocolateChip } from 'bakery/shared/types/cookie'
// import { Tiramisu, DeathByChocolate } from 'bakery/shared/types/cake'

// NEW WAY
import { Cookie, Cake } from 'bakery/shared/types`

🎉 That's it! We can still access individual interfaces from those imports like Cookie.ChocolateChip. But now, we also get autocomplete for the import statement - so you know which modules you have access to while you're importing.

It's not very exciting or even a new idea in the world of JavaScript - but let me tell you - this small change has saved us so much time, reduced our cases of duplication, and made it really obvious WHERE our type definitions should live and how we manage them.

Rails 6 Dependency Management with Service Objects

Lori Baumgartner — Wed, 10 Jun 2020 14:55:57 +0000

Do you have a Ruby on Rails app that manages integrations with multiple 3rd party APIs or external data sources?

Do you struggle with keeping your application's domain logic separate from these external data sources and flows?

Do you feel like you have to customize main flows in your app for each data source or API?

Can I grow a few extra arms to raise my hands twice for all this? ✋✋✋

Here's what I'm going to cover in this post:

How this became a problem
The Service Object architecture we've committed to for untangling these dependencies (aka Skip to the Code)
2 months later - how it's been going
The resources that were the most helpful to learn from and adapt for our use case (jump to resources)

The Problem: The Snowball Effect

I work on an eCommerce app that takes external data from our "sources" and makes that data available to our customers via a catalog. The value of our product is that it takes the data from multiple sources and combines it into one catalog.

To simplify the examples to come, let's think of the product as an online grocery store. Each data source is the maker of an item you can purchase in a grocery store. So you have farmers that supply the produce and cereal makers who supply the cereal, and the people who make Eggo waffles, etc.

So where we got into trouble with our app is that (perhaps unsurprisingly) each data source formats their data differently. They name things differently, they have different ways of matching up a SKU (an individual thing you can buy, like a snack-size pack of Oreos vs. the family-size pack of Oreos), and just think about The Thing They Are Selling differently from other suppliers.

We started out with what we call "integrations": a directory of namespaced code that houses the fetching of the external data and translating it into the common language of our Grocery Store offerings. It looks a little like this:

 app/
  |__ integrations/
    |__ farmers/
      |__ fetch_data.rb
      |__ format_data.rb
      ...
    |__ cereal_makers/
      |__ fetch_data.rb
      |__ format_data.rb
      ...
  |__ catalog/
    |__ update_skus.rb
    ...
  ...

At first, this was great! We took in the new data, structured it how we wanted, filled in missing data with default values, sanitized data - no problemo. But then we needed to add another integration. And - guess what?! - they didn't have an API. So now we had to make a CSV upload process that handles fetching this new integration's data. But we still wanted the same output: a catalog of consistent data across all suppliers.

And then we wanted to add yet another integration...and our minds sort of exploded, to be honest 🤯 . You had to be intensely familiar with each integration's incoming data structure and know THEIR domain-specific context like whether they use an API or CSVs to send us their data. And you had to support multiple intake processes that could all break in different ways. And we needed to funnel all this data to one, common process to populate our catalog.

The Solution: Rails Engines + Structured Service Objects

I'm not going to spend much time talking about Rails Engines (that deserves a post of its own!) but there's pretty good documentation out there about it if you want to learn more. The examples to follow don't require you to also use engines.

Isolate Code Related to External Logic

So the first change we committed to is that each integration with a different data source will have its import code live inside of a Rails Engine (we call them Components). A hand-wavey definition of an engine is ruby gem that is internal to your app. It has access to the main app's code, but has its own routing, test files, services, etc. For my team, this was an easy way to draw a line in the sand and say "if the behavior I'm working on belongs to the data source and not our core app, it goes into the engine".

Our app structure doesn't look much different now:

 app/
  |__ components/ # moved these integrations into a "components" directory
    |__ farmers/
      ...
    |__ cereal_makers/
      ...
  |__ catalog/
    |__ update_skus.rb
    ...
  ...

but our main "Core" app Gemfile now looks like this:

# Gemfile
...
gem 'farmers', path: 'components/farmers'
gem 'cereal_makers', path: 'components/cereal_makers'

Now that we've pulled our integration code out of our core app, let's get down to the nitty gritty with dependency management inside our components!

Service Objects & Dependencies

To establish this pattern, we needed to commit to some non-negotiable expectations:

Service objects will always return a "response object" with a specific shape
Service objects maintain their own dependencies
Service objects should handle their own failure as well as surface the failures of any dependencies

Here's what our service should look like at the end of this process:

# app/components/famers/app/services/farmers/lettuces/create_service.rb
module Farmers
  class Lettuces
    class CreateService < BaseService
      self.build
        new(Farmers::Produce::InventoryManagerService.build)
      end

      def initialize(manage_inventory_service)
       @manage_inventory_service = manage_inventory_service
      end

      def call(lettuce_params)
        @lettuce_params = lettuce_params

        lettuce, created = create_lettuce
        inventory = @manage_inventory_service.call(lettuce)

        OpenStruct.new(
          created?: created,
          lettuce: lettuce,
          inventory_updated?: inventory.updated?,
          errors: [lettuce.errors, inventory.errors].join(', ')
        )
      end

      private

      def create_lettuce
        lettuce = Lettuce.new(@lettuce_params)
        if lettuce.save
          return [lettuce, true]
        end
        [lettuce, false]
      end
    end
  end
end

Expectation: Service objects will always return a "response object" with a specific shape
This is a personal decision for your team based on your own experiences and preferences. We have a completely separate frontend app and have struggled with error handling before. So for us, we wanted to always have our controllers return status: :ok but have json objects that include errors if they exist.

We decided upon a structure with these guidelines:

The mutated/created record is returned (usually with a key of the model name, like lettuce: lettuce)
There is a boolean status key that indicates if the service completed its job or not (could be success?: true or created?: false)
There is an errors key that returns the error message(s) or nil

We used an OpenStruct object, which is mutable (meaning a service could set OpenStruct.new(success?: true) and then elsewhere it could be overwritten OpenStruct.new(success?: false). This hasn't been an issue for our team, but is good to keep in mind.

Service objects maintain their own dependencies
This falls under the larger consideration of "how the heck do I manage all this state?!".

# app/components/famers/app/services/farmers/lettuces/create_service.rb
module Farmers
  class LettucesController < ApplicationController
    def create
      results = Lettuces::CreateService
        .build
        .call(lettuce_params)
      ...
     end
    ...
  end
end

# app/components/famers/app/services/farmers/lettuces/create_service.rb
module Farmers
  class Lettuces
    class CreateService < BaseService
      # bad
      def call(lettuce_params)
        @lettuce_params = lettuce_params

        lettuce, created = create_lettuce
        inventory = Farmers::Produce::InventoryManagerService
                      .build
                      .call(lettuce)
        ...
      end

      ...
    end
  end
end

# app/components/famers/app/services/farmers/lettuces/create_service.rb
module Farmers
  class Lettuces
    class CreateService < BaseService
      # good
      self.build
        new(Farmers::Produce::InventoryManagerService.build)
      end

      def initialize(manage_inventory_service)
       @manage_inventory_service = manage_inventory_service
      end

      def call(lettuce_params)
        @lettuce_params = lettuce_params
        ...
      end

      ...
    end
  end
end

Two Months Later: How It's Been Going

I can honestly say we've been loving this change! We've started converting over old service objects and creating all new ones in this style. It's made it so much easier to know:

what is going to be changed/done when I call this service
how will I know if it succeeded or failed?

It's made us become much more thoughtful about single-purpose services that don't need to be so generalized and vast. They can be specific and accurate to one case and then put together to handle generalized cases.

My First Custom Hook in React

Lori Baumgartner — Thu, 14 Nov 2019 15:35:45 +0000

If you want to follow along, here's the codesandbox with hooks:

I've been slow the React Hooks game. First it was because my last company was on an older version of React and lately it's mostly been I just haven't focused on learning them and adding them to my code.

It seems obvious to me that hooks are here to stay, so I've recently been doing some reading and felt ready to jump into my codebase to practice.

I read a bit about how hooks were potentially good replacements for higher order components (HOC). I recently created an HOC that was checking for window resizing and communicating whether the window size met our "mobile" screen width of 640 pixels or less.

That component looked like this to start:

// connectResizer.js

import React, { Component } from 'react'

export default function withResizer(WrappedComponent) {
  return class ResizeHandler extends Component {
    constructor(props) {
      super(props)
      this.state = {
        isMobile: window.innerWidth < 640,
      }
    }

    componentDidMount() {
      window.addEventListener('resize', this.resizeWindow)
      this.resizeWindow()
    }

    componentWillUnmount() {
      window.removeEventListener('resize', this.resizeWindow)
    }

    resizeWindow = () => {
      this.setState({ isMobile: window.innerWidth < 640 })
    }

    render() {
      return <WrappedComponent isMobile={this.state.isMobile} {...this.props} />
    }
  }
}

Honestly, it works just as we needed. It passed an isMobile boolean prop to its wrapped component and we could go on our merry way implementing conditional logic like this:

// components/Navbar.js

function Navbar({ isMobile, org, user, baseUrl }) {
  if (isMobile) {
    return (
      <>
        <Dropdown>
          <AccountLinks isMobile={isMobile} baseUrl={baseUrl} />
        </Dropdown>
        <CartLink
          user={user}
          org={org}
          isMobile={isMobile}
        />
      </>
    )
  }

  return (
    <>
      <AccountLinks isMobile={isMobile} />
      <CartLink
        user={user}
        org={org}
        isMobile={isMobile}
      />
    </>
  )
}

export default withResizer(Navbar) // wrap that component to get access to isMobile in Navbar

But it's also a really great example of something that can be replaced with a useEffect hook:

it is using multiple React LifeCycle methods
it has some internal state that needs to be communicated to and reused by other components
it's pretty straightforward and easy to test

Just a note that the following example is in TypeScript because we are currently migrating our codebase over to TypeScript and if I were to change this component, I would be rewriting it in TypeScript.

So, here's what the final hook function looks like:

// useResizer.ts

import * as React from 'react'
export default function useResizer(): boolean {
  const [isMobile, setIsMobile] = React.useState(window.innerWidth < 640);

  function handleSizeChange(): void {
    return setIsMobile(window.innerWidth < 640);
  }

  React.useEffect(() => {
    window.addEventListener("resize", handleSizeChange);

    return () => {
      window.removeEventListener("resize", handleSizeChange);
    };
  }, [isMobile]);

  return isMobile;
}

It is definitely less lines of code than our HOC. But is it more readable? Because hooks are still new to me, I'm not sure. But let's dive in to see what's going on.

  // useResizer.ts

  const [isMobile, setIsMobile] = React.useState(window.innerWidth < 640);

This one line using the useState hook gives us:

our state value of isMobile,
a setter setIsMobile that will take a value and update state to that given value,
and a default value window.innerWidth < 640.

We'll be calling that method to actually update our state when our hook is notified of changes to the window width.

  // useResizer.ts

  function handleSizeChange() {
    return setIsMobile(window.innerWidth < 640);
  }

Next is our callback we pass to our window event listeners. You can see this is using our useState helper to set the isMobile boolean value when handleSizeChange is called.

Now the fun part 🙌

  // useResizer.ts

  React.useEffect(() => {
    // add event listener - update our local isMobile state
    window.addEventListener("resize", handleSizeChange);

    // handle cleanup - remove event listener when effect is done
    return () => {
      window.removeEventListener("resize", handleSizeChange);
    };
  }, [isMobile]); // add dependency - only use our effect when this value changes

Finally, don't forget this uber important last line that is outside of our useEffect function:

// useResizer.ts

return isMobile;

This is the bit that is returning the actual value of isMobile and making it accessible to the components consuming useResizer().

At the end of the day, we would update the example above to look like this:

// components/Navbar.js

function Navbar({ org, user, baseUrl }) { // notice isMobile is gone from props
  const isMobile = useResizer() // because now we use our hook!
  if (isMobile) {
    return (
      <>
        <Dropdown>
          <AccountLinks isMobile={isMobile} baseUrl={baseUrl} />
        </Dropdown>
        <CartLink
          user={user}
          org={org}
          isMobile={isMobile}
        />
      </>
    )
  }

  return (
    <>
      <AccountLinks isMobile={isMobile} />
      <CartLink
        user={user}
        org={org}
        isMobile={isMobile}
      />
    </>
  )
}

export default Navbar // no more HOC wrapper needed here, either!

Well, that's it. What do you think? I still have a lot to learn (including the gotchas) but it's starting to make sense to me.

Are you and your teams all-in on hooks or holding tight to class components?

Converting a Create-React-App using Craco to TypeScript

Lori Baumgartner — Tue, 12 Nov 2019 20:49:22 +0000

My dev team recently had an internal conversation that went like this:

Coworker1: what is everyone’s appetite to exploring typescript as a standard on new stuff we do/create in the frontend?
Me: YASSSSS
Coworker2: I am on the fence on that.

After more conversation and consideration of the pros, cons, and challenges of migration and adoption into a living, breathing app, we decided to move forward with adding TypeScript to our 2-year-old app. I volunteered to lead the project since I was the only one on the team with on-the-job TS experience 😬.

What you should expect from this post:

The tech stack I started with
What it took for me to convert one file to TypeScript, ensure nothing was broken, and ensure linting worked the app still ran
Some of my favorite TypeScript "getting started" resources

The Tech Stack

Our app is on react-scripts@3.0.0 version for Create React App. Thankfully this meant TypeScript was already supported by the app.

Adding TypeScript

The easy parts

Well, if you use create-react-app this might be all you need:

$ yarn add typescript @types/node @types/react @types/react-dom @types/jest

While that command doesn't perform all the magic we need, it did set us on the right path. Adding this meant that react-scripts now knew we were using TypeScript. So the next time I ran the yarn start command to fire up the server, the jsconfig.json was removed and the server helpfully said something along the lines of "It looks like you're using TypeScript - we've made you a tsconfig".

The hard parts

Okay, so as easy as it was to make my app compatible with TS, it was not that easy to get it configured to work with my app. Here are just a few questions I ran into:

How do I get my app path aliases to still work?

  import Component from 'components/Component' // this should still work
  import Component from 'src/shared/components/Component' // don't make me do this

I only want to convert one file at a time - how can I import .tsx files inside .js files without needing to specify the file extension?
We had a lot of linting warnings that popped up as soon as I added a local .eslintrc.js. I don't blame TS for this, but you might run into a similarly frustrating cycle of having to resolve a lot of linting errors then seeing more, then fixing more, etc.

So what actually changed?

The final PR ended up having an 8-file diff. But my first attempt had a 73-file diff. Why is that, you wonder? Well, I totally dove into the rabbit hole of trying to fix one thing which led me to feeling as though I had to upgrade a dependency to be compatible with TypeScript which then meant other dependencies needed to be upgraded. There might have also been some things that broke when I upgraded dependencies - I'm looking at you react-scripts.

Here's the list of my final files I needed to make TypeScript happen:

Create /frontend/.eslintrc.js
Delete the jsconfig.json that create-react-app used
Add the tsconfig.json
yarn.lock changes
package.json changes with new dependencies
A new /react-app-env.d.ts file that create-react-app automatically adds
The component file I was converting to TypeScript
One component spec that had a linting error

Alright, so let's walk through these changes.

Eslintrc
This file was pretty straightforward. I used most of the recommended settings and merged in the existing upper-level rules we had already in the codebase.

The main thing I wanted to point out was the fix that allowed me to import a single .tsx file into a .js file without getting a compilation or linting warning?

Two things made this work:

module.exports = {
  parser: '@typescript-eslint/parser',
  rules: {
    'import/extensions': ['.js', '.jsx', '.json', '.ts', '.tsx']
    ...
  },
  settings: {
    'import/resolver': {
      node: {
        paths: ['src'],
        extensions: ['.js', '.jsx', '.json', '.ts', '.tsx'],
      },
    },
  },
  ...
}

tsconfig
Since create-react-app generates this, it is challenging to alter it. I did add a few extra compilerOptions to fit the needs of our app, but did not change it in any way worth pointing out.

Package Changes
Most hanges in package.lock were to add new type definitions or new dependencies.

I also updated our linting script to include new .tsx files:

"lint": "eslint './src/**/*.js' './src/**/*.tsx'",

I did run into an issue where our eslint-plugin-jsx-a11y version was throwing a false-positive linting error. That was resolved by upgrading to: "eslint-plugin-jsx-a11y": "6.1.2",

The New Component

So what does a newly-converted component look like? I strategically picked the furthest leaf of a component node I could find - that is to say this component is only used in one place by one other component and renders one input. So it was simple to alter and had minimal impact on the app.

Here's a very generalized version of the component before TS:

import * as React from 'react'
import { Field } from 'formik'

export default function ComponentField({ prop1, prop2 }) {
  return (
    <div className={s.className}>
      <Field
        type="number"
        name={name}
        render={({ field }) => <input {...field} />}
      />
    </div>
  )
}

And here's what it looked like after TypeScript:


import * as React from 'react'
import { Field, FieldProps } from 'formik'

interface ComponentProps {
  prop1: boolean
  prop2: string
}

export default function ComponentField({
  prop1,
  prop2,
}: ComponentProps): JSX.Element {
  return (
    <div className={s.className}>
      <Field
        type="number"
        name={name}
        render={({ field }: FieldProps) => <input {...field} />}
      />
    </div>
  )
}

Resources I Found Helpful

This cheatsheet is extremely popular and even has a section on migrating!
Microsoft has a migration guide that might be helpful for you and has a dummy app you can follow along with
This Twitter thread about what challenges people faced while using React + TypeScript. And read the comments, too!

Conclusion

See?! Not so bad! This approach works well for our small team with devs who are unfamiliar with TypeScript. We'll be able to add and convert files as we go without the pressure of changing everything at once.

This also made a low-risk implementation for us - it was one file that we could test in isolation as opposed to renaming every file to .tsx, adding any all over the place and worrying about compilation errors or build issues.

I'm no expert, and implementing TypeScript into a legacy codebase totally depends on the setup of your app - but stick with it! You can figure it out.

Rails 5.2.x --> Rails 6 counter_cache Gotcha

Lori Baumgartner — Thu, 22 Aug 2019 16:04:51 +0000

I recently upgraded our production app from Rails 5.2.3 to Rails 6.0.0. We wanted access to all the shiny things everyone is talking about. Multiple databases! Better autoloading!

Everything was going great until I noticed one weird behavior where a count column wasn't getting updated, but all the associations were correctly updating. After talking with a coworker about the problem, we identified what was going on. The culprit? Rails ActiveRecord counter_cache.

This post will give a brief overview of counter_cache and how its behavior changed between the two Rails versions, and finally, how to update your code to get around this issue without throwing counter_cache out the window.

Counter Caching - What is it? Why would I use it?

This concept was new-to-me - which is great! I love learning new things and working towards understanding why this approach is better over others. In this case, it was older code and we couldn't ask the original writer why they made this decision. So off to the internet I went.

I found quite a few articles about how to implement counter_cache but was surprised to see that none of them were from official Rails documentation - which was interesting.

That said, I think the best resource I found was this (very old) Railscast episode about converting fetching the count on a record and its relations to counter caching in the database. I highly recommend watching it - but here's the short answer of why you would choose to implement counter caching:

A counter cache column stores the count of its associations on itself - which means you don't have to make extra database calls = more performant

Old Behavior & Implementation

Let's say we have a cookie jar and each cookie jar has many cookies inside it. Somewhere in our UI, we want to show how many cookies are in each cookie jar.

A simple implementation of setting up our models might look like this:

# cookie_jar.rb
class CookieJar
  has_many :cookies
end

# ## Schema Information
# Table name: `cookie_jars`
# ### Columns
#
# Name                 | Type               | Attributes
# -------------------- | ------------------ | ---------------
# **`id`**             | `bigint(8)`        | `not null, primary key`
# **`cookies_count`**  | `integer`          | `default(0), not null`

# cookie.rb
class Cookie
  belongs_to :cookie_jar, counter_cache: true
end

# ## Schema Information
# Table name: `cookies`
# ### Columns
#
# Name                 | Type               | Attributes
# -------------------- | ------------------ | ---------------
# **`id`**             | `bigint(8)`        | `not null, primary key`
# **`cookie_jar_id`**  | `integer`          | `not null`

So that means that we now have CookieJar, Cookie and the cookie_jars table has a column called cookies_count that uses counter_cache to calculate those values.

So now the tricky part - counter_cache is doing some work behind the scenes, which makes it easy to use, but more challenging to debug. In this case, our bug source was in some seed code that looked like this:

# seed_cookie_jar.rb
def assign_cookies
  jar = CookieJar.first
  jar.cookies.each do |cookie|
    cookie.update!(cookie_jar_id: jar.id)
  end
end

Just a note that in this example, let's not worry about where our cookies were created - just that they previously had a different cookie_jar_id that we want to change here in assign_cookies.

So, before Rails 6, this behavior worked - I move my first cookie from one jar to another and the old jar now has one less cookies_count and the new jar has incremented its cookies_count.

Our Cookie Jar table before we call assign_cookies

id	cookies_count
1	4
2	0

What our Cookie Jar table looks like after we move the cookies around

id	cookies_count
1	0
2	4

Everything is working as expected! All 4 of our cookies moved from Cookie Jar 1 to Cookie Jar 2. Delightful. Now let's wreck havoc on this and upgrade to Rails 6 💪

New Behavior & Changes Made

To be fair, there was a one-line reference to the pull request that implemented the new behavior. However, what surprised me was that the way the change was phrased in the changelog did not at all alert me that my code was now essentially broken.

Here's the changelog note: "Don't update counter cache unless the record is actually saved". Yup, that's it. Now, I'm not a Ruby or Rails pro, so maybe this was obvious behavior to other people...but boy-o it took me for a ride!

Without doing anything to our code, here was the bug we had:
Our Cookie Jar table before we call assign_cookies (same as last time)

id	cookies_count
1	4
2	0

What our Cookie Jar table looks like after we invoke assign_cookies - no errors, but those counts don't look right 🤔

id	cookies_count
1	4
2	0

More confusingly, what our Cookies table looks like after we move the cookies:

id	cookie_jar_id
1	2
2	2
3	2
4	2

WHAT?! Our cookies actually moved jars, but the counter didn't update. So in our UI, we're displaying that Cookie Jar 1 has 4 cookies in it, but when you click to see the detail of that Cookie Jar 1 - it's empty!

To be honest, the way my coworker and I figured this out was going to the pull request listed in the changelog as changing this code and looking at the code diffs, new tests cases, and try some stuff out. All that eventually led to us trying one thing: instead of passing an id value, pass the whole record to the block. (Spoiler alert - this worked!) Here's that code:

# seed_cookie_jar.rb
def assign_cookies
  jar = CookieJar.first
  jar.cookies.each do |cookie|
    cookie.update!(cookie_jar: jar)
  end
end

So no more cookie_jar_id set directly - let's pass it the whole jar instance and see what happens. Turns out, this does call a save on the jar instance and triggers the cache to update.

Thanks for sticking with me this far - hope you learned something new and are more cautious about updating association _id fields now! I definitely will think twice before passing in an explicit _id value vs. the instance from now on.

Photo by Brooke Lark on Unsplash