fix(postgrest): bubble up fetch error causes and codes

[mandarini]

Summary

Fixes fetch error handling in postgrest-js to properly bubble up underlying error causes (DNS failures, network issues, timeouts), enabling informed retry logic in middleware and applications.

Problem

Previously, when fetch failed due to network issues, postgrest-js would return a generic error:

  {
    error: {
      message: "TypeError: fetch failed",
      details: "TypeError: fetch failed\n    at ...",
      hint: "",
      code: ""
    }
  }

The underlying cause (e.g., DNS resolution failure with ENOTFOUND) was lost, making it impossible to:

• Distinguish between different types of network failures
• Implement idempotent retry logic based on error type
• Debug production issues effectively

Solution

Modified error handling in PostgrestBuilder.ts to extract and expose the cause property from fetch errors:

  {
    error: {
      message: "TypeError: fetch failed",
      details: "TypeError: fetch failed\n    ...\n\nCaused by: Error: getaddrinfo 
  ENOTFOUND example.com\n...\nError code: ENOTFOUND",
      hint: "Underlying cause: getaddrinfo ENOTFOUND example.com",
      code: "ENOTFOUND"  // ← Now populated!
    }
  }

Changes

• PostgrestBuilder.ts: Enhanced fetch error handling to capture cause information
• fetch-errors.test.ts: Added comprehensive test coverage for:
  • DNS resolution failures (ENOTFOUND)
  • Connection refused errors (ECONNREFUSED)
  • Timeout errors (ETIMEDOUT)
  • Errors with and without causes
  • Behavior with throwOnError()

[steve-chavez]

     error: {
      message: "TypeError: fetch failed",
      details: "TypeError: fetch failed\n    ...\n\nCaused by: Error: getaddrinfo 
  ENOTFOUND example.com\n...\nError code: ENOTFOUND",
      hint: "Underlying cause: getaddrinfo ENOTFOUND example.com",
      code: "ENOTFOUND"  // ← Now populated!
    }

Some problems with the above:

• hint is not really a "hint" for the user.
• code is meant to represent the upstream service error code, conflating it with client error codes can lead to confusion.

I would suggest not modifying hint and code, adding more content to details looks enough. Maybe TypeError: fetch failed\n ...\n\n from details can be removed?

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@1856

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@1856

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@1856

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@1856

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@1856

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@1856

commit: be21e84