Return async iterables from commands

[Rich-Harris]

Describe the problem

If a command kicks off a long-running task, and you want to get progress updates, you basically have to return an ID and use that to call a query.live. It involves a bunch of book-keeping on both sides of the network divide.

In some respects this is the right way to deal with it — you can use that live query in different contexts, and if it's a really long running task then you can come back to it after navigating somewhere else — but for a lot of smaller jobs, being able to get progress reports directly from the command is the sweet spot.

Describe the proposed solution

Something like this — essentially, adding async iterables to the list of things that commands can return:

export const insertLargeThing = command(v.object(...), async function* (data) {
  yield { progress: 0 };

  const task = startTask(data);

  while (!task.done) {
    yield { progress: task.progress };
    await sleep(50);
  }
});

<button
  onclick={async () => {
    for await (const task of insertLargeThing(...)) {
      progress = task.progress;
    }

    done = true;
  }}
>
  insert large thing
</button>

Alternatives considered

not doing this

Importance

nice to have

Additional Information

No response

[adiguba]

Hi,

Some remarks :

• Instead of an AsyncIterable, it would be better to use an AsyncGenerator.
  This will allow for a return value (which can be later retrieved by using the generator directly instead of a for await)

export const insertLargeThing = command(v.object(...), async function* (data) {
  yield { progress: 0 };

  const task = startTask(data);

  while (!task.done) {
    yield { progress: task.progress };
    await sleep(50);
  }
+  return task.result;
});

• I think that from the client's perspective, insertLargeThing() should still return a Promise<ReturnType>.
  This would make it easy to ignore the progress information by default, and so make it possible to add progress information to an existing command() without breaking the existing code.

<button
  onclick={async () => {
    result = await insertLargeThing(); // return the result of the command, all yield are ignored
    done = true;
  }}
>
  insert large thing (ignoring progress)
</button>

• In order to handle the progress, these RemoteCommand should have a .progress() utility.
  It simply accept a setter to update the progress, and returns the final return value.
  So, using the progress, and getting the result will be as simple as :

<button
  onclick={async () => {
    result= await insertLargeThing().progress( p => progress = p );
    done = true;
  }}
>
  insert large thing (with progress and result)
</button>

The progress() function will do something like that :

async function progress(onProgress) {
  const generator = ... // get the AsyncGenerator from current RemoteCommand
  while (true) {
    const result = await generator.next();
    if (result.done) {
      return result.value;
    }
    onProgress?.(result.value);
  }
}

• And finally, if there is a need to manage this more precisely, these RemoteCommand could have a .generator() utility with return an Async Generator :

<button
  onclick={async () => {
    for await (const task of insertLargeThing(...).generator()) {
      progress = task.progress;
    }

    done = true;
  }}
>
  insert large thing
</button>

[Rich-Harris]

I think that might be a little weird from a types perspective. One of the assumptions when building with remote functions is that you own both the front and back, so if you don't need progress updates then just don't send them. But in the (probably somewhat rare) case that a some callers need progress updates, and some just need a result, the nice thing about treating async iterables (and promises) like any other value is that you can do this sort of thing:

export const insertLargeThing = command(v.object(...), async (data) => {
  const id = crypto.randomUUID();
  const deferred = Promise.withResolvers();

  return {
    id,
    progress: getIterator(id, data, deferred),
    result: deferred.promise
  };
});

[brunnerh]

For async function*, would the yield throw a specific exception after a connection loss?

If not, how would you clean up any resources/running loops?
I guess an additional argument after the sent data could also be used, something like { onConnectionLost } that allows registering a callback.

[Rich-Harris]

On the server getRequestEvent().signal would automatically be aborted, so that's how you'd handle cleanup. On the client, yeah, it might be nice to have a way to distinguish lost connections from other errors

try {
  for (const await progress of whatever()) {
    doSomethingWith(progress);
  }
} catch (e) {
  if (isConnectionLost(e)) {
    showConnectionLostUI();
  } else {
    // ???
    throw e;
  }
}

(Then again if you know that a network error is the only possible failure mode, you could probably skip that.)