@swr-login/react 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SWRLoginConfig, AuthResponse, AuthInjector, User, TokenAdapter, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
+import { SWRLoginConfig, AuthResponse, AuthInjector, User, UserChangeSource, UserChangeEvent, TokenAdapter, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
 import React from 'react';
 
 interface SWRLoginProviderProps {
@@ -196,6 +196,30 @@ interface UseUserReturn<T extends User = User> {
      * Call with `null` to clear, or with a user object to update.
      */
     mutate: (data?: T | null) => Promise<void>;
+    /**
+     * Why the most recent `user` transition happened.
+     *
+     * - `null`         — No user-change has been observed yet in this component
+     *                    (e.g. before the first `fetchUser` resolves on mount).
+     * - `'initial'`    — First time the Provider observed a user value
+     *                    (including `null` for unauthenticated cold start).
+     * - `'login'`      — Triggered by an explicit `login()` / multi-step finalize
+     *                    / `injectAuth()` call.
+     * - `'logout'`     — Triggered by an explicit `logout()` / `injectLogout()`.
+     * - `'revalidate'` — SWR background revalidation produced a different user.
+     * - `'external'`   — Cross-tab sync via BroadcastChannel / storage events.
+     *
+     * Use this to differentiate user-initiated transitions from passive ones,
+     * e.g. to suppress a welcome toast on page refresh.
+     */
+    lastChangeSource: UserChangeSource | null;
+    /**
+     * Full event object for the most recent `user` transition, including
+     * `previousUser` and `timestamp`. `null` before the first transition.
+     *
+     * See `lastChangeSource` for a quick discriminator.
+     */
+    lastChangeEvent: UserChangeEvent<T> | null;
 }
 /**
  * Hook to access current user data via SWR cache.
@@ -213,9 +237,112 @@ interface UseUserReturn<T extends User = User> {
  * if (!isAuthenticated) return <LoginPage />;
  * return <Dashboard user={user} />;
  * ```
+ *
+ * @example Distinguish user-change sources
+ * ```tsx
+ * const { user, lastChangeSource } = useUser();
+ *
+ * useEffect(() => {
+ *   // Only auto-redirect when we detect an *existing* session on mount,
+ *   // not when the user just pressed the "Login" button (the login form
+ *   // is responsible for its own redirect there).
+ *   if (user && lastChangeSource === 'initial') {
+ *     showRedirectOverlay();
+ *   }
+ * }, [user, lastChangeSource]);
+ * ```
  */
 declare function useUser<T extends User = User>(): UseUserReturn<T>;
 
+/**
+ * Subscribe to `user-change` events as a **discrete event stream**.
+ *
+ * Unlike `useUser().user` (which reflects the *current* user value), this
+ * hook returns the most recent transition event and re-renders the caller
+ * only when a new transition occurs. It's intended for `useEffect`-driven
+ * side effects that care about *when* and *why* the user changed rather
+ * than the current user value itself.
+ *
+ * Returns `null` until the first transition is observed by the Provider.
+ *
+ * @typeParam T - Concrete user type (defaults to base `User`)
+ *
+ * @example
+ * ```tsx
+ * const change = useUserChange<MyUser>();
+ *
+ * useEffect(() => {
+ *   if (change?.source === 'login') {
+ *     toast.success(`Welcome back, ${change.user?.name}!`);
+ *   }
+ * }, [change]);
+ * ```
+ *
+ * @example Filter by source
+ * ```tsx
+ * const change = useUserChange();
+ * useEffect(() => {
+ *   if (change?.source === 'external') {
+ *     // Another tab just logged in / out — refresh local UI
+ *     refreshSidebar();
+ *   }
+ * }, [change]);
+ * ```
+ */
+declare function useUserChange<T extends User = User>(): UserChangeEvent<T> | null;
+/**
+ * Register a side-effect callback that fires on every `user-change` event,
+ * **without** triggering a re-render of the calling component.
+ *
+ * Ideal for analytics / logging / imperative side effects that don't need
+ * to participate in React's render cycle.
+ *
+ * The callback receives the full `UserChangeEvent` (including `previousUser`,
+ * `timestamp`, and `source`). The listener is automatically unsubscribed on
+ * unmount.
+ *
+ * Note: the callback reference is stored in a ref and always called with
+ * the latest closure — you do NOT need to memoize it with `useCallback`.
+ *
+ * @example Analytics
+ * ```tsx
+ * useUserChangeEffect((e) => {
+ *   if (e.source === 'login') {
+ *     analytics.track('user_login', { userId: e.user?.id });
+ *   }
+ *   if (e.source === 'logout') {
+ *     analytics.track('user_logout', { userId: e.previousUser?.id });
+ *   }
+ * });
+ * ```
+ *
+ * @example Filter sources
+ * ```tsx
+ * useUserChangeEffect((e) => {
+ *   // Only react to passive revalidations that flipped the user to null
+ *   // (e.g. server returned 401 → session expired silently).
+ *   if (e.source === 'revalidate' && e.user === null && e.previousUser) {
+ *     showReLoginPrompt();
+ *   }
+ * });
+ * ```
+ */
+declare function useUserChangeEffect<T extends User = User>(listener: (event: UserChangeEvent<T>) => void): void;
+/**
+ * Convenience hook: fires the callback only when the change source matches
+ * the given filter. Thin wrapper around {@link useUserChangeEffect}.
+ *
+ * @example
+ * ```tsx
+ * // Only run on explicit login (not on cold-start initial load)
+ * useUserChangeOn('login', (e) => router.push('/dashboard'));
+ *
+ * // Subscribe to multiple sources at once
+ * useUserChangeOn(['login', 'external'], (e) => refreshSidebar());
+ * ```
+ */
+declare function useUserChangeOn<T extends User = User>(source: UserChangeSource | UserChangeSource[], listener: (event: UserChangeEvent<T>) => void): void;
+
 interface UseLogoutOptions {
     /** Specific plugin to call logout on */
     pluginName?: string;
@@ -410,6 +537,26 @@ interface AuthGuardProps {
  */
 declare function AuthGuard({ children, permissions, roles, requireAll, fallback, loadingComponent, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Mutable hint object shared between the Provider and `useUser()` to describe
+ * *why* the next user-change event is expected to happen.
+ *
+ * The Provider writes into this object as it observes `login` / `logout` /
+ * `external` events; `useUser()` reads and clears it when the SWR cache value
+ * actually transitions. Unset/expired hint → the change is a passive
+ * `revalidate` or the very first `initial` load.
+ *
+ * Using a mutable ref-like object (instead of React state) avoids re-renders
+ * and is safe because it is written synchronously from event callbacks and
+ * read synchronously during `useUser()`'s `useEffect`.
+ *
+ * @internal
+ */
+interface UserChangeHint {
+    source: UserChangeSource | null;
+    /** `Date.now()` when the hint was written. Stale hints (>1s) are ignored. */
+    timestamp: number;
+}
 /** Internal context value passed through SWRLoginProvider */
 interface AuthContextValue {
     pluginManager: PluginManager;
@@ -418,6 +565,8 @@ interface AuthContextValue {
     stateMachine: AuthStateMachine;
     broadcastSync: BroadcastSync | null;
     config: SWRLoginConfig;
+    /** @internal shared hint for the next user-change source */
+    userChangeHint: UserChangeHint;
 }
 /**
  * Internal hook to access auth context.
@@ -426,4 +575,4 @@ interface AuthContextValue {
  */
 declare function useAuthContext(): AuthContextValue;
 
-export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseAdapterReturn, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UseMultiStepLoginReturn, type UsePermissionReturn, type UseUserReturn, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser };
+export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseAdapterReturn, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UseMultiStepLoginReturn, type UsePermissionReturn, type UseUserReturn, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser, useUserChange, useUserChangeEffect, useUserChangeOn };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SWRLoginConfig, AuthResponse, AuthInjector, User, TokenAdapter, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
+import { SWRLoginConfig, AuthResponse, AuthInjector, User, UserChangeSource, UserChangeEvent, TokenAdapter, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
 import React from 'react';
 
 interface SWRLoginProviderProps {
@@ -196,6 +196,30 @@ interface UseUserReturn<T extends User = User> {
      * Call with `null` to clear, or with a user object to update.
      */
     mutate: (data?: T | null) => Promise<void>;
+    /**
+     * Why the most recent `user` transition happened.
+     *
+     * - `null`         — No user-change has been observed yet in this component
+     *                    (e.g. before the first `fetchUser` resolves on mount).
+     * - `'initial'`    — First time the Provider observed a user value
+     *                    (including `null` for unauthenticated cold start).
+     * - `'login'`      — Triggered by an explicit `login()` / multi-step finalize
+     *                    / `injectAuth()` call.
+     * - `'logout'`     — Triggered by an explicit `logout()` / `injectLogout()`.
+     * - `'revalidate'` — SWR background revalidation produced a different user.
+     * - `'external'`   — Cross-tab sync via BroadcastChannel / storage events.
+     *
+     * Use this to differentiate user-initiated transitions from passive ones,
+     * e.g. to suppress a welcome toast on page refresh.
+     */
+    lastChangeSource: UserChangeSource | null;
+    /**
+     * Full event object for the most recent `user` transition, including
+     * `previousUser` and `timestamp`. `null` before the first transition.
+     *
+     * See `lastChangeSource` for a quick discriminator.
+     */
+    lastChangeEvent: UserChangeEvent<T> | null;
 }
 /**
  * Hook to access current user data via SWR cache.
@@ -213,9 +237,112 @@ interface UseUserReturn<T extends User = User> {
  * if (!isAuthenticated) return <LoginPage />;
  * return <Dashboard user={user} />;
  * ```
+ *
+ * @example Distinguish user-change sources
+ * ```tsx
+ * const { user, lastChangeSource } = useUser();
+ *
+ * useEffect(() => {
+ *   // Only auto-redirect when we detect an *existing* session on mount,
+ *   // not when the user just pressed the "Login" button (the login form
+ *   // is responsible for its own redirect there).
+ *   if (user && lastChangeSource === 'initial') {
+ *     showRedirectOverlay();
+ *   }
+ * }, [user, lastChangeSource]);
+ * ```
  */
 declare function useUser<T extends User = User>(): UseUserReturn<T>;
 
+/**
+ * Subscribe to `user-change` events as a **discrete event stream**.
+ *
+ * Unlike `useUser().user` (which reflects the *current* user value), this
+ * hook returns the most recent transition event and re-renders the caller
+ * only when a new transition occurs. It's intended for `useEffect`-driven
+ * side effects that care about *when* and *why* the user changed rather
+ * than the current user value itself.
+ *
+ * Returns `null` until the first transition is observed by the Provider.
+ *
+ * @typeParam T - Concrete user type (defaults to base `User`)
+ *
+ * @example
+ * ```tsx
+ * const change = useUserChange<MyUser>();
+ *
+ * useEffect(() => {
+ *   if (change?.source === 'login') {
+ *     toast.success(`Welcome back, ${change.user?.name}!`);
+ *   }
+ * }, [change]);
+ * ```
+ *
+ * @example Filter by source
+ * ```tsx
+ * const change = useUserChange();
+ * useEffect(() => {
+ *   if (change?.source === 'external') {
+ *     // Another tab just logged in / out — refresh local UI
+ *     refreshSidebar();
+ *   }
+ * }, [change]);
+ * ```
+ */
+declare function useUserChange<T extends User = User>(): UserChangeEvent<T> | null;
+/**
+ * Register a side-effect callback that fires on every `user-change` event,
+ * **without** triggering a re-render of the calling component.
+ *
+ * Ideal for analytics / logging / imperative side effects that don't need
+ * to participate in React's render cycle.
+ *
+ * The callback receives the full `UserChangeEvent` (including `previousUser`,
+ * `timestamp`, and `source`). The listener is automatically unsubscribed on
+ * unmount.
+ *
+ * Note: the callback reference is stored in a ref and always called with
+ * the latest closure — you do NOT need to memoize it with `useCallback`.
+ *
+ * @example Analytics
+ * ```tsx
+ * useUserChangeEffect((e) => {
+ *   if (e.source === 'login') {
+ *     analytics.track('user_login', { userId: e.user?.id });
+ *   }
+ *   if (e.source === 'logout') {
+ *     analytics.track('user_logout', { userId: e.previousUser?.id });
+ *   }
+ * });
+ * ```
+ *
+ * @example Filter sources
+ * ```tsx
+ * useUserChangeEffect((e) => {
+ *   // Only react to passive revalidations that flipped the user to null
+ *   // (e.g. server returned 401 → session expired silently).
+ *   if (e.source === 'revalidate' && e.user === null && e.previousUser) {
+ *     showReLoginPrompt();
+ *   }
+ * });
+ * ```
+ */
+declare function useUserChangeEffect<T extends User = User>(listener: (event: UserChangeEvent<T>) => void): void;
+/**
+ * Convenience hook: fires the callback only when the change source matches
+ * the given filter. Thin wrapper around {@link useUserChangeEffect}.
+ *
+ * @example
+ * ```tsx
+ * // Only run on explicit login (not on cold-start initial load)
+ * useUserChangeOn('login', (e) => router.push('/dashboard'));
+ *
+ * // Subscribe to multiple sources at once
+ * useUserChangeOn(['login', 'external'], (e) => refreshSidebar());
+ * ```
+ */
+declare function useUserChangeOn<T extends User = User>(source: UserChangeSource | UserChangeSource[], listener: (event: UserChangeEvent<T>) => void): void;
+
 interface UseLogoutOptions {
     /** Specific plugin to call logout on */
     pluginName?: string;
@@ -410,6 +537,26 @@ interface AuthGuardProps {
  */
 declare function AuthGuard({ children, permissions, roles, requireAll, fallback, loadingComponent, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Mutable hint object shared between the Provider and `useUser()` to describe
+ * *why* the next user-change event is expected to happen.
+ *
+ * The Provider writes into this object as it observes `login` / `logout` /
+ * `external` events; `useUser()` reads and clears it when the SWR cache value
+ * actually transitions. Unset/expired hint → the change is a passive
+ * `revalidate` or the very first `initial` load.
+ *
+ * Using a mutable ref-like object (instead of React state) avoids re-renders
+ * and is safe because it is written synchronously from event callbacks and
+ * read synchronously during `useUser()`'s `useEffect`.
+ *
+ * @internal
+ */
+interface UserChangeHint {
+    source: UserChangeSource | null;
+    /** `Date.now()` when the hint was written. Stale hints (>1s) are ignored. */
+    timestamp: number;
+}
 /** Internal context value passed through SWRLoginProvider */
 interface AuthContextValue {
     pluginManager: PluginManager;
@@ -418,6 +565,8 @@ interface AuthContextValue {
     stateMachine: AuthStateMachine;
     broadcastSync: BroadcastSync | null;
     config: SWRLoginConfig;
+    /** @internal shared hint for the next user-change source */
+    userChangeHint: UserChangeHint;
 }
 /**
  * Internal hook to access auth context.
@@ -426,4 +575,4 @@ interface AuthContextValue {
  */
 declare function useAuthContext(): AuthContextValue;
 
-export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseAdapterReturn, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UseMultiStepLoginReturn, type UsePermissionReturn, type UseUserReturn, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser };
+export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseAdapterReturn, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UseMultiStepLoginReturn, type UsePermissionReturn, type UseUserReturn, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser, useUserChange, useUserChangeEffect, useUserChangeOn };

package/dist/index.js

@@ -24,6 +24,13 @@ function SWRLoginProvider({ config, children }) {
     pluginManager.register(...config.plugins);
     const enableSync = config.security?.enableBroadcastSync !== false;
     const broadcastSync = enableSync && typeof window !== "undefined" ? new BroadcastSync() : null;
+    const userChangeHint = { source: null, timestamp: 0 };
+    const markHint = (source) => {
+      userChangeHint.source = source;
+      userChangeHint.timestamp = Date.now();
+    };
+    emitter.on("login", () => markHint("login"));
+    emitter.on("logout", () => markHint("logout"));
     if (config.onLogin) {
       emitter.on("login", ({ user }) => config.onLogin?.(user));
     }
@@ -39,7 +46,8 @@ function SWRLoginProvider({ config, children }) {
       emitter,
       stateMachine,
       broadcastSync,
-      config
+      config,
+      userChangeHint
     };
   }, [config]);
   useEffect(() => {
@@ -67,15 +75,22 @@ function SWRLoginProvider({ config, children }) {
       emitter.emit("token-expired", void 0);
     }
     if (broadcastSync) {
+      const { userChangeHint } = contextValue;
+      const markExternal = () => {
+        userChangeHint.source = "external";
+        userChangeHint.timestamp = Date.now();
+      };
       const unsubscribe = broadcastSync.onMessage((message) => {
         switch (message.type) {
           case "LOGOUT":
             tokenManager.clearTokens();
             stateMachine.transition("unauthenticated");
             emitter.emit("logout", void 0);
+            markExternal();
             break;
           case "LOGIN":
           case "TOKEN_REFRESH":
+            markExternal();
             if (cfg.cacheAdapter) {
               cfg.cacheAdapter.revalidate();
             }
@@ -116,8 +131,9 @@ function SWRLoginProvider({ config, children }) {
   return /* @__PURE__ */ jsx(AuthContext.Provider, { value: contextValue, children });
 }
 var AUTH_KEY = "__swr_login_user__";
+var USER_CHANGE_HINT_TTL_MS = 1e3;
 function useUser() {
-  const { tokenManager, stateMachine, config } = useAuthContext();
+  const { tokenManager, stateMachine, config, emitter, userChangeHint } = useAuthContext();
   const lastErrorRef = useRef(void 0);
   const retryCountRef = useRef(0);
   const [, setTick] = useState(0);
@@ -126,6 +142,8 @@ function useUser() {
     lastErrorRef.current = void 0;
     forceUpdate();
   }, [forceUpdate]);
+  const previousUserRef = useRef(void 0);
+  const [lastChangeEvent, setLastChangeEvent] = useState(null);
   const fetcher = async () => {
     const token = tokenManager.getAccessToken();
     if (!token) return null;
@@ -150,10 +168,41 @@ function useUser() {
     isLoading,
     mutate: swrMutate
   } = useSWR(AUTH_KEY, fetcher, {
-    revalidateOnFocus: true,
-    revalidateOnReconnect: true,
-    shouldRetryOnError: false
+    revalidateOnFocus: config.swrOptions?.revalidateOnFocus ?? true,
+    revalidateOnReconnect: config.swrOptions?.revalidateOnReconnect ?? true,
+    shouldRetryOnError: false,
+    ...config.swrOptions?.dedupingInterval !== void 0 && {
+      dedupingInterval: config.swrOptions.dedupingInterval
+    },
+    ...config.swrOptions?.focusThrottleInterval !== void 0 && {
+      focusThrottleInterval: config.swrOptions.focusThrottleInterval
+    },
+    ...config.swrOptions?.refreshInterval !== void 0 && {
+      refreshInterval: config.swrOptions.refreshInterval
+    }
   });
+  useEffect(() => {
+    if (data === void 0) return;
+    const prev = previousUserRef.current;
+    if (Object.is(prev, data)) return;
+    let source;
+    if (prev === void 0) {
+      source = "initial";
+    } else {
+      const now = Date.now();
+      const hintFresh = userChangeHint.source !== null && now - userChangeHint.timestamp <= USER_CHANGE_HINT_TTL_MS;
+      source = hintFresh ? userChangeHint.source : "revalidate";
+    }
+    const event = {
+      source,
+      user: data,
+      previousUser: prev,
+      timestamp: Date.now()
+    };
+    previousUserRef.current = data;
+    setLastChangeEvent(event);
+    emitter.emit("user-change", event);
+  }, [data, emitter, userChangeHint]);
   useEffect(() => {
     if (error) {
       lastErrorRef.current = error;
@@ -190,7 +239,9 @@ function useUser() {
     error,
     lastError: lastErrorRef.current,
     clearError,
-    mutate: mutate2
+    mutate: mutate2,
+    lastChangeSource: lastChangeEvent?.source ?? null,
+    lastChangeEvent
   };
 }
 
@@ -403,6 +454,40 @@ function useAuthInjector() {
   }, [tokenManager, emitter, stateMachine, config]);
   return { injectAuth, injectLogout };
 }
+function useUserChange() {
+  const { emitter } = useAuthContext();
+  const [event, setEvent] = useState(null);
+  useEffect(() => {
+    const unsubscribe = emitter.on("user-change", (payload) => {
+      setEvent(payload);
+    });
+    return unsubscribe;
+  }, [emitter]);
+  return event;
+}
+function useUserChangeEffect(listener) {
+  const { emitter } = useAuthContext();
+  const listenerRef = useRef(listener);
+  listenerRef.current = listener;
+  useEffect(() => {
+    const unsubscribe = emitter.on("user-change", (payload) => {
+      try {
+        listenerRef.current(payload);
+      } catch (err) {
+        console.error("[swr-login] Error in useUserChangeEffect listener:", err);
+      }
+    });
+    return unsubscribe;
+  }, [emitter]);
+}
+function useUserChangeOn(source, listener) {
+  const sources = Array.isArray(source) ? source : [source];
+  useUserChangeEffect((event) => {
+    if (sources.includes(event.source)) {
+      listener(event);
+    }
+  });
+}
 function useLogout() {
   const { pluginManager, stateMachine, broadcastSync } = useAuthContext();
   const [isLoading, setIsLoading] = useState(false);
@@ -537,6 +622,6 @@ function AuthGuard({
   return /* @__PURE__ */ jsx(Fragment, { children });
 }
 
-export { AUTH_KEY, AuthGuard, SWRLoginProvider, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser };
+export { AUTH_KEY, AuthGuard, SWRLoginProvider, useAdapter, useAuthContext, useAuthInjector, useLogin, useLogout, useMultiStepLogin, usePermission, useSession, useUser, useUserChange, useUserChangeEffect, useUserChangeOn };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map