User Story

Given a store which conforms to the Dojo 2 Stores API, a developer needs to express a subset of the stores objects, retrieve those store objects, work with this subset of data in a similar way of interfacing with the Stores API and receive information when this data changes.

Considerations

There are several key factors which need to be considered around the Query API:

• Immutable Results - Overall Dojo 2 attempts to promote a one way flow of data in order to reduce complex dependencies. Therefore the Query API should result in data sets that cannot be written to, the changes reflected in the original source store are reflected in the dataset, but you cannot update an object visible from a query. There should be meta data though which allows a consumer who has retrieved an object from a query to locate the source store where such mutations can be performed.
• Domain Specific Languages - There should be two distinct domain specific languages available to leverage the Query API:
  • Declarative - This API should use simple JavaScript objects (POJOs) to provide a declarative way of describing a query. This allows the query to be easily serialisable to and from JSON. It also allows an easy mechanism for other actors to procedurally generate a query and have it executed by the Query 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 the query incrementally taking advantage of intellisense and robust type validation via TypeScript. There should also be a mechanism to serialise complete functional queries into the declarative syntax.
• API Functionality - While certain store implementations will support a superset of the Query API, there must be a clearly defined base set of functionality supported by all query implementations.
• Offloading - Query implementations should be aligned to leverage the functionality of the underlying store implementation so that certain aspects of the queries are processed in the most efficient way. The implementations should also give significant considerations to pooling of aspects of processing. For example, if two different consumers share part or all of a query, then the same resources should be used where the queries overlap. Because of the one way nature of the flow of data, it should be achievable to create these common paths.
• Interaction with dojo-app - The Query 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.