Record

Records are like JavaScript objects but:

• are immutable by default

• have fixed fields (not extensible)

Type Declaration

A record needs a mandatory type declaration:

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

Creation

To create a person record (declared above):

let me = {
  age: 5,
  name: "Big ReScript"
}

When you create a new record value, ReScript tries to find a record type declaration that conforms to the shape of the value. So the me value here is inferred as of type person.

The type is found by looking above the me value. Note: if the type instead resides in another file or module, you need to explicitly indicate which file or module it is:

// School.res
type person = {age: int, name: string}

// Example.res

let me: School.person = {age: 20, name: "Big ReScript"}
/* or */
let me2 = {School.age: 20, name: "Big ReScript"}

In both me and me2 the record definition from School is found. The first one, me with the regular type annotation, is preferred.

Access

Use the familiar dot notation:

let name = me.name

Immutable Update

New records can be created from old records with the ... spread operator. The original record isn't mutated.

let meNextYear = {...me, age: me.age + 1}

Note: spread cannot add new fields to the record value, as a record's shape is fixed by its type.

Mutable Update

Record fields can optionally be mutable. This allows you to efficiently update those fields in-place with the = operator.

type person = {
  name: string,
  mutable age: int
}

let baby = {name: "Baby ReScript", age: 5}
baby.age = baby.age + 1 // `baby.age` is now 6. Happy birthday!

Fields not marked with mutable in the type declaration cannot be mutated.

JavaScript Output

ReScript records compile to straightforward JavaScript objects; see the various JS output tabs above.

Optional Record Fields

ReScript v10 introduced optional record fields. This means that you can define fields that can be omitted when creating the record. It looks like this:

type person = {
  age: int,
  name?: string
}

Notice how name has a suffixed ?. That means that the field itself is optional.

Creation

You can omit any optional fields when creating a record. Not setting an optional field will default the field's value to None:

type person = {
  age: int,
  name?: string
}

let me = {
  age: 5,
  name: "Big ReScript"
}

let friend = {
  age: 7
}

This has consequences for pattern matching, which we'll expand a bit on soon.

Immutable Update

Updating an optional field via an immutable update above lets you set that field value without needing to care whether it's optional or not.

type person = {
  age: int,
  name?: string
}

let me = {
  age: 123,
  name: "Hello"
}

let withoutName = {
  ...me,
  name: "New Name"
}

However, if you want to set the field to an optional value, you prefix that value with ?:

type person = {
  age: int,
  name?: string
}

let me = {
  age: 123,
  name: "Hello"
}

let maybeName = Some("My Name")

let withoutName = {
  ...me,
  name: ?maybeName
}

You can unset an optional field's value via that same mechanism by setting it to ?None.

Pattern Matching on Optional Fields

Pattern matching, one of ReScript's most important features, has two caveats when you deal with optional fields.

When matching on the value directly, it's an option. Example:

type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let isRescript = switch me.name {
| Some("ReScript") => true
| Some(_) | None => false
}

But, when matching on the field as part of the general record structure, it's treated as the underlying, non-optional value:

type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let isRescript = switch me {
| {name: "ReScript"} => true
| _ => false
}

Sometimes you do want to know whether the field was set or not. You can tell the pattern matching engine about that by prefixing your option match with ?, like this:

type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let nameWasSet = switch me {
| {name: ?None} => false
| {name: ?Some(_)} => true
}

Record Type Spread

In ReScript v11, you can now spread one or more record types into a new record type. It looks like this:

RESCRIPT
type a = {
  id: string,
  name: string,
}

type b = {
  age: int
}

type c = {
  ...a,
  ...b,
  active: bool
}

type c will now be:

RESCRIPT
type c = {
  id: string,
  name: string,
  age: int,
  active: bool,
}

Record type spreads act as a 'copy-paste' mechanism for fields from one or more records into a new record. This operation inlines the fields from the spread records directly into the new record definition, while preserving their original properties, such as whether they are optional or mandatory. It's important to note that duplicate field names are not allowed across the records being spread, even if the fields have the same type.

Record Type Coercion

Record type coercion gives us more flexibility when passing around records in our application code. In other words, we can now coerce a record a to be treated as a record b at the type level, as long as the original record a contains the same set of fields in b. Here's an example:

RESCRIPT
type a = {
  name: string,
  age: int,
}

type b = {
  name: string,
  age: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  name: "Name",
  age: 35,
}

let name = nameFromB(a :> b)

Notice how we coerced the value a to type b using the coercion operator :>. This works because they have the same record fields. This is purely at the type level, and does not involve any runtime operations.

Additionally, we can also coerce records from a to b whenever a is a super-set of b (i.e. a containing all the fields of b, and more). The same example as above, slightly altered:

RESCRIPT
type a = {
  id: string,
  name: string,
  age: int,
  active: bool,
}

type b = {
  name: string,
  age: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  id: "1",
  name: "Name",
  age: 35,
  active: true,
}

let name = nameFromB(a :> b)

Notice how a now has more fields than b, but we can still coerce a to b because b has a subset of the fields of a.

In combination with optional record fields, one may coerce a mandatory field of an option type to an optional field:

RESCRIPT
type a = {
  name: string,

  // mandatory, but explicitly typed as option<int>
  age: option<int>,
}

type b = {
  name: string,
  // optional field
  age?: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  name: "Name",
  age: Some(35),
}

let name = nameFromB(a :> b)

Tips & Tricks

Record Types Are Found By Field Name

With records, you cannot say "I'd like this function to take any record type, as long as they have the field age". The following won't work as intended:

type person = {age: int, name: string}
type monster = {age: int, hasTentacles: bool}

let getAge = (entity) => entity.age

Instead, getAge will infer that the parameter entity must be of type monster, the closest record type with the field age. The following code's last line fails:

RES
let kraken = {age: 9999, hasTentacles: true}
let me = {age: 5, name: "Baby ReScript"}

getAge(kraken)
getAge(me) // type error!

The type system will complain that me is a person, and that getAge only works on monster. If you need such capability, use ReScript objects, described here.

Optional Fields in Records Can Be Useful for Bindings

Many JavaScript APIs tend to have large configuration objects that can be a bit annoying to model as records, since you previously always needed to specify all record fields when creating a record.

Optional record fields, introduced in v10, is intended to help with this. Optional fields will let you avoid having to specify all fields, and let you just specify the one's you care about. A significant improvement in ergonomics for bindings and other APIs with for example large configuration objects.

Design Decisions

After reading the constraints in the previous sections, and if you're coming from a dynamic language background, you might be wondering why one would bother with record in the first place instead of straight using object, since the former needs explicit typing and doesn't allow different records with the same field name to be passed to the same function, etc.

1. The truth is that most of the times in your app, your data's shape is actually fixed, and if it's not, it can potentially be better represented as a combination of variant (introduced next) + record instead.

2. Since a record type is resolved through finding that single explicit type declaration (we call this "nominal typing"), the type error messages end up better than the counterpart ("structural typing", like for tuples). This makes refactoring easier; changing a record type's fields naturally allows the compiler to know that it's still the same record, just misused in some places. Otherwise, under structural typing, it might get hard to tell whether the definition site or the usage site is wrong.