DEV Community: Ian Jones

How xstate saved our 🥓

Ian Jones — Fri, 23 Oct 2020 15:37:39 +0000

useEffect Overload

egghead is the CMS, sale provider, and authentication for what we call Wes Bos as a Service (WBaaS) sites. This includes TestingJavaScript.com, PureReact.com, and now EpicReact.dev.

When we set out to build EpicReact.dev, we knew what we were doing. We've built 2 of these sites before and had handled authentication and purchasing. I figured it was time to extract the purchasing code out of these sites into its own package.

I used [[tsdx]] because it's a great way to author libraries and who doesn't like some [[TypeScript]]. This process went well. I was enjoying the benefits TypeScript gives you.

Heres a quick explanation of the commerce package. It was one big useReducer. I had state that relied on other elements of my state, and as Kent says, this is the time to useReducer.

The api of our hook was like this:

const {
    notification,
    parityCoupon,
    countryName,
    onApplyParityCoupon,
    displayParityCouponOffer,
    error,
    onPurchaseComplete,
    displayPrice,
    seriesPackageLoading,
    showClaimCoupon,
    purchasing,
    clearNotifications,
    appliedCoupon,
  } = usePackage({
    sellable,
    quantity: 1,
    authToken: () => {},
  });

You can tell that theres a lot going on under the hood. We passed a sellable, quantity, and authToken to the hook. A sellable is something that has a price and a url on the object to check that price along with a url to make the purchase.

For the internals, heres the stack of hooks that I ended up with:

useAvailableCoupons.tsx
useCouponFromHeader.tsx
useDefaultCoupon.tsx
useFetchPackageForSellable.tsx
usePackage.tsx
usePackageCheckout.tsx
usePackageReducer.tsx
useParityCoupon.tsx
useRequest.tsx

usePackage is the hook that orchestrated everything. The basic flow was:

receive a sellable from props
instantiate initial state
fetch the current price of the sellable
check for an applied coupon
extract available coupons
extract purchase power parity (PPP) coupon
create a function to handle purchase complete
create a function for when the coupon is applied
return display price, functions, and other relevant data

The main areas being: load the most recent price, handle any available coupons, give the user of the hook information about everything that's happening.

Most of these hooks are use effects waiting for changes of the particular state they manage. Lets take a look at the useParityCoupon hook:

const useParityCoupon = (
  dispatch: DispatchType,
  availableCoupons?: CouponType[],
) => {
  React.useEffect(() => {
    const parityCoupon = find(availableCoupons, {
      coupon_region_restricted: true,
    })
    if (parityCoupon) {
      const countryCode = get(parityCoupon, 'coupon_region_restricted_to')
      const countryName = get(parityCoupon, 'coupon_region_restricted_to_name')
      const displayParityCouponOffer = !(
        isEmpty(countryName) ||
        isEmpty(countryCode) ||
        isEmpty(parityCoupon)
      )

      dispatch({
        type: SET_PARITY_COUPON,
        displayParityCouponOffer,
        parityCoupon,
        countryName,
      })
    }
  }, [availableCoupons])
}

You may notice one of the bugs that was in our purchase flow. availableCoupons is of type CouponType[] which is not a stable value. React will shallowly compare this reference. When this hook runs again, availableCoupons will always be different. These hooks were scattered with issues like this. This is one of the foot guns that made debugging these hooks difficult.

I ran into issues testing this code in EpicReact. One being, the parity coupon was not being set when it should have been. When the value you expect to be there isn't, you have to go inspect what could be affecting it. In this case, I had to inspect these hooks:

usePackage.tsx
useFetchPackageForSellable.tsx
useAvailableCoupons.tsx
usePackageReducer.tsx
useParityCoupon.tsx

Tracing the data through all of these hooks is a nightmare. First you check if usePackage is calling useParityCoupon correctly. Next, we have to check if the values from useFetchPackageForSellable are setting state in usePackageReducer correctly. Then I had to make sure that useAvailableCoupons set the coupons correctly and finally that useParityCoupon was sending the correct event when it was supposed to. This took a lot of debugger and console.log statements to just figure out what the flow of data was.

On top of this, we have to make sure that when the user applies the PPP coupon, we refetch the price all over again.

All of this had to be stored in my head before I could start making any changes.

XState Saves the Day

One of the first things you will notice when using the XState version of this hook is how much simpler the api is:

const [state, send] = useCommerceMachine({
   sellable: bundle,
 })

XState just needs the sellable to kick off the price checking process.

XState forces you to think about your discreet states. Theres a big difference between the context you have around your state machine and the states your machine can be in.

Everything I described above can be boiled down into these states:

fetchingPrice
priceLoaded
startingPurchase
handlingPurchase
success
failure

We use these states to build up the context of our state machine. This is what we want to track in our state machine:

sellable
purchaseHeaders
error: null
price: null
appliedCoupon: null
notification: null
email: null
stripeToken: null
quantity: 1
purchase: null

As you can see sellable and purchaseHeaders are all passed in from a closure above. Heres what the basic state machine with no transitions looks like:

const createCommerceMachine = ({
  sellable,
  purchaseHeaders,
}) =>
  createMachine(
    {
      id: 'commerceMachine',
      initial: 'fetchingPrice',
      context: {
        sellable,
        purchaseHeaders,
        error: null,
        price: null,
        appliedCoupon: null,
        notification: null,
        email: null,
        stripeToken: null,
        quantity: 1,
        purchase: null,
      },
      states: {
        fetchingPrice: {},
        checkingPriceData: {},
        priceLoaded: {},
        startingPurchase: {},
        handlingPurchase: {},
        success: {},
        failure: {},
      },
    },
    {
      guards: {},
      actions: {},
    },
  )

You may notice that this createCommerceMachine function takes more arguments than our useCommerceMachine hook and thats because we create an intermediate hook to load authentication and such:

export const useCommerceMachine = ({sellable}) => {
  const {user, authToken} = useEggheadUser()
  const sellableSlug = get(sellable, 'slug')
  const userId = get(user, 'id')
  const commerceMachine = React.useMemo(() => {
    const purchaseHeaders = authToken()
      ? {Authorization: `Bearer ${authToken()}`}
      : {}
    return createCommerceMachine({
      sellable,
      purchaseHeaders,
      stripeToken: process.env.STRIPE_TOKEN,
    })
  }, [sellableSlug, userId])

  return useMachine(commerceMachine)
}

We are memoizing our call to createCommerceMachine because we only want to create a new machine if the sellableSlug or the userID has changed.

The first machine initializes in the fetchingPrice state. This is a state that is invoking a promise (xstate docs). A state can invoke a number of services but in our case we are using a promise. Heres the overview of the state:

fetchingPrice: {
    invoke: {
        id: 'fetchPrice',
        src: (context, event) => {// return a promise here},
        onDone: {
          target: 'checkingPriceData',
          actions: [// do something with the resulting data],
        },
        onError: {
          target: 'failure',
          actions: [// do something if the promise throws an error]
        },
    },
}

You can see that invoke takes a src promise. XState will handle calling this function and handing the resulting data to onDone or onError. This is where we calculate the context.price object.

onDone: {
  target: 'checkingPriceData',
  actions: [
    assign({
      price: (context, event) => event.data[0],
    }),
    'adjustPriceForUpgrade',
  ],
},

We use XState's assign function to take the data that the event gave back and assign it to the price. We have to handle a case where we adjust the price if the user is upgrading a purchase. I do this in separate action because I like to see all the different things that are happening when I read the machine. You could technically do this action in the assign above, but then you aren't optimizing for deletion.

The next state is checkingPriceData:

checkingPriceData: {
  always: [
    {
      target: 'failure',
      cond: 'couponErrorIsPresent',
      actions: ['setErrorFromCoupon'],
    },
    {target: 'priceLoaded', actions: ['checkForDefaultCoupon']},
  ],
},

This is a transient state. We use always to make a transient transition (xstate docs). This is a spot in our state machine where if some condition is true with the current context, we want to conditionally send it to another state. The first condition to return true will be the transition that's executed. The default is to send to priceLoaded state because there is no condition preventing this from happening.

We defined our couponErrorIsPresent guard in our guards object below.

guards: {
    couponErrorIsPresent: (context, event) => {
      return context?.price?.coupon_error
    },
},

All it needs to do is return true or false. We check the specific data we need to see if a coupon_error is present. If it is, we use setErrorFromCoupon to set the error context:

setErrorFromCoupon: assign({
  error: (context, event) => context.price.price_message,
}),

This allows our UI to check the state of our machine and our context to determine if it needs to display an error.

Moving along, we assume that our price check didnt return a coupon error, we move into the priceLoaded state. This is the last state our machine will automatically transition to until it receives an event from the outside telling to to transition to another state. Heres everything the outside world can tell our state machine to do:

priceLoaded: {
  on: {
    APPLY_COUPON: {
      target: 'fetchingPrice',
      actions: [
        assign({
          appliedCoupon: (context, event) => event.appliedCoupon,
        }),
      ],
    },
    DISMISS_COUPON: {
      target: 'fetchingPrice',
      actions: [
        assign({
          appliedCoupon: null,
        }),
      ],
    },
    SET_QUANTITY: {
      target: 'fetchingPrice',
      actions: [
        assign({
          quantity: (context, event) => event.quantity,
          appliedCoupon: null,
        }),
      ],
    },
    START_PURCHASE: {
      target: 'startingPurchase',
    },
    CLAIM_COUPON: {
      target: 'handlingPurchase',
      actions: [
        assign({
          email: (context, event) => event.email,
        }),
      ],
    },
  },
},

You'll notice that APPLY_COUPON, DISMISS_COUPON, and SET_QUANTITY all just send the machine back to the fetchingPrice state. This is one of the benefites of XState. We can reuse our logic on how we fetch the price but give it a slightly different context.

Say our machine recieves the APPLY_COUPON event. This event comes with appliedCoupon. You can see that we are using assign to add the appliedCoupon from the event into our context:

assign({
  appliedCoupon: (context, event) => event.appliedCoupon,
}),

Then our machine transitions back into the fetchingPrice state. I mentioned earlier that fetchingPrice invokes a promise for us. Heres what the promise looks like:

fetchingPrice: {
  invoke: {
    id: 'fetchPrice',
    src: (context, event) => {
      const {
        quantity,
        appliedCoupon,
        sellable,
      } = context
      const {
        priceCheckURL,
        site,
        egghead_id: sellable_id,
        type,
      } = sellable
      return axios
        .post(
          priceCheckURL,
          pickBy({
            sellables: [
              {
                site,
                sellable_id,
                sellable: type.toLowerCase(),
                quantity,
              },
            ],
            site,
            code: appliedCoupon,
          }),
        )
        .then(({data}) => data)
    },
    onDone: {},
    onError: {},
  },

You can see that we are grabbing quantity, appliedCoupon, sellable, and upgradeFromSellable from our context and passing some of those values to the body of our axios.post call. This is how we can reuse our fetchingPrice state, with different context to fetch prices when no coupon is applied, when we've applied a coupon, or even when the quantity we are asking for has changed.

When the user wants to start a purchase, we receive a START_PURCHASE event. This event simply transitions us to the startingPurchase state. We have this state so that we know when the user has clicked the "Purchase" button and a modal to accept their info is been created.

While in the startingPurchase state, we can do two things:

startingPurchase: {
  on: {
    CANCEL_PURCHASE: {
      target: 'priceLoaded',
    },
    HANDLE_PURCHASE: {
      target: 'handlingPurchase',
      actions: [
        assign({
          email: (context, event) => event.email,
          stripeToken: (context, event) => event.stripeToken,
        }),
      ],
    },
  },
},

We can either cancel the purchase and return to priceLoaded or the user has entered their data and is attempting a purchase that we need to handle. In our case, we contact stripe for a token and then get the email that they entered. This is all we need to kick off our purchase process.

handlingPurchase is a state that invokes a promise to POST data to our purchases api endpoint:

handlePurchase: {
  invoke: {
    id: 'handlePurchase',
    src: (context, event) => {// return promise that makes the purchase},
    onDone: {
      target: 'success',
      actions: [
        assign({
          purchase: (context, event) => event.data,
        }),
        'sendToThanks',
      ],
    },
    onError: {
      target: 'failure',
      actions: assign({
        error: (context, event) => {
          return event?.data?.response?.data?.error
        },
      }),
    },
  },
},

This is the same process we've described. We can either transition to success or failure based on the response of the purchase promise. If the purchase was successful, our specific UX is that we send the user to a /thanks page.

State machines are verbose. I haven't described every feature this machine does but in total, this file is 314 lines long. XState forces you to map our all our states and transitions explicitly. This affords you the ability to know exactly when something is happening.

Earlier, when I had a problem with my custom usePackage hook, I would have to follow all the hook calls to track the data and when things happened. In this case, say I am trying to apply a coupon but my machine loads the price, and the request comes back with a price I didn't expect. I can go to my machine and know exactly where coupons get applied to check if it's applied correctly and exactly where the coupon is being used in the request. There's no guessing involved.

As feature requests come in, it's much easier to know exactly where they fit in. Say we want to add a feature so that the user can upgrade from one package to another. We need to send the package we are upgrading from to the server. We know we'll need to pass that package in from react:

const [state, send] = useCommerceMachine({
   sellable: bundle,
   upgradeFromSellable,
 })

Then we know that we will need this object in our context inside of our machine so we can use it when we are fetching our price.

const createCommerceMachine = ({
  sellable,
  purchaseHeaders,
  upgradeFromSellable,
}) =>
  createMachine(
    {
      id: 'commerceMachine',
      initial: 'fetchingPrice',
      context: {
        sellable,
        purchaseHeaders,
        upgradeFromSellable,
       // ...
      },
      // ...
)

Now we can use this upgradeFromSellable object in our fetchingPrice promise.

fetchingPrice: {
  invoke: {
    id: 'fetchPrice',
    src: (context, event) => {
      const {
        sellable,
        upgradeFromSellable,
        // ...
      } = context
      const {
        // ...
      } = sellable
      return axios
        .post(
          priceCheckURL,
          pickBy({
            sellables: [
              {
                upgrade_from_sellable_id: upgradeFromSellable?.slug,
                upgrade_from_sellable: upgradeFromSellable?.type,
                // ...
              },
            ],
            // ...
          }),
        )
        .then(({data}) => data)
    },
    onDone: {// assign the returned price},
    onError: {// assign the error},
  },
},

There's no guessing involved in where we need to put this object to affect our prices call.

There is always state our UI's are dealing with, even if we are explicitly modeling it. State machines force you to model how you want your state to act and what can change the state in your machine. State machines expose the implicit state that you may or may not have known was there.

📆 Livestream Event - Build Your Own Public Digital Garden

Ian Jones — Mon, 18 May 2020 17:31:09 +0000

A digital garden is a place to take concepts from initial discovery all the way to original published posts. It's the idea that concepts grow over time. You tend to this concept over time rather than all at once.

Digital gardens shifted my mindset from needing to post polished blog posts to being ok with rough drafts and coming back to that post when I learn more.

On May 19th, Maggie, Aengus, Aravind, and I will be mob programming on Maggie's digital garden. We will be implementing bi-directional links, link over preview, and talking about how we use our notes to build a digital garden.

If you want to read more about digital gardens, here are some great articles:

How Do I Split Up a Large query In Sidekiq and Rails?

Ian Jones — Wed, 18 Mar 2020 23:27:06 +0000

I posted this question on Stack Overflow and thought I would get the dev.to communities perspective as well.

When we (egghead.io) release a course, we send an email blast to all of our users that are opted into commercial communication. When this happens, our server starts returning 500's because of timed out requests. We use a sidekiq worker (BroadcastMessageSendWorker) to create jobs that will send the email we have written. We use Sidekiq Pro so we can use the bulk processing feature.

ruby '2.6.5'
gem 'pg', '= 1.2.2'
gem 'rails', '= 5.2.4.1'
gem 'sidekiq', '= 5.2.2'
gem 'sidekiq-pro', '= 4.0.4'

class BroadcastMessageSendWorker
  include Sidekiq::Worker

  def perform(message_guid)
    ActiveRecord::Base.connection_pool.with_connection do
      message = BroadcastMessage.find(message_guid)

      message.with_lock do
        return unless message.pending?

        message.pickup!

        if message.contacts.count == 0
          message.finish!
          return
        end

        batch = Sidekiq::Batch.new
        batch.on(:complete, self.class, 'guid' => message_guid)
        batch.jobs do

          # We can't use `uniq` or `DISTINCT` with find_in_batches because after 1000 records it
          # will start blowing up. Instead, use an in-memory `seen` index
          seen = Set.new({})

          message.contacts.select(:id).find_in_batches do |contact_batch|
            args = contact_batch.pluck(:id).map do |contact_id| 
              next unless seen.add?(contact_id) # add? returns nil if the object is already in the set

              [message_guid, contact_id]
            end

            Sidekiq::Client.push_bulk('class' => BroadcastMessageDeliverWorker, 'args' => args.compact)
          end
        end

        message.update(batch_id: batch.bid)
      end
    end
  end

  def on_complete(_, options)
    message = BroadcastMessage.find(options['guid'])
    message.finish! if message.sending?
  end
end

We are building an in memory set to be sure that we don't send 2 of the same emails to a user. ScoutAPM is telling us that the message.contacts.select(:id) line is taking a long time (contacts joins our users table, so this is somewhat expected).

I analyzed this query:

Subquery Scan on contacts  (cost=226960.78..230344.36 rows=52055 width=32) (actual time=555.876..692.685 rows=87926 loops=1)
  Filter: (NOT (hashed SubPlan 1))
  ->  CTE Scan on base_contacts  (cost=224403.49..226485.69 rows=104110 width=264) (actual time=523.530..636.032 rows=87926 loops=1)
        CTE base_contacts
          ->  Gather  (cost=189856.23..224403.49 rows=104110 width=306) (actual time=523.525..554.679 rows=87926 loops=1)
                Workers Planned: 2
                Workers Launched: 2
                ->  Parallel Hash Left Join  (cost=188856.23..212992.49 rows=43379 width=306) (actual time=524.667..557.537 rows=29309 loops=3)
                      Hash Cond: (contacts_1.user_id = users.id)
                      Filter: ((contacts_1.user_id IS NULL) OR (users.can_contact AND ((users.managed_subscription_id IS NULL) OR CASE WHEN (users.managed_subscription_id = ANY ('{2,236,690}'::integer[])) THEN false ELSE true END)))
                      Rows Removed by Filter: 12924
                      ->  Parallel Seq Scan on contacts contacts_1  (cost=149225.21..168513.90 rows=47078 width=306) (actual time=272.862..365.114 rows=42233 loops=3)
                            Filter: ((NOT (hashed SubPlan 2)) AND (NOT (hashed SubPlan 3)))
                            Rows Removed by Filter: 108423
                            SubPlan 2
                              ->  Seq Scan on mailkick_opt_outs mailkick_opt_outs_1  (cost=0.00..2147.74 rows=71817 width=22) (actual time=0.044..16.912 rows=71898 loops=3)
                                    Filter: (active AND (list IS NULL))
                                    Rows Removed by Filter: 19576
                            SubPlan 3
                              ->  Nested Loop  (cost=0.43..146644.75 rows=101271 width=4) (actual time=0.098..142.573 rows=325264 loops=3)
                                    ->  Seq Scan on broadcast_messages  (cost=0.00..9.80 rows=1 width=4) (actual time=0.066..0.085 rows=1 loops=3)
                                          Filter: (signature = 'broadcast_message_signature'::text)
                                          Rows Removed by Filter: 63
                                    ->  Index Scan using index_ahoy_messages_on_broadcast_message_id on ahoy_messages  (cost=0.43..144633.82 rows=200113 width=8) (actual time=0.030..107.063 rows=325264 loops=3)
                                          Index Cond: (broadcast_message_id = broadcast_messages.id)
                                          Filter: ((user_type)::text = 'ClassType'::text)
                      ->  Parallel Hash  (cost=36562.34..36562.34 rows=176534 width=9) (actual time=106.742..106.742 rows=141443 loops=3)
                            Buckets: 131072  Batches: 8  Memory Usage: 3168kB
                            ->  Parallel Seq Scan on users  (cost=0.00..36562.34 rows=176534 width=9) (actual time=0.044..74.643 rows=141443 loops=3)
  SubPlan 1
    ->  Seq Scan on mailkick_opt_outs  (cost=0.00..2376.43 rows=72345 width=22) (actual time=0.011..14.309 rows=74331 loops=1)
          Filter: (active AND ((list IS NULL) OR ((list)::text = 'javascript'::text)))
          Rows Removed by Filter: 17143
Planning Time: 0.458 ms
Execution Time: 715.945 ms

The Parallel Seq Scan is taking a lot of time but I dont know how to speed it up.

My first thought it to split this worker into different ranges of IDs and query the database at different times to reduce the load on the database. So instead of querying message.contacts I would query message.contacts.where('id > 1 && id < 10000') and then message.contacts.where('id > 10001 && id < 20000')etc until we reached the max id.

This feels naive. How do I either speed this query up or spread it out over time?

I also thought of adding a multi-column index on users.managed_subscription_id and users.managed_subscription_id but hadn't tried that yet.

Custom Roam Research Themes

Ian Jones — Wed, 18 Mar 2020 00:00:00 +0000

You can write your own custom RoamResearch.com themes using the stylus extension in chrome. Maggie Appleton has came up with the idea to override the styles with your own.

I've been maintaining a Night Owl theme (s/o to Sarah Drasner for the original colors).

I put these themes up on github if you want to create your own or take mine!

Resources

Generate a RedwoodJS Project

Ian Jones — Wed, 18 Mar 2020 00:00:00 +0000

Watch "Generate a Redwood Project" on egghead.io.

First, you need to make sure your Node version is > 12. We're going to run yarn create redwood-app ./my-redwood-project

Redwood will generate a project for us with this file structure.

├── LICENSE
├── README.md
├── api
│   ├── jsconfig.json
│   ├── package.json
│   ├── prisma
│   │   ├── schema.prisma
│   │   └── seeds.js
│   ├── src
│   │   ├── functions
│   │   │   └── graphql.js
│   │   ├── graphql
│   │   └── services
│   └── tsconfig.json
├── babel.config.js
├── netlify.toml
├── package.json
├── prettier.config.js
├── redwood.toml
├── web
│   ├── jsconfig.json
│   ├── package.json
│   ├── public
│   │   ├── README.md
│   │   ├── favicon.png
│   │   └── robots.txt
│   └── src
│       ├── Routes.js
│       ├── components
│       ├── index.css
│       ├── index.html
│       ├── index.js
│       ├── layouts
│       └── pages
│           ├── FatalErrorPage
│           │   └── FatalErrorPage.js
│           └── NotFoundPage
│               └── NotFoundPage.js
└── yarn.lock

Redwood gives you an api/ folder where your prisma GraphQL api will live. web/ is where your web client is generated. The Redwood team named it this way because they plan to support CLI's and other native platforms in a single app.

To run our app, you can write yarn redwood dev. RedwoodJS will start a server on http://localhost:8910.

Understand Urql's Exchanges and Request Policies

Ian Jones — Fri, 13 Mar 2020 15:09:21 +0000

Watch "Understand Urql's Document Cache Exchange and Request Policies" (community resource) on egghead.

When you are setting up an urql client, the client comes with default exchanges that your operations go through.

These exchanges are [dedupExchange, cacheExchange, fetchExchange]. The order of the array matters.

const client = new Client({
  url: 'http://graphql.org/swapi-graphql/',
  exchanges: [dedupExchange, cacheExchange, fetchExchange],
})

In this case, the dedupExchange is the first exchange that graphql operation will pass through. This exchange has one job: to remove accidental duplicate requests. If you didn't manage your inputs correctly a user can cause many requests at once.

The next exchange the operation goes through is the cacheExchange. This exchange caches any successful requests. This is a Document Cache[01]. This sort of cache takes the query you've written and the variables and hashes them together. Whenever urql finds an operation hash coming through that matches a hash in the cacheExchange, it will return that value based on the requestPolicy.

The requestPolicy for the cacheExchange can be 1 of 4 things:

cache-first
cache-only
network-only
cache-and-network

cache-first is the default policy. It tells urql that if an operation passed to the cacheExchange has been stored already, the data found should be returned and the operation should not be passed to the fetchExchange. If the operation hash hasn't been stored in the cache, then its passed to the fetchExchange

cache-only operates like it sounds: it will only look in the cache for data matching the operation hash and will not pass the operation to the `fetchExchange.

network-only will always skip the cache and pass the operation to the fetchExchange.

cache-and-network will return any value in the cache and pass the operation to the fetchExchange even if there was a successful cache hit. The fetchExchange will then update the cache when the request comes back.

To change the default requestPolicy you can pass one of these values through the Client configuration object.

js const client = new Client({ url: 'http://graphql.org/swapi-graphql/', exchanges: [dedupExchange, cacheExchange, fetchExchange], requestPolicy: 'cache-and-network', })

The last default exchange that your graphql operation passes through is the fetchExchange. This exchanges uses fetch to make an http request to the url defined on the client.

Other exchanges to look at per the documentation.

retryExchange: Allows operations to be retried
devtoolsExchange: Provides the ability to use the urql-devtools
multipartFetchExchange: Provides multipart file upload capability
suspenseExchange (experimental): Allows the use of React Suspense on the client-side with urql's built-in suspense mode
graph cache cacheExchange

Write a GraphQL Subscription with React Hooks using Urql

Ian Jones — Fri, 06 Mar 2020 14:33:29 +0000

Watch "Write a GraphQL Subscription with React Hooks using Urql" (community resource) on egghead.

Urql provides a useSubscription hook for us to subscribe to a GraphQL subscription. The first thing we need to do is import {useSubscription} from 'urql'.

useSubscription takes an object, like useQuery this object expects a property of query and variables to be defined on it. In our particularly query, we are subscribing to the comments on a course. So we need to pass the slug of the course to our subscription query.

function App(){
  const course_slug = 'usesubscription-example'
  useSubscription({
    query: commentSubscriptionQuery,
    variables: {course_slug}
  })
  return (
    // ...
  )
}

Heres what our subscription query looks like:

const commentSubscriptionQuery = `
  subscription subscribeToComments($course_slug: String!) {
    comments(where: {course_slug: {_eq: $course_slug}}){
      text
    }
}`

useSubscription returns an array with the first element in that array being the result: const [result] = useSubscription({})

Like the the result of useQuery, this result has a couple methods on it that are useful to use.
We can use result.error to display any errors that the my have ran into.

const commentSubscriptionQuery = `
  subscription subscribeToComments($course_slug: String!) {
    comments(where: {course_slug: {_eq: $course_slug}}){
      text
    }
  }
`

function App(){
  const course_slug = 'usesubscription-example'
  const [result] useSubscription({
    query: commentSubscriptionQuery,
    variables: {course_slug}
  })

  if (result.error !== undefined) {
    return <div>{res.error.message}</div>
  }
  return (
    // ...
  )
}

Next, we need to tell the user if the query is fetching or if the data hasn't arrived yet.

function App(){
  // ...
  if (!res.fetching && res.data === undefined) {
    return <p>Loading...</p>
  }
  return (//...)

If result passes all of these checks, we know that we have result.data.comments and we can display them in a list.

Write a GraphQL Mutation using React Hooks with Urql

Ian Jones — Tue, 03 Mar 2020 14:17:12 +0000

Watch "Write a GraphQL Mutation using React Hooks with Urql" (community resource) on egghead.

The first thing we need to do is import {useMutation} from 'urql'.

We will call the useMutation hook in our component. This hook returns an array with the result in the first slot and a function to execute the mutation in the second.

const App = () => {
  const [res, executeMutation] = useMutation()
}

Now we need to define a query that we are going to use. Here is the one I am going to use:

const addCourse = `
  mutation addCourse($slug: String!, $title: String!){
    insert_courses(objects: {slug: $slug, title: $title}) {
      returning {
        title
        slug
      }
    }
  }

This query takes a slug and a title as a string (they are both required). The Hasura api I am using defines are returning object. So we will grab the title and slug off of the returned object.

Now we can pass this query to our useMutation hook.

const [res, executeMutation] = useMutation(addCourse)

Lets wire up the wire up the execution method to a button. executeMutation takes an object with keys slug and title. These are the variables we defined in our GraphQL query earlier. We are going to log our res variable to see whats returned.

const App = () => {
  const [res, executeMutation] = useMutation(addCourse)
  console.log({ res })
  return (
    <button
      onClick={() => executeMutation({ title: 'My Course', slug: 'my-course' })}
    >
      Create Course
    </button>
  )
}

{res: {fetching: true, stale: false, error: undefined, data: undefined, extensions: undefined}}
{res: {fetching: false, stale: false, data: {…}, error: undefined, extensions: undefined}}

You can see the result updates when the request starts and again when the query returns the data. This is what the data object looks like:

console.log(res.data)
{
  insert_courses: {
    returning: {
      slug: 'my-course',
      title: 'My Course'
    }
  }
}

Make a GraphQL Query Dynamic with Variables and Urqls useQuery Hook

Ian Jones — Thu, 27 Feb 2020 19:17:08 +0000

Watch "Pass Parameters to urql's useQuery React Hook" (free community resource) on egghead.

We have this GraphQL Query:

const courseQuery = `
  query courses {
    courses {
      title
    }
  }
`

To pass a parameter to a graphql query, we will add (limit: 2) to courses.

const courseQuery = `
  query courses {
    courses(limit: 2) {
      title
    }
  }
`

This parameter will limit the number of courses that come back. Next we are going to pass an offset to this query. Offset is 0 based so we will pass get our first page of courses with 0.

const courseQuery = `
  query courses {
    courses(limit: 2, offset: 0) {
      title
    }
  }
`

Incrementing offset to 1 will give use the next page of courses and so on. We dont want to hard code our query like this though. We need to pass a variable from our React component to our GraphQL query. Just as a reminder, here's what our component looks like right now:

function App() {
  const [result] = useQuery({
    query: courseQuery,
  })

  if (result.fetching) {
    return 'Loading...'
  } else if (result.error) {
    return 'There was an error :('
  }

  return (
    <div>
      <h1>egghead courses</h1>
      <button onClick={() => setOffset(offset + 2)}>Next Page</button>
      {result && result.data && (
        <ul style={{ listStyle: 'none' }}>
          {result.data.courses.map(({ title }) => (
            <li
              key={title}
              style={{
                display: 'flex',
                alignItems: 'center',
                fontSize: 16,
                fontFamily: 'sans-serif',
                marginBottom: 10,
              }}
            >
              {title}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

The first thing we need to do is update our coursesQuery to accept a variable. We will declare an $offset: Int variable in our query declaration. GraphQL query variables are always denoted with a $. They also always need to be assigned a type. In this case, we are using an integer (Int is the syntax).

const courseQuery = `
  query courses($offset: Int) {
  }
`

Now that we have a parameter of $offset declared, we are going to pass this parameter to our query with courses(offset: $offset).

const courseQuery = `
  query courses($offset: Int) {
    courses(offset: $offset, limit: 2) {
      title
    }
  }
`

Inside of our component, we need to pass a variables object with a key of offset to our useQuery hook.

const [result] = useQuery({
  query: courseQuery,
  variables: {
    offset: 0,
  },
})

Urql will handle running the query for us every time this offset variable changes. So if we create some local component state and pass that state to our useQuery hook, any time this variable is updated Urql will run our query.

const [offset, setOffset] = React.useState(0)
const [result] = useQuery({
  query: courseQuery,
  variables: {
    offset,
  },
})

Now lets increment the offset every time someone clicks our Next Page button.

return (
    <div>
      <h1>egghead courses</h1>
      <button onClick={() => setOffset(offset + 1)}>Next Page</button>
      {result && result.data && (
        //...
      )}
    </div>
  )

And thats it! now we have pagination set up with a couple simple hooks.

Introduction to Urqls useQuery React Hook

Ian Jones — Mon, 24 Feb 2020 21:48:50 +0000

If you would prefer to watch this post, you can do so with this community resource lesson on egghead.io.

The first thing we need to do is import {useQuery} from 'urql.

Heres what our React component looks like:

import React from 'react'
import { useQuery } from 'urql'

function App() {
  let result
  return (
    <div>
      <h1>egghead courses</h1>
      {result && result.data && (
        <ul style={{ listStyle: 'none' }}>
          {result.data.courses.map(({ title }) => (
            <li
              key={title}
              style={{
                display: 'flex',
                alignItems: 'center',
                fontSize: 16,
                fontFamily: 'sans-serif',
                marginBottom: 10,
              }}
            >
              {title}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

You can see that we have a result variable that we are going to get our data off of.

We are going to assign useQuery to result.

const [result] = useQuery({})

useQuery takes a configuration object. This is how we tell urql what to query along with some other things we aren't going over in this post.

The query key is required for useQuery to actually run a GraphQL query.

It is unimportant but here's what our query looks like:

const courseQuery = `
  query courses {
    courses {
      title
    }
  }
`
function App() {
  //...
}

We are defining this query above our app component. We need to pass this query to useQuery.

const [result] = useQuery({ query: courseQuery })

Now that we've passed this query in, if you console.log(result) you will see 3 log statements:

{fetching: true, stale: false, error: undefined, data: undefined, extensions: undefined}
{fetching: true, stale: false, error: undefined, data: undefined, extensions: undefined}
{fetching: false, stale: false, error: undefined, data: {…}, extensions: undefined}

You can see that there are a couple of properties on result that are useful to use.

You can use result.fetching to check the status of our query. We can return 'Loading...' to our users so they know that something is happening.

function App() {
  const [result] = useQuery({
    query: courseQuery,
  })

  if (result.fetching) {
    return 'Loading...'
  }

  return (
    // ...
  )
}

If there is an error, it will show up in result.error. Let's add this check so we display a message to our users if something terrible happens.

function App() {
  const [result] = useQuery({
    query: courseQuery,
  })

  if (result.fetching) {
    return 'Loading...'
  } else if (result.error) {
    return 'There was an error :('
  }

  return (
    // ...
  )
}

Lastly, if all of these checks return false, you can presume that the query loaded successfully.

As you've seen before, you can access the data with result.data and display the result to your users!

Add a Node to Your HTML with document.appendChild

Ian Jones — Fri, 21 Feb 2020 14:34:30 +0000

If you would prefer to watch this post, you can do so with this community resource lesson on egghead.io

Given the current state of our HTML:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Select an Element with document.querySelector</title>
  </head>
  <body>
    <ul id="movies">
      <li id="movie-1">Peanut Butter Falcon</li>
      <li id="movie-2">Knives Out</li>
    </ul>
  </body>
</html>

To add a movie to this list, we will need to first get the surrounding parent ul node from the document.

const moviesElem = document.getElementById('movies')

Now we need to actually create the element that we want to append to this list.

const uncutGems = document.createElement('li')

uncutGems.textContent = 'Uncut Gems'

We've created an element but it is not actually been added to our HTML. To do so we will call moviesElem.appendChild(uncutGems)

In the browser, you will see that our movie has been added to our list.

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <title>Select an Element with document.querySelector</title>
  </head>
  <body>
    <ul id="movies">
      <li id="movie-1">Peanut Butter Falcon</li>
      <li id="movie-2">Knives Out</li>
    </ul>

    <script>
      const moviesElem = document.getElementById('movies')
      const uncutGems = document.createElement('li')
      uncutGems.textContent = 'Uncut Gems'
      moviesElem.appendChild(uncutGems)
    </script>
  </body>
</html>

We don't want to hard code adding a movie in this script though. Lets create a button that will add a list element when we click it.

<body>
  <ul id="movies">
    <li id="movie-1">Peanut Butter Falcon</li>
    <li id="movie-2">Knives Out</li>
  </ul>

  <button>Add Uncut Gems</button>
</body>

Now we can create a function in our script tag. We'll move the code we currently have into the body of that function.

<script>
  const addMovie = () => {
    const moviesElem = document.getElementById('movies')
    const uncutGems = document.createElement('li')
    uncutGems.textContent = 'Uncut Gems'
    moviesElem.appendChild(uncutGems)
  }
</script>

Now we have to tell the browser to run our function anytime a user clicks our button. We do this by adding an onclick attribute to our button element.

<button onclick="addMovie()">Add Uncut Gems</button>

The other way to do this is to add an onclick attribute through our javascript. We would have to grab our button and and assign our function to onclick directly (If you added the onclick attribute to you button in the html, you will want to remove it before trying this way).

<body>
  <ul id="movies">
    <li id="movie-1">Peanut Butter Falcon</li>
    <li id="movie-2">Knives Out</li>
  </ul>

  <button>Add Uncut Gems</button>
  <script>
    const addMovieButton = document.querySelector('button')
    addMovieButton.onclick = () => {
      const moviesElem = document.getElementById('movies')
      const uncutGems = document.createElement('li')
      uncutGems.textContent = 'Uncut Gems'
      moviesElem.appendChild(uncutGems)
    }
  </script>
</body>

Select a DOM element with getElementByID

Ian Jones — Thu, 20 Feb 2020 13:07:30 +0000

If you would prefer to watch this post, you can do so with this community resource lesson on egghead.io.

Getting an element by id is so common that the document object has a helper function for us to use.

Given this html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Select an Element with document.getElementById</title>
  </head>
  <body>
    <ul>
      <li id="movie-1">Peanut Butter Falcon</li>
      <li id="movie-2">Knives Out</li>
    </ul>
  </body>
</html>

We can grab our <li id="movie-2">Knives Out</li> by calling document.getElementById('movie-2').

That's it!