Documentation / zerotal / session / SessionAccessor
Class: SessionAccessor
Defined in: packages/session/src/SessionAccessor.ts:66
Developer-facing session API — the object reachable as ctx.session and via
the Session facade.
A single instance is bound to session in the container. It holds no state of
its own: every method resolves the current request's SessionManager
from RequestContext and forwards to it, so a call is always scoped to
the in-flight request. Use it to read and write per-user session values, pull
one-shot data, and rotate the session ID on privilege changes.
Remarks
Mutations are made in memory during the request and persisted by
SessionMiddleware after the response is produced (via the configured
driver). If no session is active on the current request — e.g. the middleware
has not run — every method degrades gracefully: readers return undefined
/ false / "" and writers become no-ops rather than throwing.
The cookie driver enforces the 4096-byte browser cookie limit at save time, so storing large values can cause SessionCookieOverflowError to be thrown from the middleware (not from these methods) — keep only identifiers in the session and move bulky data to a server-side store (Redis driver).
Example
// Inside a controller / route handler
export async function show(ctx: HttpContext) {
const session = ctx.session;
// Read & write
const views = session.get<number>("views") ?? 0;
session.set("views", views + 1);
if (!session.has("visited")) session.set("visited", true);
}
// On login: rotate the ID to prevent session fixation, then store the user
export async function login(ctx: HttpContext) {
ctx.session.regenerate();
ctx.session.set("user_id", user.id);
// One-shot value read back exactly once on the next request
const target = ctx.session.intended("/dashboard");
return redirect(target);
}
See
SessionManager — the per-request object each method delegates to.
Constructors
Constructor
new SessionAccessor():
SessionAccessor
Returns
SessionAccessor
Flash data
pull()
pull<
T>(key):T|undefined
Defined in: packages/session/src/SessionAccessor.ts:93
Read a value and remove it from the session in one step ("read once").
Handy for consuming one-shot data such as flash messages: the value is
returned and deleted, so a subsequent get returns undefined.
Type Parameters
T
T = unknown
Expected type of the stored value.
Parameters
key
string
The key of the value to retrieve and remove.
Returns
T | undefined
The stored value, or undefined if the key is absent.
Lifecycle
regenerate()
regenerate():
void
Defined in: packages/session/src/SessionAccessor.ts:154
Issue a fresh session ID while preserving the current session data.
Call this on any privilege change (most importantly on login) to prevent session-fixation attacks. The middleware destroys the server-side record of the previous ID after the response, so the old ID cannot be replayed.
Returns
void
Reading
get()
get<
T>(key):T|undefined
Defined in: packages/session/src/SessionAccessor.ts:78
Read a value previously stored under key.
Type Parameters
T
T = unknown
Expected type of the stored value; used only to cast the result — no runtime validation is performed.
Parameters
key
string
The key of the value to retrieve.
Returns
T | undefined
The stored value, or undefined if the key is absent (or no
session is active on the current request).
has()
has(
key):boolean
Defined in: packages/session/src/SessionAccessor.ts:120
Report whether key is present in the session.
Parameters
key
string
The key to check for existence in the session.
Returns
boolean
true if the key exists, otherwise false (also false when no
session is active on the current request).
id()
id():
string
Defined in: packages/session/src/SessionAccessor.ts:166
Return the current session ID.
Returns
string
The session ID, or "" when no session is active on the current
request.
Redirect flow
intended()
intended(
defaultUrl?):string
Defined in: packages/session/src/SessionAccessor.ts:183
Consume the previously captured "intended" URL (see captureIntended).
The stored URL is pulled (read once and removed), so after a redirect the value is gone. Typically used after login to send the user back to the page they originally requested.
Parameters
defaultUrl?
string = "/"
Fallback returned when no intended URL was captured.
Defaults to "/".
Returns
string
The captured URL, or defaultUrl if none is stored.
captureIntended()
captureIntended():
void
Defined in: packages/session/src/SessionAccessor.ts:195
Remember the current request's full URL as the "intended" destination.
Call this before redirecting an unauthenticated user to the login page so that intended can send them back afterwards.
Returns
void
Writing
set()
set(
key,value):void
Defined in: packages/session/src/SessionAccessor.ts:107
Store a value under key, overwriting any existing value.
The write is held in memory and persisted by SessionMiddleware after the response is generated.
Parameters
key
string
The key of the value to set.
value
unknown
The value to store (must be JSON-serializable to persist).
Returns
void
forget()
forget(
key):void
Defined in: packages/session/src/SessionAccessor.ts:131
Remove a single value from the session.
Parameters
key
string
The key of the value to remove from the session.
Returns
void
flush()
flush():
void
Defined in: packages/session/src/SessionAccessor.ts:141
Remove every value from the session, leaving it empty. The session ID is left unchanged — use regenerate to rotate the ID as well.
Returns
void