elm-optimize-level-2/transformations.md

# Overview of Transformations

This is an overview of the transformations for `elm-optimize`.

Not all of them made the cut, but seeing that a transformation is not as effective as initially thought is really good information.

We got a huge head start because of [Robin's article](https://dev.to/skinney/improving-elm-s-compiler-output-5e1h).

Each transformation also has a rough summary of impact.


# Applying Functions Directly

Elm wraps functions in an object that tracks how many arguments the function takes(also known as 'arity').

This is so that functions can be partially applied, meaning you can apply a few arguments and get a new function that has those arguments "built in".


The most significant speedups we've seen is in finding places where we can skip the wrapper and call the actual function directly.  This happens when you call a function with exactly the number of arguments it needs.


In order to do this, we need to adjust function declarations so that the original function can be called either in the standrd 'wrapped' way, or directly.


before

```js
var MyFunction = F2(function (tag, value) {
        return value;
});
```

after

```js
var MyFunction_fn = function (tag, value) {
        return value;
}, MyFunction = F2(MyFunction_fn);
```


Then, if this function is called with `A2, we can unwrap the wrapper and call the function directly.

before
```js
A2(MyFunction, one two)
```

after
```js
MyFunction_fn(one two)
```

## Results Summary

- Included in `elm-optimize` tool**
- Potentially large positive effect on speed
- Likley small but positive effect on asset size

This has lead to dramatic speedups in some cases, especially when a large number of smaller functions are called and the overhead of calling twice as many functions is significant.

As well, it has a really interesting characteristic in that it makes the initial size of the generated JS **larger**, but usually results in a **smaller** minified asset size.

We generate two definitions for a function, but in most cases a function is either always partially applied, or always called with the full number of arguments.

If a function is always called with the full number of arguments, the minifier can eliminate our wrapped version (`F2(MyFunction_fn)`) and *also* eliminate the `A2` call, which is explicitly smaller than before.

# Direct call of Lambdas

Similar to the above, but focused on lambdas.

Let's say we have some elm code that produces the following js.

```js
var f = function(func, a, b) {
    return A2(func, a, b)
};

f(F2(function (a,b) {return a + b;}), 1, 2);
```

we can transform it to 
```js
var f = function(func, a, b) {
    return A2(func, a, b)
}, f_unwrapped = function(func, a, b) {
    return func(a, b)
};

f_unwrapped(function (a,b) {return a + b;}, 1, 2);
```




# Passing in Unwrappable Functions to Higher Order Functions

**Future Work**

Higher order functions like `List.map` have a hard time taking advantage of the direct function calls because we don't know the arity of the function within the `List.map` call.

However, we can figure it out.

If `List.map` is called with a function that we know has an arity





# Making type representation isomorphic

Currently the Elm compiler will generate objects that match the shape of a given type.

`Maybe` looks like this:

```js
var elm$core$Maybe$Just = function(a) {
  return { $: 0, a: a };
};

var elm$core$Maybe$Nothing = { $: 1 };
```

However, the V8 engine is likely better able to optimize these objects if they have the same shape.

So, this transformation fills out the rest of the variants with `field: null` so that they have the same shape.

```js
var elm$core$Maybe$Just = function(a) {
  return { $: 0, a: a };
};

var elm$core$Maybe$Nothing = { $: 1, a: null };
```

This does require information from the Elm code itself, which we're currently getting through `elm-tree-sitter`.


## Results Summary

- Included
- Has an effect in certain circumstances in browsers using V8(Chrome and Edge).  Nothing observable otherwise.
  - Most prominently observed in the `Elm Core - sum 300 list of custom types` benchmark.  Otherwise I didn't notice it.
- No noticable effect on asset size.



# Inlining literal list constructors

Before

```js
_List_fromArray(['a', 'b', 'c']);
```

After, using `InlineMode.UsingConsFunc`

```js
_List_cons('a', _List_cons('b', _List_cons('c', _List_Nil)));
```

with `InlineMode.UsingLiteralObjects`

```js
({ $: 1, a: 'a', b: { $: 1, a: 'b', b: { $: 1, a: 'c', b: _List_Nil } } });
```

*Note* - Elm actually had this originally(the literal objects verion)! But there's an issue in Chrome with more than 1000 elements.

There's also tradeoff between asset size and speed.

Also of note, becaue `_List_fromArray` is used for lists of *anything*, that it's likely being deoptimized by the javascript compiler.

There may be a nice trade off here of using `InlineMode.UsingConsFunc`, but only inlining at most 20 elements or something, and then using `List_fromArray` after that.


## Results Summary

- Not included in the elm-optimize tool because it was hard to find a benchmark that reported numbers to justify it.
- Though maybe we just need to be better at benchmarking it



# Object Update

When updating a record in elm via `{ record | field = new }`, elm runs the following function:

```javascript
function _Utils_update(oldRecord, updatedFields) {
    var newRecord = {};
    for (var key in oldRecord) {
        newRecord[key] = oldRecord[key];
    }
    for (var key in updatedFields) {
        newRecord[key] = updatedFields[key];
    }
    return newRecord;
}

```

We tried a few different variations in order to see if we could speed this up.

The trick here is that we need to copy the entire record so that it has a new reference.

So, we can't just do `record.field = new` in the js.

All of these tricks rely on either the spread operator or `Object.assign`, both of which are not supported in IE.


## Replacing the implementation of `_Util_update`:

Spread operator

```javascript 
const _Utils_update = (oldRecord, updatedFields) => {
    var newRecord = {...oldRecord};
    
    for (var key in updatedFields) {
        newRecord[key] = updatedFields[key];
    }
    return newRecord;
}
```

Spread for both

```javascript
const _Utils_update = (oldRecord, updatedFields) => ({...oldRecord, ...updatedFields});
```

Use Object.assign
```javascript
const _Utils_update = (oldRecord, updatedFields) => (Object.assign({}, oldRecord, updatedFields));
```

## Inline the call altogether

At the call site, replace

```
_Utils_update(old, newFields)
```
with
```
Object.assign({}, old, newFields)
```

## Result Summary

- Not included in elm-optimize tool
- Again, all of these tricks rely on either the spread operator or `Object.assign`, both of which are not supported in IE.
- The most promising approach was inlining the call completely with `Object.assign`.
  - Gave a `366%` boost in chrome!
  - And caused firefox to reduce performance by 50% :sweat_smile:

Simply creating a new record and copying each field manually is significantly faster than and of these transformations.(~9x in chrome, and ~6.5x in firefox).  You can do this directly in elm.

```
updateSingleRecordManually record =
    { one = 87
    , two = record.two
    , three = record.three
    }
```

It's worth exploring automating this transformation, though of course there's a question of how much this affects asset size on larger projects.

However, it's hard to explore further without knowing the actual shape of the records being updated.



# Inline Equality

If Elm's `==` is applied to any primitive such as:
  - Int
  - Float
  - String
  - Bool

Then we can inline the definition directly as `===`.

Right now `elm-optimize` will infer if something is a primitive if a literal is used.

## Results Summary

- Included in `elm-optimize` tool.
- Looks to have the most impact on code that does a lot of equality comparisons, like parsing.

The `_Utils_eq` function is very likely deoptimized because it can take *any* two values and either do a reference check, or do structural equality, which we also know takes a while.

So, my guess is the benefit here is from avoiding the call to a deoptimized function completely.

Chrome doesn't really see a speedup here though, so it's likely smart enough to do that already.



# Inline String.fromFloat/Int


Before

```
String$fromFloat(val)
```

After:

```
val + ""
```

## Results Summary

- Not included in the tool

This hasn't shown any measureable benefit.  Likel because this is a very simple function that always takes a single number and returns a string that the JS runtime is optimizing it as much as possible already.




# Arrowizing Functions

Before

```
var x = function(x){}
```
After
```
var x = (x) => {}
```

This was done for asset size.


## Results Summary

- Not included in the `elm-optimize` tool
- There does seem to be a slight asset size reduction.
- The inline-functions transformation has a larger shrinking impact on asset size.
- Comes with the caveat that the [code will not work on IE](https://caniuse.com/#feat=arrow-functions)

We didn't include this in the first version of the tool because the effect seems to be so modest and carries the risk of breaking things on IE.

We would have to add something like a `--modernize` or `--no-ie` flag to the tool, and I really like this tool having no configurability.


# Hoisting Constants

**Future Work**

This transformation hasn't been attempted yet, but the idea is that if a constant is detected in a let statement, it can be declared moved to top-level instead of recalculated every function run.