Allow Users to Traverse an Entity

[dillonredding]

An Entity could easily be traversed by implementing the Visitor pattern, allowing operations to be added to an entity graph without modifying the implementation. I believe this would also make implementing a Siren API crawler (#15) almost trivial.

Similar to this Java example, we could have something like the following:

export interface SirenElementVisitor {
  // need individual methods since JS/TS doesn't support overloading
  visitAction(action: Action): void;
  visitEmbeddedEntity(embeddedEntity: EmbeddedEntity): void;
  visitEmbeddedLink(embeddedLink: EmbeddedLink): void;
  visitEntity(entity: Entity): void;
  visitField(field: Field): void;
  visitLink(link: Link): void;
}

// each model class implements this interface
interface SirenElement {
  accept(visitor: SirenElementVisitor): void;
}

This requires each element to know how to traverse is child elements (not necessarily a bad thing). One advantage with this approach is that polymorphism handles distinguishing sub-entity types (no instanceof checks 😌).

Alternatively, instead of implementing SirenElement in each model, we could have a traverse function that understands how to traverse an entity.

function traverse(entity: Entity, visitor: SirenElementVisitor);

This fits well with the other top-level methods we have and has all the traversal logic, but the downside here is that we either need to manually distinguish between sub-entity types or have a generic visitSubEntity method, which will likely always have the boilerplate

if (subEntity instanceof EmbeddedLink) /* ... */ else /* ... */

The primary disadvantage of traverse is that you always have to start at the entity level, preventing users from (e.g.) creating an action-populating and submitting visitor.

Need to think more about the pros/cons of either approach, especially in regards to how async visits are handled (e.g., visitAction may call submit).