Sessions

Sessions let you persist state across requests: authentication, user preferences, shopping carts, or any other server-side data you want tied to a client. Primate manages session cookies, validates session data, and ensures changes are committed only if your route succeeds.

Configuration

Sessions are configured in config/session.ts. By default Primate uses an in-memory store, but you may also use any store defined in stores or define one directly in config/session.ts.

Session options

cookie.httpOnly

Whether the session cookie should be marked HttpOnly (hidden from client-side JavaScript).

cookie.name

The name of the session cookie.

cookie.path

The path for which the cookie is valid.

cookie.sameSite

The SameSite cookie policy: "Strict", "Lax", or "None".

store

The session store. By default Primate uses a store managed in memory, but you can use any store defined in stores or define one directly in config/session.ts. The store will be used for both validating the data and persisting it to a database of your choice.

The store must include a session_id field of type UUID. Primate uses this to associate each stored record with the session cookie.

Example

First create the store inside stores.

import db from "#db";
import p from "pema";
import store from "primate/store";

export default store({
  name: "session",
  db,
  schema: {
    id: store.key.primary(p.u32),
    session_id: p.uuid,
    user_id: p.number,
    last_active: p.date,
    // additional fields as needed
  },
});

Then refer to it in your configuration file.

import session from "primate/config/session";
import Session from "#store/Session";

export default session({
  store: Session,
});

Session facade

The session facade is the API used in routes to interact with session state. It hides cookie handling and persistence details, exposing a simple interface to create, read, update, and destroy sessions.

Usage in routes

Import the session facade via #session. It is bound to the session store you used in config/session.ts.

import session from "#session";
import route from "primate/route";

export default route({
  get() {
      if (!session.exists) {
        session.create({ user_id: 42 });
      }

      const data = session.get();
      return `User ${data.user_id} last active at ${data.last_active.toISOString()}`;
  },
});

SessionFacade reference

interface SessionFacade<T> {
  readonly id: string | undefined;
  readonly exists: boolean;

  create(initial?: T): void;
  get(): Readonly<T>;
  try(): Readonly<T> | undefined;

  set(next: ((previous: Readonly<T>) => T) | T): void;

  destroy(): void;
}

Validation

Primate validates data passed to create and set using the provided session store.

import db from "#db";
import p from "pema";
import store from "primate/store";

export default store({
  name: "session",
  db,
  schema: {
    id: store.key.primary(p.u32),
    session_id: p.uuid,
    token: p.string.min(10),
  },
});

import session from "#session";
import route from "primate/route";

export default route({
  post() {
      // throws if token is shorter than 10 characters
      session.set({ token: "abc" });
  },
});

This ensures your session store never contains malformed data.