Skip to main content

UserSession

The UserSession interface provides type-safe access to the current user and session information from Better Auth.

Interface Definition​

import {
  BetterAuthOptions,
  InferSession,
  InferUser,
  PrettifyDeep,
} from 'better-auth';

export interface UserSession<TOptions extends BetterAuthOptions> {
  session: PrettifyDeep<InferSession<TOptions>>;
  user: PrettifyDeep<InferUser<TOptions>>;
}

Description​

UserSession<TOptions> is a generic interface that combines user and session information from Better Auth into a single object. It leverages Better Auth's type inference system to provide accurate typing based on your specific configuration, including any plugins or custom fields you've defined.

Type Parameters​

  • TOptions - Extends BetterAuthOptions from the Better Auth library. This parameter ensures that the user and session types match your Better Auth configuration exactly.

Properties​

session​

  • Type: PrettifyDeep<InferSession<TOptions>>
  • Description: Contains the current session information, including session ID, user ID, expiration, and any additional session fields defined by your configuration or plugins.

user​

  • Type: PrettifyDeep<InferUser<TOptions>>
  • Description: Contains the current user information, including user ID, email, name, and any additional user fields defined by your configuration or plugins.

Usage​

With Parameter Decorators​

The most common way to access UserSession is through parameter decorators in your controllers:

@Controller('/api')
class UserController {
  @ApplyMiddleware(betterAuthMiddlewareServiceIdentifier)
  @Get('/profile')
  public async getProfile(
    @HonoUserSession() session: UserSession<BetterAuthOptions>,
  ): Promise<UserSession<BetterAuthOptions>> {
    return session;
  }
}

Accessing User Information​

@Controller('/api')
class UserController {
  @ApplyMiddleware(betterAuthMiddlewareServiceIdentifier)
  @Get('/user-info')
  public async getUserInfo(
    @HonoUserSession() session: UserSession<BetterAuthOptions>,
  ): Promise<{ id: string; email: string; name: string }> {
    return {
      email: session.user.email,
      id: session.user.id,
      name: session.user.name,
    };
  }
}

Accessing Session Information​

@Controller('/api')
class SessionController {
  @ApplyMiddleware(betterAuthMiddlewareServiceIdentifier)
  @Get('/session-info')
  public async getSessionInfo(
    @HonoUserSession() session: UserSession<BetterAuthOptions>,
  ): Promise<{ sessionId: string; userId: string; expiresAt: Date }> {
    return {
      expiresAt: session.session.expiresAt,
      sessionId: session.session.id,
      userId: session.session.userId,
    };
  }
}

Handling Unauthenticated Requests​

When no valid session is found, the UserSession will be null:

@Controller('/api')
class OptionalAuthController {
  @ApplyMiddleware(betterAuthMiddlewareServiceIdentifier)
  @Get('/optional-auth')
  public async optionalAuth(
    @HonoUserSession() session: UserSession<BetterAuthOptions> | null,
  ): Promise<{ authenticated: boolean; userId?: string }> {
    if (session === null) {
      return { authenticated: false };
    }

    return {
      authenticated: true,
      userId: session.user.id,
    };
  }
}

Type Safety Benefits​

  • Configuration-Aware: Types reflect your exact Better Auth configuration
  • Plugin Integration: Includes types for any Better Auth plugins you've enabled
  • Custom Fields: Supports custom user and session fields
  • Null Safety: Properly handles unauthenticated states

Framework Support​

UserSession is available across all supported frameworks through their respective parameter decorators:

  • Express: Use @ExpressUserSession()
  • Express v4: Use @ExpressUserSession() (same decorator as Express)
  • Fastify: Use @FastifyUserSession()
  • Hono: Use @HonoUserSession()