npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

express-session-cosmosdb

v0.5.0

Published

This is yet another implementation of an Express session provider, this one targeting Azure Cosmos DB.

Downloads

9

Readme

express-session-cosmosdb

This is yet another implementation of an Express session provider, this one targeting Azure Cosmos DB.

While there were a previous generation of providers created for documentdb, or the older Cosmos libraries, this targets the 2020+-era Cosmos SDK and uses TypeScript.

This library is repackaged from the open source GitHub Management Portal used at Microsoft that I created as part of my day job. See also: https://github.com/microsoft/opensource-portal/blob/develop/lib/cosmosSession/index.ts

I am unofficially packaging up this for independent use in personal projects for the time being, since it's such a basic library, and publishing into my own scoped NPM package for now.

Preparing Cosmos DB for session storage

While you'll want to review the pricing details for Cosmos, the most important capability used for session storage is time-to-live / TTL configuration. By default, Cosmos containers have TTL turned off.

When creating or configuring a new container:

  • in the Azure Portal, go to the Scale and Settings for your container
  • change TTL to either "On (no default)" or "On", and configure a default TTL value.

Using the Cosmos DB Express session provider

Configuring your Express middleware

While using Express, you simply initialize a new instance of the CosmosSessionStore object with a set of properties, and your Cosmos DB will be used for storing the session.

To protect keys, this sample code assumes you are using the npm dotnev and .env files.

require('dotenv').config(); // load .env keys into process environment variables

import express from 'express';
import session from 'express-session';
import CosmosSessionStore from 'express-session-cosmosdb';

// ... standard Express middleware ...

const store = new CosmosSessionStore({
  endpoint: process.env.COSMOS_SESSION_ENDPOINT,
  database: process.env.COSMOS_SESSION_DATABASE,
  collection: process.env.COSMOS_SESSION_CONTAINER,
  key: process.env.COSMOS_SESSION_KEY,
});

const sess = {
  store,
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    path: '/',
    httpOnly: true,
    secure: false,
  },
}

if (app.get('env') === 'production') {
  // IF using a load balancer in Azure - beware: app.set('trust proxy', 1) // trust first proxy
  sess.cookie.secure = true // serve secure cookies
}

app.use(session(sess))

// ... continue standard Express middleware ...

Runtime information and debugging

The debug module is used to allow for sharing more verbose information at runtime. If you set the environment variable DEBUG to include express-session-cosmosdb or *, initialiation information will be shown.

Helpful debug information includes detailed errors during attempted Cosmos database and container initialization, as well as diagnostics around time-to-life settings and defaults.

node DEBUG=express-session-cosmodb ./bin/www

Options

The required options taken when constructing the CosmosSessionStore conforming to the interface ICosmosSessionProviderOptions are:

  • endpoint: the URI endpoint of the Cosmos DB, directly copied from the Azure portal or CLI. Sample value: https://espresso.documents.azure.com:443/
  • key: the primary or secondary key of the Cosmos DB, a base64-encoded key
  • database: the name of the database
  • collection: the name of the collection/container for storing sessions

Optional but strongly encouraged:

  • ttl: optional, but strongly recommended unless using default TTL configured on a Cosmos container. The number of seconds to keep around sessions.

Optional other parameters:

  • createDatabaseIfNotExists: set to true to create the database if it does not exist. This could have billing implications.
  • createCollectionIfNotExists: set to true to create the collection if it does not exist. This could have billing implications. The collection also will not have a TTL default or TTL support enabled.
  • skipVerifyDatabaseExists: set to true to skip runtime validation that the database exists
  • skipVerifyCollectionExists: set to true to skip runtime validation that the collection exists

MIT License

This project was originally created as part of the opensource-portal project at Microsoft. This is a fork of the ./lib/cosmosSession/ folder, and maintains the Microsoft copyright and MIT license.

Contributors to this project may be asked to sign the Microsoft CLA.