@xof/lynx-session

Fast, lightweight, and lynx-compatible session middleware for Lynx.

• 🚀 High performance
• 🍪 Cookie-based session IDs
• 💾 Pluggable session stores
• 🔒 Secure cookie support
• ⚡ lynx-compatible API

Installation

npm install @xof/lynx-session

or

yarn add @xof/lynx-session

or

pnpm add @xof/lynx-session

Usage

const Lynx = require("@xof/lynx");
const session = require("@xof/lynx-session");

const app = new Lynx();

app.use(session({
    secret: "your-secret-key"
}));

app.get("/", (req, res) => {
    req.session.views = (req.session.views || 0) + 1;

    res.json({
        views: req.session.views
    });
});

app.listen(3000);

API

const session = require("@xof/lynx-session");

session(options)

Creates a session middleware.

app.use(session(options));

Session data is stored on the server. Only the session ID is stored inside the cookie.

Options

secret

Required

Secret used to sign session cookies.

app.use(session({
    secret: "my-super-secret"
}));

cookie

Configure session cookies.

Default:

{
    path: "/",
    httpOnly: true,
    secure: false,
    maxAge: null
}

Example:

app.use(session({
    secret: "secret",
    cookie: {
        maxAge: 86400000
    }
}));

cookie.maxAge

Cookie lifetime in milliseconds.

cookie: {
    maxAge: 1000 * 60 * 60
}

cookie.httpOnly

Prevent JavaScript from accessing cookies.

cookie: {
    httpOnly: true
}

cookie.secure

Only send cookies over HTTPS.

cookie: {
    secure: true
}

You can also use:

cookie: {
    secure: "auto"
}

cookie.sameSite

Controls cross-site cookie behavior.

Values:

• false
• true
• "lax"
• "strict"
• "none"

Example:

cookie: {
    sameSite: "lax"
}

cookie.domain

Set cookie domain.

cookie: {
    domain: ".example.com"
}

cookie.path

Cookie path.

cookie: {
    path: "/"
}

cookie.priority

Cookie priority.

Values:

• low
• medium
• high

cookie: {
    priority: "high"
}

cookie.partitioned

Enable Partitioned Cookies (CHIPS).

cookie: {
    partitioned: true
}

name

Session cookie name.

Default:

lynx.sid

Example:

session({
    name: "my.sid"
});

genid

Generate custom session IDs.

const crypto = require("node:crypto");

session({
    genid(req) {
        return crypto.randomUUID();
    },
    secret: "secret"
});

store

Custom session store.

session({
    secret: "secret",
    store: new MyStore()
});

proxy

Trust reverse proxies.

session({
    proxy: true
});

rolling

Always refresh cookie expiration.

session({
    rolling: true
});

resave

Force saving sessions.

session({
    resave: false
});

saveUninitialized

Save empty sessions.

session({
    saveUninitialized: false
});

unset

Behavior when deleting req.session.

Values:

• keep
• destroy

session({
    unset: "destroy"
});

req.session

Store data per visitor.

app.get("/", (req, res) => {
    req.session.user = {
        id: 1,
        username: "kyys"
    };

    res.json(req.session.user);
});

Session Methods

regenerate()

Generate a new session ID.

req.session.regenerate(err => {});

destroy()

Destroy current session.

req.session.destroy(err => {});

reload()

Reload session from store.

req.session.reload(err => {});

save()

Manually save session.

req.session.save(err => {});

touch()

Refresh expiration.

req.session.touch();

req.sessionID

Get current session ID.

console.log(req.sessionID);

req.session.cookie

Access current cookie.

console.log(req.session.cookie);

Session Store API

Every custom store should implement:

Required:

• get(sid, callback)
• set(sid, session, callback)
• destroy(sid, callback)

Recommended:

• touch(sid, session, callback)

Optional:

• all(callback)
• clear(callback)
• length(callback)

Example:

class MyStore {

    get(sid, callback) {}

    set(sid, session, callback) {}

    destroy(sid, callback) {}

}

Production

Do not use the default MemoryStore in production.

Instead, use a persistent store such as:

• Redis
• MongoDB
• PostgreSQL
• SQLite
• MySQL

License

MIT

Links

• GitHub: https://github.com/Xyraakyzzz/lynx-session
• npm: https://www.npmjs.com/package/@xof/lynx-session