DEV Community: Patrick Ecker

ReScript records, NextJS, undefined and getStaticProps

Patrick Ecker — Sat, 15 May 2021 12:46:07 +0000

NextJS, a pretty solid framework for building React based websites and web-applications, offers a nice feature for generating static pages from e.g. fetched endpoint data via the getStaticProps API, which looks something like this in JavaScript:

export default function MyComponent(props) {
  // props provided by getStaticProps
}

export async function getStaticProps(context) {
  // do your async stuff here to fetch data
  return {
    props: {}, // pass the data as props to your component
  }
}

There is an important restriction though: The value defined as props must be JSON serializable. JavaScript objects usually resemble JSON data by default, so oftentimes this isn't really an issue. There are still some subtle cases where confusing errors pop up, so this article will describe a typical error scenario a ReScript developer will most likely face when working with NextJS.

The JSON Issue w/ undefined values

Let's assume we want to use the getStaticProps API and return some props based on a ReScript record:

// ReScript code

type recipe = {
  diet_kind: option<string>
};

let getStaticProps = (_ctx) => {
  let recipe = {
    diet_kind: None
  };

  //last statement is the return value
    {
      "props": recipe
    }
};

As soon as you compile this code and boot up the Next development server, you will get an error similar to this:

Error: Error serializing `.diet_kind` returned from `getStaticProps` in "/".

ReScript: `undefined` cannot be serialized as JSON. Please use `null` or omit this value all together.

Let's explain what's going on here.

First of all, a ReScript record will compile to a JS object with the same object structure. The diet_kind defined as option<string> may be one of two different values, which compile to the following JS:

Some("My Diet Name") will be compiled to "My Diet Name"
None will be compiled to undefined

As soon as I construct a recipe value { diet_kind: None }, it will be compiled to { diet_kind: undefined }, which is not a well defined JSON value.

There are two solutions on how to tackle this (as already noted by the error message above), and I'd like to show how to do this specifically in ReScript.

Use `null` instead of `undefined`

Instead of using option, we need to fall back to the JS specific interop type Js.Nullable.t:

type recipe = {
  diet_kind: Js.Nullable.t(string)
};

let myRecipe = {
  diet_kind: Js.Nullable.null
};

This will compile myRecipe into { diet_kind: null } in JS, which now is valid JSON. This solution is functional but somewhat impractical. Pure ReScript code doesn't have any null values and uses options everywhere for expressing existing / non-existing values. So every time we want to use a Next based API, we'd need to map and convert those options to nullable types back and forth.

For example, on the component side, we'd now need to handle the recipe value like this:

type props = recipe;

// Interop React component without react.component ppx
let default = (props: props): React.element => {
     // Convert diet_kind back to option
   let diet_kind = Js.Nullable.toOption(props.diet_kind);

   switch(diet_kind) {
     | Some(kind) => Js.log2("here is the kind: ", kind)
     | None => Js.log("No kind found")
   };

   <div/>;
};

This doesn't really feel like a very accessible approach, so I was curious if there are other ways to do it. The alternative is a little bit more hacky and unsafe though.

Omit all `undefined` values all together

The other approach would be to completely strip every object attribute that is set to undefined. This is actually hard to do for pure ReScript code, since the JS object representation of a record will always maintain the full structure with all its attributes attached, even if they are undefined.

That's why we'll need to go the JS interoperability route and use unsafe code to strip away those values. getStaticProps is only used during build time, so I think it's okay to use the JSON.stringify / JSON.parse functions to do the dirty work for us. As a reference, that's what we want to do in JS:

const v = { a: undefined, b: "test" };
const json = JSON.parse(JSON.stringify(v));

// json = { b: "test" }

As you can see, JSON.stringify drops all the values that are not part of the JSON definition. It's also a quite generic approach, since it strips all non-JSON values recursively, and can be applied to any json data object or array.

Before proceeding to the interesting part, here's a word of caution: In ReScript it's often a trade-off between type-safety and convenience. The solutions proposed here are unsafe by design for practical reasons. If you are striving for a 100% type-safe codebase, this approach is not for you.

---------------------UNSAFE PART FROM HERE ---------------------

Somewhat unsafe `undefined` stripping for ReScript records

Let's get back to our recipe example with option values. We will start out putting everything in a Recipe module so we can easily add related functions for our recipe data type t:

module Recipe = {
  type t = {
      title: string,
      diet_kind: option<string>
    };
}

Now let's define an independent function stripUndefined for the stringify / parse logic:

let stripUndefined = (json: Js.Json.t): Js.Json.t => {
  open Js.Json
  stringify(json)->parseExn
};

Since stripUndefined defines Js.Json.t values as its input and output, we need to add very unsafe external functions to our Recipe module:

module Recipe = {
  type t = {
    title: string,
      diet_kind: option<string>,
    };
    external fromJson: Js.Json.t => t = "%identity";
    external toJson: t => Js.Json.t = "%identity";
}

let stripUndefined = (json: Js.Json.t): Js.Json.t => {
  Js.Json.(stringify(json)->parseExn);
};

Note: As mentioned before, a ReScript record is represented as a JS object during runtime (so basically a JSON structure, if we only use JSON related values inside). With the fromJson and toJson identity externals, we are lying to the compiler that our type Recipe.t is equivalent to a Js.Json.t, so this is completely unsafe and it should be made sure that your type t really is handling values that are Json compliant (except undefined values of course). That means you should only use values such as string, float, object, array, and of course option (but no other values such as functions, otherwise they will be stripped as well).

Now let's combine all these things together to see it in action:

let myRecipe = {
  Recipe.title: "My Recipe",
  diet_kind: None
};

let default = (props: recipe) => {
  // No convertion from Js.Nullable needed anymore!
  switch(diet_kind) {
   | Some(kind) => Js.log2("here is the kind: ", kind)
   | None => Js.log("No kind found")
  };
    <div/>;
};

// Simulating the getStaticProps Api without any types here
let getStaticProps = (_ctx) => {
    open Recipe;
    // Clear our recipe from any undefined values before returning
    let props = toJson(myRecipe)->stripUndefined->fromJson;
    {
      "props": props
    }
};

That's it! After compiling and rerunning the code, the error is gone and our app works as expected.

Note: If you are handling an array(recipe), you can apply the same technique to the whole array in an Js.Json.t as well, since stringify / parse can act on json objects and json arrays.

It's also noteworthy that the last fromJson call is not needed when we are not enforcing any type shapes for the props value. In my typical ReScript / Next projects (see my rescript-nextjs-template ReScript template) I enforce the props type across getStaticProps and my React components.

(As long as you are making sure that Recipe.t contains JSON compliant values, it's also perfectly safe to continue using the modified record returned by toJson(myRecipe)->stripUndefined->fromJson in ReScript code, since all runtime operations on an option value will continue to work as intended.)

Conclusion

We highlighted the problems with NextJS' getStaticProps props value limitations and why this is relevant for writing idiomatic ReScript code that interops well within the framework.

We showed how we can tackle the JSON serialization problem, either by converting option to Nullable.t, or do unsafe undefined value stripping using JSON.stringify / JSON.parse. We also dabbled a little bit into the world of compile type / runtime value representation of ReScript records.

If you are interested in more ReSCript related content, make sure to follow me on Twitter and stay tuned for more practical insights!

Tagged Unions and ReScript Variants

Patrick Ecker — Sat, 15 May 2021 10:57:42 +0000

In JavaScript there are many situations where we want to express certain shapes of an object based on the conditions of its attributes, e.g.

// Plain JS - Typical Redux Action types
if(action.type === "addUser") {
  const user = action.user;
  createUser(user);
}

if(action.type === "removeUser") {
  const userId = action.userId;
  removeUser(userId);
}

You can find this pattern in many other scenarios, such as representing the method of a request (req.method === "POST" -> req.body != null), representing UI state (userReq.isLoading -> userReq.name == undefined), or even error state (result.err != null -> result.msg != undefined). The shape of the object is different, depending on the state of attributes defined by a specific ruleset.

In TypeScript, we'd use a so called Discriminated Union Type (Tagged Unions) to be able to encode the conditional object shape within the type itself. For our previous example, we would define a type for a user action like this:

// TypeScript

type AddUser = {
  type: "addUser",
  user: User
};

type RemoveUser = {
  type: "removeUser",
  userId: string
};

type UserAction = AddUser | RemoveUser;

As a ReScript developer, you probably had troubles writing FFI (interop) code to represent such Tagged Unions. How are we able to handle these data structures without changing the JS representation?

Usually we'd define a variant for representing different shapes of data, but unfortunately variants do not compile to the same shape of user defined Tagged Unions.

This article demonstrates in a practical example how we'd map data structures for RichText data (designed as a Tagged Union) to ReScript variants.

Important: We'll only discuss mapping ReScript variants to immutable JS values, since mutations to the original values will eventually not be reflected in the variants at runtime. Handling mutable data requires a different strategy which is not covered in this post.

Background on the Use-Case

This post is based on a a real-world use-case where I needed to represent Storyblok CMS' RichText data structures within ReScript but couldn't find any proper documentation on how to do this.

I tried to keep the data model simple to only capture the basic concepts. For a more thorough side-by-side implementation of a TS / ReScript Storyblok RichText model, including rendering logic, you can check this repository later on.

Design RichText Data with TypeScript

To kick things off, we'll define some basic RichText elements we want to be able to represent: Text, Paragraph and Doc. These will be defined as a Tagged Union called RichText:

interface Text {
  type: "text";
  text: string;
}

interface Paragraph {
  type: "paragraph";
  content: RichText[];
}

interface Doc {
  type: "doc";
  content: RichText[];
}

export type RichText =
  | Doc
  | Text
  | Paragraph;

Each case of the RichText type listed above has one common attribute type, which helps the type system to differentiate the shape of a given value by checking value.type, e.g. via an if or switch statement. Let's see that in action:

// Recursively iterate through the RichText tree and print all Text.text contents
function printTexts(input: RichText) {
  switch(input.type) { 
    case "doc": 
    case "paragraph":
      return input.content.forEach(printTexts);
    case "text": {
        console.log(input.text);
        break;
      }
  };
}

const input: RichText =   {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [{type: "text", "text": "text 1"}]
      },
      {
        type: "paragraph",
        content: [{type: "text", "text": "text 2"}]
      }
    ]
  };

printTexts(input);

TypeScript will be able to infer the relevant data for each case correctly most of the time.

There's a few things I personally dislike in TS when handling Tagged Unions (especially via switch statements):

switch statements are not expressions (can't return a value without wrapping a function around it)
cases need extra braces to prevent variable hoisting and need a break / return statement to prevent case fall-through
Without any return statements or other trickery, TS apparently does not do any exhaustive checks within switches
Discriminated union types are really noisy in type space code and I often had a hard time navigating / writing types, even in smaller codebases
switch statements can only match one value at once. More complex discriminants / multiple discriminants are impractical
object types are structurally typed and TS will not always automatically infer the type correctly without type annotation (as seen in the const input declaration above). Error messages are generally harder to read because of that.

... but these are all just opinions.

In the next step, let's discover how we'd represent that data model in ReScript.

Representing Tagged Unions in ReScript

We now have an existing RichText representation, and we want to write ReScript FFI (interop) code to represent the same data without changing the JS parts.

ReScript's type system can't express Tagged Unions in the same way as TypeScript does, so let's take a step back:

The core idea of Tagged Unions is to express a "A or B or C" relation and to access different data, depending on what branch we are currently handling. This is exactly what ReScript Variants are made for.

So let's design the previous example with the help of variants. We will start defining our type model within our RichText.res module:

// RichText.res

module Text = {
  type t = {text: string};
};

type t;

type case =
  | Doc(array<t>)
  | Text(Text.t)
  | Paragraph(array<t>)
  | Unknown(t);

As you can see, there's no much going on here. Let's go through it really quick:

We defined a submodule Text, with a type t representing a Text RichText element. We refer to this type via Text.t.
type t; is representing our actual Tagged Union RichText element. It doesn't have any concrete shape, which makes it an "abstract type". We'll also call this type RichText.t later on.
Lastly we defined our case variant, describing all the different cases as defined by the Tagged Union in TS. Note how we also added an Unknown(t) case, to be able to represent malformed / unknown RichText elements as well

With these types we can fully represent our data model, but we still need to classify incoming JS data to our specific cases. Just for a quick reminder: The RichText.t type internally represents a JS object with following shape:

{
   type: string,
   content?: ..., // exists if type = "doc" | "paragraph"
   text?: ...,    // exists if type = "text"
}

Let's add some more functionality to reflect on that logic.

Classifying RichText.t data

We will extend our RichText.res module with the following functions:

// RichText.res

module Text = {
  type t = {text: string};
};

type t;

type case =
  | Doc(array<t>)
  | Text(Text.t)
  | Paragraph(array<t>)
  | Unknown(t);

let getType: t => string = %raw(`
    function(value) {
      if(typeof value === "object" && value.type != null) {
        return value.type;
      }
      return "unknown";
    }`)

let getContent: t => array<t> = %raw(`
    function(value) {
      if(typeof value === "object" && value.content != null) 
      {
        return value.content;
      }
      return [];
    }`)

let classify = (v: t): case =>
  switch v->getType {
  | "doc" => Doc(v->getContent)
  | "text" => Text(v->Obj.magic)
  | "paragraph" => Paragraph(v->getContent)
  | "unknown"
  | _ => Unknown(v)
  };

The code above shows everything we need to handle incoming RichText.t values.

Since we are internally handling a JS object and needed access to the type and content attributes, we defined two unsafe raw functions getType and getContent. Both functions receive a RichText.t value to extract the appropriate attribute (while making sure our data is correctly shaped, otherwise we will end up with an Unknown value).

Now with those two functions in place, we are able to define the classify function to refine our RichText.t into case values. It first retrieves the type of the input v and returns the appropriate variant constructor (with the correct payload). Since this code uses raw functions and relies on Obj.magic, it is considered to be unsafe code. For this particular scenario, the unsafe code is at least isolated in the RichText module (make sure to write tests!).

Note: You might have noticed that we store the content part of a "doc" object directly in the Doc(array<t>) variant constructor. Since we know that our Doc model does not contain any other information, we went ahead and made our model simpler instead.

Using the RichText module

Now with the implementation in place, let's showcase how we'd iterate over RichText data and print every Text content within all paragraphs:

// MyApp.res

// We simulate some JS object coming into our system
// ready to be parsed
let input: RichText.t = %raw(`
  {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [{type: "text", "text": "text 1"}]
      },
      {
        type: "paragraph",
        content: [{type: "text", "text": "text 2"}]
      }
    ]
  }`)

// keyword rec means that this function is recursive
let rec printTexts = (input: RichText.t) => {
  switch (RichText.classify(input)) {
  | Doc(content)
  | Paragraph(content) => Belt.Array.forEach(content, printTexts)
  | Text({text}) => Js.log(text)
  | Unknown(value) => Js.log2("Unknown value found: ", value)
  };
};

printTexts(input);

As you can see in the printTexts function above, we call the function RichText.classify on the input parameter, for the Doc | Paragraph branch we can safely unify the content payload (which both are of type array<RichText.t>) and recursively call the printTexts function again. In case of a Text element, we can deeply access the record attribute RichText.Text.text, and for every other Unknown case, we directly log the value of type RichText.t, which is the original JS object (Js.log is able to log any value, no matter which type).

In contrast to the TS switch statement, let's talk about the control flow structures here (namely the ReScript switch statement):

A switch is an expression. The last statement of each branch is the return value. You can even assign it to a binding (let myValue = switch("test") {...})
Each branch must return the same type (forces simpler designs)

The most important part is, that we have the full power of Pattern Matching, which can be performed on any ReScript data structure (numbers, records, variants, tuples,...). Here is just one small example:

switch (RichText.classify(input)) {
| Doc([]) => Js.log("This document is empty")
| Doc(content) => Belt.Array.forEach(content, printTexts)
| Text({text: "text 1"}) => Js.log("We ignore 'text 1'")
| Text({text}) => Js.log("Text we accept: " ++ text)
| _ => () /* "Do nothing" */
};

Doc([]): "Match on all Doc elements with 0 elements in its content
Doc(content): "For every other content (> 0) do the following..."
Text({text: "text 1"}): "Match on all Text elements where element.text = 'text 1'"
Text({text}): "For every other Text element with a different text do the following ..."
_ => (): "For everything else _ do nothing ()"

Extending the RichText data model

Whenever we want to extend our data model, we just add a new variant constructor to our case variant, and add a new pattern match within our classify function. E.g.

type case =
  | Doc(array<t>)
  | Text(Text.t)
  | Paragraph(array<t>)
  | BulletList(array<t>) // <-- add a constructor here!
  | Unknown(t);

let classify = (v: t): case =>
  switch (v->getType) {
  | "doc" => Doc(v->getContent)
  | "text" => Text(v->Obj.magic)
  | "paragraph" => Paragraph(v->getContent)
  | "bullet_list" => BulletList(v->getContent) // <-- add a case here!
  | "unknown"
  | _ => Unknown(v)
  };

It's that easy.

Note on Runtime Overhead

It's worth noting that our RichText module approach introduces following overhead:

Variants with payloads are represented as arrays, so every classify will create a new array with the variant content inside (also the extra classify call.
Our getContent and getType function does extra checks on the structure of each input value.

Please note that the ReScript Compiler team is currently investigating in a better runtime representation for variants to be able to map more seamlessly to JS and improve performance in the future.

Note on Recursion

I am aware that the examples used in this article are not stack-safe. This means that you can practically blow your call stack when there are enough deep recursive calls. There's ways to optimize the examples to be stack-safe, just be aware that I tried to keep it simple.

Conclusion

We started out by defining a very simple version of (Storyblok based) RichText data structures in TypeScript and highlighted some aspects of Discriminated Unions / Tagged Unions.

Later on we created FFI code wrapping variants around the same RichText data structures. We created a RichText.res module, defined a data model with a cases variant and a classify function to be able to parse incoming data. We used pattern matching to access the data in a very ergonomic way.

We only scratched the surface here. I hope this article gave you an idea on how to design your own ReScript modules to tackle similar problems!

In case you are interested in more ReScript related topics, make sure to follow me on twitter.

Special thanks to hesxenon and cristianoc for the extensive technical reviews and discussions!

A Quick Look on my ReasonML Workflow with VSCode

Patrick Ecker — Thu, 05 Mar 2020 08:10:23 +0000

Update, 10.9.2018: This article has migrated to the newly recommended VSCode plugin by Jared Forsyth.

The version of my toolchain on this date:

Reason 3.3.3 @ e10fa53
BuckleScript 4.0.5

Note: This article is aimed for beginners without any knowledge about Reason.

In April 2018, Nik Graf and I were giving workshops at React-Finland and got some really good impressions on how newcomers learn to code in Reason for their very first time.

The tools in the Reason ecosystem are quite useful to learn the language itself, so I try to show you how I work on Reason code inside VSCode and the terminal, to make it easier for you to get started.

Luckily since August 2018, the installation steps got way easier with the new VSCode plugin done by Jared Forsyth.

What’s the major difference to the existing ocaml / reason plugin? You can read the motivation behind this here.

This is also the only plugin which works on Windows without any hacks, therefore makes it the official recommended way of developing Reason.

Step 1— Installing the VSCode Reason Plugin

Go to the extension tab and search the marketplace for a plugin called reason-vscodeby Jared Forsyth, press the install button and reload your VSCode instance.

Now your editor should be able to interact with Reason code. After an initial build with BuckleScript, you should be able to see type information on cursor hover, inferred types and also basic type errors. Also you will notice that *.re will have correct syntax highlighting.

Step 2— Let’s try out the setup

For the next steps, let’s check out a Reason / BuckleScript based project. For convenience, we will use the same repository I use for my workshops:

https://github.com/ryyppy/reason-workshop

Clone the repository and run npm install to install all necessary dependencies. Since bs-platform is defined as a devDependency, all the tools you need to compile Reason to JavaScript will also be installed inside your node_modules directory.

We already defined some convenience scripts inside package.json to easily interact with the BuckleScript compiler:

"scripts": {
  "bs:clean": "bsb -clean-world",
  "bs:build": "bsb -make-world",
  "bs:watch": "bsb -make-world -w"
}

So by running npm run bs:watch you will start the BuckleScript compiler in watch mode, actively recompiling Reason files (*.re) on each change. Since BuckleScript also offers better error messages than Merlin, let’s use the watch command inside the VSCode terminal itself:

In the screenshot above, you’ll see BuckleScript up and running in the bottom terminal pane. Whenever there is a type error in our code (after saving a file), the compiler will show nice error messages for troubleshooting:

For me, I find it much easier to have BuckleScript running inside my VSCode, since I will never be required to switch from my IDE to my terminal. As soon as I adapted this workflow, I realized that my feedback loop was much quicker and I got a much more immersive coding experience.

Of course, there are many other tools which need to be run in the background, like webpack or a development server. I usually keep them in my separate terminal, because in most cases, errors only happen whenever BuckleScript doesn’t fully compile.

Last Quick Tip: Reformatting

Whenever you are editing a *.re file, you can run Shift-Option-F to reformat the editor buffer.

To try this, copy this code snippet in one of the reason files inside thesrc directory and hit the Shift-Option-F hotkey:

let addAndStringify = (
  a,
  b) => {
let c = a + b;

string_of_int(c);

};

The code should now be correctly formatted.

That’s it! After following these 2steps, you are now able to work on Reason code in VSCode.

If you have any problems with your setup, make sure to ask questions on our Reason Discord #editorsupport channel.

For more blog articles & news about Reason and other web related programming languages, follow me on Twitter.

DEV Community: Patrick Ecker

ReScript records, NextJS, undefined and getStaticProps

The JSON Issue w/ undefined values

Use null instead of undefined

Omit all undefined values all together

Somewhat unsafe undefined stripping for ReScript records

Conclusion

Tagged Unions and ReScript Variants

Background on the Use-Case

Design RichText Data with TypeScript

Representing Tagged Unions in ReScript

Classifying RichText.t data

Using the RichText module

Extending the RichText data model

Note on Runtime Overhead

Note on Recursion

Conclusion

Further Reading

A Quick Look on my ReasonML Workflow with VSCode

Step 1— Installing the VSCode Reason Plugin

Step 2— Let’s try out the setup

Last Quick Tip: Reformatting

Use `null` instead of `undefined`

Omit all `undefined` values all together

Somewhat unsafe `undefined` stripping for ReScript records