Add Flexible Sync subscribe/unsubscribe APIs

[elle-j]

What, How & Why?

Additions:

• Experimental APIs: Adds the possibility to subscribe and unsubscribe directly to and from a Results instance via Results.subscribe() and the Results.unsubscribe().
  • A SubscriptionOptions can be passed to Results.subscribe() which has been extended to include:
    • A WaitForSync behavior specifying how to wait or not wait for subscribed objects to be downloaded before the returned promise resolves.
    • A maximum waiting timeout before resolving.
• Adds the instance method MutableSubscriptionSet.removeUnnamed() allowing for the removal of unnamed subscriptions only.

Example subscribe():

const peopleOver20 = await realm
  .objects("Person")
  .filtered("age > 20")
  .subscribe({
    name: "peopleOver20",
    behavior: WaitForSync.FirstTime, // Default
    timeout: 2000,
  });
// ...
peopleOver20.unsubscribe();

Example removeUnnamed():

await realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeUnnamed();
});

This closes #5760.

☑️ ToDos

• 📝 Changelog entry
• 🚦 Tests
• 🔀 Executed flexible sync tests locally if modifying flexible sync
• 📝 Public documentation PR created or is not necessary

[takameyer]

LGTM! Just have a few pondering questions/considerations

[kneth]

It still looks good to me. I have only minor comments.

[papafe]

Maybe the test title is a little confusing for me, but this means that WaitForSync applies to the query and not to the results, am I correct?

[elle-j]

This is due to how we determine if we should wait for sync or not. If, for instance, the subscription is not named, we check if it already exists by query like you said.

I'll modify the test description and can also add some comments in the test 👍

[papafe]

Looks good! And nice test coverage

[kraenhansen]

This would be equivalent and perhaps a bit simpler?

Suggested change

	expect([...subs][0].queryString).to.equal("age > 10");
	const [ sub ] = subs;
	expect(sub.queryString).to.equal("age > 10");

[elle-j]

That can be a small but good refactor we could add in a separate PR (perhaps for our test refactor ticket), because the previous pattern is also used in other places so would be good to change all of them together.