Proposal to refactor `Requestable` interface into `Queryable` interface.

[dgeb]

In my experience, "requestable" methods that mutate a source, such as add, remove, and update, are not appropriate for assisting / rescuing. Instead, these methods provide thin wrappers over transform, and the Transformable interface provides the best way to engage with mutations.

The "requestable" methods that are in fact appropriate for assisting / rescuing are all related to querying a source: find, query, findLink, and findLinked. I think all these methods could be distilled into a single query method, given the right query definition language (see #192).

I believe we should refactor the Requestable interface into a Queryable interface that supports a single query method. This will nicely parallel the Transformable interface that supports a single transform method.

The query method will take two arguments: a query object and an options object. The query object might be as simple as specifying path: '/planets' or path: '/planets/1' or it might involve filters and conditionals (still TBD). It's possible that options should simply be a member of the query object instead of a separate argument.

I believe that this simplification will keep sources as lean and standardized as possible.

Convenience methods such as add, remove, update, and find could be added to a new class Store. A store will wrap a memory source (with a cache of course), and will be the primary interface developers use to interact with data. Behind the scenes, other sources can be wired up with their much simplified interfaces.

Major credit to @gnarf and @opsb for discussions that led to thinking about this new direction.

I'm in the midst of updating the normalized form (as per #157), which seems to make all this much more feasible.

[opsb]

Ha, I was going to suggest exactly the same name change.

[opsb]

I do like the idea of having a single query method to match transform. Moving the query encoding methods(find, findAll etc.) to the store brings a nice symmetry as well.

[gnarf]

While we are on the topic, perhaps we should consider my confirm method:

• confirm(query)
  • Search for record by ID(s) inside query object
    • If found - patch all keys present on the query on the found object and return.
    • If not found - add and return

"Find and Update" --or-- "Create if not found"

[gnarf]

Also, the use cases are way less obvious, but I ended up using an assistAdd to handle "waiting for server response" before adding to my local.

Also with assistRemove you could do something like:

source.on('assistRemove', function(type, id) {
  if (type === 'user') {
    if (window.confirm('are you sure you want to delete user ' + id)) {
      return Promise.reject(new Error("Let the source delete it");
    } else {
      // "Yeah, we deleted it.... heh"
      return Promise.resolve();
    }
  }
});

It might be a silly thing, but you could also use these assists to implement a security/permissions layer.

[opsb]

@gnarf I'm writing up my notes on adding "optimistic ui" which I think will cover

"waiting for server response" before adding to my local.

In this case the record would be added to the local store optimistically but if the server rejected it (due to permissions denied) then the change would be rolled back in the local store.

Regarding "upsert" (think that matches "find and update" or "create if not found"), perhaps this is something specific to sources? i.e. maybe you just do an add and the source can do an upsert if it supports it or follow the existing semantics if not?

[opsb]

Regarding your code snippet, I think UI <=> orbitjs interactions should probably be mediated through a Store (which @dgeb touched on).

[gnarf]

Yeah - I wasn't really arguing against this proposal, just pointing out some of the things that the current setup would let you do.

Also, not every use of orbit will have a Store

[opsb]

Also, not every use of orbit will have a Store

Just to be clear, I'm referring to an orbitjs store as opposed to an ember-orbit store. If that is what you're referring to what are the scenarios that you're considering?

[gnarf]

Regarding "upsert" (think that matches "find and update" or "create if not found"), perhaps this is something specific to sources? i.e. maybe you just do an add and the source can do an upsert if it supports it or follow the existing semantics if not?

The thing I'm worried about there, is that "upsert" is definitely a different operation than "insert" or "update" - I'd hate to conflate the two by giving them the same entry (add)

[opsb]

How do you see it working at the operation level, a single call to source.transform or source.query followed by source.transform? i.e. would you introduce a new operation verb or use the existing ones?

[gnarf]

As written in my app, the default confirm implementation uses a chained promise of find and add and patch requests. It returns the "whole updated value" when complete either way. It even worked to patch the JSON API server.

[gnarf]

Also - this has gotten off topic, perhaps we should move these last few
posts into a new issue about a confirm or upsert pattern/api.

On Sat, Sep 19, 2015 at 11:39 AM, Oliver Searle-Barnes <
notifications@github.com> wrote:

How do you see it working at the operation level, a single call to
source.transform or source.query followed by source.transform? i.e. would
you introduce a new operation verb or use the existing ones?

—
Reply to this email directly or view it on GitHub
#202 (comment).

[opsb]

Yeah, breaking it out sounds like a good idea. Sounds like a store.upsert() might fit the bill, it could take care of chaining the calls to the sources.

[dgeb]

perhaps we should move these last few posts into a new issue about a confirm or upsert pattern/api.

Sounds good to me @gnarf. I agree that this is a good candidate for a convenience method on the forthcoming OC.Store class.

It sounds like there still aren't any blockers for the Requestable -> Queryable refactor (unless I'm misunderstanding). Let's all try to focus on our uses of the current Requestable methods to ensure that we're not overlooking something.