Session
Session management module for Nhost authentication
This module exports utilities for managing authentication sessions across different environments and storage backends. It provides:
- Session storage abstractions for different environments
- Session persistence and synchronization
- Automatic token refresh mechanisms
This is an advanced submodule of the Nhost SDK, primarily used internally but it is exposed for advanced use cases.
Classes
Section titled “Classes”CookieStorage
Section titled “CookieStorage”Cookie-based storage implementation. This storage uses web browser cookies to store the session so it’s not available in server-side environments. It is useful though for synchronizing sessions between client and server environments.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CookieStorage(options?: object): CookieStorage;Creates a new CookieStorage instance
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options? | { cookieName?: string; expirationDays?: number; sameSite?: "strict" | "lax" | "none"; secure?: boolean; } | Configuration options |
options.cookieName? | string | Name of the cookie to use (defaults to “nhostSession”) |
options.expirationDays? | number | Number of days until the cookie expires (defaults to 30) |
options.sameSite? | "strict" | "lax" | "none" | SameSite policy for the cookie (defaults to “lax”) |
options.secure? | boolean | Whether to set the Secure flag on the cookie (defaults to true) |
Returns
Section titled “Returns”Methods
Section titled “Methods”get(): Session | null;Gets the session from cookies
Returns
Section titled “Returns”Session | null
The stored session or null if not found
Implementation of
Section titled “Implementation of”remove()
Section titled “remove()”remove(): void;Removes the session cookie
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”set(value: Session): void;Sets the session in a cookie
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | Session | The session to store |
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”LocalStorage
Section titled “LocalStorage”Browser localStorage implementation of StorageInterface. Persists the session across page reloads and browser restarts.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new LocalStorage(options?: object): LocalStorage;Creates a new LocalStorage instance
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options? | { storageKey?: string; } | Configuration options |
options.storageKey? | string | The key to use in localStorage (defaults to “nhostSession”) |
Returns
Section titled “Returns”Methods
Section titled “Methods”get(): Session | null;Gets the session from localStorage
Returns
Section titled “Returns”Session | null
The stored session or null if not found
Implementation of
Section titled “Implementation of”remove()
Section titled “remove()”remove(): void;Removes the session from localStorage
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”set(value: Session): void;Sets the session in localStorage
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | Session | The session to store |
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”MemoryStorage
Section titled “MemoryStorage”In-memory storage implementation for non-browser environments or when persistent storage is not available or desirable.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new MemoryStorage(): MemoryStorage;Returns
Section titled “Returns”Methods
Section titled “Methods”get(): Session | null;Gets the session from memory
Returns
Section titled “Returns”Session | null
The stored session or null if not set
Implementation of
Section titled “Implementation of”remove()
Section titled “remove()”remove(): void;Clears the session from memory
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”set(value: Session): void;Sets the session in memory
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | Session | The session to store |
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”SessionStorage
Section titled “SessionStorage”A wrapper around any SessionStorageInterface implementation that adds the ability to subscribe to session changes.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new SessionStorage(storage: SessionStorageBackend): SessionStorage;Creates a new SessionStorage instance
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
storage | SessionStorageBackend | The underlying storage implementation to use |
Returns
Section titled “Returns”Methods
Section titled “Methods”get(): Session | null;Gets the session from the underlying storage
Returns
Section titled “Returns”Session | null
The stored session or null if not found
onChange()
Section titled “onChange()”onChange(callback: SessionChangeCallback): () => void;Subscribe to session changes
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
callback | SessionChangeCallback | Function that will be called when the session changes |
Returns
Section titled “Returns”An unsubscribe function to remove this subscription
(): void;Returns
Section titled “Returns”void
remove()
Section titled “remove()”remove(): void;Removes the session from the underlying storage and notifies subscribers
Returns
Section titled “Returns”void
set(value: Session): void;Sets the session in the underlying storage and notifies subscribers
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | Session | The session to store |
Returns
Section titled “Returns”void
Interfaces
Section titled “Interfaces”DecodedToken
Section titled “DecodedToken”Decoded JWT token payload with processed timestamps and Hasura claims
Indexable
Section titled “Indexable”[key: string]: unknownAny other JWT claims
Properties
Section titled “Properties”optional exp: number;Token expiration time as Date object
optional https://hasura.io/jwt/claims: Record<string, unknown>;Hasura JWT claims with PostgreSQL arrays converted to JavaScript arrays
optional iat: number;Token issued at time as Date object
optional iss: string;Token issuer
optional sub: string;Token subject (user ID)
Session
Section titled “Session”User authentication session containing tokens and user information
Extends
Section titled “Extends”Properties
Section titled “Properties”accessToken
Section titled “accessToken”accessToken: stringJWT token for authenticating API requests
Example - "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Inherited from
Section titled “Inherited from”accessTokenExpiresIn
Section titled “accessTokenExpiresIn”accessTokenExpiresIn: numberExpiration time of the access token in seconds
Example - 900
Format - int64
Inherited from
Section titled “Inherited from”decodedToken
Section titled “decodedToken”decodedToken: DecodedTokenDecoded JWT token payload with processed timestamps and Hasura claims
refreshToken
Section titled “refreshToken”refreshToken: stringToken used to refresh the access token
Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
Inherited from
Section titled “Inherited from”refreshTokenId
Section titled “refreshTokenId”refreshTokenId: stringIdentifier for the refresh token
Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
Inherited from
Section titled “Inherited from”optional user: User;User profile and account information
Inherited from
Section titled “Inherited from”SessionStorageBackend
Section titled “SessionStorageBackend”Session storage interface for session persistence. This interface can be implemented to provide custom storage solutions.
Methods
Section titled “Methods”get(): Session | null;Get the current session from storage
Returns
Section titled “Returns”Session | null
The stored session or null if not found
remove()
Section titled “remove()”remove(): void;Remove the session from storage
Returns
Section titled “Returns”void
set(value: Session): void;Set the session in storage
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | Session | The session to store |
Returns
Section titled “Returns”void
Type Aliases
Section titled “Type Aliases”SessionChangeCallback()
Section titled “SessionChangeCallback()”type SessionChangeCallback = (session: Session | null) => voidCallback function type for session change subscriptions
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
session | Session | null |
Returns
Section titled “Returns”void
Variables
Section titled “Variables”DEFAULT_SESSION_KEY
Section titled “DEFAULT_SESSION_KEY”const DEFAULT_SESSION_KEY: 'nhostSession' = 'nhostSession'Default storage key used for storing the Nhost session
Functions
Section titled “Functions”detectStorage()
Section titled “detectStorage()”function detectStorage(): SessionStorageBackendDetects the best available storage implementation for the current environment.
The detection process follows this order:
- Try to use localStorage if we’re in a browser environment
- Fall back to in-memory storage if localStorage isn’t available
Returns
Section titled “Returns”The best available storage implementation as a SessionStorageBackend
refreshSession()
Section titled “refreshSession()”function refreshSession( auth: Client, storage: SessionStorage, marginSeconds: number): Promise<Session | null>Refreshes the authentication session if needed
This function checks if the current session needs to be refreshed based on the access token expiration time. If a refresh is needed, it will attempt to refresh the token using the provided auth client.
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
auth | Client | undefined | The authentication client to use for token refresh |
storage | SessionStorage | undefined | The session storage implementation |
marginSeconds | number | 60 | The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh. |
Returns
Section titled “Returns”Promise<Session | null>
A promise that resolves to the current session (refreshed if needed) or null if no session exists