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

rozek · June 28, 2023, 4:58am

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”

raine · June 28, 2023, 3:44pm

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.

github.com

yjs/yjs/blob/90f2a06b5e892ac08e989f5809e2e371ee101ec4/src/utils/Doc.js#L120-L125


      
          /**
           * Promise that 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.
           */
          this.whenSynced = provideSyncedPromise()

whenLoaded:

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:

github.com

yjs/yjs/blob/main/tests/doc.tests.js

import * as Y from '../src/index.js'
import * as t from 'lib0/testing'

/**
 * @param {t.TestCase} _tc
 */
export const testAfterTransactionRecursion = _tc => {
  const ydoc = new Y.Doc()
  const yxml = ydoc.getXmlFragment('')
  ydoc.on('afterTransaction', tr => {
    if (tr.origin === 'test') {
      yxml.toJSON()
    }
  })
  ydoc.transact(_tr => {
    for (let i = 0; i < 15000; i++) {
      yxml.push([new Y.XmlText('a')])
    }
  }, 'test')
}

This file has been truncated. show original

rozek · June 28, 2023, 4:54pm

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!

rozek · June 30, 2023, 7:33am

Haha,

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

raine · June 30, 2023, 2:02pm

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.

rozek · June 30, 2023, 2:12pm

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

rozek · July 4, 2023, 8:31am

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…