The Avo Rescript Style Guide

At Avo we use Rescript as our primary programming language. To allow the development team to deliver better code and reviews, we've come up with a set of guidelines:

1. All file names, just like modules, should be in PascalCase: EventsList.res
2. Define meaningful types for every variant and polymorphic variant you introduce. For example, when defining MergeBranch you would create type branchName = string and the definition would look like: MergeBranch(branchName) instead of MergeBranch(string)
3. Define type signatures explicitly unless you're sure that they should not be defined. Even when the compiler can infer the type it still is often useful to state it explicitly for readability of the code, especially outside of the IDE and to help the compiler to produce better error messages during refactoring.
4. Use named parameters if a function has multiple parameters of same type. This will prevent accidentally mixing up the parameters when calling the function.
5. Tend to use named parameters more often. This is advised for readability.
6. Imperative code (i.e. the ref keyword) should be used only with a very strong reason.
7. Default to using non polymorphic variants (type rgb = Red | Green | Blue over type rgb = [#red | #green | #blue]). We think of polymorphic variants as a lesser-typed approach and prefer to have stronger types.
8. Usage of polymorphic is not discouraged. However have in mind that they should always be used strictly typed, if possible. They can be utilised to various benefits, such as

• Directly mapping to strings in JS (#myString in res -> "myString" in JS or even #"my string" in res -> "my string"` in JS)
• Powerful, categorised switching (#...partialType => doSomething()) when used with combined types (See docs)
• In regards to structural sharing (See docs) where the fact that polymorphic variants don't have a source of truth for their type. Beware that this is just as much a con as it can be a pro and use with care.

1. Polymorphic variants should be camelCase. #success rather than #Success.

2. Non polymorphic variants should be PascalCase. MergeBranch rather than mergeBranch.

3. Encapsulate internal code with the $$private(...) block, so the public interface of a module is clear and the internal code is not leaked into the public scope.

4. Prefer using uncurried functions over curried (i. e. reduceU over reduce in Belt.List*)*, it will help the compiler to produce cleaner error messages in cases when there is a parameters mismatch, which happens quite often during refactoring. Another benefit is that it performs better in runtime.

5. Put multiline styles in the top of the file.

6. When deciding between thing->function->function and function(thing)->function read it out and pick the one that makes more sense in a natural language, i.e. Firebase.firestore(firebase)->Firebase.root("main") and maybeSomething->Belt.Option.getWithDefault("definitelySomething").

7. When working with JSON create decoders and encoders with the bs-json lib

   Json.Decode.(field("token", string, "myToken"))
   
   Json.Encode.(object_([
                 ("token", string("myToken")),
                 ("returnSecureToken", bool(true)),
               ])

   see more about using variants and this blog post for more examples.

   We tried other approaches but they all tend to end up with similar amount of work and less constrol.

8. When defining functions keep the types definition in the function, not in the variable, to allow more freedom for type inferrence, i.e. let a = (b: string, c: int): string => b === "ok" over let a: ((string, int) => boolean) = (b, c) => b === "ok"

9. ALWAYS use Js.Array2 and Js.String2. NEVER use Js.Array and Js.String. This is required to keep the -> piping consistent. A nice suggestion of how to achieve that can be found here #2

10. Use Lists for resursive data structures. Use Array otherwise. I.e.

let rec len = (myList: list('a)) =>
  switch myList {
    | [] => 0
    | [_, ...tail] => 1 + len(tail)
  }

1. Do not overuse reduce. Consider other options, like map and flatMap to achieve the result. Prefer reduce over ref though.
2. Open Belt globally. It saves a lot of typing.
3. Prefer Belt.Result over throwing exceptions. This would make the execution flow more homogeneous. Exceptions are generally considered to be avoided nowadays.
4. Don't put more than 3 React components in a single file. Use separate files for big components or components that are used in multiple places.
5. Use rescript-promise(Promise.then(…)) over Js.Promise. The bindings are nicer, have stricter error handling and are recommended as of Rescript 10.1.
6. If you want to use open locally, use it inside a function.

Firebase Cloud Functions

When creating cloud functions, only define a single function in a file, defined as let handle = {...}

In Index.re (which relates to index.js required by google cloud functions) refer to the function with [Type of Trigger][Name of Function] = File.handle

Types of Triggers

• trigger (Firestore document trigger)
• https
• pubsub

Example:

let httpsGetCustomers = GetCustomersEndpoint.handle
let triggerOnCustomerAdded = OnCustomerAdded.handle
let pubsubDeleteUserData = DeleteUserData.handle

The name defined here will be the name of the cloud function itself and helps us to easily map code with function for debugging and logging.