UI: Computed Utils

[johncowen]

This PR includes 2 computed utils, 1 is taken pretty much for the ember source (details in the documentation comments), for the other I'll quote Tom Dale in a recent RFC which he describes what this PR goes some way to solve as 'Dependency Hell'

First, it's annoying to have to type every property twice: once as a string as a dependent key, and again as a property lookup inside the function. While explicit APIs can often lead to clearer code, this verbosity often obfuscates the intent of the property. People understand intuitively that they are typing out dependent keys to help Ember, not other programmers.

Second, people tell us that this syntax is not very intuitive. You have to read the Ember documentation at least once to understand what is happening in this example.

It's also not clear what syntax goes inside the dependent key string. In this simple example it's a property name, but nested dependencies become a property path, like 'person.firstName'. (Good luck writing a computed property that depends on a property with a period in the name.)

You might form the mental model that a JavaScript expression goes inside the string—until you encounter the {firstName,lastName} expansion syntax or the magic @ each syntax for array dependencies.

The truth is that dependent key strings are made up of an unintuitive, unfamiliar microsyntax that you just have to memorize if you want to use Ember well.

Lastly, it's easy for dependent keys to fall out of sync with the implementation, leading to difficult-to-detect, difficult-to-troubleshoot bugs.

Tom proposes the use of decorators to solve this entirely (with caveats), which might be coming at some point soon, in the meantime at least the below is something I find helpful.

The purify function here essentially let's you write:

property: computed(
  'something', 'else',
  function(something, else) {
   return `${something}-${else}`;
  }
)

This does/doesn't let you do certain things:

1. It doesn't stop you having to type the same things twice, but it does let you refer to them as you'd like to in your pure function. (I might like to call the something property anything in my function, I just rename the argument here)
2. If you refrain from using get and keep your computed function pure, it goes some way to stop the 'dependency hell'.
3. We are typing out the dependent keys here because we need to use them not to 'help Ember', if you miss one out you are more likely to notice/know about it. The dependent keys are less likely to fall out of sync with the implementation.
4. It's intuitive and familiar. You pass some arguments in and return something made from those arguments, a nice pure idiomatic function.
5. It uses idiomatic ES5, (but you could also use arrow functions or whatever here)

There are no tests to accompany this yet at least:

1. The factory function is taken straight from the ember source, and is one of those things that is hardly worth testing.
2. I ummed and ahhed about writing tests for the purify function and I could do at this stage if anyone feels strongly that I should at this stage. Again its one of those functions that is hardly worth testing, but more so than the factory function. See the comments regarding support deeper properties, if I was to implement that I would probably accompany that with some tests as they then would be more worthwhile.

[johncowen]

Just had a thought this morning, the purify thing enables using default arguments which might be nice at some point?

property: computed(
  'items',
  function(possiblyEmpty = []) {
   return possiblyEmpty;
  }
)

[hanshasselberg]