@supabase/postgrest-js 2.107.0-beta.0 → 2.107.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/postgrest-js",
-  "version": "2.107.0-beta.0",
+  "version": "2.107.0-beta.6",
   "description": "Isomorphic PostgREST client",
   "keywords": [
     "postgrest",

package/src/PostgrestBuilder.ts

@@ -69,11 +69,9 @@ export default abstract class PostgrestBuilder<
   ClientOptions extends ClientServerOptions,
   Result,
   ThrowOnError extends boolean = false,
-> implements
-    PromiseLike<
-      ThrowOnError extends true ? PostgrestResponseSuccess<Result> : PostgrestSingleResponse<Result>
-    >
-{
+> implements PromiseLike<
+  ThrowOnError extends true ? PostgrestResponseSuccess<Result> : PostgrestSingleResponse<Result>
+> {
   protected method: 'GET' | 'HEAD' | 'POST' | 'PATCH' | 'DELETE'
   protected url: URL
   protected headers: Headers
@@ -476,7 +474,17 @@ export default abstract class PostgrestBuilder<
         ) {
           data = body
         } else {
-          data = JSON.parse(body)
+          try {
+            data = JSON.parse(body)
+          } catch {
+            // A 2xx status doesn't guarantee a JSON body; mirror the non-2xx fallback below.
+            error = { message: body }
+            data = null
+
+            if (this.shouldThrowOnError) {
+              throw new PostgrestError({ message: body, details: '', hint: '', code: '' })
+            }
+          }
         }
       }
 

package/src/PostgrestError.ts

@@ -1,6 +1,25 @@
 /**
  * Error format
  *
+ * Returned by every PostgREST request that fails. When something fails, the
+ * single most useful field is usually `hint` — Postgres often returns the
+ * actionable fix there, not in `message`. Always log the full object (e.g.
+ * `console.error(error)`); logging only `error.message` hides the hint.
+ *
+ * Read the fields in roughly this order of usefulness:
+ *
+ * - `hint` — actionable guidance from the database when available. For
+ *   permission-denied errors (`42501`), this is the literal SQL to fix the
+ *   problem, e.g.
+ *   `"Grant the required privileges to the current role with: GRANT SELECT ON public.users TO anon;"`.
+ *   Missing column? `hint` suggests the column you probably meant. Whenever
+ *   Postgres knows the fix, it puts it in `hint`.
+ * - `code` — stable error code from PostgREST (e.g. `PGRST301`) or Postgres
+ *   (e.g. `42501`). Branch on this rather than on `message` text.
+ * - `details` — extra context, often the offending value, key, or row.
+ * - `message` — human-readable summary. Useful in UI strings; less useful
+ *   for debugging.
+ *
  * {@link https://postgrest.org/en/stable/api.html?highlight=options#errors-and-http-status-codes}
  */
 export default class PostgrestError extends Error {

package/src/PostgrestQueryBuilder.ts

@@ -169,6 +169,33 @@ export default class PostgrestQueryBuilder<
      * }
      * ```
      *
+     * @exampleDescription Handling errors
+     * The most useful field on a Postgres error is usually `hint` — when the database knows the fix, it puts the literal SQL there. For example, a permission-denied error (`code: '42501'`) arrives with a `hint` like `"Grant the required privileges to the current role with: GRANT SELECT ON public.characters TO anon;"`. Log the full `error` object so the hint isn't hidden behind `error.message`.
+     *
+     * @example Handling errors
+     * ```js
+     * const { data, error } = await supabase.from('characters').select()
+     * if (error) {
+     *   // Logs the full error: message, code, details, and hint.
+     *   console.error(error)
+     *   return
+     * }
+     * ```
+     *
+     * @exampleResponse Handling errors
+     * ```json
+     * {
+     *   "error": {
+     *     "code": "42501",
+     *     "details": null,
+     *     "hint": "Grant the required privileges to the current role with: GRANT SELECT ON public.characters TO anon;",
+     *     "message": "permission denied for table characters"
+     *   },
+     *   "status": 401,
+     *   "statusText": "Unauthorized"
+     * }
+     * ```
+     *
      * @example Selecting specific columns
      * ```js
      * const { data, error } = await supabase
@@ -985,6 +1012,15 @@ export default class PostgrestQueryBuilder<
    * }
    * ```
    *
+   * @exampleDescription Handling errors
+   * `error.hint` from Postgres often contains the actionable fix (e.g. `"Grant the required privileges to the current role with: GRANT INSERT ON public.countries TO anon;"` for a `42501` permission-denied error). Log the full `error` object so it isn't hidden behind `error.message`.
+   *
+   * @example Handling errors
+   * ```js
+   * const { error } = await supabase.from('countries').insert({ id: 1, name: 'Mordor' })
+   * if (error) console.error(error)
+   * ```
+   *
    * @example Create a record and return it
    * ```ts
    * const { data, error } = await supabase
@@ -1226,6 +1262,15 @@ export default class PostgrestQueryBuilder<
    * }
    * ```
    *
+   * @exampleDescription Handling errors
+   * `error.hint` from Postgres often contains the actionable fix (e.g. `"Grant the required privileges to the current role with: GRANT INSERT, UPDATE ON public.instruments TO anon;"` for a `42501` permission-denied error). Log the full `error` object so it isn't hidden behind `error.message`.
+   *
+   * @example Handling errors
+   * ```js
+   * const { data, error } = await supabase.from('instruments').upsert({ id: 1, name: 'piano' }).select()
+   * if (error) console.error(error)
+   * ```
+   *
    * @example Bulk Upsert your data
    * ```ts
    * const { data, error } = await supabase
@@ -1428,6 +1473,15 @@ export default class PostgrestQueryBuilder<
    * }
    * ```
    *
+   * @exampleDescription Handling errors
+   * `error.hint` from Postgres often contains the actionable fix (e.g. `"Grant the required privileges to the current role with: GRANT UPDATE ON public.instruments TO anon;"` for a `42501` permission-denied error). Log the full `error` object so it isn't hidden behind `error.message`.
+   *
+   * @example Handling errors
+   * ```js
+   * const { error } = await supabase.from('instruments').update({ name: 'piano' }).eq('id', 1)
+   * if (error) console.error(error)
+   * ```
+   *
    * @example Update a record and return it
    * ```ts
    * const { data, error } = await supabase
@@ -1609,6 +1663,15 @@ export default class PostgrestQueryBuilder<
    * }
    * ```
    *
+   * @exampleDescription Handling errors
+   * `error.hint` from Postgres often contains the actionable fix (e.g. `"Grant the required privileges to the current role with: GRANT DELETE ON public.countries TO anon;"` for a `42501` permission-denied error). Log the full `error` object so it isn't hidden behind `error.message`.
+   *
+   * @example Handling errors
+   * ```js
+   * const { error } = await supabase.from('countries').delete().eq('id', 1)
+   * if (error) console.error(error)
+   * ```
+   *
    * @example Delete a record and return it
    * ```ts
    * const { data, error } = await supabase

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.107.0-beta.0'
+export const version = '2.107.0-beta.6'