DEV Community: Florian Hammerschmidt

[Boost]

Florian Hammerschmidt — Fri, 21 Feb 2025 23:20:23 +0000

JavaScript schema library from the Future 🧬

Dmitry Zakharov ・ Feb 21

#schema #typescript #rescript #opensource

My programming language history

Florian Hammerschmidt — Fri, 26 Aug 2022 21:39:14 +0000

Nowadays, it is certainly more the norm to be a polyglot programmer than to be lucky enough to only need one main programming language. I am no different. I stumbled over a lot of both popular and unpopular programming languages over the course of my life.

My first one was something with moving turtles. Probably Logo or some more modern take on turtle graphics, I don't know. However I was too young at that time to even understand what I am doing, but I liked to make the turtle move. Not sure if that experiences formed my brain to dive deeper into all things computers later on.

My second one was HTML. Yes, it's just a markup language, but I still created something just by writing text into an editor. Also it felt more useful to me than the Logo turtles which felt more like a game to me.

As a teenager, I stumbled over Ubuntu and started a bit of Bash scripting. This was when I really got to know the power of programming, because I could just pipe the output of one program to the next one and would only need to combine them to create something I was not even aware I could do. I mainly used it to organize my music collection - streaming services were not a thing back then.

Later I started a job in a huge company where I mostly formatted Word documents or extended huge Excel sheets. Of course I got into VBA at that time, which I learned quickly, is both boon and bane. Some excel sheets really evolved into unmaintainable behemoths, unfortunately.

But it started to really diversify when I went to university. I started studying electrical engineering, where programming is an important part. Naturally, you learn C there, which I both liked and hated. I eventually switched to information systems, not because programming in C was too hard, but the physics and electrical engineering classes were just a chore for me I could not really stand.

In information systems, Java was the bees knees. I learned it, did the necessary exams and classes but still hated it, because I found it too verbose. OOP was no problem for me, though. But using a full-fledged IDE for a project was very overwhelming at first.

Another class was based around "semistructured data", which was where I learned not only how to write well-formed XML but also XSLT. It's really powerful but also yet another markup language so of course it does not count (or does it?).

Next up I had a relational databases class FROM WHERE I found the theory pretty useful, but I would SELECT SQL as the most useful skill I took out of this class. Also one of the professors contributed to the SQL-99 standard back then, which made me automatically pay attention a bit more.

There is always the class where you get to decide what language you use for a project, so naturally our team decided to go with Python. Django was still a young technology, but the project incorporated HTML, CSS and SQL as well, so it fostered my knowledge.

Of course, some professors prefer pretty weird languages, and in another class I got to know ooRexx, which is an object-oriented extension to IBMs Rexx language which itself is said to be a programming language for humans rather than computers. And it is really true in some ways. Everything is a string, and hello world is just "SAY Hello World" (without the quotes). We scripted office applications with it which felt much nicer than VBA. Later, we also scripted Java apps with it, which felt somewhat weird, since for most things it was easier to write things in Java, which is a much more googleable language than ooRexx.

Fast-forward to my masters degree, which was when the machine learning hype started to gain traction. So I had a class where we used R. It's a language that specializes in statistical computing. I found it really nice, especially that it was so easy to create nice plots without using MS Excel.

The masters was also the time when I created my first web app with PHP, JavaScript and GeoServer. I had not really a clue what I was doing, but it worked pretty well regardless.

Then I took the most technical specialization the degree offered. The first class of it already made us compare the OOP capabilities of JavaScript, Ruby, and XOTcl. Yes the last one is an object-oriented extension to Tcl (the tool command language) which is a pretty esoteric language in itself. Eventually, we got to know this language a bit more in a later class where I made a little forum app with an upvote/downvote system.

We also had an IOT class where I was introduced to Arduino which you basically write in C++. Still, I resorted to doing the final project with a Raspberry Pi, a Bluetooth low energy module and a bunch of bash scripts. It was good enough for a working prototype (and it got me an A).

Meanwhile, before the end of my studies, I got a freelancer job as a real software developer. I needed to write a complex signup form with Ruby on Rails. That job was a great reference to land a real job which I did.

There, I was not only introduced to React, I also learned to write modern JavaScript (with flowtype at that time). Because of React-Native, I also needed to write the occasional Java or Objective-C. Or now Kotlin and Swift.

We saw that TypeScript is probably the better horse to bet on, so we ditched flow for most existing projects in favor of TS. However, also ReasonML/BuckleScript emerged at that time, which was really a good fit for the mission-critical apps we were building. And now I am involved in developing tools for it, or rather its successor, ReScript.

But wait, it does not stop there. Having learned a Meta-Language-like language like ReScript makes it really easy to get into OCaml which behaves similarly. Just for fun I also read two Rust books and tinkered with that language as well. The jump to Rust is not that far-fetched from an ML-descendant.

In the end I count 22 languages:

Bash
C/C++
HTML
Java
JavaScript
Kotlin
Logo (again, not sure about that)
Objective-C
OCaml
ooRexx
PHP
Python
R
ReScript (previously BuckleScript + ReasonML)
Ruby
Rust
SQL
Swift
TypeScript
VBA
XML/XSLT
XOTcl and its successor, the next scripting framework

and that does not even include the languages I did not even learn properly, but just by using it, for instance because they come with the tooling environment, like Groovy, YAML, and so on. Also not the languages I just tinkered with a bit, like Go or Elm.

How many languages did you already use for more than just writing "Hello, world"? Did you get to know some really weird ones? Tell me about it in the comments!

Thank you for reading, hope you enjoy this slightly different blog post from me. The next one will be focused at ReScript again, I promise.

(cover image generated with craiyon.com)

Nicer APIs with ReScript

Florian Hammerschmidt — Wed, 14 Oct 2020 21:27:30 +0000

In the world of JavaScript, many APIs are not designed in a way a functional developer might design them. Although it got a lot better over the last couple of years thanks to technologies like React, most browser APIs are still rather object-oriented or lower-level.

ReScript (previously BuckleScript) is a statically typed and sound language, compiler and build system, which generates very readable JavaScript. Thus, it is a great alternative to TypeScript for people who can't stand type holes.

ReScript offers a wide variety of decorators to make binding to JavaScript APIs easier.

Recently, I was required to use the browser's mediaDevices API. One of the most important methods is the getUserMedia method which yields a Promise containing a MediaStream object. It also has one required parameter, the constraints object, to determine if the API user requests audio, video or both. For example, to only request an audio stream one would use the following JS code:

navigator.mediaDevices.getUserMedia({audio: true, video: false})

For video only you would set audio: false, video: true and only if you require both, audio: true, video: true.

In idiomatic ReScript, such an API would probably be designed in one of the following ways:

Either via a constraints variant:

type constraints = Audio | Video | Both

let getUserMedia: constraints => Js.Promise.t<stream> = ...

/* Calling the function */
getUserMedia(Audio)
getUserMedia(Video)
getUserMedia(Both)

Or three separate functions

let getUserAudio: unit => Js.Promise.t<stream> = ...
let getUserVideo: unit => Js.Promise.t<stream> = ...
let getUserMedia: unit => Js.Promise.t<stream> = ...

/* Calling the function */
getUserAudio()
getUserVideo()
getUserMedia()

In this case, I prefer the latter one. Soon you will see, why.

Embracing externals

The default way to bind to existing JS functions is the external keyword accompanied by a bunch of different decorators/annotations, which always start with @.

NOTE: With the most current bundle of the ReScript platform (bs-platform 8.3), it will be possible to omit the bs part in the annotations. So @bs.as will turn to just @as, etc. Check if your version is new enough for even cleaner code.

Binding attempt 1

To bind to global values such as navigator.mediaDevices.getUserMedia, two annotations are necessary. Let's have a look at how one can write the binding and dissect it into parts later on.

/* Navigator.MediaDevices module */
type constraints = {
  audio: bool,
  video: bool,
}

@bs.val @bs.scope(("navigator", "mediaDevices"))
external _getUserMedia: constraints => Js.Promise.t<stream> =
  "getUserMedia"

type constraints = ...:
The first part is a type definition for the constraints parameter we need to give to the getUserMedia function. It is a so-called record which looks like an object and also compiles to a JS object of the same shape, but is actually something different.
@bs.val is to bind to global values. Global values are values which you always have in scope, like navigator or window. Well, depending on the target platform (browser, node, etc.) of course.
@bs.scope(("navigator", "mediaDevices")): When those values are nested, you need to define its scope too with @bs.scope. Here, we use a tuple of strings to tell the compiler that the scope is multiple levels deep. You can tell that it's a tuple because of the double (( and )). The outer parentheses are from the scope function, and the inner ones are from the tuple. Alternatively, you can also just use a string for the whole thing like this: @bs.scope("navigator.mediaDevices").
external _getUserMedia: The aforementioned annotations only work together with the external keyword. With it you define the name of the binding, which does not necessarily need to be the same as the JavaScript method you want to bind to.
: constraints => Js.Promise.t<stream>: Then comes the type annotation. According to MDN, this takes the constraints object mentioned earlier and returns a Promise of MediaStream, which translates to the built-in ReScript type Js.Promise.t. The <stream> type which is wrapped by the promise is unfortunately not built-in, but can be typed accordingly (left as an exercise to the reader 😉).
= "getUserMedia": At last, a string with the actual name of the function. Watch out for typos!

We also define a helper record here. It looks like an object and compiles to a JS object, but is actually something different.

Now we have a binding to getUserMedia, but do we really want to call that ugly Navigator.MediaDevices._getUserMedia({audio: true, video: true} everywhere in the codebase, or can we achieve a nicer API?

Let's write some helper functions:

/* Navigator.MediaDevices module continued */
let getUserAudio = () => _getUserMedia({audio: true, video: false})
let getUserVideo = () => _getUserMedia({audio: false, video: true})
let getUserMedia = () => _getUserMedia({audio: true, video: true})

The functions can then be called from anywhere in the codebase via:

Navigator.MediaDevices.getUserAudio()
Navigator.MediaDevices.getUserVideo()
Navigator.MediaDevices.getUserMedia()

NOTE: Simplified example, in practice you would use Js.Promise.then_ or the like, to retrieve the stream itself.

Yay, that looks better. But now we generate some extra code
like this function:

function getUserAudio(param) {
  return navigator.mediaDevices.getUserMedia({
              audio: true,
              video: false
            });
}

Binding attempt 2

Can we do better and still populate the functions with default parameters? I'd say yes, with this nifty trick.

There is also the very helpful @bs.as annotation for when you need to give an entity a complex name which you could otherwise not create. For instance, in record fields, there is no - allowed which can be mitigated by this annotation.

@bs.as takes a single string as an argument. Coincidentally, JSON is basically just a complex string and thus we can inject some complex objects into the default configuration, too.

Just write

@bs.as(json`{your-config-object}`)

with a _ afterwards to omit the value when calling the function.
Also we add a final unit (the only "parameter" of the function).

/* Navigator.MediaDevices module */
@bs.val @bs.scope(("navigator", "mediaDevices"))
external getUserAudio: (
  @bs.as(json`{"audio": false, "video": true}`) _,
  unit,
) => Js.Promise.t<stream> = "getUserMedia"

The as-JSON trick as I call it has its limits, though. It only works for JSON-compliant values, such as arrays, objects, strings, numbers and booleans. Functions would not work for instance.

We can do the same with the other two possible functions:

/* Navigator.MediaDevices module continued */
@bs.val @bs.scope(("navigator", "mediaDevices"))
external getUserVideo: (
  @bs.as(json`{"audio": true, "video": false}`) _,
  unit,
) => Js.Promise.t<stream> = "getUserMedia"

@bs.val @bs.scope(("navigator", "mediaDevices"))
external getUserMedia: (
  @bs.as(json`{"audio": true, "video": true}`) _,
  unit,
) => Js.Promise.t<stream> = "getUserMedia"

And end up with the same API as in attempt 1. Again, we can call our functions the same way as before:

Navigator.MediaDevices.getUserAudio()
Navigator.MediaDevices.getUserVideo()
Navigator.MediaDevices.getUserMedia()

But this time with no build artifacts, the second attempt comes with zero cost 🎉.

Rule-of-thumb: lets generate additional JS code, externals don't.

Thank you for reading and I hope this trick helps some of you. For a condensed example, please have a look at the ReScript playground example this blog post is based on.

What's new in BuckleScript 7?

Florian Hammerschmidt — Fri, 06 Dec 2019 17:12:39 +0000

Another groundbreaking change for all ReasonML/BuckleScript developers has emerged this week, because BuckleScript 7 has been officially released. The maintainer, Bob Zhang, does a great job in announcing the most important new features and changes on the official BuckleScript blog website, but I want to cover them in a bit more detail here. Of course, the full changelog can always be viewed at the repository, but it's a bit raw to digest and there are some great things hidden behind all those pull requests.

Allow me to also include some important changes since version 5.2.1, because many people did not even make the jump to v6 already (including me). But v7 has so many good things to offer that the relatively minor risks are outweighed by a bunch of improvements.

Before I get into it, just a heads up: We upgraded a big codebase to from 5.2.1 to 7.0.1 and had only a very minor issue. We still released it compiled via BuckleScript 5, because there was just not enough time for thorough testing, but it compiled, no tests failed, and some manual testing has also been successful.

But we also did not use any PPXes, which may be a blocker for others. This was already the biggest hurdle for people switching to v6, since it is based on OCaml 4.06, while v5 is based on OCaml 4.02. The new BuckleScript 7 will still be based on OCaml 4.06, so let's discuss the differences between those two versions first.

Changes in V6

Inline Records

Inline records can now be used as arguments to datatype constructors in sum types. This is very convenient, for instance when you have a variant type which includes a record in one case, but do not want to create a separate type for the record just for this one variant case. Previously, you were forced to declare a new record type like this:

type point = { width: int, mutable x: float, mutable y: float};

type t =
  | Point(point)
  | Other;

let v = Point({width: 10, x: 0., y: 0.});

which can be achieved with fewer lines of code now:

type t =
  | Point({ width: int, mutable x: float, mutable y: float})
  | Other;

let v = Point({width: 10, x: 0., y: 0.});

Nice!

Well, to be fair the old (v5) compiler gave you an useful error when you used inline records, at least:

refmt: internal error, uncaught exception:
  File "/[blogposts]/bs-7-example/src/InlineRecord.re", line 2, characters 4-9: inline records are not supported before OCaml 4.03

Internal Result Type

OCaml baked the result type with 4.04 into the language. result is one of the most beloved features about ML and related languages for try-catch-ridden former OOP-developers who found their new home in FP languages. I mean, you can even convert exceptions into less threatening Result.Errors and everything is fine. On a more serious note, it always bothered me that you need to open Belt to have a result type at your disposal, because it is equally fundamental to a modern FP language as the option type (in my humble opinion).

This means that you can do this:

let bustAMove = move =>
  switch (move) {
  | Ok(bust) => Js.log(bust)
  | Error(error) => Js.log2("Can't bust a move because of: ", error)
  };

without opening Belt or any other library which provides a result type.

Local opening of modules in a pattern

Local opening of modules can be very useful to prevent name clashes. It's the syntax where you put a . and () after a module name to open the module only for what's inside the parentheses, e.g.:

Sausages.(pork->meatGrinder->fillIntoSkin)

You can also use that in a pattern now!

module CallMom = {
  type t = {
    smalltalk: string,
    story: option(string),
  };
};

let callMom = call =>
  switch (call) {
  | CallMom.{story, smalltalk} => Js.log2(story, smalltalk)
  | CallMom.{smalltalk} => Js.log2("Only gossip today", smalltalk)
  };

If you tried that with the old BuckleScript, it would yield an error.

That's all for the changes introduced with BuckleScript 6, let's move on to even more interesting grounds.

Changes in V7

Refmt Update / Re-Error

There has been a lot of work put into a better code parser to get better error messages which was a common pain point for many newcomers. The so-called Re-Error coming with the current ReasonML parser & formatter (refmt) makes the developer experience a bit better.

Consider the following very simple line of code:

let x = {
  foo;

When you compile that, with older refmt versions you only get a

File "/[redacted]/bs-7-example/src/SampleError.re", line 2, characters 2-6:
Error: SyntaxError in block

whereas now the message is much more helpful and descriptive:

File "/[redacted]/bs-7-example/src/SampleError.re", line 2, characters 6-6:
Error: Unclosed "{" (opened line 1, column 8)

Even for more complex errors, it is a great relief that it can still help you out. Imagine having a big tree of JSX functions and a missing closing > somewhere in the tree:

type state = {count: int};

type action =
  | Increment
  | Decrement;

let initialState = {count: 0};

let reducer = (state, action) =>
  switch (action) {
  | Increment => {count: state.count + 1}
  | Decrement => {count: state.count - 1}
  };

[@react.component]
let make = () => {
  let (state, dispatch) = React.useReducer(reducer, initialState);

  <main>
    {React.string("Simple counter with reducer")}
    <div>
      <button onClick={_ => dispatch(Decrement)}>
        {React.string("Decrement")}
      </button>
      <span> {state.count |> string_of_int |> React.string} </span // <-- Here we miss a closing '>'
      <button onClick={_ => dispatch(Increment)}>
        {React.string("Increment")}
      </button>
    </div>
  </main>;
};

(The example is from reason-minimal-template, thanks Margarita!)

BuckleScript 5 cannot deal with this error:

File "/[redacted]/bs-7-example/src/App.re", line 17, characters 2-66:
Error: SyntaxError in block

whereas BuckleScript 7 is much better:

File "/[redacted]/bs-7-example/src/App.re", line 25, characters 60-62:
Error: syntax error, consider adding a `;' before

At least the correct line has been found in version 7. The suggestion to add an ; is valid for normal code, but not the syntactic sugar we commonly know as JSX. Still, no more searching for the correct line, you're directly pointed to it and probably can then easily figure out for yourself what's wrong.

I wanted to make the example simpler initially (i.e. with only setState which means no separately declared types, intitialState and reducer), but then also the old BuckleScript 5.2.1 found the error. The difference is still night and day though, because in my experience, most components turn out more complex than this simple example.

The work on Reerror is not finalized yet. The roadmap can be found here: Reerror-Plan, but it's nice to know that it will continue to improve over time.

Records as JS Objects

Probably the most impactful change coming with BuckleScript 7 is that now records are not compiled to (nested) arrays anymore, but JavaScript objects. This is not only very nice for debugging, it also makes many of the interop annotations obsolete, or at least makes it more straightforward to write bindings.

Easier Debugging

For instance, previously the following record:

type person = {
  firstName: string,
  lastName: string,
  phone: string
};

let jordan: person = { firstName: "Jordan", lastName: "Walke", phone: "73276665" };

Js.log(jordan);

produced an array:

[ 'Jordan', 'Walke', '73276665' ]

which may be more performant, but for more complex records (nested records) it was really hard to find the field you were looking for. Now it produces the following log output:

{ firstName: 'Jordan',
  lastName: 'Walke',
  phone: '73276665' }

which is already a great help for debugging, but it gives us much more power.

Easier Interop

Let's explore how we can get some cleaner syntax by updating some bindings. As an example, let's take NodeJS' pathObject which is the output of the parse function, as well as the input for the format function:

type pathObject;
[@bs.obj]
external pathObject:
  (
    ~dir: string,
    ~root: string,
    ~base: string,
    ~name: string,
    ~ext: string,
  ) =>
  pathObject =
  "";

[@bs.module "path"] external parse: string => pathObject = "parse";
[@bs.module "path"] external format: pathObject => string = "format";

Now if you wanted to format a pathObject into a string, with Bucklescript <= 7 it worked the following way:

let path = format(
  pathObject(
    ~dir="/[redacted]/bs-7-example/src",
    ~root="/",
    ~base="NodePath.re",
    ~name="NodePath",
    ~ext=".re",
  ),
);

Let's look at how to bind that in BuckleScript 7:

  type pathObject = {
    dir: string,
    root: string,
    base: string,
    name: string,
    ext: string,
  };

The methods themselves do not change their type signature, as we use the same name for the type. Calling parse is a bit more concise and readable now:

let path = format({
  dir: "/[redacted]/bs-7-example/src",
  root: "/",
  base: "NodePath.re",
  name: "NodePath",
  ext: ".re",
});

It really looks like JavaScript now!

Bear in mind that for functions with lots of optional parameters it's still easier to use [@bs.obj], as you would otherwise need to write conversion functions for the nullable types which come at a runtime cost. Records in ReasonML always need to have all their fields set (even if it is None or Js.null).

Another benefit of records-as-objects is the ability to pattern-match on them. So now we can match on a NodeJS pathObject without the need of converting those objects to records:

let getExtensionType = path => {
  switch (path) {
  | {ext: ".re"} => Reason
  | {ext: ".ml"} => OCaml
  | {ext: ".js"} => JavaScript
  | {ext: ".ts"} => TypeScript
  | _ => Unknown
  };
};

Of course in this case you could also just match on path.ext directly. But it may be the case that you want to combine the extension with a certain name or something. I did not want the example to be too convoluted though, I hope it still supports my intention well.

Also mentioned on the BuckleScript blog: you can now use the [@bs.as] annotation in records too, so whenever you have a - or any other otherwise unrepresentable character, you could always use that as an escape hatch. It works the same way as usual:

type httpHeaders = {
  authorization: string,
  [@bs.as "content-type"] contentType: string,
  [@bs.as "last-modified"] lastModified: string,
  [@bs.as "if-modified-since"] ifModifiedSince: string,
};

let headers = {
  authorization: "Basic thisCouldBeYourCryptoKey",
  contentType: "application/javascript; charset=utf-8",
  lastModified: "Fri, 06 Dec 2019 07:39:45 GMT",
};

Are we still fast?

One point where BuckleScript never failed to deliver is build time, which has always been very fast. Incremental builds are nearly instant and also full project compilations are no opportunity to do something else in the meantime. However, this time I have to say, that build times actually take a bit longer now, but it is a small fee for a big gain.

One of our current projects is about 27k lines of Reason code, according to the following command:

find ./src -name '*.re' -o -name '*.ml' | xargs wc -l

the full, cleaned build took around 2250 milliseconds with BuckleScript 5.2.1, whereas with BuckleScript 7.0.1, it's about 2500ms. I do have faith though, that this number will fall again with the next minor releases. The build times were tested on a MacBook Pro (15-inch, 2018), 2,6 GHz Intel Core i7, 32 GB 2400 MHz DDR4.

That's everything I have to say for today. Maybe some new patterns will emerge from this useful upgrade. I am already exited to use BuckleScript 7 in the next project, what about you? Whenever you are ready to upgrade, consider reading the official upgrade guide to v7 first or contact other Reasonauts and BuckleScriptians in the ReasonML discord for help.

Happy coding!

Reason(React) Best Practices - Part 3

Florian Hammerschmidt — Sat, 26 Oct 2019 21:12:03 +0000

Welcome back to the third part of my blog mini series (Part 1, Part 2) which derived from my talk at @reasonvienna. This part is all about writing zero-cost bindings to existing JavaScript functions and React components.

Background

Since ReasonReact included Hooks support starting with version 0.7.0, writing React in Reason has become a breeze. The library now became a very thin layer between React and BuckleScript and as a result, we did not need to write tedious boilerplate code anymore (mostly to map to the behaviour of class-based React components). But before the old way gets completely lost in history, here is a small reminder how we wrote React in ReasonML just some months ago:

let component = ReasonReact.statelessComponent("Greeting");

let make = (~name, _children) => {
  ...component,
  render: self =>
    <h1> {ReasonReact.string("Hello " ++ name)} </h1>,
};

vs.

/* Greeting.re */
[@react.component]
let make = (~name) => <h1> {React.string("Hello " ++ name)} </h1>

To be fair, some magic happens in the react.component annotation, but it was just more work to create a stateless component in which we needed to spread our component definition into. Not to speak of comparing stateful components, the differences are humungous. For compatibility reasons, we still have the old module (ReasonReact), but the new one (just React) is about a third of the size of the old one.

Penalty-free bindings

Some of the most important differences though, are the implications on performance. Whereas the old ReasonReact comes with its own React Mini to be compatible with class-based components, the new one is meant to be a very thin layer between React and ReasonML, (mostly) without any additional performance cost. To be fair, this is only true if you use the Hooks API. If you rather write class components, then you still have to use the old approach (but then you probably would not use the FP language Reason either).

This idea also spilled over to the React Native bindings, which are mostly done at this point in time (only some of the more obscure or deprecated ones are missing).

I think this attitude is a good one to have, because we do not want to lose performance-wise against plain JS - it would make newcomers more hesitant to dive into the ReasonML ecosystem. Even better: by using the right annotations, you get the most out of your bindings and win some developer experience too. For instance if you take [@bs.string] which converts plain string enums into polymorphic variants (the ones which start with a `backtick) and in consequence make the compiler restrict your code to using only those variants.

In the following section, I will examine one of the well-written React-Native bindings, by using example apis or components directly from the sources.

React-Native Alert

The Alert API consists of two callable methods, alert and prompt. While prompt actually does only trigger on iOS devices (and is not even mentioned in the official React Native docs, as of yet), we still want to bind that too for educational purposes. If you look at the JS sources of Alert, you will notice the Flow types which make it pretty straightforward to translate everything to Reason code.

Note 1: As the following section contains both JS and ReasonML code, a small comment header will tell you what language I am talking about.

Note 2: The Reason source code may be formatted differently than what refmt would put out. I adapted it for readability and conciseness.

The first type is AlertType. It is a string enum consisting of

/* JS */
  | 'default'
  | 'plain-text'
  | 'secure-text'
  | 'login-password';

this translates to

/* Reason */
type alertType: [@bs.string] [
              | `default
              | `plainText
              | `secureText
              | `loginPassword
            ];

Note that you cannot use a hyphen in polymorphic variants, so there is another step necessary:

/* Reason */
type alertType = [@bs.string] [
              | `default
              | [@bs.as "plain-text"] `plainText
              | [@bs.as "secure-text"] `secureText
              | [@bs.as "login-password"] `loginPassword
            ];

[@bs.as] takes care of that. Generally, when there are hyphens, special characters, or numbers at the start, this approach is needed.

There is also the AlertButtonStyle, which can be translated in the same way:

/* JS */
export type AlertButtonStyle = "default" | "cancel" | "destructive";

translates to

/* Reason */
type alertButtonStyle = [@bs.string] [ | `default | `cancel | `destructive],

Then there is Buttons, an array of Button. I think it is better to define a button type and then define a buttons array type instead of mixing them all into one type definition, so let's pretend that the JS types are also written like that:

/* JS */
export type Button = {
  text?: string,
  onPress?: ?Function,
  style?: AlertButtonStyle
};

becomes

/* Reason */
type button; // create abstract button type

[@bs.obj]
external button: // define a translator function for the button type
  (
    ~text: string=?,
    ~onPress: unit => unit=?,
    ~style: alertButtonStyle=?,
    unit
  ) =>
  button = // returns a button
  ""; // dummy placeholder

This one is more complex, so we use [@bs.obj] here. It lets us define a function from which the compiler derives a JS object. This is useful if you have many optional parameters, as it is the case with the button above. The =? after the corresponding type denotes that the function is not required.

Then there is the options type:

/* JS */
type Options = {
  cancelable?: ?boolean,
  onDismiss?: ?() => void
};

which works the same as the button above:

/* Reason */
type options;

[@bs.obj]
external options:
  (
    ~cancelable: bool=?,
    ~onDismiss: unit => unit=?,
    unit
  ) => options = "";

Note that the type information of onDismiss is much clearer to translate - an empty function body yielding void which becomes unit => unit in Reason land. For translating ?Function one needs to look up the flow docs which say Function is basically any, so we only know what it really returns by using it and logging things out or digging through the source code. But in this case, we know it is still unit => unit.

The final piece is the signature of the method itself. As we speak of a JS class component, the alert method's signature can be found under static alert(...):

/* JS */
static alert(
  title: ?string,
  message?: ?string,
  buttons?: Buttons,
  options?: Options,
): void

which translates to

/* Reason */
[@bs.scope "Alert"] [@bs.module "react-native"]
external alert:
  (
    ~title: string,
    ~message: string=?,
    ~buttons: array(button)=?,
    ~options: options=?,
    unit
  ) => unit = "";

The most important part here is the first line - we need [@bs.module] to tell the compiler that we want to call a method from an external module, in this case from "react-native". Also we want to look it up under the Alert module of React Native. Therefore we utilize [@bs.scope] with "Alert". Remember, this is the equivalent of doing

import { Alert } from "react-native";

in JavaScript and I think that it is mapped pretty well that way.

The signature of the prompt method is also typed:

  static prompt(
    title: ?string,
    message?: ?string,
    callbackOrButtons?: ?(((text: string) => void) | Buttons),
    type?: ?AlertType = 'plain-text',
    defaultValue?: string,
    keyboardType?: string,
  ): void

This also looks doable:

title and
message work the same way as in the alert method,
defaultValue and
keyboardTypes are just strings,
type is already typed above, known as alertType.

So easy going, right? But what abomination of a property is callbackOrButtons? This is a JavaScript'ism which I would even call an antipattern in ReasonML. In the Reason (and FP) world, you would rather statically check your types and not inspect whether your prop is an array and do something differently than what you would have done with a function, all at runtime. This is such a thing which can only be done in a dynamically typed language. *hissing snake noises*

But be assured, that even for such cases, BuckleScript provides a wonderful remedy: [@bs.unwrap]. It utilizes polymorphic variants which all get compiled away, so we don't lose our precious performance. We just have to create two of them, one for `callback and one for `buttons. The button type has been defined already above and the callback just translates easily from Flow again, string => void becomes string => unit in Reason land.

    ~callbackOrButtons: [@bs.unwrap] [
                          | `callback(string => unit)
                          | `buttons(array(button))
                        ]=?,

So we end up with this:

[@bs.scope "Alert"] [@bs.module "react-native"]
external prompt:
  (
    ~title: string,
    ~message: string=?,
    ~callbackOrButtons: [@bs.unwrap] [
                          | `callback(string => unit)
                          | `buttons(array(button))
                        ]=?,
    ~type_: [@bs.string] [ /* alertType */
              | `default
              | [@bs.as "plain-text"] `plainText
              | [@bs.as "secure-text"] `secureText
              | [@bs.as "login-password"] `loginPassword
            ]=?,
    ~defaultValue: string=?,
    ~keyboardType: string=?,
    unit
  ) => unit = "prompt";

Of course writing bindings is only half the fun, so here's is an example of how you would use the Alert.alert binding:

Alert.alert(
  ~title="Warning!",
  ~message="Do you want to delete the entry?",
  ~buttons=[|
    Alert.button(~text="Delete", ~onPress, ~style=`destructive, ()),
    Alert.button(~text="Cancel", ~style=`cancel, ()),
  |],
  ~options=
    Alert.options(
      ~cancelable=false,
      ~onDismiss=_ => Js.log("Deletion aborted."),
      (),
    ),
  (),
);

And here's is an example of how you would use the Alert.prompt binding (again, only on iOS):

Alert.prompt(
  ~title="Enter Password",
  ~message="Please enter your password.",
  ~callbackOrButtons=`callback(text => Js.log(text)),
  ~type_=`secureText,
  (),
);

Don't forget to call all the defined externals with their Module name (here Alert) before or open it in the scope.

Speaking of externals, a good rule of thumb to know whether you created some runtime overhead with your bindings, is the following:

Have a look if there are any lets in your code, rather than externals.

To be sure look into your created .bs.js bindings file. When you only see

/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

you can pat yourself on the shoulder, because you successfully created a zero-cost binding!

That's all for my mini series about Best Practices in Reason & ReasonReact, at least for now. Any upcoming posts will not be part of this series anymore, but they will almost certainly contain ReasonML stuff.

So have a great time, and make great (type-safe) things!

Reason(React) Best Practices - Part 2

Florian Hammerschmidt — Mon, 30 Sep 2019 12:05:07 +0000

Welcome back to the second part of my blog mini series (the first one is here) which kinda derived from my talk at @reasonvienna. As promised, the focus of this part is on compiler configuration and the Belt standard library.

Compiler configuration

Well, it turns out that I am not the first person writing about BuckleScript's compiler flags here on dev.to. Yawar Amin already did a great job with his post "OCaml/ReasonML best practice: warnings and errors". Still, I have a different view (and only focus on BuckleScript with ReasonML and not native, nor OCaml).

Furthermore, which warnings you really want to add or remove from the defaults is still highly subjective and may depend on you and your team's specific needs, toolchain and so on.

Warnings ⚠️

BuckleScript's compiler warnings can be modified by prepending + or - to a warning number you want to activate or deactivate. No matter whether you just modify one or many warnings, it is always a single string you assign to the "number" property in the "warnings" object of your project's bsconfig.json. Here is an example with one activated and one deactivated warning:

  // bsconfig.json
  "warnings": {
    "number": "+102-105"
  },

There is also a special A modifier, which means ALL of them - so if you for example put a +A modifier before everything else, it only makes sense to deactivate other warnings, because really all of them are now activated. We at cca.io don't use that, though. We just use the two you see above. There are even more letter-warnings, but most of them are just aliases for existing warning numbers or groups of warnings. Finally, there is an @ modifier, which does the same as + and also makes the compiler treat that specific warning as an error. If you want to list the default configuration, you can print that on the terminal via bsc -help and look under -w (or use bsc -help | grep "+a" if you are impatient). It yielded me the following on version 5.2.0:

$ bsc -help | grep "+a"
  default setting is "+a-4-6-7-9-27-29-32..39-41..42-44-45-48-50-102"

At the time of writing this post, BuckleScript comes with a whopping 62 availabe compiler warning types which have been inherited from OCaml, whereas they add another five, starting with the number 101. Here are those five BuckleScript-specific warning types (I found them in one place in the sources only, and tried to derive descriptions for them based on my usage experience).

⚠️	Type	Default	Description
101	Bs_unused_attribute	+	When a BS decorator attribute can not be applied to code underneath (Try).
102	Bs_polymorphic_comparison	-	Disallow polymorphic comparisons (i.e. using `==` on complex data structures).
103	Bs_ffi_warning	+	When a foreign function interface (FFI annotation == BS decorator) is missing. (Try).
104	Bs_derive_warning	+	When using `[@bs.deriving]` on an unsupported type (Try).
105	Bs_fragile_external	+	When using the empty `""` shorthand in external declarations to infer the JS function name from the Reason one.

As you can see, there is only one warning type deactivated by default, which is 102: Disallow polymorphic comparisons. We activated this one because when we just started writing apps in ReasonML, we used it heavily to compare deeply nested records. At some point, we stumbled over bugs where things were not equal in our minds, but the language still evaluated them so. Thus, we activated 102 and found some more possible pitfalls in our codebase. If you use it, you need to be prepared to write your own comparison functions for your data structures, or at least use the compare functions provided by the Pervasives module, or Belt's List.cmp, et cetera. Luckily, we are by far not the only ones with that mindset. It is also recommended to turn it on by the creator of BuckleScript himself, at least when you consider yourself experienced enough.

We also deactivated 105 for a current project, though that was more due to laziness to not have to change hundreds of lines of JS bindings. There were just too many warnings to cope with, after the BuckleScript upgrade to version 5.0.5.

Errors ❌

All warnings can also be treated as errors. This may disturb the developer experience, but in a continuous integration context it can be pretty useful. The programmer only needs to ensure to push code without warnings, so that the app will be built. If you feel like a 10x engineer, you can also activate it in your local coding setup. 😉

Just add the corresponding string of warnings you want to let the compiler fail on to the "error" property, like so:

  // bsconfig.json
  "warnings": {
    "error": "+8+11+12+26+27+31+32+33+34+35+39+44+45+102",
  },

The string above also happens to be the one we actually use in CI.

Flags 🏁

There is another very useful property in the bsconfig.json, the "bsc-flags", those are the parameters with which the bsc compiler is invoked by default. Most of them have pretty sane defaults, but it is still nice to know that there are lots of knobs to finetune the behaviour of the compiler. As it is the case with warnings, there are also flags derived from OCaml as well as BuckleScript-specific ones, which are prefixed with -bs.
bsc --help lists all the possible options (a load of them!), so check them out if you are interested.

Personally, I only scratched the surface of all those possibilities, but for instance you can deactivate the bs header in the compiled .bs.js files via -bs-no-version-header.
It looks like that at the top of every generated file, by default:

// Generated by BUCKLESCRIPT VERSION 5.0.4, PLEASE EDIT WITH CARE

We omit them to be able to compare output of different compiler versions (useful for beta-testing of new BS releases), and other than that, we do not feel that it's very necessary for an app you want to ship. It may be a different story for libraries which get consumed by JS.

Another useful flag is -open which requires a module name, e.g. -open Belt. This opens the given module in every Reason (or OCaml) file you are editing, so there is no need to put an

open Belt;

at the top of most files. This is especially useful, if you have a common module you want to share over the whole codebase, like some utility functions. In the case of Belt, you also cannot make the mistake anymore to use a built-in List or Array method, instead of the more idiomatic, pipe-first and camelCase Belt counterparts. This is only recommended if you are sure that you will never use the (OCaml-ish) built-ins. Personally, I don't do that yet, but I also don't really use the built-ins and could easily do the jump any time.

Speaking of Belt, let's head to the next chapter...

The Belt stdlib

When I started with Reason, I was overwhelmed by the possibilities of both the OCaml stdlib and the Belt one (Belt was also less extensive at that time). It also did not help, that you are often forced to read interface files as documentation in the OCaml world. It may be efficient, because types need to be correct which is not always the case for documentation, but if you want to lure aspiring JS devs on your type-safe boat, nothing is nicer than a pretty, tidied documentation, possibly with examples which let you dive in directly.

Luckily, the Reason Association started a big project where, among other things, the Belt documentation will be overhauled and vastly improved, extended with examples, et cetera. If you are interested, you can have a look at the current status over at the future home of ReasonML, reasonml.org or even help out and submit a PR (there are some good first issues).

Also, here on dev.to, John Jackson already wrote a pretty good series about Belt's containers, which can also help at least until the docs are finished.

The SortArray module

There is one tidbit I want to share here, and that is about how to sort Arrays with Belt. Becaues you may wonder where the sort method is (spoiler: it's not in the Belt.Array module). To keep it short: it is right in the root of the Belt module, namely Belt.SortArray. If you have an array of records, for instance users you want to sort by their last name, the idiomatic way is to provide a compare function for the User record type. The simplest compare function is a - for int, but as you learned above, a stricter approach is preferable:

module User = {
  type t = {
    firstName: string,
    lastName: string,
    id: string,
  };

  let compare = (a: t, b: t) => String.compare(a.lastName, b.lastName);
};

In the above case, we just use a simpler part of the record (the lastName, which is a string), to compare the whole user record, for instance to view it in a table sorted by last name. The String.compare function is out of the Pervasives, so it is available by default. Compare functions have to have the same signature as Pervasives.compare and return -1 (or any negative integer) when a < b, 1 (or any positive integer greater than 0) when a > b, and 0 when they are equal.

This is also the kind of function which can be consumed by SortArray, like so:

let sortUsers = (users: array(User.t)) => users->SortArray.stableSortBy(User.compare);

In this case, we use stableSortBy, which is one of the most common methods of the module, but there are many more, like intersect, diff, union or binarySearch.
Feel free to try this on an array of users in the Reason Try playground.

And that's all for this issue of my Reason(React) Best Practices blog. Next time I will shed some light on how to write zero-cost bindings to JS modules with BuckleScript.

Reason(React) Best Practices - Part 1

Florian Hammerschmidt — Fri, 20 Sep 2019 19:21:23 +0000

After using Reason with React for nearly 2 years, I decided to hold a talk about best practices with Reason and ReasonReact at the ReasonML meetup in Vienna (@reasonvienna). Given that it was my first tech talk in a tech meetup, it went pretty well. I published the slides that same day on Twitter, but slides unfortunately do not tell the full story. So I decided to give it a go and put it here in a more descriptive form. I also split it up a bit, as the talk took about one hour and I prefer to keep blog posts short and to the point.

But enough waffling, let's get into it:

The identity trick

Zero-cost React.strings!

With Reason being a 100 % type-safe language, there are some peculiarities about writing JSX in Reason which make life for beginners hard, especially when they come from JS and are used to write strings directly into a <div /> or any other React element which allows children. In Reason, the React.string method is needed everywhere where you want to render text in your app, so it makes sense to create a binding for it to a one-letter function.

You could do that by writing

let s = React.string;

but you can utilize the compiler to optimize all unnecessary parts away, by using the external keyword:

/* Shorter replacement for React.string */
external s: string => React.element = "%identity";

To compare the methods, check out this example in the ReasonML playground: ReasonML Try - 1.

As you can see, there is still a function s being created in the first example, whereas the second one is nowhere to be found. It's probably a very very small runtime improvement, but it gives a good idea of how the BuckleScript compiler works. And if you look at the sources, it is actually the same thing as the provided React.string from ReasonReact.

In either way, you probably should put the helper function in a utilities module which you can open everywhere you need those precious strings in react elements, like so:

open ReactUtils;

[@react.component]
let make = () => {
  <div>
    {s("Hello, dev.to!")}
  </div>
};

I named the module ReactUtils, because it is specifically meant for working with React elements.

Keep your codebase free of magic!

Sometimes the type system is just too strict, and in a heterogenous software system there may exist types which are completely the same thing, only with different names. With the identity trick you can convert types when they would be actually the same, for instance Js.Dict.t(string) and Js.Json.t:

type apples = Js.Dict.t(string);
type oranges = Js.Json.t;

let (apples: apples) = Js.Dict.fromArray([|("taste", "sweet")|]);

let eatFruits = (fruits: Js.Json.t) => Js.log2("Eating fruits", fruits);

eatFruits(apples);

As you can see, we have apples and oranges here. Both are fruits, as commonly known, but only oranges are actually also defined as Js.Json.t. Apples however are defined as Js.Dict.t(string) which makes the compiler throw an error (see ReasonML Try - 2).

The easiest way to make this code compile is to use Obj.magic. It basically switches the type checker off and lets the compiler do his job.

eatFruits(apples->Obj.magic);

(ReasonML Try - 3)

Obj.magic is actually also implemented by using the identity trick:

external magic : 'a => 'b = "%identity";

(see the source code).

But it is both more idiomatic (and less risky) to write a conversion function for the two specific types:

type fruits = Js.Json.t;
external applesToFruits: apples => fruits = "%identity";

eatFruits(apples->applesToFruits);

This lets your code compile and still ensures that there is only one distinct type consumed by the function and not everything. It still may make sense to use Obj.magic sometimes, especially when you just want to create a quick prototype (see ReasonML Try - 4).

Pipes

Use the Pipes like Mario!

As many (functional) languages do, also Reason provides us with a special pipe operator (->), which essentially flips the code inside out, e.g. eatFruits(apple) becomes apple->eatFruits. At first it was hard for me to read and comprehend longer pipe chains, but I got used to it after some days of using them. Now they are one of the most indispensable features to me.

Keeps you from needing to find a name for in-between variables.
Keeps code tidy.
Especially useful with Belt (BuckleScript's standard library) and its Option module which you will encounter very often as we have no null or undefined here in Reason land.
When using pipe-first (->) with, say Array.mapit makes the code look pretty similar to Js, e.g.: [|1, 2, 3|]->Array.map(x => x * 2) which would be [1, 2, 3].map(x => x * 2) in plain JS.

But just compare the two examples below, first one without using pipes:

let vehicle = Option.flatMap(member.optionalId, id => vehicles->Map.String.get(id));
let vehicleName = Option.mapWithDefault(vehicle, "–", vehicle => vehicle.name);
s(vehicleName);

vs.

member.optionalId
  ->Option.flatMap(id => vehicles->Map.String.get(id))
  ->Option.mapWithDefault("–", vehicle => vehicle.name)
  ->s

Pipe parameter position paranoia!

I know there is some war going on between the last-pipers (mostly native Reason and OCaml developers) and the first-pipers (BuckleScript developers), but in BuckleScript, because you have JS as the target language, pipe-first is the way to go. The type inference also works better that way.

If you really want to pipe into a function which is not idiomatic to BS (i.e. the positional parameter is not the first one), you can use the _ character to substitute where the piped parameter should go:

"ReasonReact"->Js.String.includes("Reason", _);

but rather use the pipe-first version of a function preferably, as long as it exists:

"ReasonReact"->Js.String2.includes("Reason");

as mentioned earlier.

Labels to the rescue!

When you have a function like String.includes where multiple parameters have the same type, it would be much better to label them directly, otherwise you won't know which of the parameters is the source string, and which one is the search string:

Even worse, if you use the wrong pipe (|>) and are unsure which parameter it takes, you can get confused easily. And the compiler cannot save you from that case, as the types are totally correct.

Here is a String.includes function binding with labels to keep you from guessing which one the positional parameter is:

module BetterString = {
  [@bs.send] external includes : (string, ~searchString: string) => bool = "includes";
};

"ReasonReact"->BetterString.includes(~searchString="Reason");

(ReasonML Try - 5)

To be fair, we now need to type a bit more, but we gain some doubtlessness and do not have to check MDN to be sure. Also, when you ignore warnings or deactivate the corresponding compiler warning (it's number 6), you could still call the function without labelling the parameter. I would still advise you to not do that, though.

That's all for the first part of Reason(React) Best Practices, our next topic will be about BuckleScript's compiler configuration and Belt.