tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
248 lines (154 loc) • 4.26 kB
Markdown
# 📚 TinyLevelUp Documentation
A lightweight XP-based leveling system for managing user experience and levels. Great for games, communities, or reward-based applications! 🎮✨
## 📐 Type Definitions
### ✍️ `UserEditor`
Represents the structure of a user object used in the leveling system.
```ts
{
exp: number; // Current experience points of the user
level: number; // Current level of the user
totalExp: number; // Total accumulated experience
}
```
## 🏗️ Class: `TinyLevelUp`
Handles experience logic, leveling up/down, validation, and XP generation.
### 🆕 Constructor
```ts
new TinyLevelUp(giveExp: number, expLevel: number)
```
* `giveExp`: Base XP value for random XP generation 🎲
* `expLevel`: Base XP required per level up 🔺
## 🧰 Methods
### ➕ `createUser()`
Creates a fresh user at level 1 with no XP.
```ts
createUser(): UserEditor
```
### 🔎 `validateUser(user)`
Throws an error if the user object is malformed or contains invalid values.
```ts
validateUser(user: UserEditor): void
```
🚨 Throws if:
* `exp`, `level`, or `totalExp` are not valid numbers.
### ✅ `isValidUser(user)`
Checks if the given user object is valid (without throwing errors).
```ts
isValidUser(user: UserEditor): boolean
```
### 🎁 `getGiveExpBase()`
Returns the base XP value used for generating XP.
```ts
getGiveExpBase(): number
```
### 🧮 `getExpLevelBase()`
Returns the base XP required per level.
```ts
getExpLevelBase(): number
```
### ⚖️ `expValidator(user)`
Validates and adjusts user level based on current XP.
```ts
expValidator(user: UserEditor): UserEditor
```
* Levels up/down the user if needed.
* Applies "extra" XP appropriately.
### 📊 `getTotalExp(user)`
Calculates total accumulated XP (including current level and progress).
```ts
getTotalExp(user: UserEditor): number
```
### 🎲 `expGenerator(multi = 1)`
Generates a random XP value based on the multiplier.
```ts
expGenerator(multi?: number): number
```
### ⏩ `progress(user)`
Returns XP required to reach the next level.
```ts
progress(user: UserEditor): number
```
### 📈 `getProgress(user)`
Alias for `progress()`. Returns XP needed to reach the next level.
```ts
getProgress(user: UserEditor): number
```
### ✍️ `set(user, value)`
Sets the current XP for the user and updates their level if necessary.
```ts
set(user: UserEditor, value: number): UserEditor
```
### ⬆️ `give(user, extraExp?, type?, multi?)`
Adds experience to the user and auto-levels if needed.
```ts
give(
user: UserEditor,
extraExp?: number,
type?: 'add' | 'extra',
multi?: number
): UserEditor
```
* `type = 'add'`: Adds generated XP + extra
* `type = 'extra'`: Adds only extra
### ⬇️ `remove(user, extraExp?, type?, multi?)`
Removes experience from the user and updates their level if necessary.
```ts
remove(
user: UserEditor,
extraExp?: number,
type?: 'add' | 'extra',
multi?: number
): UserEditor
```
* `type = 'add'`: Removes generated XP + extra
* `type = 'extra'`: Removes only extra
### 🔍 `getMissingExp(user)`
**Description:**
Calculates how much experience is missing for the user to reach the next level.
**Parameters:**
* `user` (UserEditor) — The user object containing experience and level properties.
**Returns:**
* `number` — The amount of experience points still needed to level up.
**Throws:**
* `Error` — If any property (`exp`, `level`, or `totalExp`) in the `user` object is not a valid number. ⚠️
**Example usage:**
```js
const missing = tinyLevelUp.getMissingExp(user);
console.log(`You need ${missing} more XP to level up! 🚀`);
```
## 🌟 Example Usage
```js
import TinyLevelUp from './TinyLevelUp.js';
const levelSystem = new TinyLevelUp(15, 10);
const user = levelSystem.createUser();
levelSystem.give(user); // Adds random XP
console.log(user);
levelSystem.set(user, 50); // Manually set XP
console.log(user.level);
```
## 💬 Notes
* All methods throw if invalid values are passed ❗
* You can use `isValidUser()` for safe checks without exceptions 🛡️
* This system is deterministic and extendable!