New "Wait For" Methods

[parker-codes]

I think the new mutation status API could be improved with some functions that wait for completion instead of returning a PendingRequest instance and then having to manually loop until the request is finished.

Here is how it works currently:

const request = await todo.update({
  Completed: !completed,
});

// potentially wrap this in a loop
const requestCompleted = await request.isCompleted();

We can prefix mutation methods with "waitFor", like waitForDelete, that take the normal parameters, plus an optional object at the end that defines interval to recheck (ms) plus the number of tries.

This would be achieved by having a setInterval next to a setTimeout (with a calculated time based on interval * tries). Whichever comes first completes the Promise. If the timeout is reached, reject.

The new API usage could look like:

// basic
await todo.waitForUpdate({
  Completed: !completed,
}).catch(() => {
  console.log('Update did not finish in a reasonable timeframe');
});

// with control over timing
// this would check every 2 seconds up to 30 times, so up to a minute
// I doubt it would take anything close to a minute, but hey, this is just an example 😅
await todo.waitForUpdate({
  Completed: !completed,
}, {
  interval: 2000,
  tries: 30,
}).catch(() => {
  console.log('Update did not finish within a minute');
});

I think some reasonable defaults would be: interval: 1000 tries:      10

---

TODOs

• [x] reach out to Coda team to get idea of average mutation completion time (I'll handle this)
• [ ] decide on API
• [ ] implement
• [ ] test
• [ ] document

---

@mjoyce @svennu @inguelberth @phlexib @fenixsolorzano Sorry about the pings every so often, but I want to make sure this project follows the needs and use cases of users and maintainers. If you have a preference on this topic, speak up!

[parker-codes]

Response from one of the Coda engineers:

Yeah, one second is reasonable in general.

Most updates should get applied quickly, and the doc should snapshot quickly thereafter, at which point the change is visible via the API and the endpoint will return that things are completed. However, if a doc is changing rapidly (e.g. there are lots of users making concurrent edits on it) it can take longer for the change to become visible via the endpoint.

For this reason we'd suggest some kind of backoff if you haven't seen a completed result within the first 5-10 seconds. That is, maybe check once a second for 5 seconds, then back off one second each time you retry thereafter, just so you don't make an inordinate number of requests for a response that's slow to return.

But even doing it on a fixed interval vs continuously hitting the endpoint again as soon as it returns is helpful to us.

I like the idea of a "back-off" strategy, but I don't believe it would be a simple API. Someone would have to dig into the math quite a bit more if they wanted any sort of control over it, vs just simply stating the interval and tries.

I think we should move forward with this API design, unless anyone has issues against it.

---

Also note that the chained .catch() could also be replaced by a traditional "try/catch" block because it'll throw a specific error when timing out (like PendingRequestTimeoutError).