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

[GearsDatapacks]

Anything else we need to do on this before it gets converted into an issue? I keep running into performance issues with unlabelled fields on type like Result, so I think this would be a very valuable change so we can work on improving performance.

[lpil]

I think we're ready to go!

[GearsDatapacks]

Great! I'll start working on it then

[BradBot1]

Hi! The proposed solution would break jsdoc / typing support to be introduced in 1.12 as isFirst and isSecond would not allow the ts compiler to update the type correctly.

The following code shows this:

/**
 * @typedef {object} First
 * @property {string} _0
 * @property {string} _1
 */

/**
 * @function makeFirst
 * @param {string} a
 * @param {string} b
 * @returns {First}
 */
function makeFirst(a, b) {
    return {
        _0: a,
        _1: b
    }
}

/**
 * @function isFirst
 * @param {any} value
 * @returns {boolean}
 */
function isFirst(value) {
    return true;
}

/**
 * @type {{}}
 */
const a = makeFirst("a", "b");

if (isFirst(a)) {
    console.log(a._0); // This displays an error, despite it being correct
}

This isn't something that can be fixed without instanceof checks, something the suggested solution cannot faciliate.

Rather I would suggest something like the following:

class First {
    #unnamed;
    /**
     * @param {string} _0
     * @param {number} _1
     */
    constructor(_0, _1) {
        this.#unnamed = Object.freeze([_0, _1]);
    }
    /**
     * @param {0|1} index 
     */
    getUnnamed(index) {
        return this.#unnamed[index];
    }
}

class Second {
    #unnamed;
    /**
     * @param {string} _0
     * @param {number} size
     */
    constructor(_0, size) {
        this.#unnamed = Object.freeze([_0]);
        this.size = size;
    }
    /**
     * @param {0} index 
     */
    getUnnamed(index) {
        return this.#unnamed[index];
    }
}

/**
 * @type {{}}
 */
const elem = new First("example", 1);
if (elem instanceof First) {
    console.log(elem.getUnnamed(0));
    console.log(elem.getUnnamed(1));
    console.log(elem.getUnnamed(2)); // This displays an error
} else if (elem instanceof Second) {
    console.log(elem.getUnnamed(0));
    console.log(elem.getUnnamed(1)); // This displays an error
    console.log(elem.size);
} else {
    elem.getUnnamed(0); // This displays an error
}

Ofcourse using the properties _0 and _1 are also an option but I wanted to show the other options available, jsdoc permits clear keying of literal arguments that display type hints and appropriate errors.

[lpil]

That is slow compared to named properties, so it's not an option. The primary goals here are to improve performance and to make explicit what interface to use in FFI.

[giacomocavalieri]

Version 1.12 is not generating that kind of JSDoc annotations, what did you use to generate that code? Also, that can actually be typed when generating TypeScript annotations:

function is_first(first: First) first is First

So that would not stop the compiler from being able to generate correct TypeScript annotations for a Gleam module!

[BradBot1]

Version 1.12 is not generating that kind of JSDoc annotations, what did you use to generate that code?

It's a demonstration of how jsdoc works in the proposed scenario, there is no mention of it being direct compile output?

Also, that can actually be typed when generating TypeScript annotations:

function is_first(first: First) first is First

I had (incorrectly) assumed that this would be typed as any to allow anything to be verified, but taking First as an argument here makes sense

So that would not stop the compiler from being able to generate correct TypeScript annotations for a Gleam module!

Gleam is generating TS annotations? I thought it was using JSDoc

[BradBot1]

That is slow compared to named properties, so it's not an option. The primary goals here are to improve performance and to make explicit what interface to use in FFI.

Does this mean that gleam is dropping classes all together? As they are really not performant for DTO's perf link

perf link for isFirst implementations

[GearsDatapacks]

Does this mean that gleam is dropping classes all together?

That's the idea behind this change, yes. We want to first establish an API which will work regardless of internal representation, and that will then allow us to change our internal representation to improve performance.

[yoshi-monster]

Hi! Thank you for looking into this!! I do have more thoughts on which runtime representations should be used, but I think making a stable API is an important first step to enable us to explore different representations in the first place.

When designing this API, we should consider:

• Does it limit potential optimisations in generated code?
• How much overhead is there for implementing FFI functions?
• How idiomatic is the resulting JavaScript?

I think using functions and getters for everything would be ideal for maximum flexibility. Function wrappers are extremely low-overhead since modern JS engines inline well, and separate functions might even improve performance. Using standalone functions, bundlers will remove extra code that is not needed.

Using getters as the stable public API makes sense because:

• Allows exploring unboxing single-value variants with distinct types
• Compiler can rename fields for smaller code or reduced property cache misses
• Constrains deoptimisation scope when functions handle many variants with shared field names

Of course, data and benchmarks would be needed here, but I don't like excluding this possibility from the future if we decide to stabilise the JavaScript FFI API.

Concretely, I propose that Gleam should generate and export getVariantNameFieldName functions (e.g. getOk$0 (for Ok(a)) or getUriHostname (for uri.hostname), too.

It's unsafe to assume JS values match Gleam types and vice versa even though it's a relatively wide-spread practice, so this doesn't make things worse in theory. If JavaScript consumes a value JavaScript should create it (and the other way around). Each side provides constructors/accessors for the other. This is already partially enforced by compiler warnings and best-practices.

It's already next to impossible to write JS bindings code without extra FFI wrappers, so while this does make those somewhat unusual JavaScript code, this is also somewhat expected in my opinion.

A future extension could allow marking Gleam types as external, making their runtime representation predictable and more in line with what a JavaScript library would expect.

[yoshi-monster]

Sorry this was way too rambly 😔

[BradBot1]

I think using functions and getters for everything would be ideal for maximum flexibility. Function wrappers are extremely low-overhead since modern JS engines inline well, and separate functions might even improve performance. Using standalone functions, bundlers will remove extra code that is not needed.

100%. optimising for bundlers is a a clear choice especially when gleam already requires a build step. I'd love to see this idea taken a step further with integration for automated bundling of gleam code (maybe via deno or buns native bundle subcommand if present).

As for functions for everything, that would get super messy super quickly as its possible to have multiple types with the same name in gleam. Maybe locking these methods to a class statically (Like Object.keys) could avoid the clashing as its a lot easier to rename one imported class/singleton instance than a few dozen functions.

Using getters as the stable public API makes sense because:

• Allows exploring unboxing single-value variants with distinct types
• Compiler can rename fields for smaller code or reduced property cache misses
• Constrains deoptimisation scope when functions handle many variants with shared field names

Of course, data and benchmarks would be needed here, but I don't like excluding this possibility from the future if we decide to stabilise the JavaScript FFI API.

Getters are horrendous for performance perf link and is outperformed by standard JS classes.

Concretely, I propose that Gleam should generate and export getVariantNameFieldName functions (e.g. getOk$0 (for Ok(a)) or getUriHostname (for uri.hostname), too.

Both is a lot from an importers perspective, maybe one or the other?

It's unsafe to assume JS values match Gleam types and vice versa even though it's a relatively wide-spread practice, so this doesn't make things worse in theory. If JavaScript consumes a value JavaScript should create it (and the other way around). Each side provides constructors/accessors for the other. This is already partially enforced by compiler warnings and best-practices.

Any level of checking done here is a constant performance cost on every operation, not even typescript ensures runtime validity on objects. And constant creation and destruction of objects is just performance overhead that shouldn't be required, especially when this level of strictness is not enforced in Erlang.

A future extension could allow marking Gleam types as external, making their runtime representation predictable and more in line with what a JavaScript library would expect.

I would love to see more developer type control of any kind, especially when right now opaque types cannot be created in FFI.

[yoshi-monster]

As for functions for everything, that would get super messy super quickly as its possible to have multiple types with the same name in gleam. Maybe locking these methods to a class statically (Like Object.keys) could avoid the clashing as its a lot easier to rename one imported class/singleton instance than a few dozen functions.

you cannot have multiple constructors with the same name in a single module. Adding them to a static class breaks dead code elimination in bundlers.

Getters are horrendous for performance perf link and is outperformed by standard JS classes.

Standalone getter functions as described later, not javascript getters. Sorry I thought that was clear from the context and I kinda forgot about those 😅

Anyways I told you already, this site gives you massively misleading results at best. Here are some better benchmarks:

benchmark                   avg (min … max) p75 / p99    (min … top 1%)
------------------------------------------- -------------------------------
class prop                     1.59 ns/iter   1.54 ns   █                  
                       (1.41 ns … 26.54 ns)   2.72 ns   █                  
                    (  0.10  b …  32.20  b)   0.11  b ▁▁█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
                   3.89 ipc ( 99.54% cache)    0.00 branch misses
           5.77 cycles   22.47 instructions    0.17 c-refs    0.00 c-misses

frozen prop                    1.57 ns/iter   1.54 ns █                    
                       (1.52 ns … 28.80 ns)   2.66 ns █                    
                    (  0.10  b …  37.70  b)   0.10  b █▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
                   3.91 ipc ( 99.76% cache)    0.00 branch misses
           5.75 cycles   22.47 instructions    0.17 c-refs    0.00 c-misses

prop                           1.60 ns/iter   1.54 ns   █                  
                       (1.41 ns … 35.73 ns)   3.05 ns  ▄█                  
                    (  0.10  b …  44.56  b)   0.10  b ▁██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
                   3.86 ipc ( 99.65% cache)    0.00 branch misses
           5.83 cycles   22.47 instructions    0.17 c-refs    0.00 c-misses

object getter                 14.14 ns/iter  13.63 ns  █                   
                      (13.20 ns … 47.95 ns)  22.93 ns  █                   
                    (  0.10  b …  54.87  b)   0.13  b ▁█▁▂▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
                   3.40 ipc ( 98.28% cache)    0.01 branch misses
          49.48 cycles  168.26 instructions    0.19 c-refs    0.00 c-misses

int class prop                 2.23 ns/iter   2.18 ns    █                 
                       (2.00 ns … 37.59 ns)   3.38 ns    █                 
                    (  0.10  b …  52.72  b)   0.11  b ▁▁▂█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
                   3.92 ipc ( 99.70% cache)    0.00 branch misses
           8.05 cycles   31.52 instructions    0.17 c-refs    0.00 c-misses

objects getters are over one order of magnitude slower, not approximately 20% - which is the number I get as an average when running that perf link a bunch of times. This benchmark is also kinda bad for obvious microbenchmark reasons and doesn't generalise (this is v8, JSC produces widely different results!), but I claim these numbers are more accurate than what that website reports.

Concretely, I propose that Gleam should generate and export getVariantNameFieldName functions (e.g. getOk$0 (for Ok(a)) or getUriHostname (for uri.hostname), too.

Both is a lot from an importers perspective, maybe one or the other?

I don't think that matters much. You can use wildcard imports, there's editor tooling to help you, and FFI code should not be something you need to interact with often.

Any level of checking done here is a constant performance cost on every operation, not even typescript ensures runtime validity on objects. And constant creation and destruction of objects is just performance overhead that shouldn't be required, especially when this level of strictness is not enforced in Erlang.

I'm not talking about runtime type checking here, I don't know where you're getting that from.

I would love to see more developer type control of any kind, especially when right now opaque types cannot be created in FFI.

You can either define that type fully FFI, at which point Gleam doesn't know what it is, or as internal. I think both options are fine. I don't think there's much need to add something like external to types, but it's nice to know there might be options.

[andho]

In regard to "getters" If the goal is not to interface with Gleam code in JS land except for FFI, this is fine. But if someone is consuming Gleam code in primarily JS codebase, it does make the code very long:

getWibbleWobble(wibble)   // VS
wibble.wobble

But, getters are inline with how gleam does things and keeps the internal implementation details flexible and allows for optimization so begrudgingly agree with using getters.

Also there needs to be a way to access common fields across variants. So getFieldName (without variant) for common fields?

[lpil]

Defining getter functions does seem quite smart and in-keeping with the rest of the API. It would be more awkward for JavaScript to consume, but I think it's already quite awkward here so that's no so much of a problem.

[Norlock]

Just small things that might be useful:

const someObj = { ... }
const obj = Object.assign(new Item(), someObj)

To convert easily from object to class (maybe for inside ffi's)?.

And for object comparison, because everything is autogenerated anyway you can do something like this which also really improves performance of object comparisons:

function createThingyFirst(a, b) {
  return {
     _id: (autoincrement case id here), 
    "one":a , 
    "two":b,
  }
} 

[yoshi-monster]

1. This is easy, but slow.
2. This does not change anything. Pointers and numbers both compare a single word. Gleam implements structural equality, so just tracking ids is not enough.

[Norlock]

No but every case gets its own index.

IsFirst => _id ==0 && value equals
IsSecond => _id ==1 && value equals.

And to improve even more you can create an object with the index as key and immediately retrieve the correct case function so you dont even have to compare on index

[BradBot1]

That would technically enforce a limit on the amount of objects that can exist in a programs lifetime. For unique values that represent bespoke elements use local Symbols in JS, it would do the same thing as your counter but with runtime guarantees

[Norlock]

Ok interesting, so it would be something like:

function First(one, two) { 
  this. _id = Symbol.for("Thingy.First");
  this.one = one;
  this.two = two;
}

const first = new First(3, "four");

That would be pretty clean and fast.

Here some more elaborate code:

function First(one, two) {
  this._id = Symbol.for("Thingy.First")
  this.one = one;
  this.two = two;
}

function Second(field_0, field_1) {
  this._id = Symbol.for("Thingy.Second")
  this._0 = field_0;
  this._1 = field_1;
}

function isFirst(obj, other) {
  return obj.one == other.one && obj.two == other.two;
}

function isSecond(obj, other) {
  return obj._0 == other._0 && obj._1 == other._1;
}

const a = new First(12, "aaa");
const b = new First(12, "aaa");

function isThingyEqual(obj, other) {
  switch (obj._id) {
     case Symbol.for("Thingy.First"): 
        return isFirst(obj, other);
     case Symbol.for("Thingy.Second"):
        return isSecond(obj, other);
   }
}

console.log("is equal", isThingyEqual(a, b));