@supabase/postgrest-js 2.107.0-canary.0 → 2.107.0-canary.2

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 {
@@ -3247,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
@@ -4024,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
@@ -4233,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
@@ -4397,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
@@ -4556,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