fix(postgrest): honour throwOnError when maybeSingle finds multiple rows

[Zuhef]

What kind of change does this PR introduce?

Bug fix

What is the current behavior?

Fixes #2579

Since the fix for postgrest-js#361, .maybeSingle() no longer sends Accept: application/vnd.pgrst.object+json — it fetches a list and enforces cardinality client-side, synthesising PGRST116 when more than one row comes back:

if (this.isMaybeSingle && Array.isArray(data)) {
  if (data.length > 1) {
    error = { code: 'PGRST116', /* … */ }
    data = null
    count = null
    status = 406
    statusText = 'Not Acceptable'
  } else if (…)

That branch never consults this.shouldThrowOnError. Every other error path in processResponse does — the non-2xx path ends with if (error && this.shouldThrowOnError) throw new PostgrestError(error) — and then() has no post-hoc throw, so throwing only ever happens at those sites.

The result is that .maybeSingle().throwOnError() resolves with an error object instead of rejecting, which contradicts what throwOnError() documents ("reject the promise by throwing the error instead of returning it as part of a successful response").

That fails in the unhelpful direction. Code written as

const { data } = await supabase.from('users').select().maybeSingle().throwOnError()

destructures only data precisely because it trusts throwOnError() to raise. With duplicate rows it quietly gets data === null and no exception, so the condition is swallowed rather than surfaced.

What is the new behavior?

The synthesised PGRST116 now rejects with a PostgrestError when throwOnError() is active, matching what happens when PostgREST itself returns that error.

Behaviour without throwOnError() is unchanged: still status: 406, statusText: 'Not Acceptable', error.code: 'PGRST116', data: null. The returned error object is untouched — including hint: null, which existing snapshots in basic.test.ts and transforms.test.ts assert. PostgrestError types hint as string, so the throw passes hint: error.hint ?? '', consistent with the other synthesised throw in this file which uses hint: ''.

Additional context

maybeSingle() + throwOnError() had no test coverage — the existing PGRST116 assertions check the returned error object rather than the throwing path, and they need the Dockerised PostgREST. The new test/maybe-single.test.ts uses a mocked fetch, so it runs offline and pins all four cardinality outcomes: one row, zero rows, multiple rows, and multiple rows with throwOnError().

Verification, from packages/core/postgrest-js:

$ npx jest --runInBand test/maybe-single.test.ts
Tests:  4 passed, 4 total

Before the source change, the new suite is 1 failed, 3 passed, with:

● maybeSingle cardinality handling › honours throwOnError() when multiple rows are returned
  expect(received).rejects.toThrow()
  Received promise resolved instead of rejected

Across the suites that run without Docker (fetch-errors, headers-serialization, retry, max-affected, permission-hints, maybe-single): 45 passed / 6 failed with this change, versus 44 passed / 7 failed on an unmodified checkout — the one flipped test is the new one, and nothing else moved. The 6 remaining failures are all in max-affected.test.ts and fail with ECONNREFUSED; they need the local PostgREST from docker compose, which isn't available in my environment, so those are untouched-but-unverified by me.

Also checked:

• tsc --noEmit --project tsconfig.json — clean.
• tsc --noEmit --project tsconfig.test.json — clean.
• prettier --check — clean on both files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c80d4fec-30b4-44d2-9384-382895da1e73

📥 Commits

Reviewing files that changed from the base of the PR and between 6331898 and e7a101b.

📒 Files selected for processing (2)

• packages/core/postgrest-js/src/PostgrestBuilder.ts
• packages/core/postgrest-js/test/maybe-single.test.ts

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Improved maybeSingle() handling for responses containing multiple records.
  • Multiple-record responses now consistently return a “Not Acceptable” error with no data.
  • Improved error details when .throwOnError() is enabled, ensuring the request rejects with a properly formatted error.

• Tests

  • Added coverage for single-record, empty, multiple-record, and error-throwing scenarios.

Walkthrough

maybeSingle() now honors .throwOnError() when multiple rows are returned. The synthesized PGRST116 error is converted into a PostgrestError, with a string-valued hint. Tests cover single-row unwrapping, empty results, multi-row 406 responses, and promise rejection when throwing is enabled.

Assessment against linked issues

Objective	Addressed	Explanation
Ensure maybeSingle().throwOnError() rejects on multiple rows with a PGRST116 PostgrestError [#2579]	✅

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

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

@supabase/functions-js

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

@supabase/postgrest-js

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

@supabase/realtime-js

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

@supabase/storage-js

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

@supabase/supabase-js

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

commit: e7a101b

[coveralls]

coverage: 93.355% (+12.1%) from 81.305% — Zuhef:fix/alpha-2579-maybesingle-throwonerror into supabase:master

[mandarini]

thanks