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

package/src/lib/errors.ts

@@ -297,6 +297,38 @@ 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,6 +1,17 @@
+/**
+ * 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 = {
@@ -18,18 +29,9 @@ export const internals = {
 /**
  * An error thrown when a lock cannot be acquired after some amount of time.
  *
- * 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')
- *   }
- * }
- * ```
+ * @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.
  */
 export abstract class LockAcquireTimeoutError extends Error {
   public readonly isAcquireTimeout = true
@@ -40,25 +42,15 @@ export abstract class LockAcquireTimeoutError extends Error {
 }
 
 /**
- * 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')
- * ```
+ * @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.
  */
 export class NavigatorLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 /**
- * 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')
- * ```
+ * @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.
  */
 export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 
@@ -86,12 +78,10 @@ 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.
- * @example
- * ```ts
- * await navigatorLock('sync-user', 1000, async () => {
- *   await refreshSession()
- * })
- * ```
+ *
+ * @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.
  */
 export async function navigatorLock<R>(
   name: string,
@@ -320,6 +310,11 @@ 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,12 +126,17 @@ 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,
-   * `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
+   * 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.
    */
   lock?: LockFunc
   /**
@@ -145,30 +150,14 @@ export type GoTrueClientOptions = {
    */
   throwOnError?: boolean
   /**
-   * 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.
+   * 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.
    *
    * @default 5000
    *
-   * @example
-   * ```ts
-   * const client = createClient(url, key, {
-   *   auth: {
-   *     lockAcquireTimeout: 5000, // 5 seconds, then steal orphaned lock
-   *   },
-   * })
-   * ```
+   * @deprecated Only used by the legacy lock path. Will be removed in v3
+   * along with the `lock` option.
    */
   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.106.2-canary.1'
+export const version = '2.107.0-beta.0'