interface ISession
Since 0.2.0

Per-request session handle.

Obtained from ISessionService.from (or the plugin's getSession helper). Mutations are buffered and written back by the session middleware after the handler returns, so a handler never issues a Set-Cookie itself.

Examples

Example 1

const session = getSession(ctx);
session.set('cartId', cart.id);
const userId = session.get<string>('userId');

Properties

readonly
id: string

The session identifier. Stable for the session's lifetime until ISession.regenerate is called.

readonly
isNew: boolean

Whether this session was created for this request rather than restored from a cookie. true for a first visit, and for a request whose cookie was missing, expired, or failed authentication.

Methods

get<T = unknown>(key: string): T | undefined

Reads a value.

set<T>(
key: string,
value: T
): void

Writes a value and marks the session for commit.

Passing undefined removes the key instead of storing it. undefined is not JSON-serializable, so storing it would make ISession.has report a key that serialization then drops — presence would be true before a commit and false after the next load.

has(key: string): boolean

Reports whether a key is present.

delete(key: string): boolean

Removes a key and marks the session for commit.

clear(): void

Removes every key, keeping the session and its id.

Use ISession.destroy to end the session instead.

regenerate(): void

Issues a new session id while keeping the current data.

Call this on privilege change (most importantly immediately after login) so that a session id an attacker planted before authentication does not carry into the authenticated session — session fixation. On the store strategy the previous entry is deleted, making this a real revocation.

destroy(): void

Ends the session: clears the data, deletes any stored entry, and instructs the client to drop the cookie.

Returns a plain snapshot of the current data.

Usage

import { type ISession } from "common/src/index.ts";