@supabase/postgrest-js 2.101.1 → 2.102.0-beta.0

package/dist/index.mjs

@@ -1,3 +1,32 @@
+//#region src/types/common/common.ts
+/**
+* Default number of retry attempts.
+*/
+const DEFAULT_MAX_RETRIES = 3;
+/**
+* Default exponential backoff delay function.
+* Delays: 1s, 2s, 4s, 8s, ... (max 30s)
+*
+* @param attemptIndex - Zero-based index of the retry attempt
+* @returns Delay in milliseconds before the next retry
+*/
+const getRetryDelay = (attemptIndex) => Math.min(1e3 * 2 ** attemptIndex, 3e4);
+/**
+* Status codes that are safe to retry.
+* 520 = Cloudflare timeout/connection errors (transient)
+* 503 = PostgREST schema cache not yet loaded (transient, signals retry via Retry-After header)
+*/
+const RETRYABLE_STATUS_CODES = [520, 503];
+/**
+* HTTP methods that are safe to retry (idempotent operations).
+*/
+const RETRYABLE_METHODS = [
+	"GET",
+	"HEAD",
+	"OPTIONS"
+];
+
+//#endregion
 //#region src/PostgrestError.ts
 /**
 * Error format
@@ -29,6 +58,36 @@ var PostgrestError = class extends Error {
 
 //#endregion
 //#region src/PostgrestBuilder.ts
+/**
+* Sleep for a given number of milliseconds.
+* If an AbortSignal is provided, the sleep resolves early when the signal is aborted.
+*/
+function sleep(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+			resolve();
+			return;
+		}
+		const id = setTimeout(() => {
+			signal === null || signal === void 0 || signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(id);
+			resolve();
+		}
+		signal === null || signal === void 0 || signal.addEventListener("abort", onAbort);
+	});
+}
+/**
+* Check if a request should be retried based on method and status code.
+*/
+function shouldRetry(method, status, attemptCount, retryEnabled) {
+	if (!retryEnabled || attemptCount >= DEFAULT_MAX_RETRIES) return false;
+	if (!RETRYABLE_METHODS.includes(method)) return false;
+	if (!RETRYABLE_STATUS_CODES.includes(status)) return false;
+	return true;
+}
 var PostgrestBuilder = class {
 	/**
 	* Creates a builder configured for a specific PostgREST request.
@@ -56,8 +115,9 @@ var PostgrestBuilder = class {
 	* ```
 	*/
 	constructor(builder) {
-		var _builder$shouldThrowO, _builder$isMaybeSingl, _builder$urlLengthLim;
+		var _builder$shouldThrowO, _builder$isMaybeSingl, _builder$urlLengthLim, _builder$retry;
 		this.shouldThrowOnError = false;
+		this.retryEnabled = true;
 		this.method = builder.method;
 		this.url = builder.url;
 		this.headers = new Headers(builder.headers);
@@ -67,6 +127,7 @@ var PostgrestBuilder = class {
 		this.signal = builder.signal;
 		this.isMaybeSingle = (_builder$isMaybeSingl = builder.isMaybeSingle) !== null && _builder$isMaybeSingl !== void 0 ? _builder$isMaybeSingl : false;
 		this.urlLengthLimit = (_builder$urlLengthLim = builder.urlLengthLimit) !== null && _builder$urlLengthLim !== void 0 ? _builder$urlLengthLim : 8e3;
+		this.retryEnabled = (_builder$retry = builder.retry) !== null && _builder$retry !== void 0 ? _builder$retry : true;
 		if (builder.fetch) this.fetch = builder.fetch;
 		else this.fetch = fetch;
 	}
@@ -92,77 +153,73 @@ var PostgrestBuilder = class {
 		this.headers.set(name, value);
 		return this;
 	}
-	/**  *
+	/**
 	* @category Database
+	*
+	* Configure retry behavior for this request.
+	*
+	* By default, retries are enabled for idempotent requests (GET, HEAD, OPTIONS)
+	* that fail with network errors or specific HTTP status codes (503, 520).
+	* Retries use exponential backoff (1s, 2s, 4s) with a maximum of 3 attempts.
+	*
+	* @param enabled - Whether to enable retries for this request
+	*
+	* @example
+	* ```ts
+	* // Disable retries for a specific query
+	* const { data, error } = await supabase
+	*   .from('users')
+	*   .select()
+	*   .retry(false)
+	* ```
 	*/
+	retry(enabled) {
+		this.retryEnabled = enabled;
+		return this;
+	}
 	then(onfulfilled, onrejected) {
 		var _this = this;
 		if (this.schema === void 0) {} else if (["GET", "HEAD"].includes(this.method)) this.headers.set("Accept-Profile", this.schema);
 		else this.headers.set("Content-Profile", this.schema);
 		if (this.method !== "GET" && this.method !== "HEAD") this.headers.set("Content-Type", "application/json");
 		const _fetch = this.fetch;
-		let res = _fetch(this.url.toString(), {
-			method: this.method,
-			headers: this.headers,
-			body: JSON.stringify(this.body),
-			signal: this.signal
-		}).then(async (res$1) => {
-			let error = null;
-			let data = null;
-			let count = null;
-			let status = res$1.status;
-			let statusText = res$1.statusText;
-			if (res$1.ok) {
-				var _this$headers$get2, _res$headers$get;
-				if (_this.method !== "HEAD") {
-					var _this$headers$get;
-					const body = await res$1.text();
-					if (body === "") {} else if (_this.headers.get("Accept") === "text/csv") data = body;
-					else if (_this.headers.get("Accept") && ((_this$headers$get = _this.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);
-				}
-				const countHeader = (_this$headers$get2 = _this.headers.get("Prefer")) === null || _this$headers$get2 === void 0 ? void 0 : _this$headers$get2.match(/count=(exact|planned|estimated)/);
-				const contentRange = (_res$headers$get = res$1.headers.get("content-range")) === null || _res$headers$get === void 0 ? void 0 : _res$headers$get.split("/");
-				if (countHeader && contentRange && contentRange.length > 1) count = parseInt(contentRange[1]);
-				if (_this.isMaybeSingle && Array.isArray(data)) if (data.length > 1) {
-					error = {
-						code: "PGRST116",
-						details: `Results contain ${data.length} rows, application/vnd.pgrst.object+json requires 1 row`,
-						hint: null,
-						message: "JSON object requested, multiple (or no) rows returned"
-					};
-					data = null;
-					count = null;
-					status = 406;
-					statusText = "Not Acceptable";
-				} else if (data.length === 1) data = data[0];
-				else data = null;
-			} else {
-				const body = await res$1.text();
+		const executeWithRetry = async () => {
+			let attemptCount = 0;
+			while (true) {
+				const requestHeaders = new Headers(_this.headers);
+				if (attemptCount > 0) requestHeaders.set("X-Retry-Count", String(attemptCount));
+				let res$1;
 				try {
-					error = JSON.parse(body);
-					if (Array.isArray(error) && res$1.status === 404) {
-						data = [];
-						error = null;
-						status = 200;
-						statusText = "OK";
+					res$1 = await _fetch(_this.url.toString(), {
+						method: _this.method,
+						headers: requestHeaders,
+						body: JSON.stringify(_this.body),
+						signal: _this.signal
+					});
+				} catch (fetchError) {
+					if ((fetchError === null || fetchError === void 0 ? void 0 : fetchError.name) === "AbortError" || (fetchError === null || fetchError === void 0 ? void 0 : fetchError.code) === "ABORT_ERR") throw fetchError;
+					if (!RETRYABLE_METHODS.includes(_this.method)) throw fetchError;
+					if (_this.retryEnabled && attemptCount < DEFAULT_MAX_RETRIES) {
+						const delay = getRetryDelay(attemptCount);
+						attemptCount++;
+						await sleep(delay, _this.signal);
+						continue;
 					}
-				} catch (_unused) {
-					if (res$1.status === 404 && body === "") {
-						status = 204;
-						statusText = "No Content";
-					} else error = { message: body };
+					throw fetchError;
+				}
+				if (shouldRetry(_this.method, res$1.status, attemptCount, _this.retryEnabled)) {
+					var _res$headers$get, _res$headers;
+					const retryAfterHeader = (_res$headers$get = (_res$headers = res$1.headers) === null || _res$headers === void 0 ? void 0 : _res$headers.get("Retry-After")) !== null && _res$headers$get !== void 0 ? _res$headers$get : null;
+					const delay = retryAfterHeader !== null ? Math.max(0, parseInt(retryAfterHeader, 10) || 0) * 1e3 : getRetryDelay(attemptCount);
+					await res$1.text();
+					attemptCount++;
+					await sleep(delay, _this.signal);
+					continue;
 				}
-				if (error && _this.shouldThrowOnError) throw new PostgrestError(error);
+				return await _this.processResponse(res$1);
 			}
-			return {
-				error,
-				data,
-				count,
-				status,
-				statusText
-			};
-		});
+		};
+		let res = executeWithRetry();
 		if (!this.shouldThrowOnError) res = res.catch((fetchError) => {
 			var _fetchError$name2;
 			let errorDetails = "";
@@ -207,6 +264,67 @@ var PostgrestBuilder = class {
 		return res.then(onfulfilled, onrejected);
 	}
 	/**
+	* Process a fetch response and return the standardized postgrest response.
+	*/
+	async processResponse(res) {
+		var _this2 = this;
+		let error = null;
+		let data = null;
+		let count = null;
+		let status = res.status;
+		let statusText = res.statusText;
+		if (res.ok) {
+			var _this$headers$get2, _res$headers$get2;
+			if (_this2.method !== "HEAD") {
+				var _this$headers$get;
+				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);
+			}
+			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("/");
+			if (countHeader && contentRange && contentRange.length > 1) count = parseInt(contentRange[1]);
+			if (_this2.isMaybeSingle && Array.isArray(data)) if (data.length > 1) {
+				error = {
+					code: "PGRST116",
+					details: `Results contain ${data.length} rows, application/vnd.pgrst.object+json requires 1 row`,
+					hint: null,
+					message: "JSON object requested, multiple (or no) rows returned"
+				};
+				data = null;
+				count = null;
+				status = 406;
+				statusText = "Not Acceptable";
+			} else if (data.length === 1) data = data[0];
+			else data = null;
+		} else {
+			const body = await res.text();
+			try {
+				error = JSON.parse(body);
+				if (Array.isArray(error) && res.status === 404) {
+					data = [];
+					error = null;
+					status = 200;
+					statusText = "OK";
+				}
+			} catch (_unused) {
+				if (res.status === 404 && body === "") {
+					status = 204;
+					statusText = "No Content";
+				} else error = { message: body };
+			}
+			if (error && _this2.shouldThrowOnError) throw new PostgrestError(error);
+		}
+		return {
+			error,
+			data,
+			count,
+			status,
+			statusText
+		};
+	}
+	/**
 	* Override the type of the returned `data`.
 	*
 	* @typeParam NewResult - The new result type to override with
@@ -2889,22 +3007,31 @@ var PostgrestQueryBuilder = class {
 	*
 	* @category Database
 	*
+	* @param url - The URL for the query
+	* @param options - Named parameters
+	* @param options.headers - Custom headers
+	* @param options.schema - Postgres schema to use
+	* @param options.fetch - Custom fetch implementation
+	* @param options.urlLengthLimit - Maximum URL length before warning
+	* @param options.retry - Enable automatic retries for transient errors (default: true)
+	*
 	* @example Creating a Postgrest query builder
 	* ```ts
 	* import { PostgrestQueryBuilder } from '@supabase/postgrest-js'
 	*
 	* const query = new PostgrestQueryBuilder(
 	*   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
-	*   { headers: { apikey: 'public-anon-key' } }
+	*   { headers: { apikey: 'public-anon-key' }, retry: true }
 	* )
 	* ```
 	*/
-	constructor(url, { headers = {}, schema, fetch: fetch$1, urlLengthLimit = 8e3 }) {
+	constructor(url, { headers = {}, schema, fetch: fetch$1, urlLengthLimit = 8e3, retry }) {
 		this.url = url;
 		this.headers = new Headers(headers);
 		this.schema = schema;
 		this.fetch = fetch$1;
 		this.urlLengthLimit = urlLengthLimit;
+		this.retry = retry;
 	}
 	/**
 	* Clone URL and headers to prevent shared state between operations.
@@ -3712,7 +3839,8 @@ var PostgrestQueryBuilder = class {
 			headers,
 			schema: this.schema,
 			fetch: this.fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -3846,7 +3974,8 @@ var PostgrestQueryBuilder = class {
 			schema: this.schema,
 			body: values,
 			fetch: (_this$fetch = this.fetch) !== null && _this$fetch !== void 0 ? _this$fetch : fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -4079,7 +4208,8 @@ var PostgrestQueryBuilder = class {
 			schema: this.schema,
 			body: values,
 			fetch: (_this$fetch2 = this.fetch) !== null && _this$fetch2 !== void 0 ? _this$fetch2 : fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -4233,7 +4363,8 @@ var PostgrestQueryBuilder = class {
 			schema: this.schema,
 			body: values,
 			fetch: (_this$fetch3 = this.fetch) !== null && _this$fetch3 !== void 0 ? _this$fetch3 : fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -4365,7 +4496,8 @@ var PostgrestQueryBuilder = class {
 			headers,
 			schema: this.schema,
 			fetch: (_this$fetch4 = this.fetch) !== null && _this$fetch4 !== void 0 ? _this$fetch4 : fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 };
@@ -4459,6 +4591,10 @@ var PostgrestClient = class PostgrestClient {
 	* @param options.fetch - Custom fetch
 	* @param options.timeout - Optional timeout in milliseconds for all requests. When set, requests will automatically abort after this duration to prevent indefinite hangs.
 	* @param options.urlLengthLimit - Maximum URL length in characters before warnings/errors are triggered. Defaults to 8000.
+	* @param options.retry - Enable or disable automatic retries for transient errors.
+	*   When enabled, idempotent requests (GET, HEAD, OPTIONS) that fail with network
+	*   errors or HTTP 503/520 responses will be automatically retried up to 3 times
+	*   with exponential backoff (1s, 2s, 4s). Defaults to `true`.
 	* @example
 	* ```ts
 	* import { PostgrestClient } from '@supabase/postgrest-js'
@@ -4494,10 +4630,11 @@ var PostgrestClient = class PostgrestClient {
 	*   headers: { apikey: 'public-anon-key' },
 	*   schema: 'public',
 	*   timeout: 30000, // 30 second timeout
+	*   retry: false, // Disable automatic retries
 	* })
 	* ```
 	*/
-	constructor(url, { headers = {}, schema, fetch: fetch$1, timeout, urlLengthLimit = 8e3 } = {}) {
+	constructor(url, { headers = {}, schema, fetch: fetch$1, timeout, urlLengthLimit = 8e3, retry } = {}) {
 		this.url = url;
 		this.headers = new Headers(headers);
 		this.schemaName = schema;
@@ -4525,6 +4662,7 @@ var PostgrestClient = class PostgrestClient {
 			return originalFetch(input, _objectSpread2(_objectSpread2({}, init), {}, { signal: controller.signal })).finally(() => clearTimeout(timeoutId));
 		};
 		else this.fetch = originalFetch;
+		this.retry = retry;
 	}
 	/**
 	* Perform a query on a table or a view.
@@ -4539,7 +4677,8 @@ var PostgrestClient = class PostgrestClient {
 			headers: new Headers(this.headers),
 			schema: this.schemaName,
 			fetch: this.fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -4556,7 +4695,8 @@ var PostgrestClient = class PostgrestClient {
 			headers: this.headers,
 			schema,
 			fetch: this.fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 	/**
@@ -4753,7 +4893,8 @@ var PostgrestClient = class PostgrestClient {
 			schema: this.schemaName,
 			body,
 			fetch: (_this$fetch = this.fetch) !== null && _this$fetch !== void 0 ? _this$fetch : fetch,
-			urlLengthLimit: this.urlLengthLimit
+			urlLengthLimit: this.urlLengthLimit,
+			retry: this.retry
 		});
 	}
 };