Forem: Kevan Stannard

Naming files and directories in JavaScript projects

Kevan Stannard — Sat, 30 Apr 2022 06:49:39 +0000

A brief story of naming in a project

Getting started

File names start out easy:

app.js
utils.js

Directory names also often start out easy:

/components/
/utils/

Add a utility file with multiple functions

Let's add a utility file named "product utils". This is where things start to get hard.

product-utils.js
productUtils.js
ProductUtils.js

There is no particular guideline to follow here, so let's choose product-utils.js for now.

Add a utility file with a single function

Next we need to create a utility file that contains a single function named calculateSalary.

What to name this file?

And do we use a default export or not, since its just one function?

calculateSalary.js
calculate-salary.js

Here calculate-salary feels strange since the function is named calculateSalary, so lets go with calculateSalary.js.

import calculateSalary from "./calculateSalary";

However, now we have calculateSalary.js and product-utils.js. Should we rename product-utils.js to productUtils.js? That also feels strange since the product utils file contains many functions? Let's leave as-is for now.

Add a React component

Next we need to add a React component named ProductCard.

Easy, that file should be named ProductCard.js and the component is the default export.

However we're starting to get a mix of naming conventions now, which feels uncomfortable, but also kind of makes sense.

And what about when new people join the team? That's OK, we'll just teach them the convention, easy.

Export a utility function from a React component file

Our React component file has the component as the default export, so let's make the utility function in that file a regular non default export.

So we'll have:

import ProductCard, { makeProductPrice } from "components/ProductCard"

Our React component is growing

Our Product Card is getting a bit bigger, and need to be split into multiple files, so we'll need to move it to it's own directory now. What to name that directory?

How about /ProductCard/? That matches the component name and no need to change import statements, but is different from other directory names.

How about /product-card/? It's a nice generic name, but it means our imports "from ProductCard" will all need to change.

And what about /productCard/? Also a nice generic name, but no particular reason to use this for a React component.

Let's go with /ProductCard/.

Our Product utils are growing

Our product-utils.js file is growing now and need so be split into multple files, but we want to put them into a directory. What to name that directory?

How about /ProductUtils/? Nope, that's the convention for component directories.

How about /product-utils/ or /productUtils/? Time to roll some dice 🎲 🎲 🎲 and /productUtils/ is the winner 🎉.

New developer joins the team 🎉

A new person joins your team. Unfortunately nobody has time to explain the conventions. They sees variety of different naming strategies. They've used a completely different naming strategy in their previous project. They decide to apply their own conventions to the naming. Awesome 🙌.

A Possible Solution

Let's review what happened in this project.

In most cases the file or directory name was influenced by its content. We have a lot of different kinds of content, so we end up with many different kinds of names.

Ideally a good naming system should be intuitive, but most of all simple.

So maybe we can look at this from a different perspective, consider an abstraction for our files and directories:

Consider that all directories are the same kind of thing.
Consider that all files are the same kind of thing. Fortunately they are already the same kind of thing; a module.

File naming

First, if we consider that all files are modules, then we can base our naming on that.

Second, to keep things simple, consider that modules are containers and you only access the contents via the container, meaning no default exports.

You can choose any naming convention you prefer, providing all files use the same naming convention.

Directory naming

Directories are already containers.

So you may like to use the same naming convention as you did for files.

However what's important is that all directories use the same naming convention.

An Example

Considering the scenarios above, here is what your code may start to look like.

Using PascalCase for both directories and files.

import { App } from "App";

import {
  ProductCard,
  makeProductPrice
} from "Product/Components/ProductUI";

import {
  calculateSalary
} from "Payroll/SalaryCalculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "Product/ProductUtils";

Or using camelCase for both directories and files.

import { App } from "app";

import {
  ProductCard,
  makeProductPrice
} from "product/components/productUi";

import {
  calculateSalary
} from "payroll/salaryCalculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "product/productUtils";

Using kebab-case for both directories and files.

import { App } from "app";

import {
  ProductCard,
  makeProductPrice
} from "product/components/product-ui";

import {
  calculateSalary
} from "payroll/salary-calculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "product/product-utils";

Objectively it's a simple strategy that anyone can apply.

If you are also using ESLint or TypeScript, then you have an additional benefit where if you rename a function or component in a file, then you'll be prompted to rename your imports as well, keeping consistent naming everywhere and keeping them searchable.

This is a stylistic matter

This is not really a naming discussion per se, it's really a stylistic discussion which is subjective so it can frequently lead to bike shedding.

In matters of subjectivity if you're able to find a simple guideline, and then follow it independent of personal preferences it can eliminate a whole category of discussions, leaving time for more important matters.

Thinking in ReScript

Kevan Stannard — Thu, 12 Aug 2021 03:37:42 +0000

ReScript is a new language targeting JavaScript programmers. Particularly JavaScript programmers that have developed an interest in type safety with TypeScript or Flow.

ReScript feels very familiar due to having a JavaScript-like syntax, however there are some important differences. In this post I'll try provide an overview of some of the key differences that I hope will help you become productive more quickly when exploring ReScript.

Everything is an expression

In ReScript, everything is an expression that evaluates to a value, which includes if and switch statements.

For example, in JavaScript you could write something like:

let x;
if (someCondition) {
  x = 0;
} else {
  x = 1;
}

In ReScript this could be written as:

let x = if (someCondition) {
  0
} else {
  1
}

Functions don't need "return"

The last line that executes in a function becomes the return value, so an explicit return statement is not needed.

In JavaScript we might write:

const makePoint = (x, y) => {
  return { x: x, y: y };
};

And the ReScript equivalent:

type point = {x: int, y: int}

let makePoint = (x, y) => {
  {x: x, y: y}
}

"Function first" thinking

In object oriented programming it's common to see code like this:

const name = person.getName();

This uses a subject - function pattern. Here person is the subject and getName() is the function.

ReScript is a functional programming language which reverses the order to function - subject. The example above would be written as:

let name = getName(person)

Here's another example which passes some arguments to the function. In JavaScript we might write:

person.setName("First", "Last");
person.setId(1234);

In ReScript we would write:

setName(person, "First", "Last")
setId(person, 1234)

This is such a common pattern in ReScript that a special syntax exists to support it.

ReScript provides a "pipe first" operator -> which injects a value into the first argument of a function.

The setName() and setId code above could be re-written as:

person->setName("First", "Last")
person->setId(1234)

The pipe first concept so ubiquitous in ReScript that you'll likely see it in almost every ReScript code example.

Global modules

Each ReScript file is a module. There are two important concepts to understand.

First, if you create a ReScript file named Api.res and it contains a function fetchUsers() then ReScript automatically provides a global Api module that you can access from anywhere. To call the function fetchUsers() you would write:

Api.fetchUsers()

The second important concept to understand is that your directory structure has no impact on how you access modules. In other words your Api.res file can be anywhere in your project but you would always access it as a global module named Api.

A key consequence here is that every ReScript filename in a project must be unique. A common strategy is to use a naming convention to group related modules together, and generally keep your folder structure very shallow.

Here's an example folder/file structure:

/api
  /Api_Users.res
  /Api_Products.res
/components
  /Component_Button.res
  /Component_Tile.res
/pages
  /Page_Index.res
  /Page_Products.res

Type naming conventions

Type names in ReScript are always declared starting with a lower case letter, compared to TypeScript or Flow which uses capital letters.

You'll get a ReScript compiler error if you use the incorrect casing.

For example, in TypeScript:

type Person = {
  id: number;
  name: string;
}

And in ReScript:

type person = {
  id: int,
  name: string,
}

The type `t` naming convention

When looking at example code you may frequently see a type declaration named t. This is nothing special, it's simply a naming convention referring to the default type of a module.

For example:

module Person = {
  type t = {
    id: int,
    name: string,
  }
}

So when declaring a person you might write it as:

let person: Person.t = {
  id: 1,
  name: "Laura"
}

Variants

ReScript provides a concept called Variants.

These are similar to enums but are more powerful because they can also have arguments.

Here's an example:

// Declare a variant type
type choice = Yes | No | Maybe

// Declare a variable of that type, and set its value
let answer: choice = Yes

And then later we might use a switch statement on that variable:

switch answer {
  | Yes => Js.log("Answer is Yes")
  | No => Js.log("Answer is No")
  | Maybe => Js.log("Answer is Maybe")
}

Note some differences in syntax between a ReScript switch and a JavsScript switch.

Also, Js.log() is the equivalent of console.log()

This example declares our own variant, but ReScript comes with some useful built-in variants as well.

The most common built-in variant is called option which has the two values None and Some. In this case Some is special because it has an argument which we'll show in an example below.

The option type is used to represent having a value or not. In JavaScript terms, it's similar in concept to a variable having a value or being undefined.

Let's go though an example of using the option type.

First declare some variables:

let nobody = None
let somebody = Some("Mira")

Here nobody has the value None indicating the absence of a value.

And somebody has the value Some("Mira"). You can think of Some as a container holding the value Mira.

Next, let's define a function to print these variable values.

let printName = (name: option<string>) => {
  switch name {
    | None => Js.log("Mystery person")
    | Some(name) => Js.log("Person named " ++ name)
  }
}

Notice this function takes one argument name: option<string>. The type option<string> means that name will either contain the value None or the value Some with a string value.

In the switch statement we can unwrap the Some value to get access to its contents using | Some(name). Here the name variable is the string Mira.

And finally, we can call this function:

printName(nobody)
printName(somebody)

Which prints:

Mystery person
Person named Mira

Structural Types vs Nominal Types

TypeScript using structural types. This just means that it primarily looks at the shape of the types.

For example, in TypeScript we might write:

type Status = 
  | { type: "Idle"; }
  | { type: "Processing"; id: number; }

const value: Status = { type: "Processing", id: 123 };

When TypeScript is processing the types it looks at the shape of the types. If it contains a type property matching "Processing" and a number id property then it matches the "Processing" type here.

In ReScript this would be written using variants:

type status = 
  | Idle
  | Processing(int)

let value: status = Processing(123)

When ReScript is processing the types it uses nominal typing which means it looks at the name of the types.

Structural typing and nominal typing are different type systems which means that a type solution in TypeScript may require a different approach in ReScript.

Promises

Promises are such a common concept in modern web applications, it's worth briefly highlighting how the Promise syntax works in ReScript.

Note that here I'm using the rescript-promise library, which will soon become a part of the core language.

The promise functions I'll discuss here are:

Promise.then(promise, callback)
Promise.catch(promise, callback)
Promise.resolve()

Let's assume we have a function already written Api.getUsers() that returns a promise.

We could write our ReScript code as follows:

let promise = Api.getUsers()

let promise = Promise.then(promise, users => {
  Js.log(users) // Log the users
  Promise.resolve() // Indicate we are done
})

let promise = Promise.catch(promise, error => {
  Js.log(error) // Log the error
  Promise.resolve() // Indicate we are done
})

Notice the "function first" concept in use here; then and catch accept a promise as the first argument, and also return a promise. We can use the pipe first operator described above to improve this syntax as follows:

let promise =
  Api.getUsers()
  ->Promise.then(users => {
    Js.log(users) // Log the users
    Promise.resolve() // Indicate we are done
  })
  ->Promise.catch(error => {
    Js.log(error) // Log the error
    Promise.resolve() // Indicate we are done
  })

ReScript React

While discussing syntax, a brief mention about using React in ReScript.

React has type safe support in ReScript, including JSX syntax. There are a few syntax differences.

In JavaScript you might write a component like this:

function MyButton({ onClick, children }) {
  return (
    <button
      className="my-button"
      onClick={onClick}>
      {children}
    </button>
  )
}

The ReScript equivalent would be:

module MyButton = {
  @react.component
  let make = (
    ~onClick: ReactEvent.Mouse.t => unit,
    ~children: React.element
  ) => {
    <button
      className="my-button"
      onClick={onClick}>
      {children}
    </button>
  }
}

The JSX is identical.

The module wrapping the component is just standard boilerplate for React components.

The make function is a necessary part of the convention. All ReScript React components have this function.

Spend some time learning how to bind to external modules

Lastly, when working in TypeScript and installing an npm module you'll typically look for type definitions for that module.

One of the challenges of the TypeScript community is the effort required to create and maintain the type definitions of these modules.

ReScript encourages a different philosophy. While there are a number of bindings available, and for many packages they will be useful, there is no goal to create a comprehensive repository of bindings. Instead developers are encouraged to write their own bindings as they need them.

If you're coming from TypeScript this may seem surprising, but there are important reasons behind this recommendation (which are a bit detailed to go into in this post).

However, writing bindings are easy to learn and in reality take very little time.

For example, writing a binding to the date-fns library format function might look like this:

@module("date-fns/format")
external format: (Js.Date.t, string) => string = "default"

Breaking this down:

@module("date-fns/format") refers to the module.
external format: indicates it's an external function and names the function format within ReScript.
(Js.Date.t, string) => string is the function signature; it takes a Date type and a format string as arguments, and returns a string.
= "default" means use the default export from the module.

Once you get used to ReScript's binding syntax, it's quick to write and customise those bindings to your specific needs.

Conclusion

This post highlights some of the key differences I've found between JavaScript and ReScript.

However what I haven't highlighted here is how similar much of the syntax and thinking is. Once you feel comfortable with some of these differences above, then writing ReScript code feels just like writing JavaScript but with a slightly different mindset.

Lastly I've found that after spending some time with ReScript it's significantly influence and improved how I write type safe JavaScript.

I hope you found this post useful and that it helps in your exploration of ReScript.

Simple Server Side CSS with ReScript, React and Emotion

Kevan Stannard — Wed, 09 Dec 2020 09:09:21 +0000

Introduction

A simple introduction to using server side CSS with ReScript, React and Emotion CSS.

ReScript version: bs-platform@8.3.3

NPM Packages

First install the packages we need.

npm i @emotion/css @emotion/server react react-dom reason-react

This example is using the following versions:

@emotion/css@11.0.0
@emotion/server@11.0.0
react@17.0.1
react-dom@17.0.1
reason-react@0.9.1

Update bsconfig.json

Add reason-react to bs-dependencies:

"bs-dependencies": ["reason-react"],

Create the Emotion bindings

In a file Emotion.res add the following bindings.

module Css = {
  @bs.module("@emotion/css")
  external css: {..} => string = "css"
}

module Server = {
  @bs.module("@emotion/server")
  external renderStylesToString: string => string = "renderStylesToString"
}

Render a component with some styles

In a test file, create some styles to use:

module Styles = {
  open Emotion.Css
  let container = css({"border": "1px solid black"})
}

Create a React component that uses the styles:

module Container = {
  @react.component
  let make = (~children) => {
    <div className={Styles.container}> {children} </div>
  }
}

Render the component with Emotion styles:

let el = <Container> {ReasonReact.string("Hello")} </Container>


let html =
  el
  ->ReactDOMServer.renderToStaticMarkup
  ->Emotion.Server.renderStylesToString

Which generates the following code (reformatted here for readability):

<style data-emotion="css 1r0rfp">
  .css-1r0rfp{border:1px solid blue;}
</style>
<div class="css-1r0rfp">Hello</div>

Note

If you would prefer stronger type safety with Emotion, you may like to use bs-css.

Exploring ReScript Exception Handling

Kevan Stannard — Sat, 21 Nov 2020 06:13:47 +0000

Introduction

A brief exploration of some ReScript exception handling.

Hopefully this provides some useful examples of ReScript error handling.

ReScript version: bs-platform@8.3.3

Handling JavaScript exceptions thrown from JavaScript

Write a JS function that throws an error, and add a binding for it.

%%raw(`
function a() {
  throw new Error("An error occurred")
}
`)

@bs.val external a: unit => unit = "a"

Catch the error using try/catch.

try {
  a()
} catch {
| Js.Exn.Error(error) => {
    // error: Js.Exn.t
    Js.log(Js.Exn.name(error))
    Js.log(Js.Exn.message(error))
  }
}

Or, catch the error using switch and matching on the Js.Exn.Error type:

switch a() {
| exception Js.Exn.Error(error) => {
    // error: Js.Exn.t
    Js.log(Js.Exn.name(error))
    Js.log(Js.Exn.message(error))
  }
| () => ()
}

Or, catch the error using switch, matching on any exception type, and detect the Js.Exn.t type.

switch a() {
| exception error => {
    // error: exn
    let optError = Js.Exn.asJsExn(error)
    switch optError {
    | Some(error) => {
        // error: Js.Exn.t
        Js.log(Js.Exn.name(error))
        Js.log(Js.Exn.message(error))
      }
    | None => Js.log("Unknown error")
    }
  }
| () => ()
}

Handling JavaScript exceptions thrown from ReScript

Write a function that throws a JavaScript exception:

let b = (): unit => {
  // Equivalent to throw new Error("An error occurred")
  Js.Exn.raiseError("An error occurred")
}

Handling these errors is identical to when the exception is thrown from JavaScript.

Catch the error using try/catch:

try {
  b()
} catch {
| Js.Exn.Error(error) => {
    // error: Js.Exn.t
    Js.log(Js.Exn.name(error))
    Js.log(Js.Exn.message(error))
  }
}

Or, catch the error using switch and matching on the Js.Exn.Error type:

switch b() {
| exception Js.Exn.Error(error) => {
    Js.log(Js.Exn.name(error))
    Js.log(Js.Exn.message(error))
  }
| () => ()
}

Or, catch the error using switch, matching on any exception type, and detect the Js.Exn.t type.

switch b() {
| exception error => {
    // error: exn
    let optError = Js.Exn.asJsExn(error)
    switch optError {
    | Some(error) => {
        // error: Js.Exn.t
        Js.log(Js.Exn.name(error))
        Js.log(Js.Exn.message(error))
      }
    | None => Js.log("Unknown error")
    }
  }
| () => ()
}

Handling ReScript exceptions

Write a function that throws a custom ReScript exception:

exception MyException(string)

let c = (): unit => {
  raise(MyException("An error occurred"))
}

Handle using try/catch, matching on the exception:

try {
  c()
} catch {
| MyException(reason) => Js.log("MyException:" ++ reason)
}

Handle using switch, matching on the exception.

Notice the need for the exception keyword here.

switch c() {
| exception MyException(reason) => Js.log("MyException:" ++ reason)
| () => ()
}

Handle using switch and try detect if it's a JavaScript error:

switch c() {
| exception error => {
    // error: exn
    let optError: option<Js.Exn.t> = Js.Exn.asJsExn(error)
    switch optError {
    | Some(error) => {
        // error: Js.Exn.t
        Js.log(Js.Exn.name(error))
        Js.log(Js.Exn.message(error))
      }
    | None => Js.log("Not a JavaScript error")
    }
  }
| () => ()
}

This prints "Not a JavaScript error", as expected

Handling promise rejections from JavaScript

Write a JavaScript function that returns a rejected promise, and add a binding for it.

%%raw(`
function d() {
  return Promise.reject(new Error("An error occurred"))
}
`)

@bs.val external d: unit => Js.Promise.t<unit> = "d"

Catch the error and attempt to identify that it's a JavaScript error.

d()->Js.Promise.catch((error: Js.Promise.error) => {
  switch error {
  | exception error => {
      let optError: option<Js.Exn.t> = Js.Exn.asJsExn(error)
      switch optError {
      | Some(error) => {
          Js.log(Js.Exn.name(error))
          Js.log(Js.Exn.message(error))
        }
      | None => Js.log("Not a Js.Exn.t")
      }
    }
  | _ => Js.log("Not an exn")
  }
  Js.Promise.resolve()
}, _)

This prints:

Not an exn

Notes:

The JavaScript error is converted to type Js.Promise.error, which is not a member of the exn type.
The switch case exception error match does not occur, because the error is not an exn type.

Handling JavaScript promise rejections from ReScript

Write a function that returns a rejected promise containing a JavaScript error.

let e = (): Js.Promise.t<unit> => {
  Js.Promise.make((~resolve as _, ~reject as _) => {
    Js.Exn.raiseError("An error occurred")
  })
}

Note: Raising the error has the effect of rejecting the promise.

Catch the error and try detect that it's a JavaScript error.

e()->Js.Promise.catch((error: Js.Promise.error) => {
  switch error {
  | exception error => {
      let optError: option<Js.Exn.t> = Js.Exn.asJsExn(error)
      switch optError {
      | Some(error) => {
          Js.log(Js.Exn.name(error))
          Js.log(Js.Exn.message(error))
        }
      | None => Js.log("Not a Js.Exn.t")
      }
    }
  | _ => Js.log("Not an exn")
  }
  Js.Promise.resolve()
}, _)

This prints:

Not an exn

Notes:

The JavaScript error is converted to type Js.Promise.error, which is not a member of the exn type.
The switch case exception error match does not occur, because the error is not an exn type.

Handling ReScript promise rejections from ReScript

Write a function that returns a rejected promise containing a Rescript error.

exception MyException(string)

let f = (): Js.Promise.t<unit> => {
  Js.Promise.make((~resolve as _, ~reject as _) => {
    raise(MyException("An error occurred"))
  })
}

Note: Raising the error has the effect of rejecting the promise.

Catch the error and attempt to determine its type:

f()->Js.Promise.catch((error: Js.Promise.error) => {
  switch error {
  | exception error => {
      let optError: option<Js.Exn.t> = Js.Exn.asJsExn(error)
      switch optError {
      | Some(error) => {
          Js.log(Js.Exn.name(error))
          Js.log(Js.Exn.message(error))
        }
      | None => Js.log("Not a Js.Exn.t")
      }
    }
  | _ => Js.log("Not an exn")
  }
  Js.Promise.resolve()
}, _)

This prints:

Not an exn

Notes:

The ReScript error is converted to type Js.Promise.error, which is not a member of the exn type.
The switch case exception error match does not occur, because the error is not an exn type.

Handling ReScript promise rejections using the exn Failure variant.

The Failure(string) variant has an exn type.

Write a function that rejects a promise using a Failure:

let g = (): Js.Promise.t<unit> => {
  Js.Promise.make((~resolve as _, ~reject) => {
    reject(. Failure("An error occurred"))
  })
}

Catch the error and attempt to determine its type:

g()->Js.Promise.catch((error: Js.Promise.error) => {
  switch error {
  | exception error => {
      let optError: option<Js.Exn.t> = Js.Exn.asJsExn(error)
      switch optError {
      | Some(error) => {
          Js.log(Js.Exn.name(error))
          Js.log(Js.Exn.message(error))
        }
      | None => Js.log("Not a Js.Exn.t")
      }
    }
  | _ => Js.log("Not an exn")
  }
  Js.Promise.resolve()
}, _)

This prints:

Not an exn

Notes:

The Failure error is converted to type Js.Promise.error, which is not a member of the exn type.
The switch case exception error match does not occur, because the error is not an exn type.

References

Functors, Applicatives, And Monads In Pictures (In ReasonML)

Kevan Stannard — Sun, 12 Jan 2020 02:46:24 +0000

This is a translation of Functors, Applicatives, And Monads In Pictures from Haskell into ReasonML.

I take no credit for this work, and if you enjoy this post be sure to say thanks to Aditya Bhargava (@_egonschiele) the author of the original version.

Here's a simple value:

And we know how to apply a function to this value:

Simple enough. Let's extend this by saying that any value can be in a context. For now you can think of a context as a box that you can put a value in:

Now when you apply a function to this value, you'll get different results depending on the context. This is the idea that Functors, Applicatives, Monads, Arrows etc are all based on.

Let's create a Maybe data type that defines two related contexts:

module Maybe = {
  type t('a) =
    | Nothing
    | Just('a);
}

In a second we'll see how function application is different when something is a Just(a) versus a Nothing. First let's talk about Functors!

Functors

When a value is wrapped in a context, you can't apply a normal function to it:

This is where fmap comes in. fmap is from the street, fmap is hip to contexts. fmap knows how to apply functions to values that are wrapped in a context.

Suppose you want to apply (+3) to Just(2). We can implement fmap:

Maybe.fmap((+)(3), Just(2));
// Just(5)

Bam! fmap shows us how it's done!

Just what is a Functor, really?

Functor is a class of functions that define an fmap function.

In Haskell they are defined as a type class.

In ReasonML we don't have type classes yet, but they are being worked on in OCaml, and therefore ReasonML.

Here's the definition:

A Functor is any data type that defines how fmap applies to it. Here's how fmap works:

So we can do this:

Maybe.fmap((+)(3), Just(2));
// Just(5)

This specifies how fmap applies to Justs and Nothings:

Let's add fmap to our Maybe module:

let fmap = (f, m) => {
  switch (m) {
  | Nothing => Nothing
  | Just(a) => Just(f(a))
  };
};

Here's what is happening behind the scenes when we write Maybe.fmap((+)(3), Just(2));:

So then you're like, alright fmap, please apply (+3) to a Nothing?

Maybe.fmap((+)(3), Nothing)
// Nothing

Like Morpheus in the Matrix, fmap knows just what to do; you start with Nothing, and you end up with Nothing! fmap is zen. Now it makes sense why the Maybe data type exists. For example, here's how you work with a database record in a language without Maybe:

post = Post.find_by_id(1)
if post
  return post.title
else
  return nil
end

Let's create a simple Post module in ReasonML with these functions.

module Post = {
  type t = {
    id: int,
    title: "string,"
  };
  let make = (id, title) => {id, title};
  let fmap = (f, post) => f(post);
  let getPostTitle = post => post.title;
  let findPost = id => make(id, "Post #" ++ string_of_int(id));
};

Now we can write:

Post.(fmap(getPostTitle, findPost(1)));

If findPost returns a post, we will get the title with getPostTitle. If it returns Nothing, we will return Nothing! Pretty neat, huh?

In Haskell, <$> is the common infix version of fmap.

In ReasonML we can create an equivalent alias. Adding to our Post module:

let (<$>) = fmap;

So we can now write:

Post.(getPostTitle <$> findPost(1));

Here's another example: what happens when you apply a function to a list?

Lists can operate as functors too!

In ReasonML we can make use of the list map function:

List.map

Okay, okay, one last example: what happens when you apply a function to another function?

For this case we can define a Function module that has fmap:

module Function = {
  let fmap = (f, g, x) => f(g(x));
};

So we can now write:

Function.fmap((+)(3), (+)(1));

Here's a function:

Here's a function applied to another function:

The result is just another function!

let foo = Function.fmap((+)(3), (+)(2));
foo(10);
// 15

So functions can be Functors too!

When you use fmap on a function, you're just doing function composition!

Applicatives

Applicatives take it to the next level. With an applicative, our values are wrapped in a context, just like Functors:

But our functions are wrapped in a context too!

Yeah. Let that sink in. Applicatives don't kid around. They know how to apply a function wrapped in a context to a value wrapped in a context:

Applicatives define an apply function, also written as <*> in Haskell, which we can create an alias for in ReasonML.

Let's add the applicative functions to our Maybe module:

let apply = (mf, mv) => {
  switch (mv) {
  | Nothing => Nothing
  | Just(v) =>
    switch (mf) {
    | Nothing => Nothing
    | Just(f) => Just(f(v))
    }
  };
};

let (<*>) = apply;

Here's an example using them:

Maybe.(Just((+)(3)) <*> Just(2));
// Just(5)

Let's also define applicative functions for a list. We'll create a MyList module to avoid name clashes with the built in List module:

module MyList = {
  type apply('a, 'b) = (list('a => 'b), list('a)) => list('b);

  let apply: apply('a, 'b) =
    (fs, xs) => List.flatten(List.map(f => List.map(f, xs), fs));

  let (<*>) = apply;
};

Using <*> can lead to some interesting situations. For example:

let funList = [(*)(2), (+)(3)];
let valList = [1, 2, 3];
MyList.(funList <*> valList);
// [2, 4, 6, 4, 5, 6]

Here's something you can do with Applicatives that you can't do with Functors. How do you apply a function that takes two arguments to two wrapped values?

Maybe.((+) <$> Just(5));
// Just((+)(5))

Maybe.(Just((+)(5)) <$> Just(4));
// ERROR ??? WHAT DOES THIS EVEN MEAN WHY IS THE FUNCTION WRAPPED IN A JUST

Applicatives:

Maybe.((+) <$> Just(5));
// Just((+)(5))

Maybe.(Just((+)(5)) <*> Just(3));
// Just(8)

Applicative pushes Functor aside. "Big boys can use functions with any number of arguments," it says. "Armed with <$> and <*>, I can take any function that expects any number of unwrapped values. Then I pass it all wrapped values, and I get a wrapped value out! AHAHAHAHAH!"

Maybe.((*) <$> Just(5) <*> Just(3));

Monads

How to learn about Monads:

Get a PhD in computer science.
Throw it away because you don't need it for this section!

Monads add a new twist.

Functors apply a function to a wrapped value:

Applicatives apply a wrapped function to a wrapped value:

Monads apply a function that returns a wrapped value to a wrapped value.

Monads have a function bind, or the operator alias >>= to do this.

Let's see an example.

First, we'll need to add bind to our good ol' Maybe module:

let bind = (mv, f) => {
  switch (mv) {
  | Nothing => Nothing
  | Just(v) => f(v)
  };
};

let (>>=) = bind;

Suppose half is a function that only works on even numbers:

Let's write half in ReasonML (we'll also need to define even and odd functions):

/*
 Mutually recursive function
 https://ocaml.org/learn/tutorials/labels.html
 */
let rec even = x =>
  if (x <= 0) {
    true;
  } else {
    odd(x - 1);
  }
and odd = x =>
  if (x <= 0) {
    false;
  } else {
    even(x - 1);
  };

let half = x =>
  if (even(x)) {
    Maybe.Just(x / 2);
  } else {
    Nothing;
  };

What if we feed it a wrapped value?

We need to use >>= to shove our wrapped value into the function. Here's a photo of >>=:

Here's how it works:

Maybe.(Just(3) >>= half);
// Nothing

Maybe.(Just(4) >>= half);
// Just(2)

Maybe.(Nothing >>= half);
// Nothing

What's happening inside? Monad defines a bind (or >>=) function:

Let's make our Maybe into a monad by adding the bind functions.

let bind = (mv, f) => {
  switch (mv) {
  | Nothing => Nothing
  | Just(v) => f(v)
  };
};

let (>>=) = bind;

Here it is in action with a Just(3)!

And if you pass in a Nothing it's even simpler:

You can also chain these calls:

Maybe.(Just(20) >>= half >>= half >>= half);

Cool stuff! So now we have implemented Maybe to be a Functor, an Applicative, and a Monad.

Now let's mosey on over to another example and create an IO monad:

The IO monad exists in Haskell, but we will declare our own in ReasonML.

Specifically three functions. getLine takes no arguments and gets user input:

readFile takes a string (a filename) and returns that file's contents:

putStrLn takes a string and prints it:

Our IO module might look something like this (leaving out implementation details of the helper functions):

module IO = {
  type t = Js.Promise.t(string);

  type bind('a, 'b) = (t, string => t) => t;
  let bind: bind('a, 'b) = (pa, f) => pa |> Js.Promise.then_(a => f(a));

  let (>>=) = bind;

  type getLine = unit => t;
  let getLine = ...

  type readFile = string => t;
  let readFile = ...

  type putStrLn = string => t;
  let putStrLn = ...
};

If you're interested, the full source code is available.

All three functions take a regular value (or no value) and return a wrapped Promise value. We can chain all of these using >>=!

IO.(getLine() >>= readFile >>= putStrLn);

Aw yeah! Front row seats to the monad show!

Conclusion

A functor is a data type that implements the fmap function.
An applicative is a data type that implements the apply function.
A monad is a data type that implements the bind function.

The Maybe module in our examples implements all three, so it is a functor, an applicative, and a monad.

What is the difference between the three?

Functors: you apply a function to a wrapped value using fmap or <$>.

Applicatives: you apply a wrapped function to a wrapped value using apply or <*>.

Monads: you apply a function that returns a wrapped value, to a wrapped value using bind or >>=.

So, dear friend (I think we are friends by this point), I think we both agree that monads are easy and a SMART IDEA(tm). Now that you've wet your whistle on this guide, why not pull a Mel Gibson and grab the whole bottle. Check out LYAH's section on Monads. There's a lot of things I've glossed over because Miran does a great job going in-depth with this stuff.

If you feel there is something I could change to improve this translation to ReasonML please let me know.

Thanks again to Aditya Bhargava for writing the original version of this post ❤️

Forem: Kevan Stannard

Naming files and directories in JavaScript projects

A brief story of naming in a project

Getting started

Add a utility file with multiple functions

Add a utility file with a single function

Add a React component

Export a utility function from a React component file

Our React component is growing

Our Product utils are growing

New developer joins the team 🎉

A Possible Solution

File naming

Directory naming

An Example

This is a stylistic matter

Thinking in ReScript

Everything is an expression

Functions don't need "return"

"Function first" thinking

Global modules

Type naming conventions

The type t naming convention

Variants

Structural Types vs Nominal Types

Promises

ReScript React

Spend some time learning how to bind to external modules

Conclusion

Simple Server Side CSS with ReScript, React and Emotion

Introduction

NPM Packages

Update bsconfig.json

Create the Emotion bindings

Render a component with some styles

Note

Exploring ReScript Exception Handling

Introduction

Handling JavaScript exceptions thrown from JavaScript

Handling JavaScript exceptions thrown from ReScript

Handling ReScript exceptions

Handling promise rejections from JavaScript

Handling JavaScript promise rejections from ReScript

Handling ReScript promise rejections from ReScript

Handling ReScript promise rejections using the exn Failure variant.

References

Functors, Applicatives, And Monads In Pictures (In ReasonML)

Functors

Just what is a Functor, really?

Applicatives

Monads

Conclusion

The type `t` naming convention