When do `doc.whenLoaded` and `doc.whenSynced` resolve?

Y.Doc seem to have two properties called whenLoaded and whenSynced which contain promises.

When do these promises resolve? According to my current studies, they seem to be always “pending”

According to the source code, doc.whenSynced:

resolves once the document has been synced with a backend.
This promise is recreated when the connection is lost.
Note the documentation about the isSynced property.


Promise that resolves once the document has been loaded from a presistence provider.

yjs/src/utils/Doc.js at 90f2a06b5e892ac08e989f5809e2e371ee101ec4 · yjs/yjs · GitHub

The tests make it pretty clear when they resolve in practice:

That all looks strange…

What if there are more than just one backend? How can one whenSynced promise handle all of them?

whenLoaded could just handle the first successful load - from then on, the doc would just be synced as needed

Thanks for your effort!


the tests are a joke - they simply test that whenLoaded and whenSynced resolve after a load or sync event has been emitted.

But where do these events come from in practice? I tested Y.Docs with IndexeddbPersistence and never saw whenLoaded and whenSynced resolved.

[Edit] …and isLoaded or isSynced never became true

Ah, I see. I didn’t look in depth. Good questions. I guess they are for internal use, but it would be nice to know what purpose they serve.

At first, I thought that a provider could send such an event to the associated Y.Doc - such that the user of a Y.Doc could wait whenLoaded or whenSynced to resolve (independent of any providers) and proceed.

But then I realized that

  • you still have to know your providers (or, that one exists, at least)
  • whenSynced does not re-resolve after syncing any changes

Thus, I don not see any sense

Well, I just found an important use case for whenLoaded, at least:

if you have an asynchronous provider for a Y.Doc with subdocs and you need to explicitly load such a subdoc, the implicitly created provider for that subdoc can send a load event to the subdoc in order to give you a chance to recognize that the subdoc has been loaded…

Unfortunately, whenSynced is useless in the other direction as it can be resolved once only - so, unless you apply a single change only, that promise won’t help you recognize sync completion…