Registry / database / telegraf-session-mongodb

telegraf-session-mongodb

library2.0.2jsnpmunverified

MongoDB-based session middleware for the Telegraf Telegram bot framework (v4.0+). Current stable version is 2.0.2. Provides persistent session storage using MongoDB, with support for custom collection names and session key generation. Ships TypeScript definitions, requires both `telegraf` and `mongodb` as peer dependencies. Differentiates from in-memory or file-based session stores by offering scalability and persistence via MongoDB.

database

npm install telegraf-session-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TELEGRAF-SESSION-M

telegraf-session-mongodb

databasejavascriptv2.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

session

✓ import { session } from 'telegraf-session-mongodb'

✗ const session = require('telegraf-session-mongodb')

ESM import; CommonJS require works but TypeScript types are only available with ESM-style import.

default

✓ import session from 'telegraf-session-mongodb'

✗ const session = require('telegraf-session-mongodb').default

Default export is not provided; only named export 'session' exists. Using default import will result in undefined.

MongoClient

✓ import { MongoClient } from 'mongodb'

✗ const MongoClient = require('mongodb').MongoClient

Standard import from the 'mongodb' package, not from telegraf-session-mongodb.

Sets up a Telegram bot with Telegraf and MongoDB session middleware, increments a counter on /start.

import { Telegraf } from 'telegraf'; import { MongoClient } from 'mongodb'; import { session } from 'telegraf-session-mongodb'; const bot = new Telegraf(process.env.BOT_TOKEN ?? ''); MongoClient.connect(process.env.MONGODB_URI ?? '') .then(client => { const db = client.db(); bot.use(session(db, { collectionName: 'sessions' })); bot.start((ctx) => { ctx.session.counter = ctx.session.counter || 0; ctx.session.counter++; ctx.reply(`Visited ${ctx.session.counter} times`); }); bot.launch(); }) .catch(err => console.error('MongoDB connection error', err));

Debug

Known issues

breakingVersion 2.0.0 requires Telegraf 4.0+. Using with older Telegraf versions will cause runtime errors.

fix

Upgrade to Telegraf 4.0+ or use version 1.x of this package.

affects: >=2.0.0

breakingDefault session key function changed in v2.0.0. It now uses 'from.id' instead of 'from.username' which may break existing sessions.

fix

Provide a custom sessionKeyFn to maintain backward compatibility: session(db, { sessionKeyFn: (ctx) => ctx.from?.username ?? ctx.chat?.id ?? 0 })

affects: >=2.0.0

deprecatedThe legacy session key function is deprecated and will be removed in a future version.

fix

Use the new default or provide a custom sessionKeyFn.

affects: >=2.0.0

gotchaThe session middleware must be added before any other middleware that accesses session data.

fix

Ensure bot.use(session(...)) is called before bot.use(yourOtherMiddleware).

affects: >=1.0.0

gotchaMongoClient connection must be established before passing the db object to session(). If not, middleware will fail silently.

fix

Wrap bot.use() inside the .then() of MongoClient.connect() as shown in the quickstart.

affects: >=1.0.0

deprecatedOptions 'useNewUrlParser' and 'useUnifiedTopology' are deprecated in MongoDB driver 4.0+. They are still accepted but unnecessary.

fix

Remove those options when using MongoDB driver 4.0+.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: session is not a function

Importing default export instead of named export.

fix

Use import { session } from 'telegraf-session-mongodb' instead of import session from 'telegraf-session-mongodb'.

ReferenceError: session is not defined

Middleware not added before accessing ctx.session.

fix

Make sure bot.use(session(...)) is called before any handler that uses ctx.session.

MongoError: pool destroyed

MongoClient was closed before bot stopped.

fix

Keep the MongoClient connected for the lifetime of the bot, and close it only on process termination.

TypeError: Cannot read property 'collectionName' of undefined

Passing undefined as db object to session().

fix

Ensure db is obtained from a resolved MongoClient.connect() promise.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

mongodbrequiredRequired to connect to MongoDB and perform CRUD operations on sessions.

Agent activity

23 hits · last 30 days

node