feat(postgrest): expose query builder options to .from method

Reimplement the feature from scratch on latest master, addressing all
review feedback from mandarini:

1. PostgrestQueryBuilderOptions type added to postgrest-js with headers,
   fetch, urlLengthLimit, and retry fields.
2. PostgrestClient.from() now accepts an optional options parameter.
   Per-request headers are merged (request takes precedence), and
   per-request fetch/retry/urlLengthLimit override client defaults.
3. SupabaseClient.from() forwards options to rest.from(), wrapping any
   custom fetch with fetchWithAuth so auth headers are always injected.
   A new options object is created to avoid mutating the caller's object.
4. mergeHeaders utility added for non-destructive header merging.
5. Tests cover: custom fetch usage, header precedence, auth injection,
   retry override, and non-mutation of caller options.

Co-authored-by: stenlan <stenlan@users.noreply.github.com>
Closes #438

Author: 7vignesh

packages/core/postgrest-js/src/PostgrestClient.ts

@@ -2,6 +2,8 @@ import PostgrestQueryBuilder from './PostgrestQueryBuilder'
 import PostgrestFilterBuilder from './PostgrestFilterBuilder'
 import { Fetch, GenericSchema, ClientServerOptions } from './types/common/common'
 import { GetRpcFunctionFilterBuilderByArgs } from './types/common/rpc'
+import { PostgrestQueryBuilderOptions } from './types/types'
+import { mergeHeaders } from './utils'
 
 /**
  * PostgREST client.
@@ -156,24 +158,29 @@ export default class PostgrestClient<
   from<
     TableName extends string & keyof Schema['Tables'],
     Table extends Schema['Tables'][TableName],
-  >(relation: TableName): PostgrestQueryBuilder<ClientOptions, Schema, Table, TableName>
+  >(
+    relation: TableName,
+    options?: PostgrestQueryBuilderOptions
+  ): PostgrestQueryBuilder<ClientOptions, Schema, Table, TableName>
   from<ViewName extends string & keyof Schema['Views'], View extends Schema['Views'][ViewName]>(
-    relation: ViewName
+    relation: ViewName,
+    options?: PostgrestQueryBuilderOptions
   ): PostgrestQueryBuilder<ClientOptions, Schema, View, ViewName>
   from(
-    relation: (string & keyof Schema['Tables']) | (string & keyof Schema['Views'])
+    relation: (string & keyof Schema['Tables']) | (string & keyof Schema['Views']),
+    options?: PostgrestQueryBuilderOptions
   ): PostgrestQueryBuilder<ClientOptions, Schema, any, any> {
     if (!relation || typeof relation !== 'string' || relation.trim() === '') {
       throw new Error('Invalid relation name: relation must be a non-empty string.')
     }
 
     const url = new URL(`${this.url}/${relation}`)
     return new PostgrestQueryBuilder(url, {
-      headers: new Headers(this.headers),
+      headers: mergeHeaders(this.headers, options?.headers),
       schema: this.schemaName,
-      fetch: this.fetch,
-      urlLengthLimit: this.urlLengthLimit,
-      retry: this.retry,
+      fetch: options?.fetch ?? this.fetch,
+      urlLengthLimit: options?.urlLengthLimit ?? this.urlLengthLimit,
+      retry: options?.retry ?? this.retry,
     })
   }
 

packages/core/postgrest-js/src/index.ts

@@ -27,6 +27,7 @@ export type {
   PostgrestResponseSuccess,
   PostgrestSingleResponse,
   PostgrestMaybeSingleResponse,
+  PostgrestQueryBuilderOptions,
 } from './types/types'
 export type { ClientServerOptions as PostgrestClientOptions } from './types/common/common'
 // https://github.com/supabase/postgrest-js/issues/551

packages/core/postgrest-js/src/types/types.ts

@@ -1,7 +1,7 @@
 import PostgrestError from '../PostgrestError'
 import { ContainsNull } from '../select-query-parser/types'
 import { SelectQueryError } from '../select-query-parser/utils'
-import { ClientServerOptions } from './common/common'
+import { ClientServerOptions, Fetch } from './common/common'
 
 /**
  * Response format
@@ -40,6 +40,27 @@ export type PostgrestSingleResponse<T> = PostgrestResponseSuccess<T> | Postgrest
 export type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>
 export type PostgrestResponse<T> = PostgrestSingleResponse<T[]>
 
+/**
+ * Per-request options for `.from()` queries. These override the
+ * corresponding client-level defaults for a single query.
+ */
+export type PostgrestQueryBuilderOptions = {
+  /** Additional headers to merge with the client-level headers. Per-request headers take precedence. */
+  headers?: HeadersInit
+  /** A custom fetch implementation for this request only. Auth headers are injected automatically. */
+  fetch?: Fetch
+  /** Override the client-level URL length limit for this request. */
+  urlLengthLimit?: number
+  /** Override the client-level retry setting for this request. */
+  retry?: boolean
+}
+
+/** @internal */
+export type PostgrestQueryBuilderOptionsWithSchema<TSchema extends string> =
+  PostgrestQueryBuilderOptions & {
+    schema?: TSchema
+  }
+
 export type DatabaseWithOptions<Database, Options extends ClientServerOptions> = {
   db: Database
   options: Options

packages/core/postgrest-js/src/utils.ts

@@ -0,0 +1,22 @@
+/**
+ * Non-destructively merges an optional {@link HeadersInit} into a base
+ * {@link Headers} object. Right-side entries take precedence over left.
+ */
+export function mergeHeaders(left: Headers, right?: HeadersInit): Headers {
+  const merged = new Headers(left)
+
+  if (!right) return merged
+
+  const entries =
+    right instanceof Headers
+      ? right.entries()
+      : Array.isArray(right)
+        ? right
+        : Object.entries(right)
+
+  for (const [key, value] of entries) {
+    merged.set(key, value)
+  }
+
+  return merged
+}

packages/core/supabase-js/src/SupabaseClient.ts

@@ -4,6 +4,7 @@ import {
   PostgrestClient,
   type PostgrestFilterBuilder,
   type PostgrestQueryBuilder,
+  type PostgrestQueryBuilderOptions,
 } from '@supabase/postgrest-js'
 import {
   type RealtimeChannel,
@@ -429,17 +430,38 @@ export default class SupabaseClient<
   from<
     TableName extends string & keyof Schema['Tables'],
     Table extends Schema['Tables'][TableName],
-  >(relation: TableName): PostgrestQueryBuilder<ClientOptions, Schema, Table, TableName>
+  >(
+    relation: TableName,
+    options?: PostgrestQueryBuilderOptions
+  ): PostgrestQueryBuilder<ClientOptions, Schema, Table, TableName>
   from<ViewName extends string & keyof Schema['Views'], View extends Schema['Views'][ViewName]>(
-    relation: ViewName
+    relation: ViewName,
+    options?: PostgrestQueryBuilderOptions
   ): PostgrestQueryBuilder<ClientOptions, Schema, View, ViewName>
   /**
    * Perform a query on a table or a view.
    *
    * @param relation - The table or view name to query
+   * @param options - Per-request options that override client-level defaults
    */
-  from(relation: string): PostgrestQueryBuilder<ClientOptions, Schema, any> {
-    return this.rest.from(relation)
+  from(
+    relation: string,
+    options?: PostgrestQueryBuilderOptions
+  ): PostgrestQueryBuilder<ClientOptions, Schema, any> {
+    const resolvedOptions: PostgrestQueryBuilderOptions | undefined = options?.fetch
+      ? {
+          ...options,
+          fetch: fetchWithAuth(
+            this.supabaseKey,
+            this.supabaseUrl,
+            this._getSessionToken.bind(this),
+            options.fetch,
+            this.settings?.tracePropagation
+          ),
+        }
+      : options
+
+    return this.rest.from(relation, resolvedOptions)
   }
 
   // NOTE: signatures must be kept in sync with PostgrestClient.schema

packages/core/supabase-js/test/unit/SupabaseClient.test.ts

@@ -123,6 +123,114 @@ describe('SupabaseClient', () => {
     })
   })
 
+  describe('PostgREST per-request options', () => {
+    test('should use custom fetch passed via options parameter', async () => {
+      const clientFetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+      const requestFetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+
+      const client = createClient(URL, KEY, {
+        global: { fetch: clientFetch },
+      })
+
+      await client.from('users', { fetch: requestFetch }).select()
+
+      expect(requestFetch).toHaveBeenCalled()
+      expect(clientFetch).not.toHaveBeenCalled()
+    })
+
+    test('should prefer per-request header over client-level header with same name', async () => {
+      const mockFetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+
+      const client = createClient(URL, KEY, {
+        global: {
+          headers: { 'X-Custom': 'client-value' },
+          fetch: mockFetch,
+        },
+      })
+
+      await client.from('users', { headers: { 'X-Custom': 'request-value' } }).select()
+
+      const calledHeaders = mockFetch.mock.calls[0][1]?.headers
+      const headers = calledHeaders instanceof Headers ? calledHeaders : new Headers(calledHeaders)
+      expect(headers.get('X-Custom')).toBe('request-value')
+    })
+
+    test('should inject auth headers when a custom per-request fetch is provided', async () => {
+      const requestFetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+
+      const client = createClient(URL, KEY)
+
+      await client.from('users', { fetch: requestFetch }).select()
+
+      expect(requestFetch).toHaveBeenCalled()
+      const calledHeaders = requestFetch.mock.calls[0][1]?.headers
+      const headers = calledHeaders instanceof Headers ? calledHeaders : new Headers(calledHeaders)
+      expect(headers.get('apikey')).toBe(KEY)
+    })
+
+    test('should forward per-request retry option', () => {
+      const client = createClient(URL, KEY)
+
+      // Default retry is true
+      // @ts-expect-error retryEnabled is protected
+      const defaultRetry = client.from('users').select().retryEnabled
+      expect(defaultRetry).toBe(true)
+
+      // Per-request override to false
+      // @ts-expect-error retryEnabled is protected
+      const overriddenRetry = client.from('users', { retry: false }).select().retryEnabled
+      expect(overriddenRetry).toBe(false)
+    })
+
+    test('should not mutate the caller options object', async () => {
+      const requestFetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+
+      const client = createClient(URL, KEY)
+      const options = { fetch: requestFetch }
+      const originalFetch = options.fetch
+
+      await client.from('users', options).select()
+
+      // The options object should not have been mutated
+      expect(options.fetch).toBe(originalFetch)
+    })
+  })
+
   describe('Custom Headers', () => {
     test('should have custom header set', () => {
       const customHeader = { 'X-Test-Header': 'value' }