DEV Community: Victor Trofin

Return union types in ReScript

Victor Trofin — Wed, 22 Dec 2021 14:25:58 +0000

Inspired by this article I've decided to share an approach on returning union types in ReScript. The case in point is exporting a getServerSideProps function from a Next.js page, enabling us to fetch the props for pre-rendering the page server side. This example function returns only two kinds of objects, one for the props and another for the redirect (we will not handle the not found case). Note that in the ReScript implementation we will also be using an object for the return value mainly for convenience. Since it doesn't require a type declaration, the object type makes it easy to return the runtime representation of our desired object in JavaScript.

Let's see the TypeScript implementation first to get a better idea of what we're trying to achieve. The type declaration of the getServerSideProps function reveals no surprise, its return type is a union type which can either return props, a redirect or notFound.

 // .ts
 export type GetServerSidePropsResult<P> =
   | { props: P }
   | { redirect: Redirect }
   | { notFound: true }

 export type GetServerSideProps<
   P extends { [key: string]: any } = { [key: string]: any },
   Q extends ParsedUrlQuery = ParsedUrlQuery
 > = (
   context: GetServerSidePropsContext<Q>
 ) => Promise<GetServerSidePropsResult<P>>

Here is our complete TypeScript example:

 // Page.ts
 import { GetServerSideProps, NextPage } from "next"

 type User = {
   name: string
   age: number
 }

 type Props = { user: User }

 export const getServerSideProps: GetServerSideProps<Props> = async (
   context,
 ) => {
   const response = await fetch(`https://.../user`)
   const user: User = await response.json()

   if (!user) {
     return {
       redirect: {
         destination: "/",
         permanent: false,
       },
     }
   }

   return {
     props: { user },
   }
 }

 const Page: NextPage<Props> = ({ user: { name, age } }) => {
   return (
     <div>
       <p>User name: {name}</p>
       <p>Age: {age}</p>
     </div>
   )
 }

 export default Page

Working with the union type looks effortless in TypeScript but is it the same for the ReScript counterpart? We'll start by namespacing the function's type definition into a separate module to keep things organized. Inside the module we also declare the type for the context argument this function takes.

 module GetServerSideProps = {
   module Req = {
     type t
   }

   module Res = {
     type t
   }

   type context<'props, 'params, 'previewData> = {
     params: 'params,
     preview: option<bool>,
     previewData: Js.Nullable.t<'previewData>,
     query: Js.Dict.t<string>,
     req: Req.t,
     res: Res.t,
   }

   // The type of the `getServerSideProps` function
   type t<'props, 'params, 'previewData> = context<'props, 'params, 'previewData> => Js.Promise.t<{
     "props": 'props,
   }>
 }

For convenience we choose to abstract req and res properties on the context record. We declare them as opaque types because we’re not sure about their runtime representation and we actually don’t care about it. Currently our function returns a single object type with props.

We'll group the union type definition into another nested module named Return and we'll provide a module signature to expose two methods which are responsible for returning the appropriate object kind with either props or redirection. Everything else is left as an implementation detail. Here is how the Return module looks like.

 module Return: {
   type rec t<'props>

   let inject: (~props: 'props) => t<'props>

   let redirect: (~destination: string, ~permanent: bool, unit) => t<'props>
 } = {
   @unboxed type rec t<'props> = Any('value): t<'props>

   let inject = (~props) => Any({ "props": props })

   let redirect = (~destination, ~permanent, ()) => Any({
     "redirect": { 
       "destination": destination, 
       "permanent": permanent
     },
   })
 }

Checking the module signature we notice again an opaque type t<'props> to hide the underlying type of the Return module as an implementation detail. This type references itself so we need to define it as a recursive type rec otherwise we would get a compiler error.

Inside the Return module, t is defined as a variant Any with some payload. We are also making use of the @unboxed attribute which strips out the variant constructor and makes its runtime representation equal to the underlying value. These two combined enable returning at runtime the two objects expected from geServerSideProps.
Now we can update the function's type definition to return a value of type Return.t<'props>.

type t<'props, 'params, 'previewData> = context<'props, 'params, 'previewData> => Js.Promise.t<
   Return.t<'props>,
 >

We are now ready to implement the getServerSideProps function inside the Page file. We destructure inject and redirect functions from the Return module and call them to return the desired object - inject to "inject" the props into the page and redirect to redirect to the main page when failing to load the props.

 // Page.res
 module GetServerSideProps = {
   module Req = {
     type t
   }

   module Res = {
     type t
   }

   type context<'props, 'params, 'previewData> = {
     params: 'params,
     preview: option<bool>,
     previewData: Js.Nullable.t<'previewData>,
     query: Js.Dict.t<string>,
     req: Req.t,
     res: Res.t,
   }

   module Return: {
     type rec t<'props>

     let inject: (~props: 'props) => t<'props>

     let redirect: (~destination: string, ~permanent: bool, unit) => t<'props>
   } = {
     @unboxed type rec t<'props> = Any('value): t<'props>

     let inject = (~props) => Any({"props": props})

     let redirect = (~destination, ~permanent, ()) => Any({
       "redirect": {"destination": destination, "permanent": permanent},
     })
   }

   type t<'props, 'params, 'previewData> = context<'props, 'params, 'previewData> => Js.Promise.t<
     Return.t<'props>,
   >
 }

 type user = {
   name: string,
   age: int,
 }

 type props = {user: user}

 let getServerSideProps: GetServerSideProps.t<_, _, _> = _context => {
   let {inject, redirect} = module(GetServerSideProps.Return)

   let getData = () => {
     // fetch the data from somewhere
     Js.Promise.resolve({name: "John", age: 30})
   }

   getData()->Js.Promise.then_(user => {
     inject(~props={user: user})->Js.Promise.resolve
   }, _)->Js.Promise.catch(_error => {
     redirect(~destination="/", ~permanent=true, ())->Js.Promise.resolve
   }, _)
 }

 @react.component
 let default = (~user: user) => {
   let {name, age} = user

   <div>
     <p> {`User name: ${name}`->React.string} </p>
     <p> {`Age: ${age->Js.Int.toString}`->React.string} </p>
   </div>
 }

Hopefully this example helps you get a grasp on union types in ReScript. It may require a bit more effort to master the topic as a newcomer to the language but I believe this is by no means impossible to achieve. It's definitely worth it.

Covering the edge case on the ReScript record type

Victor Trofin — Mon, 20 Dec 2021 02:01:42 +0000

In terms of preference, Typescript dominates the category for statically typed languages that compile to plain JavaScript. However, ReScript - a fairly new contender in this category - aims to improve the JavaScript experience and address some of the pitfalls. In this article I'm planning on looking at the edge case in one of the most heavily used data types for each of the two languages. How different is working with records in ReScript than working with objects in TypeScript?

As opposed to TypeScript objects, records in ReScript are immutable by default. Another big difference is that records use nominal typing while objects use structural typing. What this means is that two records sharing the same properties (field names) will not have the same type.

For example, in TypeScript this code compiles. I'm able to provide an argument of type SubscriptionUser to a function that accepts an argument of type QueryUser simply because they have the same properties.

// .ts
type QueryUser = {
  age: number
  name: string
}

type SubscriptionUser = {
  age: number
  name: string
}

const logMyUser = ({ age, name }: QueryUser) => {
  console.log(`Hi! I am ${name} of ${age} years old.`)
}

const subscriptionUser: SubscriptionUser = {
  name: "John",
  age: 30,
}
logMyUser(subscriptionUser)

This however will not work for records.

// .res
type queryUser = {
  name: string,
  age: int,
}

type subscriptionUser = {
  name: string,
  age: int,
}

let logMyUser = ({name, age}: queryUser) => {
  Js.log(`Hi! I am ${name} of ${age->Js.Int.toString} years old.`)
}

let subscriptionUser: subscriptionUser = {name: "John", age: 30}
logMyUser(subscriptionUser)

// ERROR:
// [E] Line 17, column 10:
// This has type: subscriptionUser
// Somewhere wanted: queryUser

This means that different record types with the same properties cannot be passed to the same function. The main benefit for this is that type error messages are really good and point you to the specific line of code where you need to address the issue. Anyone who has used the structurally typed polymorphic variants in ReScript may know that sometimes it is difficult to pinpoint the exact location in your codebase where you need to address the type error. You may have to do a little bit of digging to figure out where that somewhere might be.

This has type `x`
Somewhere wanted type `y`
Types for method `z` are incompatible

So, why does this matter? Well, because updating deeply nested records is a little more tedious. For example, consider the case of having a front-end react app with a graphQL query to fetch users, with reactivity provided via graphQL subscriptions. Every time an user gets updated we need to map over all of our users stored in state and replace the old values with the updated ones.

In TypeScript you would just assign the updated nested object and be done with it.

// Page.ts
import React, { useState, useEffect } from "react"

type QueryUser = {
  name: string
  age: number
}

type SubscriptionUser = {
  name: string
  age: number
}

type QueryResult = {
  id: string
  userData: QueryUser
}

type SubscriptionResult = {
  id: string
  userData: SubscriptionUser
}

// assume we have an array of users fetched from a GraphQL api
const someMagicWayToGetData = (): QueryResult[] => {
  const users = [
    { id: "1", userData: { name: "John", age: 35 } },
    { id: "2", userData: { name: "Mary", age: 20 } },
    { id: "3", userData: { name: "Kate", age: 50 } },
  ]

  return users
}

// and a graphQL subscription to push updates to our page
const someMagicWayToGetUpdates = (): SubscriptionResult => {
  const updatedUser = {
    id: "2",
    userData: { name: "Mary Jane", age: 21 },
  }

  return updatedUser
}

const Page = () => {
  const [
    users, 
    setUsers
  ] = useState<QueryResult[]>(someMagicWayToGetData())
  const updatedUser = someMagicWayToGetUpdates()

  useEffect(() => {
    const newUsers = users.map((user) => {
      if (user.id === updatedUser.id) {
        return {
          ...user,
          userData: updatedUser.userData,
        }
      }

      return user
    })

    setUsers(newUsers)
  }, [updatedUser])

  return (
    <div>
      <ul>
        {users.map(({ id, userData: { name, age } }) => (
          <li key={id}>
            User: {name}; Age: {age}
          </li>
        ))}
      </ul>
    </div>
  )
}

export default Page

In ReScript you need to manually assign each updated property within the nested record. This will not compile.

// .res
let newUsers = users->Js.Array2.map(user => {
  if user.id == updatedUser.id {
    {...user, userData: updatedUser.userData}
  } else {
    user
  }
})

// Error:
// [E] Line 43, column 20:
// This has type: subscriptionUser
// Somewhere wanted: queryUser

This compiles

// Page.res
type queryUser = {
  name: string,
  age: int,
}

type subscriptionUser = {
  name: string,
  age: int,
}

type queryResult = {id: string, userData: queryUser}
type subscriptionResult = {id: string, userData: subscriptionUser}

let someMagicWayToGetData: unit => array<queryResult> = () => {
  let users: array<queryResult> = [
    {id: "1", userData: {name: "John", age: 35}},
    {id: "2", userData: {name: "Mary", age: 20}},
    {id: "3", userData: {name: "Kate", age: 50}},
  ]

  users
}

let someMagicWayToGetUpdates: unit => subscriptionResult = () => {
  let updatedUser = {
    id: "2",
    userData: {name: "Mary Jane", age: 21},
  }

  updatedUser
}

@react.component
let default = () => {
  let (users, setUsers) = React.useState(_ => someMagicWayToGetData())
  let updatedUser = someMagicWayToGetUpdates()

  React.useEffect1(() => {
    let newUsers = users->Js.Array2.map(user => {
      if user.id == updatedUser.id {
        {
          ...user,
          userData: {
            name: updatedUser.userData.name,
            age: updatedUser.userData.age,
          },
        }
      } else {
        user
      }
    })
    setUsers(_ => newUsers)

    None
  }, [updatedUser])

  <div>
    <ul>
      {users
      ->Js.Array2.map(({id, userData: {name, age}}) =>
        <li key=id> {`User: ${name}; Age: ${age->Js.Int.toString}`->React.string} </li>
      )
      ->React.array}
    </ul>
  </div>
}

It might not look like much of a hassle in this example but in the real world, a graphQL query result with lots of nested records may become a little bit annoying to deal with.

However, the ReScript docs do provide a good alternative for this situation, and a better way to handle this case is to represent the userData as a combination of a variant and record instead. This could look like this:

// .res
type user = {
  name: string,
  age: int,
}

type userData = {
  id: string,
  userData: user,
}

type result =
  | QueryResult(userData)
  | SubscriptionResult(userData)

let users: array<result> = [
  QueryResult({
    id: "1",
    userData: {name: "John", age: 35},
  }),
  QueryResult({
    id: "2",
    userData: {name: "Mary", age: 20},
  }),
  QueryResult({
    id: "3",
    userData: {name: "Kate", age: 50},
  }),
]

let updatedUser: result = SubscriptionResult({
  id: "2",
  userData: {name: "Mary Jane", age: 21},
})

let newUsers = users->Js.Array2.reduce((allUsers, user) => {
  switch (user, updatedUser) {
  | (
      QueryResult({id}), 
      SubscriptionResult({id: subscriptionId, userData: subscriptionUserData})
    ) if id == subscriptionId =>
    allUsers->Js.Array2.concat([
      QueryResult({
        id: id,
        userData: subscriptionUserData,
      }),
    ])
  | (QueryResult(user), _) => allUsers->Js.Array2.concat([QueryResult(user)])
  | (_, _) => allUsers
  }
}, [])

I chose the reduce method in the example above to have less cases to handle in the switch pattern but definitely an array map would also work. Only thing is that we'll have to handle a few more cases and it looks a little too verbose to me, even though that is the recommended way to go.

Wonderful, isn't it? This ended up looking a lot nicer than I was expecting. I can definitely see the benefits of using the nominally typed records instead of objects even for deeply nested data structures. By the way, if you actually prefer it, the structurally typed object exists in ReScript as well but it is more suitable to be used for binding to JavaScript objects.