feat(auth): add deprecation notice to onAuthStateChange with async function (#1580)

If you pass in an async function to `onAuthStateChange` and call a
Supabase Client API, it's very likely you'll end up with a deadlock.
Example:

```typescript
supabase.auth.onAuthStateChange(async () => {
  await supabase.auth.getClaims()
})
```

This is because:

- `onAuthStateChange` runs inside an exclusive lock
- If you call another API that tries to acquire the exclusive lock, the
initial call will never finish, thereby never releasing the first lock,
and no other Auth API can be called (across all tabs)

Multiple attempts were made to detect these situations but it's not easy
as async functions don't track execution context in all environments
properly.

This change adds a deprecation notice if the callback is an async
function to discourage folks from using it, and hopefully make it a bit
faster to realize why suddenly everything is frozen.

Author: hf

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>
   ): {