@dbeauyat/user-sessions-utils

Gestion de sessions authentifiées stockées dans Redis Stack (module JSON), avec expiration automatique via TTL configurable (15 min par défaut).

Install

npm install @dbeauyat/user-sessions-utils

TypeScript

Le package inclut des déclarations de type (types/index.d.ts). Les imports sont donc typés dans les projets TypeScript, sans avoir à ajouter manuellement un fichier .d.ts :

import {
  createSession,
  retrieveSession,
  verifySession,
  updateSession,
  refreshSession,
  deleteSession,
  setConfig,
  setSessionKeyPrefix
} from '@dbeauyat/user-sessions-utils';

const { sessionId } = await createSession('alice');
const session = await retrieveSession(sessionId);
if (session) {
  console.log(session.startDate, session.contenuValide);
}

Types de retour :

| Fonction | Type de retour | |---|---| | createSession(username) | Promise<{ success: true; sessionId: string }> | | retrieveSession(sessionId) | Promise<{ startDate; lastAccess; associatedUsername; contenuValide } \| null> | | verifySession(sessionId) | Promise<{ valid: boolean; reason?: string }> | | updateSession(sessionId, updates) | Promise<{ success: true }> | | refreshSession(sessionId) | Promise<{ success: true; lastAccess: string }> | | deleteSession(sessionId) | Promise<{ success: true }> | | setConfig(key, value) | void | | setSessionKeyPrefix(newPrefix) | void |

API

createSession(username)

Crée une nouvelle session avec un identifiant aléatoire, enregistre la date de début et rafraîchit le TTL (configurable, défaut 15 min).

Paramètres :

• username (string) — nom d'utilisateur associé à la session

Retourne : Promise<{ success: true, sessionId: string }>

retrieveSession(sessionId)

Récupère les données complètes d'une session depuis Redis.

Paramètres :

• sessionId (string) — identifiant unique de la session

Retourne : Promise<{ startDate: string, lastAccess: string, associatedUsername: string, contenuValide: Record<string, any> } | null>

verifySession(sessionId)

Vérifie l'existence d'une session dans Redis.

Paramètres :

• sessionId (string) — identifiant unique de la session

Retourne : Promise<{ valid: boolean, reason?: string }>

updateSession(sessionId, updates)

Met à jour un ou plusieurs champs de l'objet contenuValide d'une session et rafraîchit le TTL.

Paramètres :

• sessionId (string) — identifiant unique de la session
• updates (object) — objet contenant les champs et valeurs à mettre à jour dans contenuValide

Retourne : Promise<{ success: true }>

refreshSession(sessionId)

Met à jour le timestamp lastAccess et réinitialise le TTL de la session (configurable, défaut 15 min).

Paramètres :

• sessionId (string) — identifiant unique de la session

Retourne : Promise<{ success: true, lastAccess: string }>

deleteSession(sessionId)

Supprime une session de Redis en utilisant JSON.DEL.

Paramètres :

• sessionId (string) — identifiant unique de la session à supprimer

Retourne : Promise<{ success: true }>

setConfig(key, value)

Modifie dynamiquement une valeur de configuration au runtime. La modification est immédiate pour le processus actuel mais disparaît au rechargement.

Paramètres :

• key (string) — chemin hiérarchique séparé par des points (ex: "DBs.redis.port", "DBs.sessionTTLMinutes")
• value (*) — nouvelle valeur à assigner

Retourne : void

Exemple :

setConfig('DBs.sessionTTLMinutes', 60); // passer le TTL à 60 min
setConfig('DBs.sessionKeyPrefix', 'monapp:sessions');

setSessionKeyPrefix(newPrefix)

Raccourci pour modifier le préfixe des clés Redis.

Paramètres :

• newPrefix (string) — nouveau préfixe (ex: "monapp:sessions")

Retourne : void

Configuration

La configuration s'effectue via variables d'environnement (12-factor). Aucun fichier de configuration n'est nécessaire :

| Variable | Description | Défaut | |---|---|---| | REDIS_HOST | Adresse du serveur Redis | 127.0.0.1 | | REDIS_PORT | Port du serveur Redis | 6379 | | REDIS_USERNAME | Nom d'utilisateur Redis | default | | REDIS_PASSWORD | Mot de passe Redis | "" | | SESSION_KEY_PREFIX | Préfixe des clés Redis ({prefix}:{sessionId}) | fimeco2:sessions | | SESSION_TTL_MINUTES | TTL de session en minutes | 15 |

Exemple :

REDIS_HOST=redis.local REDIS_PORT=6380 SESSION_TTL_MINUTES=60 node app.js

Architecture

Les sessions sont stockées sous forme de documents JSON dans Redis Stack (module ReJSON) avec le pattern de clé {prefix}:{sessionId} — le préfixe est configurable via la variable SESSION_KEY_PREFIX (défaut : "fimeco2:sessions"). Chaque session dispose d'un TTL configurable via SESSION_TTL_MINUTES (défaut : 15 min), appliqué après chaque opération d'écriture.

Technologies utilisées

• ioredis — client Redis asynchrone pour Node.js
• nanoid — génération d'identifiants uniques cryptographiquement sécurisés

Scripts npm

| Commande | Description | |----------|-------------| | npm test | Lance les tests | | npm run release:local | Crée une nouvelle version mineure et publie localement | | npm run release:public | Crée une nouvelle version mineure et publie sur npmjs.org |

Licence

ISC — © 2026 Daniel Beauyat