Feature Request: Programmatically Cancel Convex Transactions Without Throwing Exceptions

[doichev-kostia]

Description

I'm referring to the discord discussion (https://ptb.discord.com/channels/1019350475847499849/1382018814010724456),
which highlights issues with error handling and transaction rollbacks in Convex.
Currently, there is no idiomatic way to return a structured error without throwing an Exception.

There is a section in the Convex docs - "Application Errors"
that shows how to return an error

Returning different values

If you're using TypeScript different return types can enforce that you're handling error scenarios.

For example, a createUser mutation could return

Id<"users"> | { error: "EMAIL_ADDRESS_IN_USE" };

to express that either the mutation succeeded or the email address was already taken.

This ensures that you remember to handle these cases in your UI.

However, the problem in this scenario is that there is no way to programmatically cancel a transaction that runs within the mutation.
Therefore, if I want to have my queries or mutations to return Result<Data, Error>, I have to write the custom wrapper that throws the ConvexError in order for a mutation to be cancelled.

Question

Consequently, I would like to ask a question: Are there any plans to provide the API to cancel the transaction manually?

Proposed API

ctx.rollbackTransaction()

[nipunn1313]

In [mutations](https://docs.convex.dev/functions/mutation-functions), throwing an error will prevent the mutation transaction from committing

^ It's in the doc you linked.

The whole mutation is a single transaction. It either commits on success or rolls back on exception.

I don't think it makes sense to continue running mutation code after such a hypothetical rollback - as the whole point of the mutation runtime is that it is determistic and transactional.

[doichev-kostia]

In [mutations](https://docs.convex.dev/functions/mutation-functions), throwing an error will prevent the mutation transaction from committing

^ It's in the doc you linked.

The whole mutation is a single transaction. It either commits on success or rolls back on exception.

I don't think it makes sense to continue running mutation code after such a hypothetical rollback - as the whole point of the mutation runtime is that it is determistic and transactional.

Yeah, the problem is not with the transaction, it is in the way it's being caused to roll back. It makes perfect sense to roll back the transaction in case of a thrown Exception.
However, I think another useful API is to do a rollback programmatically, via something like ctx.rollBackTransaction();

Motivation
I prefer to return errors instead of throwing them, as it's easier to attach some metadata or do logging,
because the error is local, and you know the context this error was created in.
Eventually, those errors should bubble up and be returned.
However, with the current implementation of the convex mutation, we have to explicitly throw an exception to cancel a transaction.

From the consumer perspective, you then have to wrap the calls in try catch and try to parse your structured error message from the ConvexError, which is extra work that could be omitted.
Here is an example of the mutation, where I would like to return an error (this is a custom wrapper around "convex/server" mutation, so I can return the errors as values).

import { ok, err, Result } from "neverthrow";
import { ApiError } from "./lib/error.ts";
import { RealtimeProvider } from "./lib/time.ts";
import { mutation } from "./lib/api.ts";
import { Account } from "./domain/account.ts";

export const createAccount = mutation({
    name: "accounts.create",
    args: z.object({
        token: z.string(),
        name: z.string(),
        type: Account.AccountType,
    }),
    returns: z.object({
        id: Account.Id,
    }),
    handler: async (ctx, args): Promise<Result<{ id: Account.Id }, ApiError>> => {
        if (args.token !== config.internalApiKey) {
            return err(new ApiError(ErrorCode.Unauthenticated, "invalid api key"));
        }
        let tp = new RealtimeProvider();
        let result = await Account.create(ctx.db, { name: args.name, type: args.type, timeProvider: tp });
        if (result.isErr()) {
            logger.error(`convex.accounts.create_account.create_failed err=${result.error}`);
            // I would love to do this
            ctx.rollbackTransaction();
            return err(result.error)
            // instead i have to do this
            throw result.error;
        }

        return ok({
            id: result.value.id
        })
    },
});

[thomasballinger]

Therefore, if I want to have my queries or mutations to return Result<Data, Error>, I have to write the custom wrapper that throws the ConvexError in order for a mutation to be cancelled.

I see where you're coming from here. You can use a different useQuery() hook like const {data, error} = useMyQuery() that even has the right types if you follow specific conventions, but then TypeScript isn't working for you on the server if you want something like Effect or neverthrow or your error objects: you'd like the return value of the mutation to be Result<Value, Error> but to do that you need to throw as the last step and then lie about the type to smuggle that error type back to the frontend. That's all to say you can do it, but it takes extra steps.

⬆️ I wrote this before seeing your last message above, yeah just like you're doing here.

For internal logging we want errors to be identifiable as errors; we want it to be very clear that a mutation has failed. Requiring throwing to abort the transaction is a nice way to do that.

In a sense ctx.rollbackTransaction() is too powerful, it's confusing to give give you the ability to mark the transaction as aborted and then keep doing reads and writes. Maybe a specific wrapper type could be used instead, so a return validator like

    returns: z.union([
      z.object({
        id: Account.Id,
      }),
      z.object({
        isConvexError: true,
        message: v.string()
      })
    ]);

could have the special effect of cancelling the transaction. This can be accomplished via middleware (meaning mutation wrappers and useMutation wrappers) but propagating that error type is a bother.

This isn't planned but it makes sense, especially for e.g. an Effect-based API.

[doichev-kostia]

Therefore, if I want to have my queries or mutations to return Result<Data, Error>, I have to write the custom wrapper that throws the ConvexError in order for a mutation to be cancelled.

I see where you're coming from here. You can use a different useQuery() hook like const {data, error} = useMyQuery() that even has the right types if you follow specific conventions, but then TypeScript isn't working for you on the server if you want something like Effect or neverthrow or your error objects: you'd like the return value of the mutation to be Result<Value, Error> but to do that you need to throw as the last step and then lie about the type to smuggle that error type back to the frontend. That's all to say you can do it, but it takes extra steps.

⬆️ I wrote this before seeing your last message above, yeah just like you're doing here.

For internal logging we want errors to be identifiable as errors; we want it to be very clear that a mutation has failed. Requiring throwing to abort the transaction is a nice way to do that.

In a sense ctx.rollbackTransaction() is too powerful, it's confusing to give give you the ability to mark the transaction as aborted and then keep doing reads and writes. Maybe a specific wrapper type could be used instead, so a return validator like

    returns: z.union([
      z.object({
        id: Account.Id,
      }),
      z.object({
        isConvexError: true,
        message: v.string()
      })
    ]);

could have the special effect of cancelling the transaction. This can be accomplished via middleware (meaning mutation wrappers and useMutation wrappers) but propagating that error type is a bother.

This isn't planned but it makes sense, especially for e.g. an Effect-based API.

Alright, thanks for the reply!

[thomasballinger]

@doichev-kostia thinking about this again today, if you have ideas for how to make this work without a full ctx.rollbackTransaction would love to hear. We could e.g. say "returning a ConvexError<T> instance (inc. subclass instance) also cancels the transaction," and that can pack any payload you like. What should this look like on the client side, still a thrown error or now an error object can be returned and you need a whole new style on the client for dealing with this?