\n\n---\n\n> CREDITS TO ORIGINAL CREATOR [RAHULETTO](https://github.com/rahuletto) FOR SIMPLY-XP **VERSION 1**\n\n---\n\n \n\n## 🖥️ Installation\n\n```shell\nnpm install simply-xp@latest mongodb\n```\n\n(or)\n\n```shell\nnpm install simply-xp@latest better-sqlite3\n```\n\nInstall only the adapter you actually use:\n\n- `mongodb` for the MongoDB adapter\n- `better-sqlite3` for the SQLite adapter\n\nsimply-xp itself supports Node.js 14+, but the adapters set their own, higher floors:\n\n| Adapter | Requires Node.js |\n| ------------------- | ---------------- |\n| `better-sqlite3@13` | `>=22` |\n| `mongodb@7` | `>=20.19` |\n\n \n\n## 🚀 Examples\n\n### Connect to a database\n\n```js\nconst { connect } = require(\"simply-xp\");\n\n// SQLite\nawait connect(\"./xp.sqlite\", { type: \"sqlite\" });\n\n// or MongoDB\nawait connect(process.env.MONGO_URI, { type: \"mongodb\" });\n```\n\n### Add and fetch XP\n\n```js\nconst { addXP, fetch } = require(\"simply-xp\");\n\nconst result = await addXP(userId, guildId, { min: 10, max: 25 }, username);\nif (result.levelDifference > 0)\n\tconsole.log(`${username} levelled up to ${result.level}!`);\n\nconst user = await fetch(userId, guildId);\nconsole.log(\n\t`${user.name} is level ${user.level} with ${user.xp} XP (rank #${user.position})`,\n);\n```\n\n### Leaderboards\n\n```js\nconst { leaderboard } = require(\"simply-xp\");\n\nconst top10 = await leaderboard(guildId, 10);\nfor (const user of top10)\n\tconsole.log(`#${user.position} ${user.name} - ${user.xp} XP`);\n```\n\n### Level roles and events\n\n```js\nconst { LevelRoles, XpEvents } = require(\"simply-xp\");\n\nawait LevelRoles.add(guildId, { level: 5, roles: [roleId] });\n\nXpEvents.on({\n\tlevelUp: (user, newRoles) => {\n\t\tconsole.log(`${user.name} reached level ${user.level}!`);\n\t\t// newRoles are the role IDs LevelRoles has set for this level\n\t},\n});\n```\n\n \n\n## ⚡ Benchmarks\n\n> Benchmarks run for 50 iterations and report average/peak Node.js process memory as `heapUsed + external`, plus wall-clock execution time per iteration.\n\n| Database | Avg Total Memory | Avg Completion Time | Peak Total Memory |\n| -------- | ---------------- | ------------------- | ----------------- |\n| SQLite | 9.5 MB | 0.9 s | 11.0 MB |\n| MongoDB | 34.5 MB | 2.4 s | 35.2 MB |\n\n**Test Environment (This Benchmark Run)**:\n\n- **OS:** Ubuntu 26.04 (Linux 7.0.0-31-generic)\n- **CPU:** AMD Ryzen 9 9950X3D\n- **RAM:** 6400 MHz DDR5\n\n> Benchmarks include common operations like addXP(), setLevel(), rankCard(), compareCard(), charts(), and leaderboardCard(). Actual usage may vary depending on server load, GC timing, and configuration.\n>\n> SQLite memory reflects simply-xp's footprint with a local file-based adapter,\n> while MongoDB execution time is higher due to network latency and the nature of the database, but still performs well within typical expectations for a leveling system.\n\n---\n\n## 🆕 What's new in V2\n\nThis is a complete rewrite of simply-xp transitioning to TypeScript and a more modular architecture, with a focus on improved performance, better error handling, and more flexible database support. I've also removed `discord.js` as a dependency, making the library simply more flexible!\n\n### ✅ Additions\n\n- `SQLite` support (`better-sqlite3`) next to `MongoDB`, both optional peer dependencies, install only the one you use.\n- New: `LevelRoles`, `compareCard()`, `leaderboardCard()`, `XpEvents`, `registerPlugins()`, `setFlags()`, `removeXP()`/`removeLevel()`, and a `Migrate` class for moving data around.\n- Every XP/level mutation is now atomic, no more lost XP from concurrent updates hitting the same user.\n\n### ⚠️ Breaking Changes\n\n- Functions take plain IDs and strings now (`userId`, `guildId`, `username`), not a `message` or `client`.\n- `roleSetup` / `lvlRole()` => `LevelRoles`. `rank()` => `rankCard()`.\n- `fetch()` and `leaderboard()` return a different shape: `rank` is now `position`, and `reqxp`/`shortxp`/`shortreq` are gone.\n- `create()` now requires a `username`. `charts()` no longer takes a `message`.\n- Imports are named exports now: `const { connect, addXP } = require(\"simply-xp\")` instead of `xp.addXP(...)`.\n","readmeFilename":"README.md"}
![\"XP](\"https://i.ibb.co/cCKJ9FS/simplyxp.png\")
\n