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,
}

You can also nest definitions of records.

type nestedPerson = {
  age: int,
  name: string,
  notificationSettings: {
    sendEmails: bool,
    allowPasswordLogin: bool,
  },
}

let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
}

Nesting record definitions is a nice way to group records that are part of the same structure, and won't be referenced from the outside.

If you end up needing to refer to a nested record type explicitly, you should make it an explicit definition instead of a nested one. This is mainly for 2 reasons:

• The records that are automatically generated for the nested record definitions are named in a way that would require you to use escaped identifiers to reference them. The nested record at notificationSettings above would be named \"person.notificationSettings" for instance

• For the sake of clarity (and caring about your co-workers), having an explicit and named definition to look at and refer to is much easier than scanning a potentially large record definition for the nested record you're looking for

So if we in the example above ended up needing to refer to person.notificationSettings nested record from the outside, we should instead make it explicit, just like how we normally define records:

type personNotificationSettings = {
  sendEmails: bool,
  allowPasswordLogin: bool,
}

type explicitPerson = {
  age: int,
  name: string,
  notificationSettings: personNotificationSettings
}

let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
}

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 schoolPerson = {age: int, name: string}

// Example.res

let me: School.schoolPerson = {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

Destructuring Record Rest

You can destructure individual fields and capture the remaining fields as another record. Declare a type for the remaining fields, then use ...typeName as bindingName in the pattern:

type contact = {name: string, email: string, active: bool}
type contactDetails = {email: string, active: bool}

let contact = {name: "Ada", email: "ada@example.com", active: true}
let {name, ...contactDetails as details} = contact

Console.log(name) // "Ada"
Console.log(details.email) // "ada@example.com"

Here, contactDetails is a type, while details is the new value containing email and active, but not name. Unlike JavaScript's {name, ...details}, ReScript requires the rest record type to be declared; it does not infer a new record type from the leftover fields.

The rest type must describe the remaining fields with compatible types and optionality. You can use a type from another module, such as ...ContactDetails.t as details. A pattern can contain only one rest element.

Record rest patterns cannot be used on source records with mutable fields or with unboxed record types.

Pattern Matching and Function Parameters

Record rest also works in switch cases and function parameter patterns:

type contact = {name: string, email: string, active: bool}
type contactDetails = {email: string, active: bool}

let describeContact = (contact: contact) => {
  switch contact {
  | {name: "Ada", ...contactDetails as details} =>
    `Contact Ada at ${details.email}`
  | {name, ...contactDetails as details} =>
    `Contact ${name} at ${details.email}`
  }
}

let getDetails = ({name: _, ...contactDetails as details}: contact) => details

In the first case, name: "Ada" matches a particular value. In the second, name binds any other name. Both cases capture the remaining fields in details. In getDetails, name: _ excludes name without binding it.

Record rest creates a new record without mutating the original. The copy is shallow: nested objects are still shared. This differs from record type coercion, which changes only the type and keeps the original value, and from immutable update, which creates a new value of the same record type.

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 mutablePerson = {
  name: string,
  mutable age: int
}

let baby: mutablePerson = {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 optionalPerson = {
  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 optionalPerson = {
  age: int,
  name?: string
}

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

let friend: optionalPerson = {
  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 personWithOptionalName = {
  age: int,
  name?: string
}

let me: personWithOptionalName = {
  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 personWithOptionalName = {
  age: int,
  name?: string
}

let me: personWithOptionalName = {
  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 matchedOptionalPerson = {
  age: int,
  name?: string,
}

let me: matchedOptionalPerson = {
  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 matchedOptionalRecord = {
  age: int,
  name?: string,
}

let me: matchedOptionalRecord = {
  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 matchedOptionalPerson = {
  age: int,
  name?: string,
}

let me: matchedOptionalPerson = {
  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:

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

type b = {
  age: int
}

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

type c will now be:

RES
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:

RES
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:

RES
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.

Coercion requires matching field optionality. In ReScript 12, a mandatory option<int> field cannot be coerced directly to an optional int field. Construct the target record explicitly instead:

RES
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 b: b = {name: a.name, age: ?a.age}
let name = nameFromB(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
// This example intentionally rejects the second call to getAge.
type person = {age: int, name: string}
type monster = {age: int, hasTentacles: bool}
let getAge = entity => entity.age

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

Why use records instead of objects?

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.