Discuss potential improvements to declarative data API

[amcgee]

Opening this issue to collect challenges and potential improvements we uncover while using the App Runtime for more and larger apps.

1. Support selectors in query or options, to support transformations from returned
2. fetchMore abstraction, rather than refetch({ page: xyz })
3. Document and reconsider promise behavior in imperative (engine.query) and refetch interfaces
4. Consider alternative approaches to conditional and dependent queries (a la https://swr.vercel.app)
5. Allow singular, un-namespaced queries (currently every query requires a namespace, even if it doesn't have any siblings, which leads to an unnecessary level of nesting
6. Find a good way to generate paths like some/path/<id>/items or analytics/<path>/<program-id> where id, program-id path would be passed as a variables

Expand on these or list more here!

[Mohammer5]

fetchMore abstraction, rather than refetch({ page: xyz })

What about fetchNextPage, fetchPrevPage and fetchPage?

Document and reconsider promise behavior in imperative (engine.query) and refetch interfaces

I'd expect non-200 + ok responses to reject and backend errors of non-technical nature (I'm not talking about 5XX responses) to be part of the response (response.error?)

Allow singular, un-namespaced queries (currently every query requires a namespace, even if it doesn't have any siblings, which leads to an unnecessary level of nesting

Would be nice to allow namespaced mutations as well

Find a good way to generate paths like some/path//items or analytics// where id, program-id path would be passed as a variables

Do you have a specific example in mind where we'd need a whole path to be passed in instead of an id?

[edoardo]

Do you have a specific example in mind where we'd need a whole path to be passed in instead of an id?

Yes, I'm working on porting d2.analytics to analytics and replace d2 with app-runtime.
Examples are URLs similar to the one I mentioned:
analytics/events/query/<program-id>
analytics/events/aggregate/<program-id>
analytics/events/cluster/<program-id>
analytics/events/count/<program-id>
and more

The actual query definition, besides the different path, is exactly the same.

cfr. https://docs.dhis2.org/2.35/en/dhis2_developer_manual/web-api.html#analytics

[Mohammer5]

Ok, it's not a path but a segment or some kind of type string, I was wondering if the path included /s

[edoardo]

Yes, not technically the URL's path, but anything that follows the api part which is handled by app-runtime anyway.
Basically what you would put in resource (whenever the id segment comes last).
There are also cases where the id is followed by another "segment", ie: dimensions/<dimension-id>/items, which is now obtained with:

resource: 'dimensions',
id: ({ id }) => `${id}/items`

[Mohammer5]

I'm still undecided whether a function or string with placeholders (as I proposed here; I don't really care about the sytnax) would be better for this.

Right now I'm leaning towards a string with placeholders as we could perform some checks on it (e. g. no slashes, must be of type string, etc.) and we'd prevent complex logic for the resource path.
Also strings can be parsed/validated while that's a lot harder with functions.

[ghost]

There is an additional usecase here: https://jira.dhis2.org/browse/LIBS-9 (props and data can be momentarily out of sync).