API between cozy-stack-client and cozy-client for mutations

[ptbrowne]

In this comment, drazik asks if we should have a destroyAll method on the client, similar to the queryAll method. I am a bit unclear where lies the boundary between the stack-client and cozy-client on this problem.

Reflecting on this, I think we should not, queryAll is almost a helper that should not be directly on CozyClient.

CozyClient::query naming makes a bit hard to see but query can executes all queries made by the DSL. Maybe instead of the destroy all, we should leverage the mutate method :

client.mutate(Mutations.deleteAll([1, 2, 3]))

It stills feel a bit clunky.

To me, the API should be the same between querying and mutating, and it should be easier to do one or the other. I think the Mutations should be accessible via the DSL. What do you think ?

[drazik]

My concern in the comment is that in cozy-stack-client's collections we have a destroyAll method, but we can't do the same by using CozyClient only. It means that if we need to do a destroyAll in an app, we have to get the cozy-stack-client collection (thus bypassing any PouchLink and breaking offline-first feature) or do it by hand.

[ptbrowne]

Yes, this is the important thing. This is why I think we should do it via the DSL that can be understood by all links (like for querying). My concern with the Mutations DSL is that the API is a bit clunky (have to import Mutations for example). I think we could have a mutate helper on cozy-client to create a mutation. The problem is that it would be a bit weird to have mutate creating a mutation definition, where query does not create a mutation definition but executes it.

There could be one way to create a query/mutations definition on CozyClient, via a helper that we could name Q.

import CozyClient, { Q } from 'cozy-client'
Q('io.cozy.todos').where({ done: true }) // a query
Q('io.cozy.todos').getByIds([1,2,3,4]).update({ done: false }) // a mutation
Q('io.cozy.todos').getByIds([1,2,3,4]).destroy({ done: false }) // a mutation
Q('io.cozy.todos').create({ done: false }) // a mutation

Those definitions would still need to be executed by cozy-client (passed to links etc..)

client.execute(client.Q('io.cozy.todos').create({ done: false }))

This would make the API between queries and mutations more symmetrical and easier to use IMHO.