Better error messages

[blast-hardcheese]

Problem:

Missing operationId is not a useful error message, especially with particularly large specification files.

--

Given:

class Foo(val a: Bar)
class Bar(val b: Baz)
class Baz(val c: String)

the following will compile:

val result: Tracker[Option[String]] =
  Tracker(foo).downField("b", _.b).flatDownField("c", _.c)

there are a number of combinators borne of necessity, though my intent that it should be possible to write Traverse and Monoid instances for these structures, which may simplify syntax a bit.

I've broken out IndexedFunctor and IndexedDistributive, as well as some syntax around these combinators, but that permitted a significant reduction in bespoke syntax extensions.

The intent of opening this PR is to get feedback on this approach, as well as to publicize the fact that this is coming, in case others plan on doing major refactors.

Contributing to Twilio

All third-party contributors acknowledge that any contributions they provide will be made under the same open-source license that the open-source project is provided under.

• I acknowledge that all my contributions will be made under the project's license.

[blast-hardcheese]

OK, ready for review. There are many more warnings around .get, but this is to track the process of infecting more functions with Tracker. Everywhere there's a .get currently, there's an opportunity to provide better error messages, as we're unwrapping the Tracker directly without showing its history to the user.

[blast-hardcheese]

Turns out these were all the same, with only two variants (has default vs no default possible)

[blast-hardcheese]

from https://stackoverflow.com/a/3912833. distinctBy is a member of 2.13's View, so this can go away when we upgrade.

[kelnos]

This looks mostly fine to me. I don't really understand some or it, like IndexedDistributive, but I appreciate that there are new tests around this, and all the old tests still pass.

[kelnos]

extends AnyVal? (Otherwise, why bother with dummy?)

(& other examples of the same in this file)

[blast-hardcheese]

This follows the pattern used in cats to partially apply type arguments. dummy is presumably required to avoid syntactic ambiguity, but the big thing is by fixing C in the call site, it permits:

t.downField[Int]("foo", _.getFoo) instead of t.downField[Option[Int], Int]("foo", _.getFoo)

Small improvement in ergonomics for the user, as it frees the unspecified type parameter to be resolved by the compiler.

[kelnos]

Yeah, I've seen that pattern cats, but they do extends AnyVal on those. I assumed the need for dummy was just because you have to have one-and-only-one val constructor param when extending AnyVal.

[blast-hardcheese]

To follow up on "I don't really understand some of it, like IndexedDistributive", I found Distributive to solve part of the problem I was having, as described here:

given G[F[A]], I want F[G[A]], but I want the typeclass that controls exactly how G[_] is applied over the different F[_]s to know that that is what's happening, instead of how traverse/sequence work, in the sense of strictly regimented generic methods that don't know about either structure.

I think the name comes from the distributive property of arithmetic: A * (B + C) == (A * B) + (A * C), Tracker * List[B + C] == List[Tracker[B] + Tracker[C]].

---

The other side of the name, Indexed, comes from the fact that Distributive in that Hackage link doesn't know anything about the implementation details of the data structure it's walking over. I needed the key: String of a Map to be in scope so I could appropriately represent that we've indexed into a Tracker[Map[K, V]] to get a Map[K, Tracker[V]] for all Ks, similarly with Tracker[List[A]] and List[Tracker[A]]. This is expressed in the tests by the history.downField.list and history.downField.map tests.

---

Initially I actually didn't have this abstraction, and I ended up writing almost identical syntax extensions for all the different structures I was trying to represent. There was a lot of duplication and divergent method names, since I wasn't sure what I had already implemented. When I started unifying them under this new banner of IndexedFunctor and IndexedDistributive things really started cleaning up.

[blast-hardcheese]

Rebased!

[kelnos]

Welp, I don't really understand the stuff in that hackage link, but your description helped a lot, thanks!