@brightcove/hono-sessions

Hono Sessions

A session manager for Hono. Uses cookies and DynamoDB as the session storage backend

Install

npm install @brightcove/hono-sessions --save

Usage

A middleware is provided that allows configuration of the session options and adds the object sessions to the Hono context.

import { DynamoDBConnector } from '@brightcove/dynamodb-connector';
import { sessions } from '@brightcove/hono-sessions';

// Localstack configuration example
const client = new DynamoDBClient({
    endpoint: 'http://localhost:4566',
    region: 'us-east-1'
});

const app = new Hono();

app.use(sessions({
  dynamo: {
    tableName: 'my-table',
    primaryKey: 'pk',
    sortKey: 'sk',
    expiresAttr: 'expires',
    client: client
  },
  name: 'session_storage',
  cookie: {
    maxAge: 60000,
    secure: true
  }
}));

app.get('/my_route', async (c, next) => {
    const session = c.get('session');
});

Options

Param	Type	Description	Required	Default
dynamo	object	DynamoDB options	yes
dynamo.tableName	string	DynamoDB table name	yes
dynamo.primaryKey	string	DynamoDB primary key	no	pk
dynamo.sortKey	string	DynamoDB sort key	no	sk
dynamo.expiresAttr	string	DynamoDB TTL attribute name. This will be used for setting session expiration and auto expiration behavior	no	expires
dynamo.client	DynamoDBClient	https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/Class/DynamoDBClient/	yes
cookie	object	Accepts all the Hono cookie options	yes
name	string	The session cookie name	no	sid.bgs
secret	string	The secret used for signing cookies	yes, if cookie.secure, otherwise no
logger	Logger	What will be used for logging errors (ie. logger.error()). console is used by default if not specified	no	console
allowOverwrite	boolean	Determines whether a new session can be started when the current one hasn't been ended	no	true

Starting a session

This creates the session item in the database, initialized with a serialized version of any data passed into the function (must be serializable or this will fail) and sets the session cookie on the response.

import { startSession } from '@brightcove/hono-sessions';

app.get('/my_route', async (c, next) => {
    await startSession(c, {
        user_id: 1234,
        name: 'user'
    });
    ...
});

Updating a session

The sessions object exposes both the session and cookie, which can freely be edited.

app.get('/my_route', async (c, next) => {
    const session = c.get('session');
    const cookie = c.get('sessionCookie');

    session.newField = 'new value';
    ...
});

If any of the updated cookie options are invalid, this will fail.

When the request is finalizing, if either has been updated the changes will automatically be synced back to the database.

If any of the cookie options were updated an updated cookie will be set in the response.

Ending a session

This deletes the session from the database and the session cookie in the response.

import { endSession } from '@brightcove/hono-sessions';

app.get('/my_route', async (c, next) => {
    await endSession(c);
    ...
});