⚠️ Error Handling

Errors inherently happen over networks. next-supa-utils treats errors not as exceptions that crash your Node.js server container, but as serialized objects you can gracefully handle through the handleSupaError() utility.

The handleSupaError Utility

Normalizes any thrown value into a consistent SupaError shape. It is used internally by createAction and the React hooks, but is also explicitly exported for direct usage if you are creating your own highly-customized data layer!

import { handleSupaError } from 'next-supa-utils';
import type { SupaError } from 'next-supa-utils';

function handleError(error: unknown): SupaError {
  return handleSupaError(error);
}

The SupaError Interface

SupaError normalizes both standard JavaScript errors and Supabase AuthError / PostgrestError incidents (extracting HTTP code and Postgres statuses).

export interface SupaError {
  message: string;
  code?: string;
  status?: number;
}

What Does It Catch?

If an error is thrown, handleSupaError catches it conditionally:

1. Supabase Core Errors (AuthError, PostgrestError): Securely extracts .message, .code, and HTTP .status codes securely.
2. Javascript Error Objects: Falls back to catching native DOM or Node.js runtime errors (like syntax crashes or unhandled references), serializing .message.
3. Strings: Normalizes literal thrown strings throw "Database crashed" into an object { message: "Database crashed" }.
4. Unknown Types: Provides a fallback "An unknown error occurred" if an unpredictable state collapses natively.

Always assume your server responses can fail, and confidently check the .error property bound to your UseSupa* client hooks or mapped createAction yields immediately!