@samveys/session

# createSessionMiddleware Function

The `session` middleware. Loads the session named by the cookie (or starts a new one), exposes it as `ctx.session`, and after the handler saves it only when it changed. A request that never writes to the session sets no cookie and writes no row. Two requests of one browser that run at the same time and both change the session race: the later save wins. If a handler throws, nothing is saved. @param database Connection, or a function returning it, for `store: 'database'` (the default).

function createSessionMiddleware(options?: SessionOptions, database?: Database | DatabaseResolver): Middleware;

Exported from packages/session/src/middleware.ts

# databaseSessionStore Function

A store in the `samveys_sessions(id, data, expires_at)` table, created on first use (`create table if not exists`, so it also works with the table made by a migration). `database` is a connection or a function that returns one (the plugin passes `container.make('db')`).

function databaseSessionStore(database: Database | DatabaseResolver, options?: DatabaseSessionStoreOptions): SessionStore;

Exported from packages/session/src/stores.ts

# memorySessionStore Function

A store that keeps sessions in this process's memory. For tests and single-process tools: nothing survives a restart and nothing is shared between processes. Records are kept as JSON text, so a value that cannot be serialized fails here as it would in the database.

function memorySessionStore(): SessionStore;

Exported from packages/session/src/stores.ts

# newSessionId Function

A session id: 32 random bytes, base64url.

function newSessionId(): string;

Exported from packages/session/src/middleware.ts

# session Function

The `@samveys/session` plugin. Registers the named middleware `session` (use it as `use: ['session']` on a route or group, or list it in the global `middleware`) and the lazy `ctx.session`. Defaults: database store, cookie `svs_session` with `Secure; HttpOnly; SameSite=Lax; Path=/`, 2 hour lifetime.

function session(options?: SessionOptions): import("@samveys/core").Plugin<SessionOptions>;

Exported from packages/session/src/plugin.ts

# sessionOf Function

`ctx.session`, or SVS_E090 when the route does not run the `session` middleware.

function sessionOf(ctx: HttpContext): Session;

Exported from packages/session/src/middleware.ts

# DatabaseSessionStoreOptions Interface

Options of {@link databaseSessionStore}.

interface DatabaseSessionStoreOptions {
    /** Default `samveys_sessions`. A plain identifier. */
    readonly table?: string;
}

Exported from packages/session/src/contracts.ts

# Session Interface

The session of one request.

interface Session {
    /** The current id. Changes after `regenerate()` and `invalidate()`. */
    readonly id: string;
    /** True when the request carried no valid session cookie. */
    readonly isNew: boolean;
    get<T = unknown>(key: string): T | undefined;
    get<T = unknown>(key: string, fallback: T): T;
    put(key: string, value: unknown): void;
    /** Removes `key`. */
    forget(key: string): void;
  …

interface Session {
    /** The current id. Changes after `regenerate()` and `invalidate()`. */
    readonly id: string;
    /** True when the request carried no valid session cookie. */
    readonly isNew: boolean;
    get<T = unknown>(key: string): T | undefined;
    get<T = unknown>(key: string, fallback: T): T;
    put(key: string, value: unknown): void;
    /** Removes `key`. */
    forget(key: string): void;
    /** Readable with `get()` during the NEXT request only (e.g. a message after a redirect). */
    flash(key: string, value: unknown): void;
    /** A copy of every value, including the flash data left by the previous request. */
    all(): Record<string, unknown>;
    /** New id, same data; the old id stops working. Call it on every login to stop session fixation. */
    regenerate(): Promise<void>;
    /** Logout: deletes the stored data now and clears the cookie (or starts a fresh session if you write again). */
    invalidate(): Promise<void>;
}

Exported from packages/session/src/contracts.ts

# SessionCookieOptions Interface

No documentation comment.

interface SessionCookieOptions {
    /** Default `svs_session`. */
    readonly name?: string;
    /** Default `true`. Turn off only for plain-HTTP local development. */
    readonly secure?: boolean;
    /** Default `true`: scripts cannot read the cookie. */
    readonly httpOnly?: boolean;
    /** Default `'Lax'`. */
    readonly sameSite?: SameSite;
    /** Default `/`. */
  …

interface SessionCookieOptions {
    /** Default `svs_session`. */
    readonly name?: string;
    /** Default `true`. Turn off only for plain-HTTP local development. */
    readonly secure?: boolean;
    /** Default `true`: scripts cannot read the cookie. */
    readonly httpOnly?: boolean;
    /** Default `'Lax'`. */
    readonly sameSite?: SameSite;
    /** Default `/`. */
    readonly path?: string;
    /** Cookie lifetime, renewed whenever the session is saved. Default 2 hours. */
    readonly maxAgeMs?: number;
}

Exported from packages/session/src/contracts.ts

# SessionOptions Interface

No documentation comment.

interface SessionOptions {
    /** `'database'` (default) uses the `'db'` binding; `'memory'` is for tests and single-process tools. */
    readonly store?: 'database' | 'memory' | SessionStore;
    readonly cookie?: SessionCookieOptions;
    /** How long an idle session stays valid. Default: the cookie's `maxAgeMs`. */
    readonly idleTimeoutMs?: number;
    /** Clock in epoch milliseconds. Tests pass a fake so expiry never needs a sleep. */
    readonly now?: () => number;

Exported from packages/session/src/contracts.ts

# SessionRecord Interface

What a store keeps for one session id.

interface SessionRecord {
    /** JSON-serializable values. */
    readonly data: Readonly<Record<string, unknown>>;
    /** Epoch milliseconds after which the record is dead. */
    readonly expiresAt: number;
}

Exported from packages/session/src/contracts.ts

# SessionStore Interface

Where session data lives. Stores never see the clock: the middleware compares `expiresAt` itself, so a store only has to remember what it was given.

interface SessionStore {
    read(id: string): Promise<SessionRecord | undefined>;
    write(id: string, record: SessionRecord): Promise<void>;
    destroy(id: string): Promise<void>;
}

Exported from packages/session/src/contracts.ts

# DatabaseResolver Type

No documentation comment.

type DatabaseResolver = () => Database;

Exported from packages/session/src/contracts.ts

# SameSite Type

No documentation comment.

type SameSite = 'Lax' | 'Strict' | 'None';

Exported from packages/session/src/contracts.ts