Forem: Kwirke

Implementing a Shopping Cart with ApolloJS 3

Kwirke — Fri, 18 Jun 2021 14:37:26 +0000

ApolloJS is a GraphQL framework that lifts a lot of heavy work in both client and server. It also aims to provide a good solution for local state management in client, but one can quickly see it is still very young in this business: The docs give 3 different solutions for state management, but none of them is extensibly documented. Also, none of them allow for event dispatching nor state machines.

In the official ApolloJS docs, there is half an example of a shopping cart. As the lack of explanation left me puzzled, I tried several things, and I am going to explain here a solution that is both simple and idiomatic to Apollo.

Ingredients

In this example we are assuming we have:

A datasource with methods getItem(itemId) and getAllItems()
A GraphQL proxy, implemented with apollo-server
Ability to edit this proxy
The next schema:

type Item {
  id: String
  name: String
  price: Int
}

type Query {
  allItems: [Item!]!
  item(id: String!): Item
}

The Cart in the Client

In order to implement the cart, we want to store in the client's state the minimum amount of data we can.

A possible implementation would be to have a fully-fledged store and replicate there the data of all the selected items in the cart, but we already have this data in the Apollo cache, and we want to take advantage of that.

The minimum data we need is the list of selected IDs, so that's what we will be storing.

But what happens if we haven't fetched the selected items yet? We will need a way to fetch their data, but we only have a way to get one or all the items. Even worse: In a real case, the allItems query will be paginated and we won't have any guarantee we have fetched the selected items.

The Server

In order to fetch the missing data, we will need a query that fetches only the selected items.

Let's add the new query to the schema:

type Query {
  allItems: [Item!]!
  item(id: String!): Item
  items(ids: [String!]!): [Item!]!
}

We also need to add the appropriate resolver:

const resolvers = {
  items: (_, {ids}, {dataSources}) => (
    Promise.all(ids.map(
      id => dataSources.itemsAPI.getItem(id)
    ))
  ),
  ...
}

The Client

In order to have local state in Apollo, we extend the schema with local fields as follows:

const typeDefs = gql`
  extend type Query {
    cartItemsIds: [Int!]!
  }
`

Apollo gives us three ways of handling this local state, each one worse than the rest:

Rolling our own solution

This means having our own local dataSource (localStorage, Redux store, etc).

In order to read the data, we can write a read resolver for our client queries that resolve against this local dataSource.

In order to modify the data, the documentation doesn't say anywhere that we can write resolvers for mutations, and tells us to directly call the dataSource, coupling it everywhere, and afterwards calling manually cache.evict({id, fieldName}) in order to force the refresh of all the dependents of the modified entity.

Using the cache

Just as in the previous, we write a read resolver, but we will use Apollo's cache itself as a dataSource, thus avoiding the call to cache.evict.

This means we will have to call readQuery with a GraphQL query in order to resolve a GraphQL query. It also means we will need to add types to the extended schema, and that we won't be able to store anything that is not a cacheable entity (has an ID) or is not directly related to one.

We want to store an array of IDs, which shouldn't need to have an ID on its own because it is not an instance of anything.

This solution would force us to implement this as a boolean isInCart client field in the Item itself, querying the cache and filtering all items that have isInCart === true. It is fine for the cart case, but not extensible to things that are not related to entities in the cache. We don't want to be forced to use different methods for different local data.

It will also force us to call directly writeQuery in order to modify the data. All in all, suboptimal at best.

Reactive Variables

The chosen solution.
We create a global (ehem) reactive variable, then write a resolver that will retrieve its value, and we can also check and modify the variable in any component using the useReactiveVar hook.

This solution still forces us to read data using a different paradigm that the way we write it. However, we won't have to use cache.evict nor the suicide-inducer cache API.

Client Implementation

We create the reactive variable and check it in the resolver for our local cartItemsIds query:

const itemsInCart = makeVar([]) // We start with no item selected

const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: { // boilerplate
        cartItemIds: {
          read() {
            return itemsInCart()
          }
        }
      }
    }
  }
})

const client = new ApolloClient({
  uri: 'https://...',
  typeDefs,
  cache,
})

Now we can make the following client query from any component:

query ItemIdsInCart {
  cartItemsIds @client
}

And we can combine this query with the new server query in order to get all the data for each item:

const GET_CART = gql`
  query GetCart($itemIds: [String!]!) {
    cartItemIds @client @export(as: "itemIds")
    items(ids: $itemIds) {
      id
      name
      price
    }
  }
`

const Cart = () => {
  const {loading, error, data} = useQuery(GET_CART)
  if (loading || error) return null
  return (
    <ul>
      {data.items.map(item => (
        <li key={item.id}>
          {`${item.name}...${item.price}$`
        </li>
      ))}
    </ul>
  )
}

Even a better solution

If we look closely, we will see we could fetch the reactive variable from the component, and thus avoid the local query altogether. Let's see how:

First, we ignore Apollo docs and remove the pyramid of doom from the InMemoryCache:

const itemsInCart = makeVar([])

const client = new ApolloClient({
  uri: 'https://...',
  cache: new InMemoryCache(),
  // no typeDefs either
})

Now, we can use the reactive variable directly in the component without any sense of guilt:

const GET_CART = gql`
  query GetCart($itemIds: [String!]!) {
    items(ids: $itemIds) {
      id
      name
      price
    }
  }
`

const Cart = () => {
  const cartItemIds = useReactiveVar(itemsInCart)
  const {loading, error, data} = useQuery(GET_CART, {
    variables: {itemIds: cartItemIds},
  })
  if (loading || error) return null
  return (
    <ul>
      {data.items.map(item => (
        <li key={item.id}>
          {`${item.name}...${item.price}$`}
        </li>
      ))}
    </ul>
  )
}

Modifying the Cart

So how do we modify the variable? We call it with the new value, and all dependents will magically update and all queries will be refetched.

We will add a removeFromCart function to the component to see how this works:

const Cart = () => {
  const cartItemIds = useReactiveVar(itemsInCart)
  // + vvv
  const removeFromCart = useCallback(id => {
    const remainingItems = cartItemIds.filter(item => item !== id)
    // This will trigger the re-render due to useReactiveVar
    itemsInCart(remainingItems)
  }, [cartItemIds])
  // + ^^^
  const {loading, error, data} = useQuery(GET_CART, {
    variables: {itemIds: cartItemIds},
  })
  if (loading || error) return null
  return (
    <ul>
      {// Call removeFromCart on click
      data.items.map(item => (
        <li key={item.id} onClick={() => removeFromCart(item.id)}>
          {`${item.name}...${item.price}$`
        </li>
      ))}
    </ul>
  )
}

Conclusions

You can find the full code here:
Server: codesandbox.io/s/awesome-northcutt-iwgxh
Client: codesandbox.io/s/elegant-mclean-ekekk

A special thanks to this article by Johnny Magrippis for the environment set-up:
https://medium.com/javascript-in-plain-english/fullstack-javascript-graphql-in-5-with-code-sandbox-374cfec2dd0e

What is the utility of custom local-only fields, then?

As far as I have seen, none. I haven't found any way to make local queries derive the output from several remote queries. As these dependencies are meant to be solved in the component, we may as well connect it to Redux for all the local state and make all the queries based on the values in the state. We will have full reactivity as well, and a coherent way to get and set all local state.

I don't have a lot of experience with Apollo and this conclusion should be taken cautiously. This article is only meant as a tutorial as well as a critique to Apollo's incomplete docs.

If this helped you in any way or you know more than I do, please let me know.

Solving Caret Jumping in React Inputs

Kwirke — Wed, 09 Jun 2021 09:48:47 +0000

There are many explanations out there about unwanted caret jumping in React inputs, but I couldn't find any that addressed the issue we found.

This might be an easy way to encounter the issue in complex apps, so I thought I'd add my grain of sand.

The inciting situation - async update on each keystroke

We have a controlled input that gets its value from a context that is updated asynchronously, and for this input in particular, it is updated per keystroke, not after blur.

This makes the input receive a possibly updated value every keystroke. If you have a caret in a middle position and the value changes unexpectedly, the input element won't make any assumption on the caret position, and will jump it to the end.

The problem we faced is that it also jumps when the value hasn't changed at all, except for the new character just typed.

Note that this flow might be necessary in some cases, but it is generally a bad idea. As a general rule, do not change the input value asynchronously while the user is typing.

Why does the caret jump

When you inject programmatically a different value in a DOM input, the input makes no assumption about caret position and moves it to the end.

In a controlled input, React is always capturing the input's events and then forcing a new value into the element. So, in order to avoid the caret jumping always, React will optimise(*) the synchronous updates, but it will not be able to do anything with asynchronous updates.

(*) This may be related to React internals, which I'm not the best person to ask about. I tried reproducing the caret jump with vanilla JS, to no success. If you can explain the specific reason, please be welcome to do so in the comments!

See this React issue: https://github.com/facebook/react/issues/5386

As Dan Abramov puts it:

If you use controlled inputs, you’re expected to update the value synchronously. If you need to, for example, debounce, you can do this after updating the value. For example one might maintain two values in the state: one for the input, and one for the “debounced” value.

From the point of view of the input element, the value was hell| world with the caret at the |, then the user pressed o but the event was prevented from happening, and the next it knows is that it's receiving a new value that is different, hello world, but it could as well be good bye and it's not the input's job to compare it, so it puts the caret at the end.

How to solve it

Make always a synchronous update before sending the update up the asynchronous flow.

If we have this, assuming onChange is asynchronous:

const Broken = ({ value, onChange }) => {
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
};

We want to allow React to do the synchronous optimisation, to tell the input "Hey, this keypress was for you, do your thing and move the caret naturally".

Then, when the asynchronous update returns, if the value has not changed, the caret will not move. If the value has changed asynchronously (from another source of truth), then the caret will jump, and that is OK (**).

(**) If it is not OK for you, you will need to store the caret position yourself and implement your own custom logic to your liking. See https://stackoverflow.com/questions/46000544/react-controlled-input-cursor-jumps

How do we do that? We put a synchronous cache between the input and the async store. For example, with local state:

const Fixed = ({ value, onChange }) => {
  const [val, setVal] = useState(value);
  const updateVal = (val) => {
    /* Make update synchronous, to avoid caret jumping when the value doesn't change asynchronously */
    setVal(val);
    /* Make the real update afterwards */
    onChange(val);
  };
  return <input value={val} onChange={(e) => updateVal(e.target.value)} />;
};

And that's it. You can find the full example code here:

https://codesandbox.io/s/react-caret-jump-3huvm?file=/src/App.js

Javascript Composable Decoders with Validation

Kwirke — Wed, 10 Jul 2019 05:54:45 +0000

I'm a suspicious person. If I don't find my slippers by my bed, I suspect. If I see a cat wearing a coat and looking at my direction, I suspect. The same way, when I receive data from an external source, I suspect.

Doesn't matter what the Swagger or the specs say, if you are receiving data from an API or any other external source, it is always good to know that it fulfills a format and any business restrictions. This is where TypeScript types stop helping you. Even if there are nice libraries that help cover this gap, like io-ts, you might still miss a good way to trace what failures happened and where.

Here I'll describe how I implemented a Javascript decoder that accumulates the errors of the received data while keeping all needed data after the decoding process. You can see the full snippet here.

The Problem

To illustrate the example, I'll be receiving a list of videogames data, like this:

const videogames = [
  {id: 1, name: 'Doom', genre: 'FPS', rating: 7},
  {id: 2, name: 'NieR: Automata', genre: 'Action RPG', rating: 100},
  {id: 3, name: 'Dead Cells', genre: 'Rogue-like', rating: 8},
]

We will have some restrictions as well, namely:

The dataset must be an array of videogames.
A videogame must have an id, a name, a genre and a rating.
name can't be empty
genre must be one of our recognised genres (FPS, RPG, Simulator, Strategy, and Platforms).
rating must be between 1 and 10.

If you are a keen observer, you'll see the example dataset already breaks some of those restrictions. Excellent.

What we want is to be able to parse this kind of datasets, know all the errors that happened so we can inform the user or developer, and keep or throw away invalid data at our convenience.

The Tool to Solve It

In order to do so, I'll use my library Validation. Validation is a monad. A monad is a software pattern for a type/class that has certain functions and certain restrictions. Being a monad means two things:

It is a wrapper for something (in our case, values) and can be constructed using Validation.of(value) (this is called Applicative).
It implements "Mappable" or has a map function (this is called Functor), and "Chainable", or a chain function (and this, Chain).

Mapping a monad means applying a function to its values without modifying the container, as if it was an array: [1, 2].map(x => x + 1) === [2, 3]

Chaining a monad means applying a function to its values and changing the container for the one returned by the function. It is also called flatMap because, if you map a function that returns another container and don't flatten the result, you end up with a container inside a container:
[1, 2].map(x => [x, 0]) === [[1, 0], [2, 0]], but
[1, 2].flatMap(x => [x, 0]) === [1, 0, 2, 0]

Validation<E, V> is a monad that can be of two types: Valid and Invalid. E and V here are generic types for the two values that a Validation wraps: Its errors and its value.

A Valid type only stores some data of type V, and affirms it is "valid" so far. It can be constructed with Validation.of, but also using Validation.valid

An Invalid type stores two values: Some invalid data of type V, and a list of errors of type E. It can be constructed using Validation.invalid.

Having all that we can validate a specific rating like this:

const ratingDecoder = rating => (
  isBetween(1, 10)(rating)
    ? Validation.valid(rating)
    : Validation.invalid(rating, `Rating must be between 1 and 10, but received ${rating}`)
)

Here we're returning a Valid(rating) in case rating fulfills the restriction, and Invalid(rating, errorMessage) when rating does not fulfill it.

The unicorn stuff we have here that other validation libraries don't offer is that we're keeping the rating value, even if we know it is invalid, because we may need this information later.

The Plan

Ok, so what's the plan? How are we going to use this to decode all the data?

First, we want to do it recursively, and secondly, with composable decoders that also describe our data shape. For example, our videogameDecoder will be something like this:

const videogameDecoder = videogame => doSomeStuff({ // We'll complete this later
  id: idDecoder,
  name: nameDecoder,
  genre: genreDecoder,
  rating: ratingDecoder,
}, videogame)

This way, videogameDecoder is serving two purposes:

It is a decoder function that returns a validated videogame.
It is a declaration of the videogame type shape, like PropTypes. This is also a good documentation when we don't have TypeScript.

We will do this with all levels, all shapes and types. In our case, this is our four attributes (id, name, genre, and rating), our videogame type, and our videogameArray type. Let's begin:

Decoding For Fun

We'll begin with the nameDecoder function. Assuming we have a function isFilled(str) that tells us if a name is non-empty, we can do something similar to the ratingDecoder before:

const nameDecoder = name => (
  isFilled(name)
    ? valid(name)
    : invalid(name, 'name can not be empty')
)

So we'll have to do this with all the attributes. Isn't it a little boilerplate-y? Luckily, Validation comes with several helpers, one of which is fromPredicateOr(errorFn, predicate). It can be used to create a function that will receive our value and return a Validation of it. Let's look at how can we use it:

const nameDecoder = fromPredicateOr(() => 'name can not be empty', isFilled)

Much better! Now, when we call nameDecoder, it will check isFilled and return a Valid or Invalid depending on its truthiness.

Moreover, if another type that is not a videogame needs to have a name that can not be empty, we can reuse this decoder!

We now have all the attributes decoded:

const idDecoder = valid
const nameDecoder = fromPredicateOr(() => 'name can not be empty', isFilled)
const genreDecoder = fromPredicateOr(() => 'genre must be in validGenres', flip(includes)(validGenres))
const ratingDecoder = fromPredicateOr(() => 'rating must be between 1 and 10', isBetween(1, 10))

What about idDecoder? It doesn't have any restriction, so it will be valid always, but we still need to provide a Validation out of it, so we will use the valid constructor directly.

The Videogame Type

The function videogameDecoder that we want will receive a videogame object, validate each one of its attributes, and then group (or reduce) all validations into one single validation:

// Videogame
{
  id: 3,
  name: 'Dead Cells',
  genre: 'Rogue-like',
  rating: 8
}

// Videogame with validated attributes
{
  id: valid(3),
  name: valid('Dead Cells'),
  genre: invalid('Rogue-like', ['genre is not in validGenres']),
  rating: valid(8),
}

// Validated videogame without invalid properties
invalid({
  id: 3,
  name: 'Dead Cells',
  rating: 8,
}, ['genre is not in validGenres'])

Note that, in the last step, we are choosing not to keep the invalid values. It doesn't need to be like that, we can choose to keep them, but we won't need them any longer in this example.

In order to do the first step, we could use the evolve method from Ramda, but we won't because it doesn't apply any function to missing attributes, and we want to detect a missing attribute to say it is invalid.

We could also iterate over the object properties:

const validations = {id: idDecoder, name: nameDecoder, /* ... */}

Object.keys(validations).reduce(
  (acc, k) => ({
    ...acc,
    [k]: property(k, videogame).chain(val => validations[k](val)),
  }),
  {}
)

Note how, in the fourth line, we are using the Validation.property method that returns a Valid if it finds that attribute, and an Invalid otherwise. Then, we chain it to a function that will return a Valid if the validation for that attribute passes, or an Invalid otherwise.

How does that work?

When we chain Validations, it remembers the errors that we had detected previously, and adds them to any new errors. It will behave like this:

valid(1).chain(n => valid(2)) === valid(2)
valid(1).chain(n => invalid(2, ['error'])) === invalid(2, ['error'])
invalid(1, ['error1']).chain(n => invalid(2, ['error2']) === invalid(2, ['error1', 'error2'])

This way, information about the errors is preserved.

Instead of doing it this way, we will use another Validation helper: validateProperties. It does exactly what we wanted:

const videogameWithValidatedProperties = validateProperties({
  id: idDecoder,
  name: nameDecoder,
  /* ... */
}, videogame)

On to the second and last step, we need to iterate over the object properties and add only the properties that are valid. We can check this using Validation.isValid() method, and access the value inside with Validation.value:

const allProperties = obj => (
  Object.keys(obj).reduce((validatedObj, k) => (
    validatedObj.chain(validObj => obj[k].isValid()
      ? Validation.of({...validObj, [k]: obj[k].value})
      : obj[k].map(() => validObj)
    )),
    valid({})
  )
)

However, this is a complex function, and a common enough one to have its own helper as well, Validation.allProperties, so we'll use that.

At the end, we will have our videogameDecoder pretty terse thanks to the helpers:

const videogameDecoder = videogame => {
    const videogameWithValidatedProperties = Validation.validateProperties({
        id: idDecoder,
        name: nameDecoder,
        genre: genreDecoder,
        rating: ratingDecoder,
    }, videogame)
    return Validation.allProperties(videogameWithValidatedProperties)
}

We can improve that if we refactor it using point-free style with the help of the pipe function from Ramda:

const videogameDecoder = pipe(
    Validation.validateProperties({
        id: idDecoder,
        name: nameDecoder,
        genre: genreDecoder,
        rating: ratingDecoder,
    }),
    Validation.allProperties,
)

Validation Arrays

Just as Validation has some helpers to deal with objects, it has other ones to deal with arrays.

As it turns out, these operations are well defined in the functional programming world, because FP loves lists. Enter the Monoid.

A monoid is, just like a monad, another programming pattern (although they don't have much more in common, even if the names look similar). A type is a monoid if it is "Concatenable" and has an "empty" function that returns an empty element.

Therefore, a monoid will always have two functions:

empty returns the empty element. With arrays, that would be [].
concat concatenates the values of two monoids and returns another monoid. With arrays, that would be Array.concat.

This means JS arrays are a monoid, and if they had an .empty() method that returned [], they would even be Static Land compliant. But they don't.

Validation, as it turns out, is conveniently a Static Land compliant monoid when the wrapped value is an array (when it is not, it is casted to an array when concatenating). This means we have the full power of the monoids in the palm of our hands.

The List Type

Now for the last function: videogameArrayDecoder. It receives an array of videogames, and returns a Validation of the array.

We can do that in two steps just like before: Validate each of the videogames, then accumulate (reduce) the Validations into a single Validation.

// Array of videogames
[vg1, vg2, vg3]

// Array of videogame Validations
[valid(vg1), invalid(vg2, err2), invalid(vg3, err3)]

// Validation of array of videogames
invalid([vg1], [...err2, ...err3])

Note that, just like before, in the last step we will be dropping the invalid videogames off the list because we want to.

To validate each of the videogames, we can do that with a conventional Array.map like this:

const validatedVideogames = videogames.map(videogameDecoder)

Eezy-peezy. For the second step, we want to reduce the array of validations to a validation of arrays. As we know, Validation acts as a monoid when the values are arrays, so let's map them to one-element arrays:

const toArrayValidation = Validation.map(x => [x])
const videogameArrayValidations = validatedVideogames.map(toArrayValidation)

Now we are ready to concat them, because they contain arrays. Validation.concat method concatenates the valid values, and drops the invalid values, just like we want. This means we can reduce the list like follows:

const videogamesValidation = videogameArrayValidations
    .reduce(Validation.concat, Validation.empty())

This looks awesome because it is the very definition of generating a list with a monoid. It is so awesome it has its own function in the library:

const videogamesValidation = Validation.sequence(videogameArrayValidations)

If we instead wanted to keep the invalid values, we would have to do it another way:

const losslessSequence = l => l.reduce((valList, val) => (
  valList.chain(list => val.map(x => [...list, ...x]))
), Validation.empty())

const videogamesValidation = losslessSequence(videogameArrayValidations)

By using map inside chain, what we are doing is concatenating all values inside the new validation in each iteration, and then chaining it to the original one to keep the errors, because the chain function preserves all the errors.

So how will the decoder look like?

const videogameArrayDecoder = videogames => {
    const validatedVideogames = videogames.map(videogameDecoder)
    return Validation.sequence(validatedVideogames)
}

If we refactor it using point-free style and Ramda, we get this:

const videogameArrayDecoder = pipe(map(videogameDecoder), Validation.sequence)

The Result

Finally, this is the complete code of our whole decoder:

const {Validation, valid, invalid} = require("@rexform/validation")
const {isNil, isEmpty, complement, either, includes, flip, both, lte, gte, pipe, map} = require('ramda')

const videogames = [
    {id: 1, name: 'Doom', genre: 'FPS', rating: 7},
    {id: 2, name: 'NieR: Automata', genre: 'Action RPG', rating: 100},
    {id: 3, name: 'Dead Cells', genre: 'Rogue-like', rating: 8},
]

const validGenres = ['FPS', 'Platforms', 'RPG', 'Strategy', 'Simulator']

const isFilled = complement(either(isNil, isEmpty))
const isBetween = (a, b) => both(flip(lte)(b), flip(gte)(a))

const nameDecoder = Validation.fromPredicateOr(() => 'name can not be empty', isFilled)
const genreDecoder = Validation.fromPredicateOr(() => 'genre must be in validGenres', flip(includes)(validGenres))
const ratingDecoder = Validation.fromPredicateOr(() => 'rating must be between 1 and 10', isBetween(1, 10))

const videogameDecoder = pipe(
    Validation.validateProperties({
        id: valid,
        name: nameDecoder,
        genre: genreDecoder,
        rating: ratingDecoder,
    }),
    Validation.allProperties,
)

const videogameArrayDecoder = pipe(map(videogameDecoder), Validation.sequence)

videogameArrayDecoder(videogames)

And this is the result:

Invalid(
  [{id: 1, name: 'Doom', genre: 'FPS', rating: 7}],
  [
    "genre must be in validGenres",
    "rating must be between 1 and 10",
    "genre must be in validGenres",
  ]
)

The only missing problem is that, when we see the errors, we don't know what videogame produced them. We can fix that if we come back to our videogameDecoder and add the videogame id in the error message (or, instead of the id, the whole videogame object stringified, if we want).

We can use the function mapError to add the id to the error message. The function mapError works like map, but for the wrapped error array instead of the wrapped value. It will only modify each of the errors without changing the Validation:

const videogameDecoder = pipe(
    Validation.validateProperties({
        id: valid,
        name: nameDecoder,
        genre: genreDecoder,
        rating: ratingDecoder,
    }),
    Validation.allProperties,
    videogame => videogame.mapError(e => `In ID=${videogame.value.id}: ${e}`),
)

That's it, now the result will have much more meaning:

Invalid(
  [{id: 1, name: 'Doom', genre: 'FPS', rating: 7}],
  [
    "In ID=2: genre must be in validGenres",
    "In ID=2: rating must be between 1 and 10",
    "In ID=3: genre must be in validGenres",
  ]
)

We finished our new videogame decoder, hurray! 😄

Thanks

If you reached this point, thank you! This is my first article, and I welcome any suggestions or feedback. I hope you learned something out of it, but if you didn't, maybe you can teach me something!

Also, if you liked it, give Validation a try 😉