Overview

This package contains utilities for navigating and interacting with Siren based
APIs. The central idea in this approach is that it should be possible to chain
together complex sequences of interactions. What complicates things is the fact
that the events described do not take place in response to the commands themselves.
Instead, all processing is deferred as long as possible (i.e., until an actual
result is required). Fundamentally, there is something inherentily monadic in all
this although that wasn't a direct goal (just a useful pattern).

This is all achieved by the fact that lots of "promises" are being tracked
behind the scenes to describe the results of each processing step. Further
complicating things is the fact that some requests that "trigger" the processing
are not necessarily the end of the chain.

To understand what is going on, consider the following code:

``
nav
.follow("task")
.performHyperAction("submit", {
properties: {
source: this.state.currentSource,
}
})
.followLocation()
.follow("result")
.getSiren();
`

We start with a SirenNav instance, nav. This has presumably already been created.
It manages the current "state" of the navigation internally. That state mainly consists
of knowing what the URL of the current resoure is. But it DOES NOT update the state
after the chain calls like follow. Instead, what it does is record the process by
which the current state (whatever that happens to be) can be transformed into the
next step without actually doing it. These chains of state transformations are stored
up until an actual request is to be made. In this example, that is the performHyperAction
call. This necessarily must perform a (POST) request and returns a NavResponse object.
Again, note that this is not itself a promise of anything, but intead a "holder" of a
promise to the result. The actual request could have been requested (via the get or
getSiren methods). But in this case, the followLocation method initiates a new request that returns
a fresh SirenNav instance. In other words, the chaining continues by turning a
SirenNav instance into a NavResponse instance and back again into a SirenNav`
instance.