@supabase/auth-js 2.107.0-beta.1 → 2.107.0-canary.0

package/src/lib/errors.ts

@@ -297,38 +297,6 @@ export function isAuthRetryableFetchError(error: unknown): error is AuthRetryabl
   return isAuthError(error) && error.name === 'AuthRetryableFetchError'
 }
 
-/**
- * Returned when the server rotated a refresh token successfully but the
- * client chose not to persist the rotated tokens because the local session
- * changed mid-flight. Usually means a concurrent `signOut` cleared storage
- * between when the refresh started and when it came back.
- *
- * Set on the `error` field of the refresh result so callers can tell "we
- * got rotated tokens but threw them away" apart from "the refresh failed."
- * The rotated session on the server will be picked up on the next refresh
- * via GoTrue's parent-of-active path.
- *
- * @example
- * ```ts
- * import { isAuthRefreshDiscardedError } from '@supabase/auth-js'
- *
- * if (isAuthRefreshDiscardedError(error)) {
- *   // Concurrent signOut/sign-in raced our refresh. Treat as a no-op.
- * }
- * ```
- */
-export class AuthRefreshDiscardedError extends CustomAuthError {
-  constructor(
-    message = 'Refresh result discarded: session state changed mid-flight (e.g., concurrent signOut)'
-  ) {
-    super(message, 'AuthRefreshDiscardedError', 409, undefined)
-  }
-}
-
-export function isAuthRefreshDiscardedError(error: unknown): error is AuthRefreshDiscardedError {
-  return isAuthError(error) && error.name === 'AuthRefreshDiscardedError'
-}
-
 /**
  * This error is thrown on certain methods when the password used is deemed
  * weak. Inspect the reasons to identify what password strength rules are

package/src/lib/locks.ts

@@ -1,17 +1,6 @@
-/**
- * Lock primitives retained for backwards-compatible imports. The auth client
- * coordinates refreshes itself (deduping in-instance callers onto a shared
- * in-flight promise) and lets the GoTrue server resolve cross-instance races,
- * so it does not invoke any primitive from this module. The functions still
- * work for direct callers that need a navigator.locks-backed or in-process
- * exclusive lock of their own.
- */
-
 import { supportsLocalStorage } from './helpers'
 
 /**
- * @deprecated Debug flag for `navigatorLock` / `processLock`. The auth
- * client ignores both, so this has no client-side effect.
  * @experimental
  */
 export const internals = {
@@ -29,9 +18,18 @@ export const internals = {
 /**
  * An error thrown when a lock cannot be acquired after some amount of time.
  *
- * @deprecated The auth client doesn't acquire locks around auth operations,
- * so this error never originates from `supabase.auth.*` calls. Direct callers
- * of `navigatorLock` / `processLock` still receive it on acquire timeout.
+ * Use the {@link #isAcquireTimeout} property instead of checking with `instanceof`.
+ *
+ * @example
+ * ```ts
+ * import { LockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * class CustomLockError extends LockAcquireTimeoutError {
+ *   constructor() {
+ *     super('Lock timed out')
+ *   }
+ * }
+ * ```
  */
 export abstract class LockAcquireTimeoutError extends Error {
   public readonly isAcquireTimeout = true
@@ -42,15 +40,25 @@ export abstract class LockAcquireTimeoutError extends Error {
 }
 
 /**
- * @deprecated The auth client doesn't call `navigator.locks`, so this error
- * never originates from `supabase.auth.*` calls. Direct callers of
- * `navigatorLock` still receive it on acquire timeout.
+ * Error thrown when the browser Navigator Lock API fails to acquire a lock.
+ *
+ * @example
+ * ```ts
+ * import { NavigatorLockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * throw new NavigatorLockAcquireTimeoutError('Lock timed out')
+ * ```
  */
 export class NavigatorLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 /**
- * @deprecated The auth client doesn't run `processLock`, so this error
- * never originates from `supabase.auth.*` calls. Direct callers of
- * `processLock` still receive it on acquire timeout.
+ * Error thrown when the process-level lock helper cannot acquire a lock.
+ *
+ * @example
+ * ```ts
+ * import { ProcessLockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * throw new ProcessLockAcquireTimeoutError('Lock timed out')
+ * ```
  */
 export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 
@@ -78,10 +86,12 @@ export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
- *
- * @deprecated The auth client coordinates refreshes itself and the server
- * resolves concurrent refresh races, so passing `{ lock: navigatorLock }`
- * to it has no effect. You can safely drop the import from your client setup.
+ * @example
+ * ```ts
+ * await navigatorLock('sync-user', 1000, async () => {
+ *   await refreshSession()
+ * })
+ * ```
  */
 export async function navigatorLock<R>(
   name: string,
@@ -310,11 +320,6 @@ const PROCESS_LOCKS: { [name: string]: Promise<any> } = {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
- *
- * @deprecated The auth client coordinates refreshes itself and the server
- * resolves concurrent refresh races, so passing `{ lock: processLock }`
- * to it has no effect. You can safely drop the import from your client setup.
- *
  * @example
  * ```ts
  * await processLock('migrate', 5000, async () => {

package/src/lib/types.ts

@@ -126,17 +126,12 @@ export type GoTrueClientOptions = {
   /* If debug messages are emitted. Can be used to inspect the behavior of the library. If set to a function, the provided function will be used instead of `console.log()` to perform the logging. */
   debug?: boolean | ((message: string, ...args: any[]) => void)
   /**
-   * Provide your own locking mechanism based on the environment. By default
-   * the client coordinates refreshes itself (single-flight via
-   * `refreshingDeferred` + commit guard) and relies on the GoTrue server to
-   * resolve cross-tab refresh races. Passing a custom lock opts into a
-   * legacy path that wraps every auth operation in your supplied lock — this
-   * path is preserved for backwards compatibility (typically React Native
-   * `processLock` or Node multi-process setups).
-   *
-   * @deprecated Custom locks still work in v2.x for backwards compatibility.
-   * The legacy lock path will be removed in v3 — drop this option from your
-   * constructor options before upgrading.
+   * Provide your own locking mechanism based on the environment. By default,
+   * `navigatorLock` (Web Locks API) is used in browser environments when
+   * `persistSession` is true. Falls back to an in-process lock for non-browser
+   * environments (e.g. React Native).
+   *
+   * @experimental
    */
   lock?: LockFunc
   /**
@@ -150,14 +145,30 @@ export type GoTrueClientOptions = {
    */
   throwOnError?: boolean
   /**
-   * The maximum time in milliseconds to wait for acquiring the custom lock
-   * supplied via the `lock` option. Only consulted when a custom `lock` is
-   * passed — the default lockless path doesn't use this timeout.
+   * The maximum time in milliseconds to wait for acquiring a cross-tab synchronization lock.
+   *
+   * When multiple browser tabs or windows use the auth client simultaneously, they coordinate
+   * via the Web Locks API to prevent race conditions during session refresh and other operations.
+   * This timeout controls how long to wait before attempting lock recovery.
+   *
+   * - **Positive value**: Wait up to this many milliseconds. If the lock is still held, attempt
+   *   automatic recovery by stealing it (the previous holder is evicted, its callback continues
+   *   to completion without exclusive access). This recovers from orphaned locks caused by
+   *   React Strict Mode double-mount, storage API hangs, or aborted operations.
+   * - **Zero (0)**: Fail immediately if the lock is unavailable; throws `LockAcquireTimeoutError`
+   *   (check `error.isAcquireTimeout === true`).
+   * - **Negative value**: Wait indefinitely — can cause permanent deadlocks if the lock is orphaned.
    *
    * @default 5000
    *
-   * @deprecated Only used by the legacy lock path. Will be removed in v3
-   * along with the `lock` option.
+   * @example
+   * ```ts
+   * const client = createClient(url, key, {
+   *   auth: {
+   *     lockAcquireTimeout: 5000, // 5 seconds, then steal orphaned lock
+   *   },
+   * })
+   * ```
    */
   lockAcquireTimeout?: number
 

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.107.0-beta.1'
+export const version = '2.107.0-canary.0'

package/migrations/lockless-coordination.md

@@ -1,89 +0,0 @@
-# Lockless auth coordination
-
-**Since:** v2.X.Y (update at release time)
-**Action required by:** v3.0.0
-
-`@supabase/auth-js` now coordinates session refreshes without a shared mutex by default. The legacy `lock` option is still honored when supplied, but it is deprecated and will be removed in v3.
-
-## What changed
-
-- **Default coordination is lockless.** A client constructed without a `lock` option no longer acquires `navigator.locks` or any in-process lock. In-tab concurrent refreshes are deduplicated via the pre-existing single-flight (`refreshingDeferred`); cross-tab refresh races are resolved by GoTrue's server-side parent-of-active mechanism on the v1 refresh-token path.
-- **Commit guard inside `_callRefreshToken`.** The client snapshots storage before the rotated-token fetch and re-reads after. If a non-null pre-fetch snapshot was cleared between the two reads (typical case: a concurrent `signOut` ran `_removeSession`), the rotated tokens are discarded instead of being written back over the cleared storage. The discarded result resolves with `{ data: null, error: new AuthRefreshDiscardedError() }`.
-- **New `AuthRefreshDiscardedError`** (with `isAuthRefreshDiscardedError` type guard). Surfaces through `refreshSession()` and `getSession()` results when the commit guard fires. Distinct from `AuthRetryableFetchError` (transient network) and `AuthApiError` (server rejection).
-- **New `client.auth.dispose()`.** Tears down the auto-refresh interval, the `visibilitychange` listener, the `BroadcastChannel`, and registered `onAuthStateChange` subscribers. Idempotent. Designed for React Strict Mode and HMR cleanup hooks. In-flight `fetch` calls are not aborted — they run to completion.
-- **`lock` and `lockAcquireTimeout` options.** Accepted and honored when supplied (legacy opt-in path); both are `@deprecated` and will be removed in v3.
-
-## Who is affected
-
-**Most callers: nothing to do.** If you do not pass a `lock` option to `createClient` / `GoTrueClient`, you are already on the lockless default path and will get the bug fixes and new APIs without any code change.
-
-**Callers passing a custom `lock`** (typically React Native `processLock`, Node multi-process setups with shared AsyncStorage, or a custom lock implementation):
-
-- v2.x (this release): your custom `lock` is still invoked exactly as before. The legacy `_acquireLock` machinery is preserved on an opt-in path gated by `settings.lock != null`. No code change required.
-- v3.0.0 (planned): the `lock` and `lockAcquireTimeout` options will be removed entirely. Drop them from your client options before upgrading to v3.
-
-## New APIs worth knowing
-
-### `client.auth.dispose()`
-
-Tears down the client's background work in one call. Safe to call repeatedly.
-
-```ts
-useEffect(() => {
-  const supabase = createClient(URL, KEY)
-  return () => {
-    supabase.auth.dispose()
-  }
-}, [])
-```
-
-### `AuthRefreshDiscardedError`
-
-Returned from `refreshSession()` / `getSession()` when the commit guard discards a successfully-rotated session.
-
-```ts
-import { isAuthRefreshDiscardedError } from '@supabase/auth-js'
-
-const { data, error } = await supabase.auth.refreshSession()
-if (isAuthRefreshDiscardedError(error)) {
-  // A concurrent signOut cleared storage between fetch start and now.
-  // The rotated tokens were discarded; the SIGNED_OUT event already fired.
-  // Treat as a successful no-op — no need to retry.
-}
-```
-
-## Behavior changes worth flagging
-
-- **`_autoRefreshTokenTick` may run concurrently with `signOut` / `setSession` / `getUser`** on the lockless default path. Previously the tick used `_acquireLock(0, ...)` which skipped whenever any auth op held the lock. The lockless equivalent only skips when `refreshingDeferred` is set. The commit guard keeps storage consistent under the new concurrency. The legacy lock opt-in path retains the old skip-on-any-lock behavior.
-- **`onAuthStateChange` async callbacks** that call `getUser`, `setSession`, or read the session from inside the callback are now safe on the default path (previously deadlocked through the lock). One residual hazard remains: calling `refreshSession` (or anything routing through `_callRefreshToken`) from inside a `TOKEN_REFRESHED` handler still deadlocks via `refreshingDeferred`. The `@deprecated` marker on the async overload is kept with its reason updated to point at this specific case.
-- **Subscriber timing on the default path:** subscribers stay awaited; same as before. What changes is that `signOut` no longer waits for an in-flight refresh's HTTP and continuation to finish before its own fetch goes out. Both fetches now run concurrently, and the commit guard keeps storage consistent.
-
-## Migration steps
-
-### If you do not pass a custom `lock` (most users)
-
-No action required for v2. No action required for v3.
-
-### If you pass a custom `lock` (e.g., React Native `processLock`)
-
-No action required for v2 — your lock continues to work.
-
-For v3 readiness:
-
-1. Remove `lock` and `lockAcquireTimeout` from your `createClient` / `GoTrueClient` options before upgrading to v3.
-2. If you depended on cross-process serialization (e.g., Node multi-process with shared AsyncStorage), validate that the lockless coordination (in-tab single-flight + server parent-of-active) is sufficient for your runtime. The default is safe for the cases the lock was originally added to handle (cross-tab refresh races), since the server resolves them.
-
-```ts
-// Before (v2.x, still works):
-const supabase = createClient(URL, KEY, {
-  auth: { lock: processLock, lockAcquireTimeout: 5000 },
-})
-
-// After (v3-ready):
-const supabase = createClient(URL, KEY)
-```
-
-## Reference
-
-- Server-side parent-of-active mechanism: `internal/tokens/service.go:376-385` in the [supabase/auth](https://github.com/supabase/auth) repo (v1 branch, the `*models.RefreshToken` type assertion). When a request arrives with a revoked refresh token whose child is the currently-active token, the server returns the active token instead of rejecting — both tabs receive the same rotated token under DB row locking.
-- `lib/locks.ts` exports (`navigatorLock`, `processLock`, `LockAcquireTimeoutError`, `NavigatorLockAcquireTimeoutError`, `ProcessLockAcquireTimeoutError`, `internals`) remain available for direct imports, marked `@deprecated`. Direct callers who use these exports outside the `GoTrueClient` constructor option are unaffected.