crafting (and) JavaScript

Learning ReScript - Part 3 (Format, Start Typing)

The setup is working, I can compile and run ReScript files, I touched a bit on the syntax in Part 2, next I will continue through the docs chapters from top to bottom.

ReScript docs TOC
ReScript docs TOC


  1. Formatting
  2. First Type Annotations
  3. Type Alias
  4. Retrospective #1
  5. An Opinion on the Docs
  6. To be Continued ...


I remember having heard on the podcast with Patrick Ecker that ReScript comes with a formatting tool (just like golang, or many of the newer languages), which prevents discussions about code layout, cool. Now it's time to apply it, the hello world code is growing, it needs some proper styling.

After rescript -h (remember, not --help!) I figured out it is rescript format. Alright. I run rescript format, nothing happens. So I have to pass the filename explicitly. Sad. Ok, rescript format src/hello.res works fine. It took me a while to read the rescript format -h help page properly to figure out that

# rescript format -all

is the script I want to call. Remember -all with one dash only (not --all!). I ran it on the code, committed and do not worry about coding style anymore (I thought).

First Type Annotations

Yeah, a lot of tooling and stuff but no real types yet. Here we go:

let helloWorld: string = "Hello World"

I added the :string type annotation (see commit), it compiled and made no problems. I didn't expect it to either.

The type can go behind the value, enclosed in parens like so (see commit):

let helloWorld = ("Hello World": string)

Cool this feels like it might come in handy, eventually.

Type Alias

Next I am trying a type alias. Makes it handy when I know this type might get more specialized later, I had seen this often. Some value is currently of type string but is actually a "license plate" or "city name", so why not start out with a type alias like type licensePlate = string. I also think it can make code more understandable, it's like a comment but eventually can be verified, once the licensePlate becomes a more explicit type than a string. So I try:

type HelloWorldString = string
let helloWorld = ("Hello World": HelloWorldString)

I get a syntax error, a bit cryptic but I seem not to be the only one that feels this is not the best error message yet, but it's on the radar of the ReScript team:

Syntax error!

1 │ type HelloWorldString = string
2 │ 
3 │ module Printer = {

Did you forget a `.` here?

The answer to this error comes later in the docs, when learning about variants, there the docs say "a variant's constructors need to be capitalized". My assumption the compiler mixes this up and gives some error message that I can not "understand" yet. I am leaving it at this for now. It feels like something that eventually will dissolve when I read some docs or ReScript source code. Good enough for now, that I learned types must start with lower case.

Unsurprisingly this compiles and works just fine:

type HelloWorldString = string
let helloWorld = ("Hello World": HelloWorldString)

the commit is here.

Retrospective #1

I want to wrap up the learning experience up to here a bit.

Actually I did not feel guided by the docs yet. What I did was going through the docs from top to bottom not knowing how much is left and if that path is a good path.
I am quite convinced that learning ReScript is a good thing, but I also remember that it was the same thing with PureScript and I dropped it eventually when I got drowned in the functional rabbit hole way to deep. I am not sure if this can and will happen here too. So I am bringing along a lot of optimism and hope that my time is well invested.

I am not sure everyone is so interested in finding this out by investing a lot of time and eventually being disappointed. Maybe the docs could offer a short walk through ReScript for those that have a shorter attention span.

Of course I was scrolling the docs a bit and I have seen that there is a lot more to come for me to learn. But that is not surprising me and also just confirms that I need a sustainable way of learning it. I am always advancing the repo and some time later coming back here to write something down, which is a great recap for me. And I am convinced it helps me to learn better.

My initial goal was to rewrite jskatas.org in ReScript, but I realized quickly that I want to understand the language better before running with it. That might just be how I roll. So be it. Find your way!

Along the way I was also looking for writing katas and learning ReScript that way, since that is something I highly appreciate. But I didn't know how to do that in a language that I don't know yet, I am quite happy extending the hello-world more and more. I know the code becomes insanely stupid, just so I can use langauge features. But this serves the purpose well, at least for me.

An Opinion on the Docs

The docs have quite an opinionated touch to them and, to be honest, they don't read easy all the time. Sentences like "ReScript is the language for folks who don't necessarily love JavaScript, but who still acknowledge its importance." on the intro page of the docs don't make me feel as if I want this language for those reasons. I really do like JavaScript, there is not just one language on this planet, but I also want to learn ReScript but for different reasons.

The very opinionated "thankfully" sprinkled across the "Comparison to JS" page, which I interpret (maybe wrongly) as "what a stupid language feature", might scare off some people. Not sure if this is intentional. I don't like it.

The intro page, has some glorification and subjective comparisons on it, like "TypeScript's type system is ...", "Faster than JavaScript" and "Readable Output & Great Interop". I am not sure this belongs in a technical language documentation. Maybe everything there is correct, but it feels kinda like "ReScript is better", it doesn't make me feel too comfortable reading it.

Others that also caught my attention (or am I just trying hard to find more examples?), are phrases like

  • "other crazy patterns you'll soon find horrible, after getting used to ReScript's alternatives."
  • "The more you overload the poor string type, the less the type system (or a teammate) can help you!"

all of them on the Primitive Types page in the docs. They are right, no doubt. For me there is too much opinion in the docs. I want cold facts and decide for myself if anything I used to do was horrible or not. Maybe I just don't agree and therefore drop learning ReScript, definitely not an intention of the docs, right? Or am I too sensitive?

To be Continued ...

Let's tackle real useful data structures, some that don't (yet) exist in JavaScript land, go on to Part 4.