# @gemeentenijmegen/session

> A dynamodb-backed Session module. Used for applications requiring managing session and login state. Currently in development.

Latest version **0.0.39** (published 2026-09-28) · EUPL-1.2 license · 0 weekly downloads

## Install

```sh
npm install @gemeentenijmegen/session
pnpm add @gemeentenijmegen/session
yarn add @gemeentenijmegen/session
bun add @gemeentenijmegen/session
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.39 |
| Published | 2026-09-28 |
| First published | 2022-05-17 |
| Weekly downloads | 0 |
| License | EUPL-1.2 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 46.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Maintainers | espernijmegen, teppei01, jvanderborg, martijnvdijk, bramwithaar, marnixdessing, wkremer |

## Links

- npm: https://www.npmjs.com/package/@gemeentenijmegen/session
- Repository: https://github.com/GemeenteNijmegen/modules-session
- Homepage: https://github.com/GemeenteNijmegen/modules-session#readme
- Issues: https://github.com/GemeenteNijmegen/modules-session/issues
- npm.io page: https://npm.io/package/@gemeentenijmegen/session

## Dependencies (2)

- [cookie](https://npm.io/package/cookie.md) ^0.7.2
- [@aws-sdk/client-dynamodb](https://npm.io/package/@aws-sdk/client-dynamodb.md) ^3.1134.0

## Recent versions

- 0.0.39 (latest) — 2026-09-28
- 0.0.38 — 2026-09-17
- 0.0.37 — 2026-08-06
- 0.0.36 — 2026-04-21
- 0.0.35 — 2026-03-12
- 0.0.34 — 2026-02-06
- 0.0.33 — 2026-01-05
- 0.0.32 — 2025-12-01
- 0.0.31 — 2025-10-14
- 0.0.30 — 2025-09-18
- 0.0.29 — 2025-08-19
- 0.0.28 — 2025-07-24
- 0.0.27 — 2025-06-18
- 0.0.26 — 2025-05-20
- 0.0.25 — 2025-05-06
- … 24 more at https://npm.io/package/@gemeentenijmegen/session/versions

## README

# Gemeente Nijmegen Session

A dynamodb-backed Session module. Used for applications requiring managing session and login state. Currently in development.

## How to use
Quickstart:

Install using npm: 

```npm i @gemeentenijmegen/session```

```
// dynamoDBClient is an instance of DynamoDBClient in @aws-sdk/client-dynamodb
// create session object
const session = new Session('', dynamoDBClient);
// initialize
await session.init();
// create a new session, passing in the session data
await session.createSession({'user': 'john'});
```

The session returns a cookie-header string value when `session.getCookie()` is called. this string will contain a cookie named 'session' with a random UUID4 as its value. This acts as the session identifier.

## Using an existing session
After initializing the session, call `getSession` on the session instance passing the cookie header as the parameter. The cookie will be parsed and the identifier used to retrieve session Data.

## Checking for login state
To check login state, the `isLoggedin` convenience method can be called. If this field is not set or false, this method will return false. It will only return true if the field is set in session data, and is (boolean) true.

## Setting session state
call the async method `createSession` or `updateSession` on the session instance, passing in an object containing session state. It must be of the form expected by dynamodb. For example:
```
const data = {
    loggedin: { BOOL: true },
    user: { S: 'John' }
}
```
The only 'special' field in the data object is the loggedin-field. If this is present the `loggedIn`-method is available. All methods that set session state automatically reset the TTL for the session. Session length is currently hardcoded to 15 minutes.

## Retrieving session state
after calling `getSession`, individual fields can be retrieved by calling `getValue(key, type)`, where `key` is the key for the field you want (i.e. `user`) and type defaults to `S`, and is required to be the dynamoDB data type. For example:
```
session.getValue('user') // => 'John'
session.getValue('loggedin', 'BOOL') // => true
```


## Updating sessions
Calling `setValue(key, value)`, where `key` is the key for the field you want (i.e. `user`) value the (string) value of the field, you can update an existing session.
```
session.getValue('user') // => 'John'
session.setValue('user', 'Joe')
session.getValue('user') // => Joe
```

---
_Source: https://npm.io/package/@gemeentenijmegen/session · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._