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

​
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

​
Constructors

​
Constructor

new CookieStorage(options?: object): CookieStorage;
Creates a new CookieStorage instance
Parameters
ParameterTypeDescription
options?{ cookieName?: string; expirationDays?: number; sameSite?: "strict" | "lax" | "none"; secure?: boolean; }Configuration options
options.cookieName?stringName of the cookie to use (defaults to “nhostSession”)
options.expirationDays?numberNumber of days until the cookie expires (defaults to 30)
options.sameSite?"strict" | "lax" | "none"SameSite policy for the cookie (defaults to “lax”)
options.secure?booleanWhether to set the Secure flag on the cookie (defaults to true)
Returns
CookieStorage

​
Methods

​
get()

get(): null | Session;
Gets the session from cookies
Returns
null | Session The stored session or null if not found
Implementation of
SessionStorageBackend.get

​
remove()

remove(): void;
Removes the session cookie
Returns
void
Implementation of
SessionStorageBackend.remove

​
set()

set(value: Session): void;
Sets the session in a cookie
Parameters
ParameterTypeDescription
valueSessionThe session to store
Returns
void
Implementation of
SessionStorageBackend.set

​
LocalStorage

Browser localStorage implementation of StorageInterface. Persists the session across page reloads and browser restarts.

​
Implements

​
Constructors

​
Constructor

new LocalStorage(options?: object): LocalStorage;
Creates a new LocalStorage instance
Parameters
ParameterTypeDescription
options?{ storageKey?: string; }Configuration options
options.storageKey?stringThe key to use in localStorage (defaults to “nhostSession”)
Returns
LocalStorage

​
Methods

​
get()

get(): null | Session;
Gets the session from localStorage
Returns
null | Session The stored session or null if not found
Implementation of
SessionStorageBackend.get

​
remove()

remove(): void;
Removes the session from localStorage
Returns
void
Implementation of
SessionStorageBackend.remove

​
set()

set(value: Session): void;
Sets the session in localStorage
Parameters
ParameterTypeDescription
valueSessionThe session to store
Returns
void
Implementation of
SessionStorageBackend.set

​
MemoryStorage

In-memory storage implementation for non-browser environments or when persistent storage is not available or desirable.

​
Implements

​
Constructors

​
Constructor

new MemoryStorage(): MemoryStorage;
Returns
MemoryStorage

​
Methods

​
get()

get(): null | Session;
Gets the session from memory
Returns
null | Session The stored session or null if not set
Implementation of
SessionStorageBackend.get

​
remove()

remove(): void;
Clears the session from memory
Returns
void
Implementation of
SessionStorageBackend.remove

​
set()

set(value: Session): void;
Sets the session in memory
Parameters
ParameterTypeDescription
valueSessionThe session to store
Returns
void
Implementation of
SessionStorageBackend.set

​
SessionStorage

A wrapper around any SessionStorageInterface implementation that adds the ability to subscribe to session changes.

​
Constructors

​
Constructor

new SessionStorage(storage: SessionStorageBackend): SessionStorage;
Creates a new SessionStorage instance
Parameters
ParameterTypeDescription
storageSessionStorageBackendThe underlying storage implementation to use
Returns
SessionStorage

​
Methods

​
get()

get(): null | Session;
Gets the session from the underlying storage
Returns
null | Session The stored session or null if not found

​
onChange()

onChange(callback: SessionChangeCallback): () => void;
Subscribe to session changes
Parameters
ParameterTypeDescription
callbackSessionChangeCallbackFunction that will be called when the session changes
Returns
An unsubscribe function to remove this subscription 
(): void;
Returns
void

​
remove()

remove(): void;
Removes the session from the underlying storage and notifies subscribers
Returns
void

​
set()

set(value: Session): void;
Sets the session in the underlying storage and notifies subscribers
Parameters
ParameterTypeDescription
valueSessionThe session to store
Returns
void

​
Interfaces

​
DecodedToken

Decoded JWT token payload with processed timestamps and Hasura claims

​
Indexable

[key: string]: unknown
Any other JWT claims

​
Properties

​
exp?

optional exp: number;
Token expiration time as Date object

​
https://hasura.io/jwt/claims?

optional https://hasura.io/jwt/claims: Record<string, unknown>;
Hasura JWT claims with PostgreSQL arrays converted to JavaScript arrays

​
iat?

optional iat: number;
Token issued at time as Date object

​
iss?

optional iss: string;
Token issuer

​
sub?

optional sub: string;
Token subject (user ID)

​
Session

User authentication session containing tokens and user information

​
Extends

​
Properties

​
accessToken

accessToken: string
JWT token for authenticating API requests Example - "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Inherited from
Session.accessToken

​
accessTokenExpiresIn

accessTokenExpiresIn: number
Expiration time of the access token in seconds Example - 900 Format - int64
Inherited from
Session.accessTokenExpiresIn

​
decodedToken

decodedToken: DecodedToken
Decoded JWT token payload with processed timestamps and Hasura claims

​
refreshToken

refreshToken: string
Token used to refresh the access token Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24" Pattern - \b[0-9a-f]\b-[0-9a-f]-[0-9a-f]-[0-9a-f]-\b[0-9a-f]\b
Inherited from
Session.refreshToken

​
refreshTokenId

refreshTokenId: string
Identifier for the refresh token Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24" Pattern - \b[0-9a-f]\b-[0-9a-f]-[0-9a-f]-[0-9a-f]-\b[0-9a-f]\b
Inherited from
Session.refreshTokenId

​
user?

optional user: User;
User profile and account information
Inherited from
Session.user

​
SessionStorageBackend

Session storage interface for session persistence. This interface can be implemented to provide custom storage solutions.

​
Methods

​
get()

get(): null | Session;
Get the current session from storage
Returns
null | Session The stored session or null if not found

​
remove()

remove(): void;
Remove the session from storage
Returns
void

​
set()

set(value: Session): void;
Set the session in storage
Parameters
ParameterTypeDescription
valueSessionThe session to store
Returns
void

​
Type Aliases

​
SessionChangeCallback()

type SessionChangeCallback = (session: Session | null) => void
Callback function type for session change subscriptions

​
Parameters

ParameterType
sessionSession | null

​
Returns

void

​
Variables

​
DEFAULT_SESSION_KEY

const DEFAULT_SESSION_KEY: 'nhostSession' = 'nhostSession'
Default storage key used for storing the Nhost session

​
Functions

​
detectStorage()

function detectStorage(): SessionStorageBackend
Detects the best available storage implementation for the current environment. The detection process follows this order:
  1. Try to use localStorage if we’re in a browser environment
  2. Fall back to in-memory storage if localStorage isn’t available

​
Returns

SessionStorageBackend The best available storage implementation as a SessionStorageBackend

​
refreshSession()

function refreshSession(
  auth: Client,
  storage: SessionStorage,
  marginSeconds: number
): Promise<null | Session>
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

ParameterTypeDefault valueDescription
authClientundefinedThe authentication client to use for token refresh
storageSessionStorageundefinedThe session storage implementation
marginSecondsnumber60The 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

Promise<null | Session> A promise that resolves to the current session (refreshed if needed) or null if no session exists