Forem: Becca Bailey

React Refactoring Tips: Dysfunctional API Boundaries

Becca Bailey — Wed, 15 Jan 2020 16:02:52 +0000

We all have that friend. You know, the one who just can't get it together after years of trying. I know we love them anyway, but after getting involved in their problems enough times it's time to put up some boundaries to prevent their dysfunctional behavior from seeping into our own lives.

Sometimes I feel this way about an API. I don't want to slam the developers, the deadlines, or the technical requirements that got us into this situation, but it's bad. Maybe there is inconsistent data formatting between different endpoints, null or undefined values I'm not expecting, duplicated data, or flattened data that should be nested.

I have been reading Refactoring by Martin Fowler, and it has inspired me to share a few of my most common front-end refactoring strategies. Components that are a little too friendly with the API data is one of the most common problems I have seen (or created) in many codebases.

The Problem

Let's say I have two API endpoints: one that returns a logged-in user and another that returns the profile information for that user.

// GET /logged-in-user

{
  data: {
    id: "123",
    firstName: "Leslie",
    lastName: "Knope",
    email: "leslie@nationalparks.org",
  }
}

// GET /profile/:id

{
  data: {
    userData: {
      userFirstName: "Leslie",
      userLastName: "Knope",
      userEmail: "leslie@nationalparks.org",
      userLastLoginDate: "1/15/2020",
      userBio: null,
      userAddress1: "123 Cherry Street",
      userCity: "Pawnee",
      userState: "Indiana",
      userZip: 46012
    }
  } 
}

On the alignment chart of bad APIs, I would probably consider this one a chaotic neutral. We have some inconsistent nesting, a non-ISO date format, and data attributes with different names, e.g. email vs userEmail. Overall though, it's pretty clear which attributes represent which values.

If I were designing these components based on the API response, I might have prop types that look like this.

type NavbarProps = {
  id: string,
  firstName: string,
  email: string,
  title: string,
  baseUrl: string,
  links: Array<{ text: string, url: string }>
}

type UserProfileProps = {
  userData: {
    userFirstName: string,
    userLastName: string,
    userEmail: string,
    userLastLoginDate: string,
    userBio?: string,
    userAddress1: string,
    userAddress2?: string,
    userCity: string,
    userState: string,
    userZip: number
  }
}

You can see that for both of these components, we're starting to have the "too many required props" problem. Martin Fowler calls this the "Long Parameter List" problem. Even though UserProfileProps only has one required prop, the userData object has lots of required fields.

The primary problem with long and inconsistent props is how hard they are to replicate quickly. Even with the help of Typescript or prop types to tell me when I'm getting it wrong, it's going to be a pain to recreate this API data every time I want to test this component or render it in Storybook.

Also, with this approach, there is a good chance you have several lines of code in each component for parsing dates, checking for null values, and cleaning up the data that gets passed in. Fortunately, there's a better way!

The Solution

Let's start by creating a couple of basic types that are a little more descriptive of the data we have here.

type User = {
  id: string,
  firstName: string,
  lastName: string,
  email: string,
  bio?: string,
  lastLoginDate?: Date
}

type Address = {
  line1: string,
  line2?: string,
  city: string,
  state: string,
  zipCode: string
}

This isn't required, but I like to create factory functions for these types to make them easier to quickly instantiate all required props. For example, this is what a createUser function might look like.

function createUser(props: Partial<User> = {}): User {
  return {
    id: "",
    firstName: "",
    lastName: "",
    email: "",
    ...props
   }
}

In order to create a boundary between my components and my API, I need to think about what my ideal component API would look like.

type NavbarProps = {
  user: User,
  title: string,
  baseUrl: string,
  links: Array<{ text: string, url: string }>
}

type UserProfileProps = {
  user: User,
  address: Address,
}

I still have all the same data here, but my props are structured in a way that is more consistent and easier to understand. If I am making this change to an existing component, I would need to update props as well as my tests and rendering logic.

This is all well and good, but how do we deal with the fact that our API data is still less than perfect? This is where we would write a function to map our API data to our component props. For example, the formatter for GET /profile/:id might look something like this.

import { createUser, createAddress } from "./factories";
import { parse } from "date-fns";

type UserProfileData {
  // same as original UserProfileProps
}

export function getPropsFromData({ userData }: UserProfileData) {
  const { 
    userFirstName, 
    userLastName, 
    userEmail,
    userLastLoginDate,
    userBio,
    userAddress1,
    userAddress2,
    userCity,
    userState,
    userZip
  } = userData;

  return {
    user: createUser({
      firstName: userFirstName,
      lastName: userLastName,
      email: userEmail,
      bio: userBio,
      lastLoginDate: parse(userLastLoginDate, 'MM/DD/YYYY', new Date())
    }),
    address: createAddress({
      line1: userAddress1,
      line2: userAddress2,
      city: userCity,
      state: userState,
      zipCode: String(userZip)
    })
  }
}

If my API data changes, that's okay. I'll just come back here and update this formatter. If it doesn't, that's okay too. Putting up this boundary and formatting my own props means that I can design my components the way that I want whether or not my API data gets it together any time soon.

Live the way you want, and don't let dysfunctional APIs get in the way.

A Few Pointers on React Component Props

Becca Bailey — Thu, 12 Sep 2019 16:55:57 +0000

One of the first things we learn as React developers are how to use props to pass arguments into our components. However, there are a few common pitfalls that we often run into when designing the API of our components that make our components more difficult to use and test. Here are a few pointers that will help us to write more usable components.

Think about the API of your React components the same way you would think about the API of a shared library. How can you make it as easy as possible for another user (or yourself) to get it right?

Required Props

Your components should have as few required props as possible. For example, boolean props shouldn't be required and should default to false. We see this pattern in the HTML spec and should mimic it in our components.

<MyButton disabled={false}/>
<MyButton disabled={true}/>

// vs

<MyButton />
<MyButton disabled />

Also, we should provide reasonable defaults for any props that don't affect the behavior of the component.

const MyButton = ({ color: color.primary }) => {
  ...
}

Data Structures

Sometimes, I see prop types that look like this.

// JS

MyComponent.propTypes = {
  data: PropTypes.object.isRequired
}

If I am using this component, there's no way I can tell at a glance what the structure of this prop is. I would need to read through the logic in the render method, and then hope for the best.

You could give data a more specific type, like this.

MyComponent.propTypes = {
  data: PropTypes.shape({ 
    value: PropTypes.string,
    id: PropTypes.number,
  }).isRequired,
}

But an even better approach might be to flatten out this data structure.

MyComponent.propTypes = {
  value: PropTypes.string,
  id: PropTypes.number,
}

If you are dealing with formatted API data, it is okay to re-format this data at the top level for the sake of readability in your lower-level presentational components.

If you keep props as simple and readable as possible, I promise you will thank yourself later.

ES6 Generators for State Management in React

Becca Bailey — Wed, 04 Sep 2019 20:51:17 +0000

When we talk about state management in JavaScript, we’re usually talking about using framework-specific libraries or tools, like redux or setState in React. But as we are looking for a state management strategy, I think there are powerful tools at our disposal in ES6. If we are implementing sequential state updates (multi-step forms, carousels, animations, etc), one such tool is a generator.

What are generators?

Generators are special JavaScript functions that implement the iterator protocol. If you have never used one before, bear with me because it is a bit of a learning curve to wrap your mind around them the first time!

If you’re already familiar with iterators, feel free to skip ahead, but if not, here’s my ten-second introduction.

Intro to Iterators

For a function to implement the iterator protocol, it must return an object with a next function. This next function returns an object with the attributes value and done.

const myIterator = createIterator();
const { value, done } = myIterator.next();

We can create our own iterator function like this.

function createColorIterator() {
  let i = 0;
  const colors = ["red", "yellow", "blue"];
  return {
    next: () => {
      if (i < colors.length) {
        let value = colors[i];
        i++;
        return {
          value: value,
          done: false
        };
      } else {
        return {
          value: undefined,
          done: true
        };
      }
    }
  };
}

let iterator = createColorIterator();

console.log(iterator.next());
// { value: "red", done: false }
console.log(iterator.next());
// { value: "yellow", done: false }
console.log(iterator.next());
// { value: "blue", done: false }
console.log(iterator.next());
// { value: undefined, done: true }

This iterator keeps track of its own state using the createColorIterator function’s local scope. In this case, we can change the value of i, and it will persist inside the iterator. For more information, you can read about closures and lexical scoping here.

Also, I should note that any iterables in JS (Array, String, Map, Set, etc.) have a property called Symbol.iterator that returns an iterator.

const colors = ["red", "yellow", "blue"];
const iterator = colors[Symbol.iterator]();

console.log(iterator.next());
// { value: "red", done: false }
// ...same as above

Back to generators…

So, iterators are great! But building one from scratch can mean writing a lot of boilerplate. This is where generators come in! Generators are special functions that do some ES6 magic for you to create an iterator. Generators can be super helpful for asynchronous programming, though I’m not really going to get into that here.

For example, I can now use function* syntax to re-write my iterator with a lot less code.

function* createColorIterator() {
  let i = 0;
  const colors = ["red", "yellow", "blue"];
  while (i < colors.length) {
    const color = colors[i];
    i++;
    yield color;
  }
}

console.log(iterator.next());
// { value: "red", done: false }
// ...same as above

Notice how this generator function uses the yield keyword. When a generator encounters this keyword, it immediately exits the function and returns the value after yield. The function execution can then be resumed when next is called again.

How could I use a generator to store state in my React application?

Generators open up lots of possibilities for us! For now, let’s continue this simple example with colors.

In my React component, I need to create a single state variable to store the generator’s current state. This is mostly to trigger a re-render every time this state is updated, since I am rendering view components based on the current iterator state.

let colors = createColorIterator();
let initialState = colors.next();

function App() {
  const [colorState, setColorState] = React.useState(initialState);

  function updateBackgroundColor() {
    setColorState(colors.next());
  }

  function reset() {
    colors = createColorIterator();
    setColorState(initialState);
  }

  const { value, done } = colorState;

  return (
    <Container backgroundColor={value}>
      <h1>Hello!</h1>
      <Button disabled={done} onClick={updateBackgroundColor}>
        Change background color
      </Button>
      <Button onClick={reset}>Reset</Button>
    </Container>
  );
}

Notice how I am defining my iterator and the initial state value outside of the component’s scope, to avoid resetting this state with every re-render.

Colors Generator Example - CodeSandbox

Why might I use generators for state management?

For most use cases, I actually wouldn’t recommend using generators over more traditional state management strategies. Because a generator is not a pure function (it’s value changes ever time it is called, even with the same arguments), we can’t use one in conjunction with more functional state management strategies like redux or useReducer.

However, I think there is lots of potential here for creating incremental state updates, testing state in isolation from component rendering (but also integration testing your components), and sharing code between frameworks. I didn’t do this for the purpose of this post, but it would be pretty trivial to implement the same logic in Angular or Vue without changing the core logic.

Design Patterns for State Management in React and Typescript

Becca Bailey — Tue, 16 Jul 2019 03:40:17 +0000

In any interactive web application, we have state. Menus open and close, forms keep track of values, modals appear and disappear. But as our application grows, how do we keep track of this state in a way that doesn't cause us to lose our minds?

Definitions

Let's start by defining some terms. When we talk about state management, we are actually talking about two things. Local state management, and global state management.

Local

Local state is the state of one individual component. For example, a menu, a modal, a form. Each of the strategies outlined here can be used to manage local state.

Global

Global state is available throughout an entire application. We often use tools like Flux or Redux for this, though I will be covering some other strategies here as well. Global state might be used for the current logged-in user, alerts, cached API response data, or more complex component interactions.

When should I use local or global state?

My rule of thumb is typically to use local state until you need global state. Components that keep track of their own state are easier to test and interact with in isolation. For example, if I am writing an automated test for a component or using a tool like Storybook, I don't want to mock out my global state management in order for the component to be functional.

We can use strategies like compound components (a set of components that are used together and share state) to share state between multiple components without making their state globally available.

State management strategies

React State

React provides built-in state in class components. This is the most basic way to get and set state, and will be used under the hood in multiple examples here.

For example, we can create a simple card component with an expanded state property. This property can be updated with setState in a React component class.

class Home extends React.Component {
  state = {
    visible: false
  };

  render() {
    return (
      <Container>
        <Button onClick={() => this.showModal()}>Click me!</Button>
        <Modal visible={this.state.visible} onClose={() => this.hideModal()}>
          <h1>Surprise!</h1>
          <Button onClick={() => this.hideModal()}>Close</Button>
        </Modal>
      </Container>
    );
  }

  private showModal() {
    this.setState({
      visible: true
    });
  }

  private hideModal() {
    this.setState({
      visible: false
    });
  }
}

This might be the first strategy we reach for becuase it is the simplest to use and understand. However, this basic method can only be used in React component classes. For functional components, we can use a useState hook to accomplish the same thing.

const Home: React.SFC = () => {
  const [visible, setIsVisible] = React.useState(false);

  function showModal() {
    setIsVisible(true);
  }

  function hideModal() {
    setIsVisible(false);
  }

  return (
    <Container>
      <Button onClick={showModal}>Click me!</Button>
      <Modal visible={visible} onClose={hideModal}>
        <h1>Surprise!</h1>
        <Button onClick={hideModal}>Close</Button>
      </Modal>
    </Container>
  );
};

The common pitfall of this approach is repetition. What if I wanted to have multiple kinds of modals in my application? I could take this basic component, and just reproduce the state logic, or I could create an abstraction that just handles state. This is where we might use render props or context.

Render Props

This pattern has gained a lot of popularity over the past few years as a way to pass state from a parent to a child component in a way that is slightly more explicit than a higher-order component. It can be implemented in a couple of different ways, but this example involves rendering children as a function to pass down state props.

In this example, we are going to create a ModalManager that passes down an expanded and toggle prop to its children, which can be used to open and close the modal.

const Home: React.SFC = () => {
  return (
    <Container>
      <ModalManager>
        {({ showModal, hideModal, visible }) => {
          return (
            <React.Fragment>
              <Button onClick={() => showModal()}>Click me!</Button>
              <Modal visible={visible}>
                <h1>Surprise!</h1>
                <Button onClick={() => hideModal()}>Close</Button>
              </Modal>
            </React.Fragment>
          );
        }}
      </ModalManager>
    </Container>
  );
};

This pattern creates an inversion of dependency between a component and its state, reducing state-related repetition. However, when over-used this strategy can lead to what is known as "render prop hell". This is what happens when a component is wrapped with so many levels of nesting that becomes nearly unreadable.

For this reason, in 2019 render props are largely being replaced with hooks.

Hooks

Hooks are React's coolest new toy, but I promise I didn't include them here just to sound hip and trendy. the hooks API is React's answer to some of the downsides of class-based component state (as seen above) and render prop hell.

We can create a custom hook to replace the render props in the example above. This custom hook provides the same functionality, but with slightly different syntax.

function useModal(initialVisible = false) {
  const [visible, updateVisible] = React.useState(initialVisible);

  function showModal() {
    updateVisible(true);
  }

  function hideModal() {
    updateVisible(false);
  }

  return { visible, showModal, hideModal };
}

const Surprise: React.SFC = () => {
  const { showModal, hideModal, visible } = useModal();
  return (
    <React.Fragment>
      <Button onClick={() => showModal()}>Click me!</Button>
      <Modal visible={visible}>
        <h1>Surprise!</h1>
        <Button onClick={() => hideModal()}>Close</Button>
      </Modal>
    </React.Fragment>
  );
};

Hooks can be used with functional components, reducing the need to convert a component to a class component if a change in specification requires it to keep track of state. Hooks still come with their limitations--they can only be used at the top level of a functional component. Also, a React upgrade might be required in order to use hooks in an established project.

Custom hooks and render props are a great solution to the problem of repetiton. But what if I wanted to ensure that I was only displaying one modal at a time? Or maybe I want to separate my component that is responsible for displaying a modal from the component that is responsible for opening or closing it? This is a use case for context.

Context

The Context API provides a way for individual components to access shared state. Context is also a great solution to the problem of prop drilling, or passing a prop down through multiple layers of nesting to access it in a child component. Context allows us to create a provider component (the parent component that controls the state) and consumer components (child components that can access the state).

We can use context globally to share the state with the entire application, or we can use it in a single view to create compound components, as we see in this example. In this example, we are creating a ModalProvider that keeps track of the visible modal ID and passes down a function to open and close any modal. Any component with a context consumer now has access to these variables and functions from the provider without explicitly receiving props.

Note: In this example, we are using the useContext hook, though we can also use context with a Context.Consumer component and render props.

const Home: React.SFC = () => {
  const { showModal } = React.useContext(ModalContext);
  return (
    <Container>
      <Button onClick={() => showModal("kittens")}>Click me!</Button>
      <Modal id="kittens">
        <h1>Kittens!</h1>
        <Image src="/assets/kittens.gif" />
        <Button onClick={() => showModal("error")}>Close</Button>
      </Modal>
    </Container>
  );
};

When using this strategy, keep in mind that while every component can use a context consumer, not every component in your application should. Using context in a component couples it to a context provider, and will require you to use a provider or mock it out when using or testing this component. For example, low-level components like buttons, form fields, etc. should probably accept callback props instead of using context to keep them as flexible and reusable as possible.

Which design pattern should I use?

None of these patterns is a one-size-fits-all solution to every state management problem. Most applications should probably be using a combination of strategies, ideally differentiating between state that is only used in one place, and state that can be shared. Maybe a library like Redux is a good solution for your more complex global state interactions, while basic React state or render props are better for individual component state.

As much as possible, keep your patterns consistent, and be willing to revisit your choices as tools and requirements change.