microstates / microstates.js / 350

99%

push

travis-ci

Introduce chaining API. (#62)

The funcadelic function signatures for `map`, `filter`, and `foldl`
don't read well in JavaScript when you start composing them a lot in a
single place.

The filter -> map -> filter operation that's happening here in this
pipeline isn't really captured by the way the code reads.

```js
let methods = filter(({ value }) => isFunctionDescriptor(value), descriptors);
let transitionFns = filter(
  ({ key }) => key !== 'constructor',
  map(({ value }) => value, methods)
);
```

The flow of data is.

1. filter out everything that isn't a function descriptor
2. map the descriptor to the actual function
3. filter out the 'constructor' function

To follow this flow in the code though, you have to start on line 1,
but then jump to line 4, then jump back up to line 2.

When you're reading the code for the first time (or a second, or a
third), it makes an already difficult task that much harder. We're
doing some amazingly complex and subtle transformations to these
structures, so the least we can do is highlight the steps involved.

This introduces a chaining API so that code flow can follow transform
flow. By making the transform (chain) itself a first class entity, we
can track it directly. So for example, the above code becomes:

```
let transitionFns = $(descriptors)
  .filter(({ value }) => isFunctionDescriptor(value))
  .map(({ value }) => value)
  .filter(({ key }) => key !== 'constructor')
  .valueOf();
```

And the flow of the transform (filter -> map -> filter) becomes
illuminated.

As a nice knock-on effect, it also addresses the problem of forgetting
the "subject" of a `map` or a `filter`. When you're mapping, you're
usually so focused on the transform itself that you often forget to
include what you're mapping over, which results in weird runtime
errors.

With the chaining API, you "capture" your subject at the very
beginning, and you hold onto it with each transformatio... (continued)

78 of 78 branches covered (100.0%)

Branch coverage included in aggregate %.

173 of 175 relevant lines covered (98.86%)

1236.82 hits per line