docs: improve docs around session config (#758)

docs/content/2.configuration/2.nuxt-config.md

@@ -68,7 +68,7 @@ interface ModuleOptions {
    * Configuration of the application-side session. You can configure the following attributes:
    * - enableRefreshPeriodically: Whether to refresh the session every `X` milliseconds. Set this to `false` to turn it off. The session will only be refreshed if a session already exists. Setting this to `true` will refresh the session every second. Setting this to `false` will turn off session refresh. Setting this to a number `X` will refresh the session every `X` milliseconds.
    * - enableRefreshOnWindowFocus: Whether to refresh the session every time the browser window is refocused.
-   * 
+   *
    * @example { enableRefreshPeriodically: 5000 }
    * @example { enableRefreshOnWindowFocus: false }
    * @default { enableRefreshPeriodically: false, enableRefreshOnWindowFocus: true }
@@ -231,7 +231,7 @@ type ProviderLocal = {
      */
     maxAgeInSeconds?: number,
     /**
-     * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. 
+     * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com.
      *
      * See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7
      *
@@ -337,8 +337,8 @@ type ProviderRefresh = {
     refresh?: { path?: string, method?: RouterMethod },
   },
     /**
-   *  When refreshOnlyToken is set, only the token will be refreshed 
-   * 
+   *  When refreshOnlyToken is set, only the token will be refreshed
+   *
    * @default true
    */
   refreshOnlyToken?: boolean;
@@ -400,7 +400,7 @@ type ProviderRefresh = {
      */
     maxAgeInSeconds?: number,
     /**
-     * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. 
+     * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com.
      *
      * See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7
      *
@@ -529,6 +529,14 @@ type SessionConfig = {
    * @default true
    */
   enableRefreshOnWindowFocus: boolean
+  /**
+   * A custom refresh handler to use. This can be used to implement custom session refresh logic.
+   * If not set, the default refresh handler will be used.
+   *
+   * @example ./src/runtime/utils/refreshHandler.ts
+   * @default undefined
+   */
+  refreshHandler?: RefreshHandler;
 }
 ```
 ```ts [GlobalMiddlewareOptions]

docs/content/2.configuration/5.session-config.md

@@ -0,0 +1,73 @@
+# Session Config
+
+Use this section to configure the application-side session. The following type defines the options you can use inside your auths `session`-key:
+
+```ts
+/**
+ * Configuration for the application-side session.
+ */
+type SessionConfig = {
+  /**
+   * Whether to refresh the session every `X` milliseconds. Set this to `false` to turn it off. The session will only be refreshed if a session already exists.
+   *
+   * Setting this to `true` will refresh the session every second.
+   * Setting this to `false` will turn off session refresh.
+   * Setting this to a number `X` will refresh the session every `X` milliseconds.
+   *
+   * @example 1000
+   * @default false
+   *
+   */
+  enableRefreshPeriodically: number | boolean
+  /**
+   * Whether to refresh the session every time the browser window is refocused.
+   *
+   * @example false
+   * @default true
+   */
+  enableRefreshOnWindowFocus: boolean
+  /**
+   * A custom refresh handler to use. This can be used to implement custom session refresh logic.
+   * If not set, the default refresh handler will be used.
+   *
+   * @example ./src/runtime/utils/refreshHandler.ts
+   * @default undefined
+   */
+  refreshHandler?: RefreshHandler;
+}
+```
+
+## Application side session
+
+Per default nuxt-auth will use the set values for `enableRefreshPeriodically` & `enableRefreshOnWindowFocus` to refresh your application-side session. If you don't provide a configuration nuxt-auth won't trigger a job that refreshes the session periodically but it will always refresh the session if the window is refocussed.
+
+If you set `enableRefreshPeriodically` simply to true a job will be run every second (1000ms) that will fetch your specified `getSession` endpoint. You can customize the interval if you provide a number instead of a boolean value.
+
+To disable the session refresh when the window is refocussed simply set `enableRefreshOnWindowFocus` to `false`.
+
+## Using a custom RefreshHandler
+
+To customize the session refreshing you can provide a refresh handler. A custom `RefreshHandler` requires an `init`- and a `destroy`-function.
+
+`init` will be called when the nuxt application is mounted. Here you may add event listeners and initialize custom refresh behaviour. The method will receive a `RefreshHandlerConfig`. The type consists of `enableRefreshPeriodically` & `enableRefreshOnWindowFocus`.
+
+`destroy` will be called when your app is unmounted. Here you may run your clean up routine e.g. to remove your event listeners.
+
+```ts
+export type RefreshHandler = {
+  /**
+   * Initializes the refresh handler with the given configuration.
+   * init will be called inside app:mouted lifecycle hook.
+   *
+   * @param config The configuration to use for the refresh handler.
+   */
+  init: (config: RefreshHandlerConfig) => void;
+
+  /**
+   * Handles cleanup of the refresh handler. This method will be called when the app is destroyed.
+   */
+  destroy: () => void;
+};
+```
+
+To get an idea the `defaultRefreshHandler` could be useful.