So, I thought it would a good idea to put down some thoughts and examples of testing pages when using TanStack Router.

Simple cases

Sometimes you are testing a component that requries the Router to be available in context. The component may not do anything particularly interesting with the router, maybe it just needs the location current location for something:

import { useLocation, useRouter, type LinkProps } from "@tanstack/react-router"

// Within a component
const router = useRouter()
const { pathname } = useLocation()

In this case, you may just get away with a blank router provider, which is pretty simple to create:

import type { PropsWithChildren } from "react"
import {
  createRootRoute,
  createRoute,
  createRouter,
  RouterProvider,
} from "@tanstack/react-router"

export const EmptyRouterProvider = (props: PropsWithChildren) => {
  const rootRoute = createRootRoute({
    component: () => props.children,
  })

  const router = createRouter({
    routeTree: rootRoute.addChildren([
      createRoute({
        path: "*",
        component: () => props.children,
        getParentRoute: () => rootRoute,
      }),
    ]),
  })

  return <RouterProvider router={router} />
}

Then in a test just wrap it in an act

const view = await act(() =>
      render(
        <div>
          <EmptyRouterProvider>
            <MyComponentWithLocation />
          </EmptyRouterProvider>
        </div>
      )
    )

Alternatively avoid using router hooks in Components

Typically, I would try to avoid the above in tests. It's not that it's necessarily wrong, but I prefer components to have the data required passed down to them and leave any router or loading logic up to the router. This leds to having a src/routes folder with all the routes and /src/pages for the pages rendered. The RouteComponent within a route would be used for calling all the router or TanStack Query hooks.

For example, the simple test above could've been simplified if the component took a location or path prop. The route can make the useLocation call and pass the required data to a Page

This style results in simple components that just take data (or if needs be, QueryResult<MyData>) or generic functions; which are very easy to test. This means no wrapping in QueryProviders, mocking fetch, etc. when testing the page.

This leads to all the loading and routing taking place in the route files, so we need to test the route code thoroughly. Treating those tests more like integration tests, then supplementing those tests with Playwright, Cypress, etc. So how do we write such a test?

Testing Routes

This requires a little more setup; thankfully, you only need to do it once. If you don't use TanStack Query then you could simplify all this.

The following snippet may be a little complex, but it sets up a router using your projects generated routes file with a QueryClient:

import { QueryClient } from "@tanstack/react-query"
import {
  createMemoryHistory,
  createRouter,
  RouterProvider,
} from "@tanstack/react-router"
import { render } from "@testing-library/react"

import { QueryProvider } from "~/integrations/tanstack/root-provider"
import { routeTree } from "~/route-tree.gen"

export function makeRouter({
  initialRoute,
  contextData = defaultContext, // Your routers context, this could be session info for example
  queryClient = makeTestQueryClient(),
}: {
  initialRoute: string
  contextData?: YourRouterContext
  queryClient?: QueryClient
}) {
  const memoryHistory = createMemoryHistory({
    initialEntries: [initialRoute],
    initialIndex: 0,
  })

  const router = createRouter({
    defaultPendingMinMs: 0,
    history: memoryHistory,
    routeTree: routeTree,
    context: {
      queryClient: queryClient,
      contextData: contextData,
    },
  })

  return router
}

export type TestRouter = ReturnType<typeof makeRouter>

export async function navigateToRoute(
  router: TestRouter,
  navigateProps: Parameters<TestRouter["navigate"]>[0]
) {
  await act(() => router.navigate(navigateProps))
}

export const makeTestQueryClient = () =>
  new QueryClient({
    defaultOptions: { queries: { retry: false } },
  })

export async function renderWithRouter({
  initialRoute,
  session = emptySession,
  queryClient = makeTestQueryClient(),
}: {
  initialRoute: string
  context?: RouterContext // Your router's context!
  queryClient?: QueryClient
}) {
  const router = makeRouter({
    initialRoute,
    session,
    queryClient,
  })

  const app = render(
    <QueryProvider client={queryClient}>
      <RouterProvider<typeof router> router={router} />
    </QueryProvider>
  )

  await navigateToRoute(router, {
    to: initialRoute,
  })

  return {
    router,
    app,
  }
}

What you really need to care about in that is renderWithRouter which allows you to test your routes easily.

A quick example

Lets imagine you have a route that prefetches data as part of it's preload then uses that data later. How do we test this given the above?

// This is just a helper for mocking fetch using vitest
const fetchMock = setupFetchMock() 
// Lets just
fetchMock.mockResolvedValue({
    ok: true,
    status: 200,
    json: async () => await {the_data: "is good"},
} as Response )

// Lets create our component
// We can use a real path to test search validation/etc
const { app, router } = await renderWithRouter({
	initialRoute: "/my-page?query=something",
})

// You can test the fetch call was made
expect(fetchMock).toHaveBeenCalledWith(
	expect.stringContaining(
		"/my-api/some-network-call?user-query=something"
	),
    expect.objectContaining({
        method: "GET",
        headers: { Accept: "application/json" },
  	})
)

// You test using `app` like you would in RTL. I'd only do
// minimal checks here and test the page individually:
const heading = await waitFor(() =>
    app.getByRole("heading", {
    name: "The Page",
  })
)
expect(heading).toBeInTheDocument()

// Or test the router
expect(router.state.location.pathname).toBe("/my-page")

So there you go. You are directly testing the route component here using the actual router. From here you test the page if you want via app, the router by accessing it, and the fetch calls (or use MSW if that's your thing)

Likewise, you get to provide the initial context. So if you use the router context for holding an auth session you can provide a fake one when testing authenticated routes, and test your navigation when no session is provided.

As mentioned prior, I prefer to split data/routing from the page itself. Stick to testing routes, context related functions, and data loading in these tests. Then use that to create a page where you can test interactivity.

From working with Scala I am used to creating Value Classes, which can be compared to Haskell's newtype. These constructs allow the developer to express greater levels of type information and abstraction in their code, with little or no runtime performance penalty. It's possible to achieve the same effect in ReasonML with singleton variants.

What is a Value Class?

A value class is a simple wrapper around a primitive type that gives you more control over the input and output of functions. This has a number of benefits, such as restricting construction to validated values or simply aiding with passing around many parameters into a function.

These are very easy to construct in Scala by extending AnyVal

case class Name(value: String) extends AnyVal

Whilst it looks like there is an additional overhead here; after all, the String has been boxed inside a class which you would expect would need to be instantiated each time – in the JVM the wrapping class is removed after compilation. So there should not be a performance cost when wrapping types in this manner. There is just one minor issue, if you wish to access the underlying String then you have to manually access it:

val name = Name("Cat")

println("The name is: " + name.value)

You can achieve something similar in ReasonML by boxing the type and I'll demonstrate it later.

Why would you want to do this?

Essentially to make your code more descriptive and to prevent mistakes. This is probably best illustrated with examples. So let us imagine you have a function type signature for a simple function to create a person:

let makePerson: (string, string, string, int) => unit;

As simple as the definition is, it may leave you wondering about a number of things: how you know distinguish between the meaning of these fields? Which holds the first name and which the surname? Just what exactly is that integer? Why are there three string parameters?

Sure, you could probably work those questions out by looking at the output type, and yes, I deliberately left it as unit to make life hard. Still, this function could be storing its output in a database or mutable dictionary somewhere and unit could be an acceptable output type.

So in order to answer that question, you may wish to use named parameters instead. And that's a reasonable solution:

let makePerson: (
  ~firstName: string,
  ~surname: string, 
  ~hometown: string, 
  ~age: int
) => unit 

Now at least you can identify what goes where and it would be acceptable to finish here. Still, this has some minor issues that can be addressed. For example, you could accidentally pass in a name into the hometown field.

Another alternative would be to use type aliases for the fields, which would make the method more descriptive without the overhead of typing the labels each time:

type firstName = string;
type surname = string;
type hometown = string;
type age = int;

let makePerson: (
  firstName,
  surname, 
  hometown, 
  age) => unit

Whilst very readable, this code is no safer than the original implementation. Aliases don't provide any protection and you can pass any string as any of the function's parameters.

In both solutions, the string type is still being used for three different things; however, in Scala is possible to abstract the string away by using Value Classes. Let's quickly demonstrate that:

case class FirstName(value: String) extends AnyVal
case class Surname(value: String) extends AnyVal
case class Hometown(value: String) extends AnyVal
case class Age(value: String) extends AnyVal

abstract def makePerson(
  firstName: FirstName,
  surname: Surname, 
  hometown: Hometown,
  age: Age): Person
  
// Or if you simply wanted to use a constructor
case class Person(
  firstName: FirstName,
  surname: Surname, 
  hometown: Hometown,
  age: Age)

So in the above example, unlike simple type aliases, you cannot pass a FirstName into say the Hometown field. Each of those types is independent of the primitive type it wraps.

So how do we do this in Reason?

So how do we do this in Reason? Well, we can box the primitive types within single-argument variants.

type firstName = FirstName(string);
type surname = Surname(string);
type hometown = Hometown(string);
type age = Age(int);

let makePerson: (
  firstName,
  surname, 
  hometown, 
  age) => unit = (a, b, c, d) => ();

Now it isn't possible to accidentally pass in a hometown as a surname, any such mistake would cause the program to not compile. Whilst this is only a simple example, this becomes more useful the bigger your solution gets. Anywhere else in the codebase it would no longer be possible to mistake a surname for a string or an age for an int.

A common situation for this in a larger application is for id fields. You may end up with int being used for a user id, post id, account id, payment id, group id, and so on. If these types are abstracted within singleton variants, then we can differentiate between the types.

Now, at some point you will need to unbox the values from these singleton variants. You could use a switch, but that's a little long-winded. Instead, try using the handy fun shortcut.

let name = FirstName("Dave");

let nameString = name |> fun | FirstName(str) => str;

That's nice, but there's yet another, easier way to unbox the value:

let FirstName(nameString) = name;

/* Now you can use `nameString` 
Js.log("The person's name is: " ++ nameString");

Isn't there a performance cost?

Unlike Scala, the above example does come with a penalty. There is a small cost as Reason will construct the variant as a single argument array. Accessing the value in the code above is like accessing an array using myArray[0]. For example the above name construction compiles to:

var name = /* FirstName */["Dave"];

However, since release 7.1.0 we are able to use unboxed to get around this! What is this? Let's look at the OCaml manual:

unboxed can be used on a type definition if the type is a single-field record or a concrete type with a single constructor that has a single argument. It tells the compiler to optimize the representation of the type by removing the block that represents the record or the constructor (i.e. a value of this type is physically equal to its argument).

This now means a singleton variant is not compiled as an array but is instead unboxed to the underlying type. Essentially, like with Scala, the OCaml compiler will erase the singleton variant in a later stage of compilation as it's not required at runtime. To use this mark the type as [@unboxed] like so:

[@unboxed]
type hometown = Hometown(string);
let tokyo = Hometown("tokyo");

This will then be unboxed from the array to a simple var during compilation:

var tokyo = "tokyo";

So no more performance penalties! According to the release notes, this can also be used to unbox singleton records . Note, that whilst the release notes are for development version, this feature was released with bs-platform@7.1.0.

To give you a quick example of using singleton records:

[@unboxed]
type hometown = {name: string};
let kyoto = {name: "kyoto"};

That will compile to the following JavaScript:

var kyoto = "kyoto";

As a record it may be simplier to extract the values, there's no need for pattern matching:

[@unboxed]
type hometown = {name: string};
let kyoto = {name: "kyoto"};

Js.log("The name is: " ++ kyoto.name);

Whether you prefer to use singleton variants or records for this is a personal choice. As you can see, variants are not as clean to extract from as records, but are quicker to construct.

I was used to using dependency injection – often known as DI – as a pattern from writing Java and Scala, which is a pattern that enables inversion of control. Or more simply put, constructing an object or module from other modules/objects and using the functions provided.

Now in ReasonML  functors – functions from modules to modules – can be used to  implement dependency injection. Functors can be used for more advanced techniques, such as creating modules that parameterise other modules; however, this is a good introduction to the module system. When I first used this technique the language server failed to understand what I was doing! Thankfully, that issue been fixed!

Why would you want to use dependency injection? Well, for example, you could have a service that uses another module to make a call to an API:

module MyService = {
  let userAndComments = id => { 
     let user = UserApi.userById(id);
     switch(user) {
       | Some(user) => { 
       let comments = CommentsApi.fetchUserComments(id); 	
       Some({ user.name, comments });
       }
       | None => None
     }
   };
};

The code probably works, but are a few issues with this:

• It can lead to a spiderweb of dependencies.
• It can be hard to unit test, in this example you cannot test the userAndComments method without making a HTTP call. In order to test this module,  you would require either a mocked server or an integration test.

We can use dependency injection to control what the service receives in order to facilitate easier unit testing. So how would we go about that?

First, let define a type that we can inject. This is a simple type definition for logging output.

module type Logger = {
  let log: string => unit;
};

Then we can create a new module that uses the `Logger` we have defined. In OCaml and Reason a module that is built from other modules is known as a Functor.

module GreetingService = (LOG: Logger) => {
  let sayHello = name => LOG.log("Hello " ++ name); 
};

Now we can implement a Logger and pass it into a GreetingService: creating a module from another module.

module ConsoleLogger = {
  let log = loggable => Js.Console.log(log);
};

module ConsoleGreeter = GreetingService(ConsoleLogger);

ConsoleGreeter.sayHello("World");

Note that we are free to choose how the Logger works – it only has to match the type signature. For example, you could implement an ErrorLogger instead:

module ErrorLogger = {
  let log = loggable => Js.Console.error(log);
};

Effectively we have taken away control from GreetingService to Logger. Now GreetingService describes what it wants to do, but doesn't actually implement how to do it. This is often reffered to as inversion of control.

When writing systems in a modern object-oriented style using programming languages such as Java or Kotlin, this technique is heavily used. Often you will read that you should "prefer composition over inheritance" and DI is used to alongside composition to create cleaner more testable code.

This pattern can be used in ReasonML (and OCaml), by using functors for dependency injection. Lets go back to the original example to demonstrate this:

Updating the Original Service

Remember this? It's the MyService module from the first example.

module MyService = {
  let userAndComments = id => { 
     let user = UserApi.userById(id);
     switch(user) {
       | Some(user) => { 
       let comments = CommentsApi.fetchUserComments(id); 	
       Some({ user.name, comments });
       }
       | None => None
     }
   };
};

We can turn MyService into a functor and construct an instance by passing module types for UserApi and CommentsApi.

module MyService = (Users: UserApi, Comments: CommentsApi) => {
  let userAndComments = id => { 
    let user = Users.userById(id);
    switch(user) {
      | Some(user) => { 
      let comments = Comments.fetchUserComments(id); 	
      Some({ user.name, comments });
      }
     | None => None
    }
  };
};

Now this module is easier to test. You can pass in stubbed versions of the modules in order to test the flow of the userAndComments function.

module StubUserApi = {
  let userById = id => switch(id) {
    | 1 => Some({ name: "Test User"})
    | _ => None
  };
};

module StubCommentsApi = {
  let fetchUserComments = id => 
    { title: "Test Comment", message: "Hello" };
};

Now it's easy to test the service using these simple stubbed modules:

module UnderTest = MyService(StubUserApi, StubCommentsApi);

let result = UnderTest.userAndComments(1); // Some({ ...
let anotherResult = Undertest.userAndComment(2); // None

I started using this part way through building Bouken. As previously stated, I initially imported modules from anywhere as that seemed to be the way things were done and worked for my frontend logic. Shortly afterwards, the game loop became unwieldy and needed breaking up.

RawToast/bouken

React based ASCII Rogue. Contribute to RawToast/bouken development by creating an account on GitHub.

RawToastGitHub

Over time the more complex modules were broken down into smaller modules for easier testing and code management. This eventually turns into a dependency tree of module types. For example, the main game builder is defined as follows:

module CreateGame: (
  Types.GameLoop, 
  Types.World, 
  Types.WorldBuilder
) => (Types.Game) = (
    GL: Types.GameLoop, 
    W: Types.World, 
    WB: Types.WorldBuilder
  ) => { };
  
// Which is build outf
module CreateGameLoop = (
  Pos: Types.Positions, 
  EL: EnemyLoop
) => { };

module CreateEnemyLoop = (
  Pos: Types.Positions, 
  Places: Types.Places, 
  World: World
) => { };

So as demonstrated, you can use Reason's advanced module system for dependency injection – you do not need to use objects! Instead, use modules for organising your code and leave objects alone until you absolutely require open types or inheritance.

Using open object types you can create functions or methods that accept various types that may only have a single value in common. For example, what if you wanted to require the parameter had a field called name but didn't care about the rest of the data? How would such an open object be defined?

type tx('named) = {
  ..
  getName: string,
} as 'named;


let tellMeYourName: tx('named) => unit = named => {
  Js.log(named#getName);
};

The key to this definition is the double dot .., which indicates that the type is open, thus it can contain other fields and values. This means that the above snippet defines a type with a getName method that returns a string – and any other methods.

The next snippet demonstrates the function declared above being called with various difference types.

class dog (name: string) = {
  as _;
  pub getName = name;
  pub talk = Js.log("Woof!");
};

let myDog = new dog("Spot");
tellMeYourName(myDog);

let makeCat = (name: string, age: int) => {
  as _;
  val mutable catName = name;
  val mutable catAge = age;
  pub getName = catName;
  pub getAge = catAge;
  pub setAge = age => catAge = age;
};

let myCat = makeCat("Cool Cat", 12);
tellMeYourName(myCat);

Note that if you’d rather not have the intermediary type, you can simply define the structure in the function. This reminds me of structural typing in JavaScript.

let tellMeYourNameAgain: { .. getName: string } => unit = 
  named => Js.log(named#getName);

tellMeYourNameAgain(myDog);
tellMeYourNameAgain(myCat);

Note that if you don't include the type in the function definition,  the type for the parameter should be inferred as as open object containing getName.

let tellMeYourNamez = named => {
  print_endline(named#getName);
};
// Type from sketch.sh
// let tellMeYourNamez: {.. getName: string } => unit = <fun>;

It is not possible to pass in a record to a function with an open object parameter, but you could convert to the object type beforehand; however, writing such converters might be the same effort as using varients and pattern matching...

For now, this is the end of my short series on using objects in Reason. I do have some notes on using row polymorphism within a functional program, with any luck I'll post something this week.

Most ReasonML developers have come across the syntax below to update immutable records:

type cat = {name: string, age: int};

let kitten = { name: "Charles", age: 1 };

let oldCat = { ...kitten, age: 4 };

A similar technique exists for objects; however, it's not so well known amongst Reason developers, as I believe it is not included in the documentation. So at first, you might attempt something like the example below, which works but quickly becomes verbose as your records grow in size:

class immutableDog(name, age) = {
  as _;
  pub getAge: int = age;
  pub getName: string = name;
  pub setName: string => immutableDog = newName => new immutableDog(newName, age);
  pub setAge: int => immutableDog = newAge => new immutableDog(name, newAge);
};

Instead, you can override values to make a new instance with only the specified updates, similar to records. The syntax is not so obvious:

class immutableCat(name, age) = {
  as _;
  val name = name;
  val age = age;
  pub getAge: int = age;
  pub getName: string = name;
  pub setName = newName => {<name: newName>}; // Creates a new instance.
  pub setAge = newAge => {<age: newAge>};
};

This technique uses the override construct {< ... >}, which returns a copy of the current object and allows you to override the value of instance variables or methods.

Lets see what it looks like in action:

let myImmutableCat: immutableCat = new immutableCat("Cool Cat", 5);
let myNewCat: immutableCat = myImmutableCat#setName("Dave");

Note that in the above example, myImmutableCat does not change.

It is also possible to update values in the same way:

class immutable = (number) => {
  as _;
  val counter = number * number;
  pub makeNegative = {<counter: -counter>};
  pub getCounter = counter;
};

let myImmutable = new immutable(4);
let negative = myImmutable#makeNegative;
myImmutable#getCounter // 4
negative#getCounter // -16

Whilst this is a nice feature, the syntax could definately be improved and the functionality better documented.

And finally you're ready for the final part: row polymorphism and structural subtyping!

The Polymorphic Nature of Objects

Polymorphism is that ability for an object or method to take many forms. Essentially a function or method is polymorphic when it can take more than one type of parameter.  

There is an interesting feature of objects where – unlike records – any object that matches the signature of a function is deemed acceptable, this makes writing polymorphism easy to achieve.  Note that can even be as undesirable, as it means methods or functions taking objects not as strict as with records: the wrong object could be passed in and the compiler may not help you!

We can create polymophic functions by using an object type as the parameter for a method. So lets create a simple type:

type pet = {
  .
  getName: string,
  talk: unit
}

Then you are free to implement this type as many times as you like.

class cat = (name) => {
  as _;
  pub getName = String.trim(name);
  pub talk =  Js.log("Nya!");
};

class dog = (name) => {
  as _;
  pub getName = String.capitalize_ascii(name);
  pub talk =  Js.log2("Woof!", name);
};

As both the cat and dog classes implement the pet signature, we can write a function that works on pet and it will accept both cats and dogs:

let myCat: cat = new cat(" Cuddles ");
let myDog: dog = new dog("spot");
let greet: pet => string = 
	p => "Hello " ++ p#getName;
let doubleGreet: string = 
	greet(myCat) ++ " and " ++ greet(myDog);

Abstraction using Virtual Classes

Inheritance in ReasonML can be defined using virtual objects and methods. Essentially a virtual method or object is similar to an abstract method or class in Java — it is left undefined and has to be implemented by the inheriting class.

We can define a virtual class as follows:

class virtual pet (name: string) = {
  as self;
  pri getName = 
    name 
    |> String.trim 
    |> String.capitalize_ascii;
  pub virtual talk: unit;
};

// You can't do this:
let myVirtualPet = new pet("davey");

There a few things to take note of here:

• If class is defined as virtual, we cannot instantiate it.
• A virtual class may contain private methods. These act like protected methods in Java. When defining a subclass, we will have access to them; however, once we instantiate a class we will not have access to it. This is a form of abstraction.
• You can define concrete methods alongside virtual methods. In this case getName handles trimming and capitalising for us and the user no-longer has to define that functionality per class.

Inheriting from a Virtual Class

Instead of creating virtual classes, we have to define a new class that inherits from the virtual class. Note how in this instance we are able to access the getName private method from within the class definition; however, this cannot be accessed from a dog or pet object.

class dog (name) = {
  as self;
  inherit (class pet)(name);
  pub talk = 
    Js.log(self#getName ++ ", says Woof!");
};


let myDog: pet = new dog("Spot");
myDog#talk; // prints 'Spot, says Woof!'
myDog#getName; // does not compile :(
class cat (name) = {
  as _;
  inherit (class pet)(name);
  pub talk = "Nya!");
};
let myCat: pet = new cat("Kitten");
myCat#talk; // prints 'Nya!'

As you can see the talk method is implemented differently for both instances. Thus a pet has polymophic behaviour, unless we know which instance it actually is we are unable to determine how it behaves.

Overriding a Method

Sometimes you wish to override the functionality provided by the class you are inheriting from. This can be done by adding an exclamation mark after inherit , like so:

class cat (name) = {
  as self;
  inherit (class pet)(name);
  pub talk = 
    Js.log(self#getName ++ ", says Nya!");
};
class shyCat (name) = {
  as self;
  inherit (class cat)(name);
  pub! talk = Js.log(self#getName);
};

In the above example, shyCat ‘s talk method overrides cat to not include the cat’s name.

Multiple Inheritance and the Diamond Problem

Interestingly OCaml supports multiple inheritance. This is something that often needs to be treated with care as there is a chance you may run into the diamond problem:

An ambiguity that arises when two classes B and C inherit from A, and class D inherits from both B and C. If there is a method in A that B and C have overridden, and D does not override it, then which version of the method does D inherit: that of B, or that of C?

Thankfully OCaml mitigates this by enforcing that you define the inheritance in order. Thus sub-classes will take the last defined instance of a method.

class virtual namedDave = {
  as _;
  pri getName = "Dave";
  pub virtual count: int;
};
class dog (name) = {
  as self;
  inherit (class namedDave);
  inherit! (class pet)(name);
  pub talk = Js.log(self#getName ++ ", says Woof!");
  pub count = 0;
};
class otherDog (name) = {
  as self;
  inherit (class pet)(name);
  inherit! (class namedDave);
  pub talk = Js.log(self#getName ++ ", says Woof!");
  pub count = 1;
};
let dog1 = new dog("Not Dave");
let dog2 = new otherDog("Will be called Dave");

Next up in this little series about objects in Reason: immutable updates.

As Reason is a syntax for OCaml, it also comes with support for object-oriented programming. I get the impression that object-oriented programming is typically not recommended in OCaml, and this seems to also apply to ReasonML. Hence there is little documentation for using objects in Reason ML -- there's just a single page in the official documentation.

As I struggled to find any resources documenting the object-oriented aspect of the language, I felt compelled to write something for others without an OCaml background.

Now, my goal in writing this isn’t to push object-oriented programming. Instead, it is to highlight some of the features that the object support provides. For me, I find the real benefit is structural subtyping (row polymorphism), which I have been able to utilise to write pure functional code using the RIO Monad.

An Introduction to Objects in Reason

ReasonML is typically demonstrated as a functional language alongside Reason-React. In such tutorials you will often see records, but never objects, which seem to be a little discussed feature of the language.

Unlike Records, Objects are able to mutate their own state. Whilst it is possible to have a mutable field or reference on a record, it is not possible for a record to contain a method that mutates that state (it would have to be a function declared elsewhere).

Let’s demonstrate how an object can mutate its own state using a simple type for a cat, with an immutable name and a mutable age. This example reminds me of the sort of code I to write 10 years ago in Java… there are getters for both fields, but a setter for the age. Note the . after the brace, which indicates that this is an object and not a record.

type cat = {
  .
  getName: string,
  getAge: int,
  setAge: int => unit,
  describe: string
};

Now lets see one way to implement that type:

let makeCat: (string, int) => cat = (name, age) => {
  as self; // this is a reference to the object itself
  val mutable catAge = age;
  pub getName = name;
  pub getAge = catAge;
  pub setAge = age => catAge = age;
  pri ageString = string_of_int(catAge);
  pub describe = self#getName ++ " is " ++ self#ageString ++ " years old."
};

There’s a few things to take from this.

as self; This is a reference to the object itself and you can call it whatever you wish (even _ if you don’t require it). You can think of this like self in Python or this in Java or TypeScript.

val mutable catAge = age Here we define an mutable instance variable to hold the cat’s age. We don’t need to do this for name as it’s immutable. This can only be accessed using the public getAge method.

pub getAge = catAge This is a method for fetching the age. As it is prefixed with pub the method is public. Note that it refers to the mutable reference and not the immutable age value we use to construct the instance.

pri ageString On the other hand, this is a private method which cannot be called outside of the object definition.

pub describe = self#getName ++ " " ++ self#ageString ++ "years old"; Note that unlike with values and variables, you must use the self reference to call the other methods on the object. The # syntax is a little strange compared to the dot notation used by records.

Finally, an object does not require a type definition. You can define an object with no type and use it within a function. If you so wish you can delay defining the object until you need it.

let double = x => x#value * 2;

let myObject = {
  as _;
  pub value = 3;
};

let result = double(myObject); // 6

Using Classes to Construct Objects

Whilst I used a function to build my object, you can use a class instead. The code is very similar:

class cat(name, age) = {
  as self;
  val mutable age = age;

  pub getName = name;
  pub getAge = age;
  pub setAge = (newAge: int) => age = newAge;
  pri ageString = string_of_int(age);
  pub describe = name ++ " is " ++ self#ageString ++ " years old."
};

Calling Methods on Objects

Once you’ve constructed an object you can call it’s methods using the # syntax. The simple example below demonstrates that we are mutating the state of the cat object:

let myOtherCat = new cat("Top Cat", 4);

myOtherCat#setAge(6)
myOtherCat#getAge // 6
myOtherCat.describe // "Top Cat is 6 years old."

Apart from the strange syntax, the basics of objects and classes are rather simple. Whilst you could use these techniques to do build object-oriented systems in ReasonML, it's not common to do so – nor is it common in OCaml. Modules are recommended for most use cases, whilst objects are only used when polymorphism and inheritance are required. This article has only scratched the surface of what is possible with objects and I will expand upon in this in later posts.

Next up, implementing inheritance and virtual types.

A few projects I have worked on have looked at using Swagger to document the APIs. Unfortunately, the recommended way to achieve this involves adding a number of annotations to the endpoints and JSON representations which I feel clutter the codebase. I have never been happy with this, as in my opinion it is simply shifting the work from a wiki to some annoitations and is liable to the same problem — developers forget to update the annotations/documentation.

Hence I was very happy to find and implement automatic documentation using the Swagger JaxRs maven build plugin. Configuring the plugin can be done in three simple steps. Just note that I am using swagger 2.1.0, and you probably should use the latest version.

1. Add the plugin to your maven build (there are instructions for gradle).
2. Add the assets in your dropwizard application.
3. Import the swagger-ui files to into your project and amend a single line to point at your service definition.

Integrating the Plugin

So the first job you need to do is add the following to your maven pom’s build section. Obviously you need to remove the “build” and “plugins” sections if you already have them in your pom.

<build>
  <plugins>
  <!-- Swagger Doclet -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9.1</version>
      <executions>
          <execution>
          <id>generate-service-docs</id>
          <phase>generate-resources</phase>
          <configuration>
            <doclet>com.carma.swagger.doclet.ServiceDoclet</doclet>
            <docletArtifact>
              <groupId>com.carma</groupId>
              <artifactId>swagger-doclet</artifactId>
              <version>1.1.1</version>
            </docletArtifact>
            <reportOutputDirectory>${project.build.outputDirectory}</reportOutputDirectory>
            <useStandardDocletOptions>false</useStandardDocletOptions>
            <additionalparam>-apiVersion 1 -docBasePath /apidocs -apiBasePath / -swaggerUiPath ../../../src/main/resources/swagger-ui-2.1.0</additionalparam>
          </configuration>
          <goals>
            <goal>javadoc</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Just take note of the following part:

<additionalparam>-apiVersion 1 -docBasePath /apidocs -apiBasePath / -swaggerUiPath ../../../src/main/resources/swagger-ui-2.1.3</additionalparam>

• /apidocs is the location of the documention resource.
• ../../../src/main/resources/swagger-ui-2.1.0 — is the location of swagger-ui. I have it pointing to the standard resources directory, as that’s where I will place swagger-ui.

Register the Assert Bundle

First double check you are already importing dropwizard-assets in your dependencies. It should look something like this:

<dependency>
  <groupId>io.dropwizard</groupId>
  <artifactId>dropwizard-assets</artifactId>
  <version>${dropwizard.version}</version>
</dependency>

Now you can add the assets bundle within your main application class. All you need to do is add the bundle in the initialize method of your main application, like so:

@Override
public void initialize(Bootstrap bootstrap) {
  // Other init code
  bootstrap.addBundle(
    new AssetsBundle("/apidocs", "/apidocs", "index.html")
  );
}

Things to note here:

• /apidocs is the location of the documentation endpoint. This is the same as the value in the additionalparams section of the maven plugin.
• index.html You shouldn’t need to change this. This is the html file that loads when you hit the resource and is provided by swagger-ui.

Importing the Swagger UI Resources

Download the latest version of Swagger (I’ve tested this setup against 2.1.0 and 2.1.3) from the Swagger-UI GitHub. You’re only interested in the dist folder, so extract the zip to a temporary directory and delete everything except for the dist folder.

In the dist folder you need to open index.html to amend the swagger service definition location. By default swagger will be pointing to the ‘petstore example’, which isn’t very useful for us! This should be located on line 36 and will look like this:

url = "http://petstore.swagger.io/v2/swagger.json";

Amend this to service.json and it will be pointing at the json schema generated by the plugin.

url = "service.json";

The next step is very simple. Create a folder in resources named swagger-ui-<version> so in my case: src/main/resources/swagger-2.1.0 Now simply move the contents of the dist folder into this newly created directory.

Wrapping it up

Now everything should be completed. Simply build your maven project (mvn clean package) and start your application as usual. The documentation should be located at <your application>/apidocs/. So if you were using the default Dropwizard ports try: localhost:8080/apidocs/  (Note the final slash is important!)