メインコンテンツまでスキップ
バージョン: v2.0

Database

このクラスは、データベースを操作するためのメソッドを提供します。MongoDB と SQLite の両方をサポートし、ユーザーおよびレベルロールのドキュメントを作成、更新、削除、検索できます。レコードの作成または更新時には、createdAt と lastUpdated のタイムスタンプが設定されます。

Methods​

Database.getCollection()​

データベースからコレクションを返します。

注意

この関数は MongoDB データベースでのみ使用できます。

パラメーター​

ParameterTypeRequiredDescription
collectionstring✅取得するコレクション名。

戻り値 Collection - MongoDB コレクション​

Database.createOne()​

注意

ここでは query のプロパティを すべて 指定する必要があります。

データベースに新しいドキュメントを作成します。このメソッドは createdAt と lastUpdated の ISO タイムスタンプを自動で追加します。data オブジェクトの多くのフィールド (name、user、level、xp、flags など。simply-xps の場合) は任意です。MongoDB と SQLite の両方をサポートします。

パラメーター​

ParameterTypeRequiredDescription
queryUserOptions LevelRoleOptions✅ユーザーまたはレベルロール用オプション。

戻り値 Promise<UserResult | LevelRoleResult> - User または LevelRole​

Database.deleteMany()​

複数のドキュメントを削除します。基盤ドライバーが結果オブジェクトを返した場合に true を返します。SQLite では run() の結果が成功時に truthy として扱われます。

パラメーター​

ParameterTypeRequiredDescription
queryUserOptions LevelRoleOptions✅ユーザーまたはレベルロール用オプション。

戻り値 Promise<boolean> - ドキュメントが削除された場合は true、それ以外は false​

Database.deleteOne()​

単一のドキュメントを削除します。

パラメーター​

ParameterTypeRequiredDescription
queryUserOptions LevelRoleOptions✅ユーザーまたはレベルロール用オプション。

戻り値 Promise<boolean> - ドキュメントが削除された場合は true、それ以外は false​

Database.findOne()​

データベースから 1 件のドキュメントを検索します。

パラメーター​

ParameterTypeRequiredDescription
queryUserOptions LevelRoleOptions✅ユーザーまたはレベルロール用オプション。

戻り値 Promise<UserResult | LevelRoleResult> - User または LevelRole​

Database.find()​

指定したギルドのドキュメントを検索します。SQLite では simply-xps の flags カラムは JSON から配列に再変換されます。collection パラメーターには simply-xps または simply-xp-levelroles を指定する必要があります。

パラメーター​

ParameterTypeRequiredDescription
collectionsimply-xps
simply-xp-levelroles		✅取得するコレクション名。
guildstring✅ギルド ID。
limitnumber❌返却する最大ドキュメント数。

戻り値 Promise< UserResult[] | LevelRoleResult[] > - User または LevelRole​

Database.findAll()​

すべてのドキュメントを検索します。

パラメーター​

ParameterTypeRequiredDescription
collectionsimply-xps
simply-xp-levelroles		✅取得するコレクション名。
limitnumber❌返却する最大ドキュメント数。

戻り値 Promise< UserResult[] | LevelRoleResult[] > - User または LevelRole​

Database.findGlobalLeaderboard()​

すべてのギルドを横断したグローバルリーダーボードを取得し、ユーザーごとに 1 行だけを残します。各ユーザーについて、XP が最も高いギルドの行が採用されます（同点の場合は最終更新日時、次に作成日時が新しい方が優先されます）。guildId を指定せずに leaderboard() を呼び出した際に内部で使用されます。

パラメーター​

ParameterTypeRequiredDescription
limitnumber❌返却する最大ユーザー数。

戻り値 Promise< UserResult[] > - XP の降順で並んだ、ユーザーごとに 1 行の結果。​

Database.updateOne()​

データベース内のドキュメントを更新します。

パラメーター​

ParameterTypeRequiredDescription
filterUserOptions LevelRoleOptions✅ユーザーまたはレベルロール用オプション。
updateUserOptions LevelRoleOptions✅ドキュメントに適用する更新内容。
options{ upsert?: boolean }❌MongoDB の upsert オプション。

戻り値 Promise<UserResult | LevelRoleResult> - User または LevelRole​

Database.namespace()​

プラグイン専用のキー/値ストアを返します。これにより、プラグインは xp.database や simply-xp のテーブルを直接操作することなく、独自のデータを保存できます。

MongoDB と SQLite の両方で動作します。ストレージは最初の書き込み時に遅延作成されるため、何も保存しないプラグインはデータベースに一切影響しません。

パラメーター​

ParameterTypeRequiredDescription
namestring✅名前空間。通常はプラグインのパッケージ名。

戻り値 PluginStore​

メソッド戻り値説明
get(key)Promise<T | null>値を読み取ります。未設定の場合は null。
set(key, value)Promise<void>値を書き込みます。JSON 化できる値であれば何でも可。
delete(key)Promise<boolean>キーを削除し、存在したかどうかを返します。
keys()Promise<string[]>この名前空間のすべてのキーを列挙します。
clear()Promise<number>この名前空間のすべてのキーを削除し、その件数を返します。

例外​

  • XpFatal - 名前が指定されていない場合、またはデータベース接続がない場合。

例​

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; // まだクールダウン中
ヒント

名前空間は互いに分離されているため、2 つのプラグインが同じキー名を安全に使用できます。

Database.countUsersWithMoreXp()​

指定した値より厳密に多くの XP を持つギルド内のユーザー数を数えます。fetch() と rankCard() が、ギルド全体をメモリに読み込まずにユーザーのリーダーボード順位を計算するために内部で使用します。

パラメーター​

ParameterTypeRequiredDescription
guildIdstring✅ギルド ID。
xpValuenumber✅この値より多い XP を持つユーザーを数えます。

戻り値 Promise<number> - より多くの XP を持つユーザー数。​