Enable improvement of JavaScript custom type performance now and in future

[lpil]

The JavaScript code we generate for custom types could be changed to improve performance with current JavaScript engines, and future changes to JavaScript engines may motivate further changes.

It's hard to make changes today as we have not made clear what the intended interface is for JavaScript code using Gleam data structures. I propose we create and document an interface for external code authors to use which will give them sufficient control while being abstract enough to permit changes to the underlying data structures.

Code generated by the Gleam compiler could opt to work directly with the underlying data structures if there is a performance benefit to that, but we would document that to do the same in external code is to use private APIs and could result in breakages in future.

I believe these to be the required capabilities:

• Construct custom type variants
• Check whether a value is of a specific variant
• Access labelled field values
• Access unlabelled field values

Proposed API

Construction

For each variant provide a makeVariantName function which takes the field values and returns the constructed record.

Variant checking

For each variant provide a isVariantName function which return a boolean indicating if the argument is of the specific variant.

Access labelled fields

The typical JavaScript .label syntax can be used to access these fields. It is presumed that property access like this will continue to be very fast in JavaScript due to how common it is and thus important to engines.

Access unlabelled fields

The ._0, ._1, ._2 syntax can be used to access these fields. This is to be used instead of [0] as these string keys benchmark faster than number indexing, and the same assumption about future performance is made here.

Example

pub type Thingy {
  First(one: Int, two: String)
  Second(String, Int)
}

// The public interface we provide
const makeFirst = (one, two) => ...
const isFirst = (value) => ...

const makeSecond = (x1, x2) => ...
const isSecond = (value) => ...

import { isFirst, isSecond } from "./the/gleam/module.mjs"

// Example usage by JS code
export function main(x) {
  if (isFirst(x)) {
    return x.two
  }

  if (isSecond(x)) {
    return x._0
  }

  throw new Error("Unexpected value")
}

[GearsDatapacks]

I think that sounds good. I haven't done a whole lot of FFI yet so I'm not sure if there are any other APIs we want to expose, but seems like a good set of functions so far

[giacomocavalieri]

Yeah and I think it's best to start exposing as little as possible, we can always add new things later if we realise something is missing