DEV Community: Mat Warger

AWS Amplify GraphQL Operations with TypeScript and Hooks - Part 4 [Subscriptions]

Mat Warger — Sat, 14 Sep 2019 00:19:32 +0000

Next up is subscriptions. This is a fun feature of GraphQL and AppSync in general. The ability to leverage real-time data can really bring some nice UX to your apps. I tend to use it sparingly, but it's super helpful for small lists and instant feedback.

Our previous posts have built up a fairly nice set of abstractions that we can use here as well. Because of this, I'm going to paste the result at the start this time and break it down into pieces. Grab a cup of coffee and we'll get to it.

The Code

Here's our finished custom hook:

type ConfigType<VariableType extends {}> = {
  query: string;
  key: string;
  variables?: VariableType;
};

export const useSubscriptionByItself = <
  ItemType extends { id: string },
  VariablesType extends {} = {}
>({
  config,
  itemData,
}: {
  config?: ConfigType<VariablesType>;
  itemData?: ItemType;
} = {}) => {
  const [item, update] = React.useState<ItemType | undefined>(itemData);

  React.useEffect(() => {
    let unsubscribe;
    if (config) {
      const { query, key, variables } = config;
      const subscription = API.graphql(graphqlOperation(query, variables));
      if (subscription instanceof Observable) {
        const sub = subscription.subscribe({
          next: payload => {
            try {
              const {
                value: {
                  data: { [key]: item },
                },
              }: {
                value: { data: { [key: string]: ItemType } };
              } = payload;

              update(item);
            } catch (error) {
              console.error(
                `${error.message} - Check the key property: the current value is ${key}`
              );
            }
          },
        });
        unsubscribe = () => {
          sub.unsubscribe();
        };
      }
    }
    return unsubscribe;
  }, [JSON.stringify(config)]);

  return [item];
};

There's a lot here, but our use-case is simple. Our subscription is going to handle an item. This could be something as simple as subscribing to new blog posts that are created, for example:

const [item] = useSubscription<postFragment>({
  config: {
    key: 'onCreatePost',
    query: onCreatePost,
  },
});

We could also pass some variables to subscribe to a comment when it is updated:

const [comment] = useSubscriptionByItself<
  commentFragment,
  onUpdateCommentSubscriptionVariables
>({
  itemData: comment,
  config: {
    key: 'onUpdateComment',
    query: onUpdateComment,
    variables: {
      id,
    },
  },
});

The point is that we are able to take the boilerplate of const subscription = API.graphql(graphqlOperation(query, variables)); and extract it away into something that can be re-used, as well as leaning into the convention of how AWS Amplify returns data to handle everything in a strongly-typed way.

Let's start at the top and see what's going on.

Typing the Configuration

type ConfigType<VariableType extends {}> = {
  query: string;
  key: string;
  variables?: VariableType;
};

export const useSubscription = <
  ItemType extends { id: string },
  VariablesType extends {} = {}
>({
  config,
  itemData,
}: {
  config?: ConfigType<VariablesType>;
  itemData?: ItemType;
} = {}) => {

Let's take a look at the type parameters (the things in between the angle brackets). This takes some explaining because I start out assuming a convention. The ItemType represents the object that we're going to be returning and operating on in our hook. The extends { id: string } means that whatever object we pass in, it must have an id of type string as a property. This is useful, as we want a unique identifier for our object. The itemData used in case we want to initialize our state.

Note that I'm leveraging fragments to provide a single typed object that we can work with. Once created, the Amplify codegen tool will create types for your fragments that you can then use as we are in this example. You can learn more about fragments and how to use them with GraphQL here.

The second VariableType is going to be an object that represents any variables that we will be passing to our subscription graphqlOperation. This is used further down in the type declaration to the ConfigType. This represents the configuration that holds the subscription query, variables and key that we will use to establish our subscription. We'll come back to the key a bit later.

The State

const [item, update] = React.useState<ItemType | undefined>(itemData);

This is pretty straightforward. We use the ItemType parameter we passed in to type the useState function. This is possibly undefined, so we note that as well. If we passed in initial itemData, we use this as well to establish the state that will keep track of the subscription we're working with.

The Effect

Here's the real meat of it.

React.useEffect(() => {
  let unsubscribe;
  if (config) {
    const { query, key, variables } = config;
    const subscription = API.graphql(graphqlOperation(query, variables));
    if (subscription instanceof Observable) {
      const sub = subscription.subscribe({
        next: payload => {
          try {
            const {
              value: {
                data: { [key]: item },
              },
            }: {
              value: { data: { [key: string]: ItemType } };
            } = payload;

            update(item);
          } catch (error) {
            console.error(
              `${error.message} - Check the key property: the current value is ${key}`
            );
          }
        },
      });
      unsubscribe = () => {
        sub.unsubscribe();
      };
    }
  }
  return unsubscribe;
}, [JSON.stringify(config)]);

First things first, we're going to be establishing a subscription, so for an effect, we need to clean it up when we're done. We declare a variable that will hold the function we want to run when returning from the effect.

Next, we will check if the config exists, as it is optional. We destructure the components and will use them to construct our subscription. The next lines are important:

  const subscription = API.graphql(graphqlOperation(query, variables));
  if (subscription instanceof Observable) {
    ...

The API.graphql call actually returns Observable | Promise<> - what this means is that the result will be one or the other. To get the autocomplete help that we expect (and stop TypeScript from yelling at us) we need to do what is called "type narrowing" using a type guard. We do this by using the instanceof keyword to check if the type is an Observable. I've added the @types/zen-observable package (yarn add -D @types/zen-observable) to provide the type.

The Subscription

const sub = subscription.subscribe({
  next: payload => {
    try {
      const {
        value: {
          data: { [key]: item },
        },
      }: {
        value: { data: { [key: string]: ItemType } };
      } = payload;

      update(item);
    } catch (error) {
      console.error(
        `${error.message} - Check the key property: the current value is ${key}`
      );
    }
  },
});
unsubscribe = () => {
  sub.unsubscribe();
};

We have our subscription that's returned from our graphql call, so now we need to subscribe to it. This is using what is called an observable. Last time I checked, Amplify is using the zen-observable library for the subscription implementation. Observables operate with values by returning them as streams, so you can listen for updates to the stream by supplying callbacks - in this case, next. Our next callback takes a payload (this will be the value of the next event in the stream) and we then do some destructuring on this value to get the underlying data we want. Amplify follows a convention for returning data in the subscriptions, so we can use this to make sure our destructuring is correct.

const {
  value: {
    data: { [key]: item },
  },
}: {
  value: { data: { [key: string]: ItemType } };
} = payload;

We use the key we talked about earlier, as well as the ItemType type we passed in, to create a type and properly destructure from the nested object (in the form of value.data[key]). Once this data is handled, we use the update method from our useState hook to persist our state, and if anything goes wrong we log out the error.

After the callback, we assign a small arrow function to our unsubscribe variable that will do the work of unsubscribing from our subscription if the component the hook is used in is unmounted.

[JSON.stringify(config)];

Our useEffect hook takes in one dependency (an object) so we'll just stringify it to make sure that if it's changed in any way, our hook will run again and we can re-establish the appropriate subscription.

The last line merely returns the data kept in state, so we can use it from the caller.

return [item];

The Wrap

This is, at its core, just a wrapper over the existing Amplify tools. But for TypeScript projects, it gives you the help you can use to make sure your app is doing what you expect. The nice by-product, in my opinion, is that the API surface is more complete while abstracting away the common bits. It's generally a good practice to extract these things away and avoid having useEffect directly in your components. This is just one little step in that direction.

If anyone has any feedback on this approach, please leave it in the comments. I use this often, only in TypeScript projects, and I hope it can help someone. You can also ping me on twitter @mwarger.

...

But wait, what if you need to subscribe to many events? That's next up - follow me to be notified when it's published!

AWS Amplify GraphQL Operations with TypeScript and Hooks - Part 3 [Mutations]

Mat Warger — Mon, 29 Jul 2019 02:38:00 +0000

Let's take a quick look at mutations. This will be a short post, as Amplify makes mutations relatively painless, and the format of GraphQL mutations that we'll look at closely resemble the queries that we've already looked at (take a look at the previous posts in this series for more on that).

Mutations

To set up for mutations, we need to look at part of the query we did in the previous section.

const fetchQuery = async (query: string, variables?: VariablesType) => {
  try {
    setLoading(true);
    const { data } = (await API.graphql(
      graphqlOperation(query, variables)
    )) as {
      data: ResultType;
    };
    setData(data);
  } catch (error) {
    console.log(error);
    setError(error);
  } finally {
    setLoading(false);
  }
};

All GraphQL API calls made with Amplify using the graphqlOperation function. We can reuse this, so let's make another function to handle the returning of data.

export const gqlOp = async <
  ResultType extends {},
  VariablesType extends {} = {}
>(
  query: string,
  variables?: VariablesType
) => {
  const { data } = (await API.graphql(graphqlOperation(query, variables))) as {
    data: ResultType;
  };
  return data;
};

Now we can use this little function in place of the fetch call.

const fetchQuery = async (query: string, variables?: VariablesType) => {
  try {
    setLoading(true);
    const data = await gqlOp<ResultType, VariablesType>(query, variables)
    setData(data);
  } catch (error) {
    console.log(error);
    setError(error);
  } finally {
    setLoading(false);
  }
};

Now that's done, let's create a function for mutations.

export const mutation = async <
  ResultType extends {},
  VariablesType extends {} = {}
>(
  query: string,
  variables?: VariablesType
) => gqlOp<ResultType, VariablesType>(query, variables);

Alright, that's it. Thanks for reading!

Stay tuned for the next one where we tackle subscriptions.

AWS Amplify GraphQL Operations with TypeScript and Hooks - Part 2 [Custom Hooks]

Mat Warger — Wed, 19 Jun 2019 18:30:15 +0000

Custom Hooks allow you to extract commonly used functionality away to be used in multiple parts of your app. In the last post, we talked about what it looks like to leverage hooks and the Amplify library with TypeScript to fetch some data. There were some common elements involved with this, so let's make our data fetching more useful by extracting a custom hook we can use whenever we want to query our API.

The Hook:

Here is the code we left with from the previous post:

const [gameData, setGameData] = React.useState(undefined); 

React.useEffect(() => {
  const fetchGames = async () => {
    try {
      const response: any = await API.graphql(graphqlOperation(popularGames)); 
      setGameData(response.data); 
    } catch (error) {
      console.log(error);
    }
  };

  fetchGames();
}, []);

Let's take this and put it inside a custom hook called useQuery. We need to rename the return values from our useState call because we're not specifically talking about game stuff, we're making a re-usable hook.

The result is below:

const useQuery = () => {
  const [data, setData] = React.useState(undefined);

  React.useEffect(() => {
    const fetchQuery = async () => {
      try {
        const response: any = await API.graphql(graphqlOperation(popularGames));
        setData(response.data); 
      } catch (error) {
        console.log(error);
      }
    };

    fetchQuery();
  }, []);
};

Wait, that doesn't look like anything. It's just a function.

Exactly.

Hooks are functions that we can use to encapsulate and compose other hooks that we want to leverage in our code.

Passing arguments

There are some things that we need to generalize to be able to re-use this function elsewhere. Namely, the popularGames query and any possible variables (this example doesn't have any, but we want to accommodate other queries that may).

We can accomplish this by passing arguments into the hook just like any other function.

const useQuery = (query: string, variables?: any) => {

  const [data, setData] = React.useState(undefined);

  React.useEffect(() => {
    const fetchQuery = async () => {
      try {
        const response: any = await API.graphql(graphqlOperation(query)); 
        setData(response.data);
      } catch (error) {
        console.log(error);
      }
    };

    fetchQuery();
  }, [query, variables]); 
};

We've done a few things here, including adding two new arguments (query and variables), adding them to the dependency array for the useEffect declaration, and updating the graphqlOperation to take the query.

However, in doing this we've lost any help provided to us by the types that we were using in the previous post's example. We need to fix that - but how?

Generics

Generics allow us to pass types to functions, in a similar way to passing arguments to functions. In this case, we want to pass generic type arguments to our useQuery hook to give it information about what types our query and variables are.

It looks like this:


const useQuery = <ResultType extends {}, VariablesType extends {} = {}>(

  query: string,
  variables?: VariablesType 
) => {
  const [data, setData] = React.useState({} as ResultType);

  React.useEffect(() => {
    const fetchQuery = async () => {
      try {
        const { data } = (await API.graphql(
          graphqlOperation(query, variables)
        )) as {
          data: ResultType;
        };

        setData(data);
      } catch (error) {
        console.log(error);
      }
    };

    fetchQuery();
  }, [query]);
};

Here, we are saying that we can pass two types to our useQuery hook. The first type is the ResultsType we are going to have returned from our network call. The second is the VariablesType that we can use if we want to pass variables to our Amplify query call. We default this to an empty object by putting = {} after the declaration. We use this type after the optional variables declaration for our function.

Returning Data

You may have noticed that we are not returning anything from this hook. We are fetching data and that data is set to the state within the hook - but that's it. We can return whatever we want from this hook, like our data, and we can also return helpful information like whether we're currently loading the data or have encountered an error. We can add some state to keep track of these and also return an object holding our different pieces of state. It looks like this:

type UseQueryType<ResultType> = {
  loading: boolean;
  error: any;
  data: ResultType;
  refetch: () => void;
};

export const useQuery = <ResultType extends {}, VariablesType extends {} = {}>(
  query: string,
  variables?: VariablesType
): UseQueryType<ResultType> => {
  const [loading, setLoading] = React.useState(true); 
  const [error, setError] = React.useState(''); 
  const [data, setData] = React.useState({} as ResultType);

  const fetchQuery = async (query: string, variables?: VariablesType) => {
    try {
      const { data } = (await API.graphql(
        graphqlOperation(query, variables)
      )) as {
        data: ResultType;
      };
      setData(data);
    } catch (error) {
      console.log(error);
      setError(error);
    } finally {
      setLoading(false);
    }
  };

  React.useEffect(() => {
    fetchQuery(query, variables);
  }, [query]);


  return {
    loading,
    data,
    error,
  };

};

We're going to initialize the loading state to true, set the error to an empty string, and then return all our stateful parts in an object to the client. The last thing we'd like to do is set the return type for the function, and we can make use of generics again to create another type that encapsulates the different parts of the state.

The type will look like this:

type UseQueryType<ResultType> = {
  loading: boolean;
  error: any;
  data: ResultType;
};

We can use it by declaring the return type after the hook, like this:

export const useQuery = <ResultType extends {}, VariablesType extends {} = {}>(
  query: string,
  variables?: VariablesType
): UseQueryType<ResultType> => { 
  ...

Adding Convenience

Just as a convenience, we're going to add a function to our hook that we can pass back to the consumers of our hook that will let us re-fetch the data (maybe to refresh a list manually if we choose). I've added that ability here:

type UseQueryType<ResultType> = {
  loading: boolean;
  error: any;
  data: ResultType;
  refetch: () => void;
};

export const useQuery = <ResultType extends {}, VariablesType extends {} = {}>(
  query: string,
  variables?: VariablesType
): UseQueryType<ResultType> => {
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState('');
  const [data, setData] = React.useState({} as ResultType);

  const fetchQuery = async (query: string, variables?: VariablesType) => {
    try {
      const { data } = (await API.graphql(
        graphqlOperation(query, variables)
      )) as {
        data: ResultType;
      };
      setData(data);
    } catch (error) {
      console.log(error);
      setError(error);
    } finally {
      setLoading(false);
    }
  };

  const refetch = () => {
    fetchQuery(query, variables);
  };

  React.useEffect(() => {
    fetchQuery(query, variables);
  }, [query]);

  return {
    loading,
    data,
    error,
    refetch,
  };
};

Nice, mmkay - this is a pretty fun hook that takes a lot of boilerplate off our tray. You can give this a try in an app, and it will fetch the data just fine. But, if you run it in the latest version of create-react-app, you will see a warning about hook dependencies. The problem is that for our useEffect hook, we're providing the query argument, but not the variables that we also use within the hook. What this means is that if the variables change, the effect will not re-run and we will have incorrectly run the graphqlOperation with stale variables.

We can fix this by adding variables to the dependency array.

React.useEffect(() => {
  fetchQuery(query, variables);
}, [query, variables]);

But if you run this, you will end up with the hooks infinitely looping over and over! Why is this? variables is an object, and for dependencies that are an object, we need to compare their properties, which React does not do by default. We could write this ability ourselves. But luckily, Kent Dodds already has.

Install this by running npm i use-deep-compare-effect (or yarn add use-deep-compare-effect).

Next, we need to update our useEffect call to use this instead.

First, import it:

import useDeepCompareEffect from 'use-deep-compare-effect';

and replace the call to useEffect:

useDeepCompareEffect(() => {
  fetchQuery(query, variables);
}, [query, variables]);

Now, your objects will be compared using deep equality and the infinite loops will be a thing of the past.

Wrapping Up

The final iteration of this particular demonstration is below. I hope this helps explain some different aspects of hooks when working with Amplify, GraphQL, and TypeScript. Follow me on twitter and let me know if you found it helpful or if you had any problems!

type UseQueryType<ResultType> = {
  loading: boolean;
  error: any;
  data: ResultType;
  refetch: () => void;
};

export const useQuery = <ResultType extends {}, VariablesType extends {} = {}>(
  query: string,
  variables?: VariablesType
): UseQueryType<ResultType> => {
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState('');
  const [data, setData] = React.useState({} as ResultType);

  const fetchQuery = async (query: string, variables?: VariablesType) => {
    try {
      const { data } = (await API.graphql(
        graphqlOperation(query, variables)
      )) as {
        data: ResultType;
      };
      setData(data);
    } catch (error) {
      console.log(error);
      setError(error);
    } finally {
      setLoading(false);
    }
  };

  const refetch = () => {
    fetchQuery(query, variables);
  };

  useDeepCompareEffect(() => {
    fetchQuery(query, variables);
  }, [query, variables]);

  return {
    loading,
    data,
    error,
    refetch,
  };
};

This post was originally posted on my website. You can see this and other articles like it, as well as what I'm all about. Follow me on @twitter and reach out if you have any questions!

AWS Amplify GraphQL Operations with TypeScript and Hooks - Part 1 [Queries]

Mat Warger — Fri, 03 May 2019 19:47:24 +0000

I'm a big fan of Amplify. I'm also a big fan of TypeScript. Amplify is not built with TypeScript, and to use it effectively, sometimes you need to give it a little help. This is especially true when it comes to GraphQL. With the advent of hooks, we can create some nice utilities for ourselves that let us leverage the power of TypeScript with our GraphQL queries. Let's see what that looks like.

> I'll be assuming familiarity with React and TypeScript, including the usage of Amplify and GraphQL for this post. There are tons of great resources online. Here's a great set of steps to setup a similar project. Or, you can clone the sample app and run `amplify init` at the root of the project to see the final result.

Simple Query

From our sample app we have a list of popular games we want to retrieve. The query looks like this:

popularGames {
    id
    name
    popularity
    url
    summary
    # ommitted for brevity
}

Starting out, this is a great first start to what we're going for. We want to use useEffect to handle fetching our data. We're using Amplify's graphql method and passing the GraphQL query from above to the graphqlOperation method.

React.useEffect(() => {
  const fetchGames = async () => {
    try {
      const response = await API.graphql(graphqlOperation(popularGames));
    } catch (error) {
      console.log(error);
    }
  };

  fetchGames();
}, []);

The response objects has a data property, which contains our list of games. Here's a couple from the list.

{
  "data": {
    "popularGames": [
      {
        "id": "76882",
        "name": "Sekiro: Shadows Die Twice",
        "popularity": 3954.25
      },
      {
        "id": "114455",
        "name": "Pacify",
        "popularity": 1472.0
      }
    ]
  }
}

We want to display these on our page, so we need to load them into state. With hooks, you accomplish this by creating a useState declaration and then using the method created for you to load them into state.

const [gameData, setGameData] = React.useState(undefined); 

React.useEffect(() => {
  const fetchGames = async () => {
    try {
      const response: any = await API.graphql(graphqlOperation(popularGames));
      setGameData(response.data);
    } catch (error) {
      console.log(error);
    }
  };

  fetchGames();
}, []);

At this point, you could display your games on the page using the gameData object.

But in TypeScript land, we actually have more problems here. By initializing the state object to undefined, TypeScript can only infer that the value allowed for the gameData object is undefined, and will give us an error if we try to set our query response using the setGameData method. Additionally, there is a keyword we have used to get past this problem that bites many a first-time TypeScript developer in the ass.

any

This word will strike fear into the hearts of all who witness it. At least, it should if you want your future self to thank your past self at some point (Thanks, Paul, for this great insight).

We don't want anys anywhere.

We really want to try our best to give ourselves and our tools as much power as possible.

We can't tell what our data will be right now, which is a problem... but Amplify can help us.

Types to the Rescue

In our project, if it's not configured already, we need to run amplify configure codegen. This will setup code generation and walk us through the process of generating types based on our queries. This is super helpful (and as far as I'm concerned, should be the default if a .tsconfig file is present at the root of the project...).

This gives us a type that we can use for our data. Normally, we could just throw this after the variable and be done with it.

const response: { data: PopularGamesQuery } = await API.graphql(
  graphqlOperation(popularGames)
);

We know that response is going to be this type if the operation doesn't fail. However, the types returned by the graphql function are a mashup of GraphQLResult and Observable since this same function is used for both. Until this changes, we're going to let it know what we expect to get back. We can do this by using the as keyword to tell TypeScript what we know our type will be.

const response = (await API.graphql(graphqlOperation(popularGames))) as {
  data: PopularGamesQuery;
};

Now we get the type help that we want. Hovering over the response object confirms that TypeScript recognizes the response to be an object with a data property of type PopularGamesQuery.

Games, setState

We'll use the same type to tell our useState function how we want to utilize our gameData object.

useState accepts a generic type parameter that allows us to inform the function about the type we want to use.

const [gameData, setGameData] = React.useState<PopularGamesQuery | undefined>(
  undefined
);

Here, we have passed the same PopularGamesQuery type (as well as the possible undefined value we use to initialize it with). This consoles the TypeScript compiler and we can move forward with displaying our games.

As simple as this is, there are a few boilerplatey things that are staring us in the face. We can extract these things out and create some re-usable code that will make future queries in other components much easier to setup. Custom hooks to the rescue!

Stay tuned for the next post where we do just that!

This post was originally posted on my website. You can see this and other articles like it, as well as what I'm all about. Follow me on @twitter and reach out if you have any questions!