Emit `'changed'` on query `'ready'`?

[alecgibson]

At the moment, if you want to respond to changes to a Query, you have to listen for both the 'ready' and 'changed' events. Current usage looks like:

const query = connection.createSubscribeQuery(...)
query.on('ready', () => {
  // query.results were set for the first time
});
query.on('changed', () => {
  // query.results were updated
});

Sometimes we don't care about whether the results were set for the first time or not, and we just want to react to whenever any changes happen. For example, if you want to keep all of your query docs subscribed, you have to do something like:

function subscribe(docs) {
  docs.forEach((doc) => doc.subscribe());
}

query.on('ready', () => subscribe(query.results));
query.on('changed', () => subscribe(query.results));

It would be nice if we could simplify this to a single listener:

query.on('changed', () => {
  query.results.forEach((doc) => doc.subscribe());
});

We could achieve this by:

• emitting 'changed' at the same time as 'ready'; or
• introducing a new event, which fires any time query.results is touched (something like 'updated'?)

I think I would personally prefer to emit 'changed' at the same time as 'ready', just to reduce the confusion around what 'changed' vs 'updated' means, although this would be a breaking change.

That being said, there may also be cases where consumers care about only running after the first set? Could potentially be handled by firing 'changed' just before 'ready' (so consumers can check query.ready)?

[pypmannetjies]

Makes sense... I think a new query name would be best, as it will be confusing even if it is a breaking change that the behaviour has changed subtly.

Perhaps we can deprecate changed so that people know which one to use from now on 🤔

[alecgibson]

As discussed in #468 turns out that docs that are part of queries are always subscribed anyway, so this use case is less relevant, I guess.

[ericyhwang]

To elaborate a bit - for this use-case, there's not really a need to use "ready" or "changed", but it would be good to document the subscribe interaction between queries and docs.

Putting in some links based on the discussion:

• When a doc is a part of a subscribed query, the server QueryEmitter emits ops on the doc, which then get passed through middleware and sent down to the client, regardless of whether or not the doc was individually subscribed to from the client.
• This means the client Doc may still receive "op" events via subscribed queries, even if doc.subscribed === false.
• Also implied - It's not necessary to manually subscribe to each individual doc in the query.
• Adding event listeners to docs that are in the query results should be done via query "insert" and "remove" events
  • Using the "changed" event would result in duplicated listeners, since the "changed" event is a very broad event with no details on what changed
  • Example of handling query events from the Racer library: https://github.com/derbyjs/racer/blob/0690856c064a74466bf299b424debce0a1e0a3b9/lib/Model/Query.js#L271-L302 (doc events are reacted to via listeners added to the doc when it gets instantiated in the client, here)