Session Management

Session management for Basil server handlers. Provides key-value storage that persists across requests using cookie-based sessions.

⚠️ Sessions are only available inside Basil server handlers. They are not available in standalone Parsley scripts.

Note: There is no @std/session module to import. Sessions are accessed via the basil.session object which is automatically available in handler code.

Session Data

.get(key, default?)

Retrieve a value from the session. Returns null (or the default) if the key does not exist:

let username = basil.session.get("username")
let theme = basil.session.get("theme", "light")  // "light" if not set

.set(key, value)

Store a value in the session:

basil.session.set("username", "Alice")
basil.session.set("preferences", {theme: "dark", lang: "en"})

Values are serialized for storage — strings, numbers, booleans, arrays, and dictionaries are supported.

.delete(key)

Remove a key from the session:

basil.session.delete("username")

.has(key)

Check if a key exists in the session:

basil.session.has("username")        // true or false

.clear()

Remove all session data and flash messages:

basil.session.clear()

.all()

Return all session data as a dictionary:

let data = basil.session.all()
data.username                        // "Alice"

Flash Messages

Flash messages are one-time values that are automatically removed after being read. They are commonly used to pass status messages across redirects (e.g., "Item saved successfully").

.flash(key, message)

Set a flash message:

basil.session.flash("success", "Profile updated!")
basil.session.flash("error", "Invalid email address")

.getFlash(key)

Retrieve and remove a flash message. Returns null if no message exists for the key:

let msg = basil.session.getFlash("success")
// msg is "Profile updated!" (and the flash is now deleted)

let again = basil.session.getFlash("success")
// again is null (already consumed)

.getAllFlash()

Retrieve and remove all flash messages as a dictionary:

let flashes = basil.session.getAllFlash()
// {success: "Profile updated!", error: "Invalid email"}
// All flash messages are now cleared

.hasFlash()

Check if any flash messages exist:

basil.session.hasFlash()             // true or false

Session Regeneration

.regenerate()

Regenerate the session, preserving existing data. Use this after authentication to prevent session fixation attacks:

// After successful login
basil.session.set("userId", user.id)
basil.session.regenerate()

Methods Summary

Common Patterns

Login / Logout

// Login handler
fn handleLogin(req) {
    let user = authenticate(req.body.email, req.body.password)
    check user != null else api.unauthorized("Invalid credentials")

    basil.session.set("userId", user.id)
    basil.session.set("role", user.role)
    basil.session.regenerate()
    basil.session.flash("success", "Welcome back, " + user.name + "!")

    api.redirect("/dashboard")
}

// Logout handler
fn handleLogout(req) {
    basil.session.clear()
    basil.session.flash("info", "You have been logged out")
    api.redirect("/")
}

Displaying Flash Messages

// In a page template
let flashes = basil.session.getAllFlash()

if (flashes.success) {
    <div class=alert-success>flashes.success</div>
}
if (flashes.error) {
    <div class=alert-error>flashes.error</div>
}

Key Differences from Other Languages

• No explicit save — session data is automatically persisted at the end of the request. Setting a value with .set() marks the session as dirty.
• Flash is built in — no need for a separate flash middleware. Flash messages are a first-class part of the session API.
• Cookie-based — sessions are stored in signed cookies by default. No server-side session store is required.

See Also

• @std/api — auth wrappers and HTTP error helpers
• Security Model — security policies
• Error Handling — check for guard-style preconditions