Enhance WorkflowStatus type to include returnValue for completed status

[ecwyne]

There is currently no way to get the return value of a workflow except for getting it in an onComplete handler. This PR adds the returnValue to the WorkflowStatus when the status is "completed".

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ecwyne]

Thanks for all you've built @ianmacartney! Your contributions to Convex make a huge difference.

Let me know if you have any feedback on this or if there's anything else I could do to help get it merged if you're interested.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/workflow/@convex-dev/workflow@93

commit: d0b9ca8

[ianmacartney]

Whoops sorry for the delay here @ecwyne - my only hesitation right now is I'd like to stop persisting the return value by default and encourage folks to save it somewhere as part of the onComplete.
However, if they're fine with the knowledge that when they clean it up it won't be available anymore, this seems reasonable. It already looks like we would be returning "pending" incorrectly if it finishes & is cleaned up, by my read.

What's your use-case where you don't want to use the onComplete to capture it?

[ecwyne]

Thanks @ianmacartney! No worries about the delay.

My current use case is running server-side and I'm waiting for the workflow to complete before responding to the request.

My workflow has the following logic to create a new customer:

1. Call a 3rd party api in an action
2. Write customer to db using the result of the action
3. Return the newly created customer

When I'm starting the workflow all I have to identify the created customer is the workflowId, so I'll need to add that to the created customer (and have an index on workflowId just so that I can read it back out after the workflow completes. (I don't have a customer id to read yet)

I don't have to do any of that if I can get the result of the workflow when I check the status, as it's right in the returnValue

[ianmacartney]

Gotcha - thanks that makes sense.
This would be a great usecase for custom / client-side ID generation, which we've started designing but don't have an ETA on shipping.

A couple questions to tease out the usecase:

1. What's your timeline on deleting the data afterwards? Do you do periodic cleanup, immediately, or keep them around by default?
2. If the request fails, how does the client know how to resume / if the call succeeded/ failed? If the workflow doesn't finish in time, will the customer become an orphaned entity of sorts?

One option, which I know is not as satisfying, would be to run a mutation which creates the empty user, starts a workflow passing the ID in, then returns the ID to the http action to use. It requires making a non-finalized user though. Or making your own progress type table, where you pass that ID to the workflow and return it to the client to subscribe on - which would allow using a mutation instead of an action / endpoint, which has nice behavior around idempotency, retries, etc.

[ecwyne]

I agree, client-side id generation would absolutely work in this case.

1. What's your timeline on deleting the data afterwards? Do you do periodic cleanup, immediately, or keep them around by default?

At this point I am not doing any cleanup, but in theory I could do so immediately.

2. If the request fails, how does the client know how to resume / if the call succeeded/ failed? If the workflow doesn't finish in time, will the customer become an orphaned entity of sorts?

Customer creation is the last step of the workflow, so it wouldn't be orphaned. If the workflow fails then I reply with a server error.

One option, which I know is not as satisfying, would be to run a mutation which creates the empty user, starts a workflow passing the ID in, then returns the ID to the http action to use. It requires making a non-finalized user though. Or making your own progress type table, where you pass that ID to the workflow and return it to the client to subscribe on - which would allow using a mutation instead of an action / endpoint, which has nice behavior around idempotency, retries, etc.

I'd like to avoid making a "non-finalized" customer. As of now my schema requires the data I get from the first call to the 3rd-party api before creating a customer and I'd like to avoid the possibility of having orphaned/incomplete customers at all.

[ianmacartney]

Sorry for the delay here. Given a cleanup policy (likely cron-based if not immediate) it would need to handle the result going away. I'd like to maintain a separation of data ownership - where the workflow writes progress and final results with the associated workflowId. Even better would be the client passing up a UUID that it uses to ensure it only kicks off one workflow, associating the workflowId and eventually userId & intermediate progress with that ID. However, this does seem really convenient for use cases like yours, where the result is semi-ephemeral (going from a workflowId -> a result in the context of an active session), so I may add this as I dig more into Workflow soon

…

On Wed, Sep 3, 2025 at 6:40 AM Eric Wyne ***@***.***> wrote: *ecwyne* left a comment (get-convex/workflow#93) <#93 (comment)> I agree, client-side id generation would absolutely work in this case. 1. What's your timeline on deleting the data afterwards? Do you do periodic cleanup, immediately, or keep them around by default? At this point I am not doing any cleanup, but in theory I could do so immediately. 2. If the request fails, how does the client know how to resume / if the call succeeded/ failed? If the workflow doesn't finish in time, will the customer become an orphaned entity of sorts? Customer creation is the last step of the workflow, so it wouldn't be orphaned. If the workflow fails then I reply with a server error. One option, which I know is not as satisfying, would be to run a mutation which creates the empty user, starts a workflow passing the ID in, then returns the ID to the http action to use. It requires making a non-finalized user though. Or making your own progress type table, where you pass that ID to the workflow and return it to the client to subscribe on - which would allow using a mutation instead of an action / endpoint, which has nice behavior around idempotency, retries, etc. I'd like to avoid making a "non-finalized" customer. As of now my schema requires the data I get from the first call to the 3rd-party api before creating a customer and I'd like to avoid the possibility of having orphaned/incomplete customers at all. — Reply to this email directly, view it on GitHub <#93 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW3IDKNSTBBJJZBL6NT3Q3VWJAVCNFSM6AAAAACESOPNFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTENBZGMYDSMBQGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ecwyne]

Thank you @ianmacartney, I'm curious if there's anywhere I can track the implementation of client-generated ids as that would also solve my use-case?