Database

Cette classe fournit des méthodes pour interagir avec la base de données. Elle prend en charge les backends MongoDB et SQLite et propose des opérations pour créer, mettre à jour, supprimer et interroger les documents d'utilisateur et de level-role. Les méthodes définissent les timestamps ISO createdAt et lastUpdated lors de la création ou de la mise à jour des enregistrements.

Méthodes

Database.getCollection()

Retourne une collection depuis la base de données.

attention

Cette fonction ne peut être utilisée qu'avec MongoDB.

Parameters

Parameter	Type	Required	Description
collection	string	✅	Le nom de la collection à récupérer.

Returns Collection - Collection MongoDB

---

Database.createOne()

attention

TOUTES les propriétés de query sont requises ici.

Crée un nouveau document dans la base de données. La méthode ajoute automatiquement les timestamps ISO createdAt et lastUpdated. De nombreux champs de l'objet data sont optionnels (par exemple name, user, level, xp et flags pour simply-xps). La méthode prend en charge MongoDB et SQLite.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	Les options pour l'utilisateur ou le level-role.

Returns Promise<UserResult | LevelRoleResult> - UserResult ou LevelRoleResult

---

Database.deleteMany()

Supprime plusieurs documents de la base de données. Retourne true lorsque le driver sous-jacent renvoie un objet résultat (pour SQLite, le résultat de run() est considéré comme truthy en cas de succès).

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	Les options pour l'utilisateur ou le level-role.

---

Database.deleteOne()

Supprime un seul document de la base de données.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	Les options pour l'utilisateur ou le level-role.

Returns Promise<boolean> - true si un document a été supprimé, sinon false

---

Database.findOne()

Récupère un document dans la base de données.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	Les options pour l'utilisateur ou le level-role.

Returns Promise<UserResult | LevelRoleResult> - UserResult ou LevelRoleResult

---

Database.find()

Récupère les documents d'une guilde donnée. Pour SQLite, les lignes simply-xps verront la colonne flags reconvertie depuis du JSON en tableau. Le paramètre collection doit être simply-xps ou simply-xp-levelroles.

Parameters

Parameter	Type	Required	Description
collection	simply-xps simply-xp-levelroles	✅	Le nom de la collection à récupérer.
guild	string	✅	L'ID de la guilde.
limit	number	❌	Nombre maximal de documents à retourner.

Returns Promise< UserResult[] | LevelRoleResult[] > - UserResult[] ou LevelRoleResult[]

---

Database.findAll()

Récupère tous les documents de la base de données.

Parameters

Parameter	Type	Required	Description
collection	simply-xps simply-xp-levelroles	✅	Le nom de la collection à récupérer.
limit	number	❌	Nombre maximal de documents à retourner.

Returns Promise< UserResult[] | LevelRoleResult[] > - UserResult[] ou LevelRoleResult[]

---

Database.findGlobalLeaderboard()

Récupère le classement global tous serveurs confondus, en ne gardant qu'une ligne par utilisateur : celle de son serveur où son XP est la plus élevée (en cas d'égalité, la plus récemment mise à jour, puis la plus récemment créée). Utilisée en interne par leaderboard() lorsqu'il est appelé sans guildId.

Paramètres

Paramètre	Type	Requis	Description
limit	number	❌	Nombre maximal d'utilisateurs à retourner.

Retourne Promise< UserResult[] > - Une ligne par utilisateur, triée par XP décroissant.

---

Database.updateOne()

Met à jour un document dans la base de données.

Parameters

Parameter	Type	Required	Description
filter	UserOptions LevelRoleOptions	✅	Les options pour l'utilisateur ou le level-role.
update	UserOptions LevelRoleOptions	✅	La mise à jour à appliquer au document.
options	UpdateOneOptions	❌	Options pour la mise à jour (MongoDB seulement).

Returns Promise<UserResult | LevelRoleResult> - UserResult ou LevelRoleResult

---

Database.namespace()

Retourne un stockage clé/valeur privé pour un plugin, afin que les plugins puissent conserver leurs propres données sans toucher directement à xp.database ni aux tables de simply-xp.

Fonctionne avec MongoDB et SQLite. Le stockage est créé de manière paresseuse lors de la première écriture : les plugins qui n'enregistrent rien n'ajoutent rien à votre base de données.

Paramètres

Paramètre	Type	Requis	Description
name	string	✅	L'espace de noms, généralement le nom de votre paquet.

Retourne PluginStore

Méthode	Retourne	Description
get(key)	Promise<T | null>	Lit une valeur, ou null si la clé n'est pas définie.
set(key, value)	Promise<void>	Écrit une valeur. Tout ce qui est sérialisable en JSON est accepté.
delete(key)	Promise<boolean>	Supprime une clé et indique si elle existait.
keys()	Promise<string[]>	Liste toutes les clés de cet espace de noms.
clear()	Promise<number>	Supprime toutes les clés et retourne leur nombre.

Erreurs

• XpFatal - Si aucun nom n'est fourni, ou s'il n'y a pas de connexion à la base de données.

Exemple

const { Database } = require("simply-xp");

const store = Database.namespace("simply-xp-rate-limits");

await store.set(`cooldown:${userId}`, { until: Date.now() + 60_000 });

const cooldown = await store.get(`cooldown:${userId}`);
if (cooldown && cooldown.until > Date.now()) return; // encore en attente

astuce

Les espaces de noms sont isolés les uns des autres : deux plugins peuvent utiliser les mêmes noms de clés sans risque.

---

Database.countUsersWithMoreXp()

Compte les utilisateurs d'une guilde ayant strictement plus d'XP qu'une valeur donnée. Utilisée en interne par fetch() et rankCard() pour calculer la position d'un utilisateur dans le classement sans charger toute la guilde en mémoire.

Paramètres

Paramètre	Type	Requis	Description
guildId	string	✅	L'ID de la guilde.
xpValue	number	✅	Compte les utilisateurs avec plus d'XP que cette valeur.

Retourne Promise<number> - Le nombre d'utilisateurs avec plus d'XP.