@aventii/db (1.3.1)

Published 2026-11-06 11:19:22 +00:00 by Valentin

Installation

@aventii:registry=
npm install @aventii/db@1.3.1
"@aventii/db": "1.3.1"

About this package

@aventii/db

Primitives génériques de connexion aux bases de données pour les services Aventii.

Le package fournit une abstraction légère du cycle de vie des connexions sans imposer un moteur de base de données, une méthode de récupération de l'URI ou une organisation des bases, collections et modèles. Il prend actuellement en charge MongoDB natif et Mongoose.

Installation

Le package est distribué sur le registre npm privé Aventii :

npm install @aventii/db

Une configuration npm Aventii valide est nécessaire.

Principes

@aventii/db sépare trois responsabilités :

  1. Le gestionnaire de connexion (createDatabaseManager).
  2. L'adapter du moteur (createMongoAdapter ou createMongooseAdapter).
  3. Le secret provider qui fournit l'URI (createHttpSecretProvider ou createDirectSecretProvider).

Le service consommateur reste responsable de ses bases, collections, modèles et règles métier.

Gestionnaire de connexion

const { createDatabaseManager } = require('@aventii/db');

const database = createDatabaseManager({
    adapter,
    secretProvider
});

await database.initialize();

Le gestionnaire récupère l'URI, établit la connexion, conserve son état, réessaie au démarrage, peut contrôler périodiquement si l'URI a changé et permet une fermeture propre.

Initialisation et politique d'échec

const database = createDatabaseManager({
    adapter,
    secretProvider,
    retry: {
        attempts: 3,
        delayMs: 1000,
        timeoutMs: 20000
    }
});

Les valeurs ci-dessus sont les valeurs par défaut. Si aucune connexion ne peut être établie, initialize() rejette sa promesse. Le délai timeoutMs limite l'attente de initialize() mais n'annule pas les opérations sous-jacentes déjà lancées ; elles peuvent continuer après expiration du délai.

État et accès à la connexion

const status = database.getStatus();
const connection = database.getConnection();
const db = database.getDb('Auth');

L'état contient connected, lastAttempt, lastSuccess, lastError et attempts. getConnection() échoue avant l'initialisation. getDb() requiert un adapter qui expose cette méthode.

MongoDB natif

const { createDatabaseManager, createMongoAdapter } = require('@aventii/db');

const database = createDatabaseManager({
    adapter: createMongoAdapter(),
    secretProvider
});

await database.initialize();
const users = database.getDb('Auth').collection('Users');

Des options MongoClient peuvent être fournies :

const { ServerApiVersion } = require('mongodb');

const adapter = createMongoAdapter({
    clientOptions: {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true
        }
    }
});

Mongoose

const { createDatabaseManager, createMongooseAdapter } = require('@aventii/db');

const database = createDatabaseManager({
    adapter: createMongooseAdapter(),
    secretProvider
});

await database.initialize();
const authDb = database.getDb('Auth');
const User = authDb.model('User', userSchema, 'Users');
const users = authDb.collection('Users');

L'adapter Mongoose utilise useDb(name, { useCache: true }) pour les bases nommées.

Secret provider HTTP et serveur de secours

createHttpSecretProvider récupère l'URI depuis un service HTTP de secrets. Il accepte un serveur principal (baseUrl) et, facultativement, un serveur de secours (fallbackBaseUrl).

const { createHttpSecretProvider } = require('@aventii/db');

const secretProvider = createHttpSecretProvider({
    baseUrl: process.env.KEY_API_URL,
    ...(process.env.FALLBACK_KEY_API_URL && {
        fallbackBaseUrl: process.env.FALLBACK_KEY_API_URL
    }),
    secretName: {
        production: 'MONGO_URI',
        staging: 'MONGO_URI_STAGING',
        local: 'MONGO_URI_LOCAL'
    },
    environment: process.env.NODE_ENV,
    getAuthToken
});

Règles de bascule

  • Chaque appel à getSecret() commence par le serveur principal.
  • Tout échec pendant la tentative principale entraîne une tentative sur le secours, s'il est configuré : réseau, timeout, statut HTTP 4xx ou 5xx, JSON invalide, secret absent ou invalide, ou erreur de construction des en-têtes d'authentification.
  • Les en-têtes, notamment le token obtenu par getAuthToken(), sont reconstruits pour chaque tentative.
  • Chaque requête utilise AbortSignal.timeout(5000) ; ce délai s'applique au fetch et aux opérations qui respectent son signal d'annulation.
  • Si le secours réussit, son secret est retourné. Le prochain appel repart néanmoins du principal.
  • Sans secours, l'erreur principale est propagée. Si les deux tentatives échouent, une AggregateError contenant les deux erreurs est levée.
  • Les erreurs de résolution du nom du secret (secretName) ou de construction du chemin (pathBuilder) surviennent avant la tentative principale et ne déclenchent pas de bascule.

Par défaut, une requête GET est envoyée vers key/<nom-du-secret-encodé> ; la réponse JSON doit contenir une propriété key non vide. Le token facultatif est transmis via x-auth-token.

Les options pathBuilder, headers, responseExtractor et fetchImpl permettent de personnaliser le provider. Les deux serveurs utilisent le même chemin, la même extraction de réponse et le même mécanisme d'authentification. Le package ne connaît ni l'adresse réelle du service de secrets ni sa logique métier.

Attention : le fallback concerne la récupération de l'URI, et non une bascule automatique entre serveurs MongoDB. Une URI différente renvoyée par le secours peut provoquer un remplacement de connexion lors du rafraîchissement.

URI fournie directement

Le service de secrets est facultatif :

const { createDirectSecretProvider } = require('@aventii/db');

const secretProvider = createDirectSecretProvider({
    uri: process.env.MONGO_URI
});

Rafraîchissement de la chaîne de connexion

const database = createDatabaseManager({
    adapter,
    secretProvider,
    refreshIntervalMs: 15 * 60 * 1000
});

Le rafraîchissement (15 minutes par défaut) compare l'URI récupérée avec l'URI courante. Si elle change, une nouvelle connexion est établie et validée avant la fermeture de l'ancienne. Si la récupération du secret ou la nouvelle connexion échoue, l'ancienne connexion reste active et refresh() renvoie false.

Pour désactiver le rafraîchissement :

refreshIntervalMs: 0

Cette option est utile lorsqu'un consommateur conserve des objets liés à une connexion particulière, notamment certains modèles Mongoose. Le rafraîchissement ne constitue pas un contrôle de santé permanent de la base : une URI inchangée n'entraîne pas de reconnexion.

Hook de connexion

const database = createDatabaseManager({
    adapter,
    secretProvider,
    onConnected: async connection => {
        // Initialisation propre au consommateur (par exemple, index).
    }
});

Si le hook échoue, la nouvelle connexion est fermée et n'est pas adoptée.

Fermeture propre

await database.close();

Par exemple :

async function gracefulShutdown() {
    await database.close();
    process.exit(0);
}

process.on('SIGINT', gracefulShutdown);
process.on('SIGTERM', gracefulShutdown);

Plusieurs moteurs dans un même service

Plusieurs gestionnaires indépendants peuvent coexister. Un microservice peut utiliser MongoDB natif, Mongoose ou d'autres adapters futurs, chacun avec son propre cycle de vie.

API

Le package exporte :

createDatabaseManager
createMongoAdapter
createMongooseAdapter
createHttpSecretProvider
createDirectSecretProvider

Une instance createDatabaseManager expose :

initialize
refresh
close
getStatus
getConnection
getDb

Le provider HTTP expose getSecret() et resolveSecretName().

Hors périmètre

@aventii/db ne décide pas quelles bases, collections, modèles ou schémas utiliser, comment structurer les données métier, quelles routes accèdent aux données, quel moteur choisir, ni si le rafraîchissement dynamique convient au consommateur. Il ne fournit pas non plus de bascule automatique de serveur MongoDB ni de surveillance de santé de la base.

Tests

npm test

La suite de tests couvre le gestionnaire, les adapters MongoDB et Mongoose, les providers HTTP et direct, ainsi que les politiques d'initialisation et d'échec. La couverture effective des nouveaux scénarios de fallback doit être vérifiée ou complétée (erreurs 4xx/5xx, réseau, timeout, JSON invalide, absence de fallback et double échec).

Dependencies

Development Dependencies

ID Version
jest ^30.0.0
mongodb ^6.0.0
mongoose ^8.0.0

Peer Dependencies

ID Version
mongodb >=6
mongoose >=8
Details
npm
2026-11-06 11:19:22 +00:00
13
UNLICENSED
latest
8.4 KiB
Assets (1)
db-1.3.1.tgz 8.4 KiB
Versions (6) View all
1.3.1 2026-11-06
1.3.0 2026-11-06
1.2.1 2026-08-19
1.2.0 2026-08-19
1.1.0 2026-08-19