User Story

A developer, having a set of data, either directly via the Stores API or via the Query API, needs to transform that data from its source shape to another shape(s). Also, this transformation needs to be able to observe the source data set, so that subsequent changes are propagated through the transformation pipeline.

Considerations

There are several key factors that need to be considered around the Transformation API:

• Results - Externally, the results of a transformation should have an API surface similar to that of a read only Store. There should be a way to retrieve meta data about the underlying source of an object that has been transformed so a consumer could go back to the authoritative source to perform a mutation.
• Multiple Views - It is anticipated that many use cases of the transformation will be to take a query or store and transform it into multiple views. Conceptually, think of a list of todo items, where a developer would need to create widgets (via setting unique widget states) for every todo item returned from a query. It would need to transform that also to a value of the number of todo items to be displayed in a widget which lists the count of items.
• Domain Specific Languages - There should be available two domain specific languages available to leverage the Transformation API:
  • Declarative - This API should use simple JavaScript objects (POJOs) to provide a declarative way of describing a transformation. This allows the transformation to be easily serialisable to and from JSON. It also allows an easy mechanism for other actors to procedurally generate a transformation and have it executed by the Transformation API.
  • Functional - This should have full functional parity with the declarative syntax but be offered up in chain-able functions, so that a developer can build a transformation incrementally taking advantage of intellisense and robust type validation via TypeScript. There should also be a mechanism to serialise complete functional transformations into the declarative syntax.
• Offloading and the Query API - Implementations of the Transformation API are likely going to be very co-dependent on query implementations to achieve efficient offloading. This is because most server side implementations do not have a strong architectural division between querying and transformation.
• API functionality - While it isn't expected to have a significant superset of the Transformation API for certain implementations, there maybe cause to do so. This should generally be limited so that the transformation functionality is as "universal" as possible.
• Interaction with dojo-app - The Transformation API should work with dojo-app to be able to reference more complex objects, like instances of stores, functions, actions and other complex object instances it may need to reference.