@supabase/postgrest-js 2.107.0-beta.1 → 2.107.0-beta.7

package/dist/index.cjs

@@ -33,6 +33,25 @@ const RETRYABLE_METHODS = [
 /**
 * 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}
 */
 var PostgrestError = class extends Error {
@@ -351,7 +370,18 @@ var PostgrestBuilder = class {
 				const body = await res.text();
 				if (body === "") {} else if (_this2.headers.get("Accept") === "text/csv") data = body;
 				else if (_this2.headers.get("Accept") && ((_this$headers$get = _this2.headers.get("Accept")) === null || _this$headers$get === void 0 ? void 0 : _this$headers$get.includes("application/vnd.pgrst.plan+text"))) data = body;
-				else data = JSON.parse(body);
+				else try {
+					data = JSON.parse(body);
+				} catch (_unused) {
+					error = { message: body };
+					data = null;
+					if (_this2.shouldThrowOnError) throw new PostgrestError({
+						message: body,
+						details: "",
+						hint: "",
+						code: ""
+					});
+				}
 			}
 			const countHeader = (_this$headers$get2 = _this2.headers.get("Prefer")) === null || _this$headers$get2 === void 0 ? void 0 : _this$headers$get2.match(/count=(exact|planned|estimated)/);
 			const contentRange = (_res$headers$get2 = res.headers.get("content-range")) === null || _res$headers$get2 === void 0 ? void 0 : _res$headers$get2.split("/");
@@ -379,7 +409,7 @@ var PostgrestBuilder = class {
 					status = 200;
 					statusText = "OK";
 				}
-			} catch (_unused) {
+			} catch (_unused2) {
 				if (res.status === 404 && body === "") {
 					status = 204;
 					statusText = "No Content";
@@ -3236,6 +3266,33 @@ var PostgrestQueryBuilder = class {
 	* }
 	* ```
 	*
+	* @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
@@ -4013,6 +4070,15 @@ var PostgrestQueryBuilder = class {
 	* }
 	* ```
 	*
+	* @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
@@ -4222,6 +4288,15 @@ var PostgrestQueryBuilder = class {
 	* }
 	* ```
 	*
+	* @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
@@ -4386,6 +4461,15 @@ var PostgrestQueryBuilder = class {
 	* }
 	* ```
 	*
+	* @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
@@ -4545,6 +4629,15 @@ var PostgrestQueryBuilder = class {
 	* }
 	* ```
 	*
+	* @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