From e05cad97da0b391f12a43f380e4a35613d53064f Mon Sep 17 00:00:00 2001
From: Stojan Dimitrovski <sdimitrovski@gmail.com>
Date: Thu, 2 Oct 2025 12:02:31 +0200
Subject: [PATCH] feat(auth): add deprecation notice to `onAuthStateChange`
 with async function

---
 packages/core/auth-js/src/GoTrueClient.ts | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/packages/core/auth-js/src/GoTrueClient.ts b/packages/core/auth-js/src/GoTrueClient.ts
index 45a4415e4..341d35ce0 100644
--- a/packages/core/auth-js/src/GoTrueClient.ts
+++ b/packages/core/auth-js/src/GoTrueClient.ts
@@ -2078,8 +2078,30 @@ export default class GoTrueClient {
 
   /**
    * Receive a notification every time an auth event happens.
+   * Safe to use without an async function as callback.
+   *
    * @param callback A callback function to be invoked when an auth event happens.
    */
+  onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => void): {
+    data: { subscription: Subscription }
+  }
+
+  /**
+   * Avoid using an async function inside `onAuthStateChange` as you might end
+   * up with a deadlock. The callback function runs inside an exclusive lock,
+   * so calling other Supabase Client APIs that also try to acquire the
+   * exclusive lock, might cause a deadlock. This behavior is observable across
+   * tabs. In the next major library version, this behavior will not be supported.
+   *
+   * Receive a notification every time an auth event happens.
+   *
+   * @param callback A callback function to be invoked when an auth event happens.
+   * @deprecated Due to the possibility of deadlocks with async functions as callbacks, use the version without an async function.
+   */
+  onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => Promise<void>): {
+    data: { subscription: Subscription }
+  }
+
   onAuthStateChange(
     callback: (event: AuthChangeEvent, session: Session | null) => void | Promise<void>
   ): {