Results and errors

Repository methods never throw for database errors. They return an AsyncResult, which you can await for a Result or unwrap:

const result = await db.customers.findById(id);
if (!result.ok) {
  if (result.error.kind === "not_found") return notFound();
  throw result.error;
}
result.data.name;

// Or throw a DbException on error:
const customer = await db.customers.findById(id).orThrow();

// Or chain:
const name = await db.customers
  .findById(id)
  .map((row) => row.name)
  .unwrapOr("Unknown");

AsyncResult has orThrow, unwrapOr, map, mapError and andThen. mapError here rewrites the DbError inside one result; betterSupabase.mapError() (below) changes what .orThrow() throws.

Error kindsCopy Anchor Link

DbError is plain data, safe to return from server actions and RPC handlers.

The status field feeds the RFC 9457 problem details mapping in the server adapters.

Custom kinds and mappersCopy Anchor Link

Add mappers for your own RAISE codes:

const betterSupabase = defineSupabase(schema, {
  errors: [
    (raw, fallback) =>
      raw.hint === "quota_exceeded"
        ? dbError("forbidden", fallback.message)
        : undefined,
  ],
});

Plugins can also contribute a mapError. These mappers turn a raw Postgres or PostgREST error into a DbError; the next section turns a DbError into your own error.

Domain errors for .orThrow()Copy Anchor Link

betterSupabase.mapError(fn) sets the error .orThrow() throws for every db it connects, instead of a DbException:

export class AppError extends Error {
  constructor(readonly error: DbError) {
    super(error.message, { cause: error });
  }
}

export const toAppError = (error: DbError) => new AppError(error);
export const betterSupabase = defineSupabase(schema).mapError(toAppError);

await db.customers.findById(id).orThrow(); // throws AppError

Results themselves keep their DbError, so they stay serializable. The mapper survives map, mapError and andThen; a factory passed to .orThrow(factory) takes precedence.

Set the DbError as the error's cause. The server, Next.js, Hono and oRPC adapters then still answer with Problem Details, and isConflict, isCheck and isForeignKey still match. TanStack Query hooks always see a DbException, whatever the mapper.

better-resultCopy Anchor Link

To return better-result values instead, wrap the db with withBetterResult or convert single results with toBetterResult. See better-result.