@supabase/postgrest-js 2.114.0 → 2.115.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/postgrest-js",
-  "version": "2.114.0",
+  "version": "2.115.0",
   "description": "Isomorphic PostgREST client",
   "keywords": [
     "postgrest",

package/src/PostgrestBuilder.ts

@@ -5,66 +5,11 @@ import type {
   MergePartialResult,
   IsValidResultOverride,
 } from './types/types'
-import {
-  ClientServerOptions,
-  Fetch,
-  DEFAULT_MAX_RETRIES,
-  getRetryDelay,
-  RETRYABLE_STATUS_CODES,
-  RETRYABLE_METHODS,
-} from './types/common/common'
+import { ClientServerOptions, Fetch } from './types/common/common'
 import PostgrestError from './PostgrestError'
+import { fetchWithRetry } from './fetchWithRetry'
 import { ContainsNull } from './select-query-parser/types'
 
-/**
- * Sleep for a given number of milliseconds.
- * If an AbortSignal is provided, the sleep resolves early when the signal is aborted.
- */
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
-    if (signal?.aborted) {
-      resolve()
-      return
-    }
-    const id = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort)
-      resolve()
-    }, ms)
-    function onAbort() {
-      clearTimeout(id)
-      resolve()
-    }
-    signal?.addEventListener('abort', onAbort)
-  })
-}
-
-/**
- * Check if a request should be retried based on method and status code.
- */
-function shouldRetry(
-  method: string,
-  status: number,
-  attemptCount: number,
-  retryEnabled: boolean
-): boolean {
-  // Don't retry if retries are disabled or we've exhausted attempts
-  if (!retryEnabled || attemptCount >= DEFAULT_MAX_RETRIES) {
-    return false
-  }
-
-  // Only retry idempotent methods (GET, HEAD, OPTIONS)
-  if (!RETRYABLE_METHODS.includes(method as (typeof RETRYABLE_METHODS)[number])) {
-    return false
-  }
-
-  // Only retry on specific status codes (520 - Cloudflare errors)
-  if (!RETRYABLE_STATUS_CODES.includes(status as (typeof RETRYABLE_STATUS_CODES)[number])) {
-    return false
-  }
-
-  return true
-}
-
 export default abstract class PostgrestBuilder<
   ClientOptions extends ClientServerOptions,
   Result,
@@ -314,75 +259,32 @@ export default abstract class PostgrestBuilder<
       status: number
       statusText: string
     }> => {
-      let attemptCount = 0
-
-      while (true) {
-        // Serialize headers as a plain object rather than a Headers instance.
-        // React Native's XHR-based fetch silently drops headers (notably Content-Type)
-        // when given a Headers instance, causing PGRST202 on parameter-less RPC calls.
-        // See supabase/supabase-js#1562 and facebook/react-native#33933.
-        // All sibling packages (auth-js, storage-js, functions-js) already pass plain objects.
-        const headers: Record<string, string> = {}
-        this.headers.forEach((value, key) => {
-          headers[key] = value
-        })
-        if (attemptCount > 0) {
-          headers['X-Retry-Count'] = String(attemptCount)
-        }
-
-        // Only wrap the fetch call itself — processResponse errors must never trigger retries
-        let res: Response
-        try {
-          res = await _fetch(this.url.toString(), {
-            method: this.method,
-            headers,
-            body: JSON.stringify(this.body, (_, value) =>
-              typeof value === 'bigint' ? value.toString() : value
-            ),
-            signal: this.signal,
-          })
-          // JS allows throwing any value, and serverless or realm-crossing fetch
-          // implementations can reject with non-Error objects. `instanceof Error`
-          // is too narrow here; narrow at the use site with optional chaining.
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        } catch (fetchError: any) {
-          // Never retry aborted requests
-          if (fetchError?.name === 'AbortError' || fetchError?.code === 'ABORT_ERR') {
-            throw fetchError
-          }
-
-          // Don't retry network errors for non-idempotent methods
-          if (!RETRYABLE_METHODS.includes(this.method as (typeof RETRYABLE_METHODS)[number])) {
-            throw fetchError
-          }
-
-          // Check if we should retry network errors
-          if (this.retryEnabled && attemptCount < DEFAULT_MAX_RETRIES) {
-            const delay = getRetryDelay(attemptCount)
-            attemptCount++
-            await sleep(delay, this.signal)
-            continue
-          }
-
-          // Exhausted retries or retries disabled, throw the last error
-          throw fetchError
-        }
-
-        // Check if we should retry this HTTP response
-        if (shouldRetry(this.method, res.status, attemptCount, this.retryEnabled)) {
-          const retryAfterHeader = res.headers?.get('Retry-After') ?? null
-          const delay =
-            retryAfterHeader !== null
-              ? Math.max(0, parseInt(retryAfterHeader, 10) || 0) * 1000
-              : getRetryDelay(attemptCount)
-          await res.text()
-          attemptCount++
-          await sleep(delay, this.signal)
-          continue
-        }
+      // Serialize headers as a plain object rather than a Headers instance.
+      // React Native's XHR-based fetch silently drops headers (notably Content-Type)
+      // when given a Headers instance, causing PGRST202 on parameter-less RPC calls.
+      // See supabase/supabase-js#1562 and facebook/react-native#33933.
+      // All sibling packages (auth-js, storage-js, functions-js) already pass plain objects.
+      const headers: Record<string, string> = {}
+      this.headers.forEach((value, key) => {
+        headers[key] = value
+      })
 
-        return await this.processResponse(res)
-      }
+      // Only the fetch itself is retried — processResponse errors must never trigger retries
+      const res = await fetchWithRetry(
+        _fetch,
+        this.url.toString(),
+        {
+          method: this.method,
+          headers,
+          body: JSON.stringify(this.body, (_, value) =>
+            typeof value === 'bigint' ? value.toString() : value
+          ),
+          signal: this.signal,
+        },
+        this.retryEnabled
+      )
+
+      return await this.processResponse(res)
     }
 
     let res = executeWithRetry()

package/src/PostgrestClient.ts

@@ -2,6 +2,62 @@ import PostgrestQueryBuilder from './PostgrestQueryBuilder'
 import PostgrestFilterBuilder from './PostgrestFilterBuilder'
 import { Fetch, GenericSchema, ClientServerOptions } from './types/common/common'
 import { GetRpcFunctionFilterBuilderByArgs } from './types/common/rpc'
+import PostgrestError from './PostgrestError'
+import { fetchWithRetry } from './fetchWithRetry'
+import {
+  PostgrestOpenApiSpec,
+  PostgrestResponseFailure,
+  PostgrestSingleResponse,
+} from './types/types'
+
+/**
+ * Build the error for a failed OpenAPI request. PostgREST answers with a JSON
+ * error object when it produced the failure itself; proxies and disabled
+ * OpenAPI output answer with plain text or an empty body, in which case the
+ * body (or, failing that, the status text) becomes the message.
+ */
+function toOpenApiError(body: string, statusText: string): PostgrestError {
+  try {
+    const parsed = JSON.parse(body)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return new PostgrestError({
+        message: String(parsed.message ?? body),
+        details: parsed.details ?? '',
+        hint: parsed.hint ?? '',
+        code: parsed.code ?? '',
+      })
+    }
+  } catch {
+    // Not JSON; fall through to the plain-text message.
+  }
+  return new PostgrestError({ message: body || statusText, details: '', hint: '', code: '' })
+}
+
+/**
+ * Build the response for a request that yielded no readable body: the fetch
+ * itself rejected (no status is known, so it is 0), or the body stream failed
+ * while being read (the response status is preserved).
+ */
+function toTransportFailure(
+  cause: unknown,
+  status: number,
+  statusText: string
+): PostgrestResponseFailure {
+  const err = cause as { name?: string; message?: string } | null | undefined
+  return {
+    success: false,
+    error: new PostgrestError({
+      message: `${err?.name ?? 'FetchError'}: ${err?.message}`,
+      details: '',
+      hint: '',
+      code: '',
+    }),
+    data: null,
+    count: null,
+    status,
+    statusText,
+  }
+}
 
 /**
  * PostgREST client.
@@ -203,6 +259,87 @@ export default class PostgrestClient<
     })
   }
 
+  /**
+   * Fetch the OpenAPI description PostgREST publishes for this client's schema.
+   *
+   * The document lists only the tables, views and functions the caller's role
+   * holds privileges on; PostgREST applies that filtering server-side. The
+   * schema is the one this client was created with, so call `.schema()` first
+   * to describe a different one. Transient failures are retried according to
+   * the client's `retry` option, like any other idempotent request.
+   *
+   * @example
+   * ```ts
+   * const { data, error } = await supabase.getOpenApiSpec()
+   * ```
+   *
+   * @example Describe a schema other than the client default
+   * ```ts
+   * const { data, error } = await supabase.schema('billing').getOpenApiSpec()
+   * ```
+   *
+   * @category Database
+   */
+  async getOpenApiSpec(): Promise<PostgrestSingleResponse<PostgrestOpenApiSpec>> {
+    const headers = new Headers(this.headers)
+    headers.set('Accept', 'application/openapi+json')
+    if (this.schemaName) {
+      headers.set('Accept-Profile', this.schemaName)
+    }
+
+    // Headers reach the fetch implementation as a plain object, as in
+    // PostgrestBuilder: React Native's XHR-based fetch drops headers that are
+    // supplied as a Headers instance.
+    const requestHeaders: Record<string, string> = {}
+    headers.forEach((value, key) => {
+      requestHeaders[key] = value
+    })
+
+    const fetchImpl = this.fetch ?? globalThis.fetch
+    let res: Response
+    try {
+      res = await fetchWithRetry(
+        fetchImpl,
+        `${this.url}/`,
+        { method: 'GET', headers: requestHeaders },
+        this.retry ?? true
+      )
+    } catch (fetchError) {
+      return toTransportFailure(fetchError, 0, '')
+    }
+
+    let body: string
+    try {
+      body = await res.text()
+    } catch (readError) {
+      return toTransportFailure(readError, res.status, res.statusText)
+    }
+
+    if (res.ok) {
+      try {
+        return {
+          success: true,
+          error: null,
+          data: JSON.parse(body) as PostgrestOpenApiSpec,
+          count: null,
+          status: res.status,
+          statusText: res.statusText,
+        }
+      } catch {
+        // A 2xx status does not guarantee a JSON body; report it like a failure.
+      }
+    }
+
+    return {
+      success: false,
+      error: toOpenApiError(body, res.statusText),
+      data: null,
+      count: null,
+      status: res.status,
+      statusText: res.statusText,
+    }
+  }
+
   /**
    * Perform a function call.
    *

package/src/fetchWithRetry.ts

@@ -0,0 +1,141 @@
+import {
+  DEFAULT_MAX_RETRIES,
+  Fetch,
+  getRetryDelay,
+  RETRYABLE_METHODS,
+  RETRYABLE_STATUS_CODES,
+} from './types/common/common'
+
+/**
+ * Sleep for a given number of milliseconds.
+ * If an AbortSignal is provided, the sleep resolves early when the signal is aborted.
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+    const id = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    function onAbort() {
+      clearTimeout(id)
+      resolve()
+    }
+    signal?.addEventListener('abort', onAbort)
+  })
+}
+
+/**
+ * Check if a request should be retried based on method and status code.
+ */
+function shouldRetry(
+  method: string,
+  status: number,
+  attemptCount: number,
+  retryEnabled: boolean
+): boolean {
+  // Don't retry if retries are disabled or we've exhausted attempts
+  if (!retryEnabled || attemptCount >= DEFAULT_MAX_RETRIES) {
+    return false
+  }
+
+  // Only retry idempotent methods (GET, HEAD, OPTIONS)
+  if (!RETRYABLE_METHODS.includes(method as (typeof RETRYABLE_METHODS)[number])) {
+    return false
+  }
+
+  // Only retry on specific status codes (520 - Cloudflare errors)
+  if (!RETRYABLE_STATUS_CODES.includes(status as (typeof RETRYABLE_STATUS_CODES)[number])) {
+    return false
+  }
+
+  return true
+}
+
+export interface RetryableRequest {
+  method: string
+  /** Plain object, never a Headers instance: React Native's XHR-based fetch drops the latter. */
+  headers: Record<string, string>
+  body?: string
+  signal?: AbortSignal
+}
+
+/**
+ * Perform a request with the retry policy shared by every PostgREST call.
+ *
+ * Idempotent methods (GET, HEAD, OPTIONS) are retried up to
+ * `DEFAULT_MAX_RETRIES` times when the fetch rejects or the server answers
+ * with a retryable status (503, 520). The wait honours the `Retry-After`
+ * header when present and backs off exponentially otherwise. Retried
+ * attempts carry an `X-Retry-Count` header. Aborted requests and
+ * non-idempotent methods are never retried: their rejection propagates
+ * unchanged. A response body is drained before its request is retried.
+ */
+export async function fetchWithRetry(
+  fetchImpl: Fetch,
+  url: string,
+  request: RetryableRequest,
+  retryEnabled: boolean
+): Promise<Response> {
+  let attemptCount = 0
+
+  while (true) {
+    const headers: Record<string, string> = { ...request.headers }
+    if (attemptCount > 0) {
+      headers['X-Retry-Count'] = String(attemptCount)
+    }
+
+    let res: Response
+    try {
+      res = await fetchImpl(url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        signal: request.signal,
+      })
+      // JS allows throwing any value, and serverless or realm-crossing fetch
+      // implementations can reject with non-Error objects. `instanceof Error`
+      // is too narrow here; narrow at the use site with optional chaining.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (fetchError: any) {
+      // Never retry aborted requests
+      if (fetchError?.name === 'AbortError' || fetchError?.code === 'ABORT_ERR') {
+        throw fetchError
+      }
+
+      // Don't retry network errors for non-idempotent methods
+      if (!RETRYABLE_METHODS.includes(request.method as (typeof RETRYABLE_METHODS)[number])) {
+        throw fetchError
+      }
+
+      // Check if we should retry network errors
+      if (retryEnabled && attemptCount < DEFAULT_MAX_RETRIES) {
+        const delay = getRetryDelay(attemptCount)
+        attemptCount++
+        await sleep(delay, request.signal)
+        continue
+      }
+
+      // Exhausted retries or retries disabled, throw the last error
+      throw fetchError
+    }
+
+    // Check if we should retry this HTTP response
+    if (shouldRetry(request.method, res.status, attemptCount, retryEnabled)) {
+      const retryAfterHeader = res.headers?.get('Retry-After') ?? null
+      const delay =
+        retryAfterHeader !== null
+          ? Math.max(0, parseInt(retryAfterHeader, 10) || 0) * 1000
+          : getRetryDelay(attemptCount)
+      await res.text()
+      attemptCount++
+      await sleep(delay, request.signal)
+      continue
+    }
+
+    return res
+  }
+}

package/src/index.ts

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

package/src/types/types.ts

@@ -40,6 +40,28 @@ export type PostgrestSingleResponse<T> = PostgrestResponseSuccess<T> | Postgrest
 export type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>
 export type PostgrestResponse<T> = PostgrestSingleResponse<T[]>
 
+/**
+ * OpenAPI description served by PostgREST at the REST root (`GET /`).
+ *
+ * PostgREST emits OpenAPI 2.0 (Swagger), so the version lives in `swagger`.
+ * OpenAPI 2.0 requires only `swagger`, `info` and `paths`; a PostgREST
+ * `db-root-spec` override may leave out any other field. Only the top level
+ * is typed here; the contents of `paths`, `definitions` and `parameters`
+ * follow the OpenAPI 2.0 specification and vary with the PostgREST version.
+ *
+ * {@link https://docs.postgrest.org/en/stable/references/api/openapi.html}
+ */
+export interface PostgrestOpenApiSpec {
+  swagger: string
+  info: Record<string, unknown>
+  host?: string
+  basePath?: string
+  paths: Record<string, Record<string, unknown>>
+  definitions?: Record<string, Record<string, unknown>>
+  parameters?: Record<string, Record<string, unknown>>
+  [key: string]: unknown
+}
+
 export type DatabaseWithOptions<Database, Options extends ClientServerOptions> = {
   db: Database
   options: Options

package/src/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.114.0'
+export const version = '2.115.0'