# 🎯 TinyAdvancedRaffle

**TinyAdvancedRaffle** is an advanced, event-driven raffle system designed for complex probability-based selections.
It goes beyond simple random draws by offering **weighted probabilities**, **normalization modes**, **pity mechanics**, **temporary modifiers**, and **seedable randomness** for reproducible outcomes.

With **import/export in JSON format**, **group-based filtering**, and **exclusion lists**, it’s ideal for games, loot systems, prize distributions, and any scenario requiring **balanced yet configurable randomness**.

✨ **Key Features**

* 📊 **Weighted items** — Assign different probabilities to each item.
* 🧮 **Normalization modes** — Choose between *relative* and *softmax*.
* 🎯 **Pity system** — Guarantee fairness over multiple draws.
* 🔄 **Temporary modifiers** — Adjust weights dynamically for limited draws.
* 🗂️ **Group filtering** — Include or exclude items by groups.
* 🔐 **Item exclusions** — Prevent specific items from being drawn.
* 📦 **Import/export in JSON** — Save and restore raffle states easily.
* ⏳ **Seedable RNG** — Ensure deterministic and repeatable results.
* 📡 **Event-driven** — Hook into lifecycle events for customization.

---

## 🎯 Type Definitions & Core Concepts

This section defines the **core data structures**, **callbacks**, and **types** used by the `TinyAdvancedRaffle` system.

---

### 📊 Normalization Modes

```ts
type Normalization = 'relative' | 'softmax';
```

Defines the available normalization strategies for **probability weight calculations**:

* **`relative`** – Direct proportion based on item weights.
* **`softmax`** – Applies a softmax transformation for a probability distribution with exponential scaling.

---

### 🎲 RNG Generator

```ts
type RngGenerator = () => number;
```

A callback that generates a pseudo-random number between `0` (inclusive) and `1` (exclusive).

---

### ⏳ Temporary Weight Modifier

```ts
type TempModifier = {
  fn: WeightsCallback;
  uses: number;
};
```

Represents a **temporary weight modifier** that is applied for a **limited number of draws**.

* **`fn`** – Function that modifies the item weights.
* **`uses`** – Number of draws before the modifier is removed.

---

### 📦 Item Data Template

```ts
type ItemDataTemplate<TGroups extends Set<string> | string[]> = {
  id: string;
  label: string;
  baseWeight: number;
  groups: TGroups;
  locked: boolean;
  meta: ItemMetadata;
};
```

Represents the **core data structure** for an item in the raffle system.

| Property     | Type                        | Description                               |
| ------------ | --------------------------- | ----------------------------------------- |
| `id`         | `string`                    | Unique identifier for the item.           |
| `label`      | `string`                    | Human-readable name for the item.         |
| `baseWeight` | `number`                    | Base probability weight before modifiers. |
| `groups`     | `Set<string>` or `string[]` | Groups the item belongs to.               |
| `locked`     | `boolean`                   | Whether the item is excluded from draws.  |
| `meta`       | `ItemMetadata`              | Arbitrary metadata.                       |

---

### 💾 Exported Raffle State

```ts
type ExportedJson = {
  items: ItemDataGetter[];
  pity: [string, Pity][];
  exclusions: string[];
  normalization: Normalization;
  seed: number | null;
};
```

Represents the **serialized state** of the raffle system for export or persistence.

---

### 🏷 Specialized Item Types

* **`ItemData`** – Item where `groups` is a `Set<string>`.
* **`ItemDataGetter`** – Item where `groups` is a `string[]`.

---

### 🗃 Metadata Container

```ts
type ItemMetadata = Record<string | number | symbol, any>;
```

Arbitrary key-value container for **extra item information**.

---

### 🛠 Weight Calculation Context

```ts
type ComputeEffectiveWeightsContext = {
  metadata?: ItemMetadata;
  previousDraws?: DrawOne[];
};
```

Provides **context** to weight modification functions during a draw.

---

### ⚖ Weight Map

```ts
type Weights = Map<string, number>;
```

Maps **item IDs** to their computed **effective weight**.

---

### 🎯 Pity System

```ts
type Pity = {
  threshold: number;
  increment: number;
  cap: number;
  counter: number;
  currentAdd: number;
};
```

Defines **pity mechanics** for guaranteeing item selection after repeated failures.

---

### 🧮 Weight Modifier Callback

```ts
type WeightsCallback = (
  weights: Weights,
  context: ComputeEffectiveWeightsContext
) => Weights | null;
```

A function that modifies or overrides computed weights **before** a draw.

---

### 🎟 Draw Result

```ts
type DrawOne = {
  id: string;
  label: string;
  meta: ItemMetadata;
  prob: number;
};
```

Represents the **result** of a single draw.

---

### 📡 Event Handler

```ts
type handler = (payload: any, event: any) => void;
```

Generic event handler for message or signal reception.

---

## 🎰 Core Properties, Getters & Setters

This section covers the **private fields**, **public getters/setters**, and **constructor** of the `TinyAdvancedRaffle` class.

---

### 🔒 Private Fields

* **`#normalization`**: *(Normalization)* — Defines the strategy for scaling probabilities before a draw.

  * Options: `'relative'` or `'softmax'`.

* **`#seed`**: *(number | null)* — RNG seed for deterministic results. If `null`, draws are fully random.

* **`#globalModifiers`**: *(WeightsCallback\[])* — Persistent weight-modifying functions applied to **every** draw.

* **`#temporaryModifiers`**: *(TempModifier\[])* — Temporary weight modifiers that expire after a set number of draws.

* **`#conditionalRules`**: *(WeightsCallback\[])* — Dynamic rules adjusting weights based on the raffle state.

* **`#pitySystems`**: *(Map\<string, Pity>)* — "Pity" mechanisms to increase chances after repeated failures.

* **`#exclusions`**: *(Set\<string>)* — Item IDs that cannot be drawn.

* **`#groups`**: *(Map\<string, Set\<string>>)* — Named groups containing sets of item IDs.

* **`#rng`**: *(RngGenerator)* — The random number generator used in draws.

* **`#items`**: *(Map\<string, ItemData>)* — All raffle items and their associated data.

* **`#freq`**: *(Map\<string, number>)* — Tracks how many times each item has been drawn.

---

### 📤 Public Getters

| Getter               | Returns                          | Description                                      |
| -------------------- | -------------------------------- | ------------------------------------------------ |
| `freq`               | `Record<string, number>`         | Draw frequency as a plain object.                |
| `size`               | `number`                         | Total number of registered items.                |
| `normalization`      | `Normalization`                  | Current probability scaling method.              |
| `seed`               | `number \| null`                 | RNG seed (if any).                               |
| `globalModifiers`    | `WeightsCallback[]`              | Copy of persistent modifiers.                    |
| `temporaryModifiers` | `TempModifier[]`                 | Copy of temporary modifiers with usage counts.   |
| `conditionalRules`   | `WeightsCallback[]`              | Copy of conditional rules.                       |
| `pitySystems`        | `Record<string, Pity>`           | Copy of all pity configurations.                 |
| `exclusions`         | `string[]`                       | List of excluded item IDs.                       |
| `groups`             | `Record<string, string[]>`       | Copy of group definitions.                       |
| `rng`                | `RngGenerator`                   | RNG function used for draws.                     |
| `items`              | `Record<string, ItemDataGetter>` | Copy of all item definitions (groups as arrays). |

---

### 📝 Public Setters

Each setter **validates input types** and throws `TypeError` for invalid data.

* **`normalization`** — Must be a non-empty string: `'relative'` or `'softmax'`.
* **`seed`** — Must be a finite number or `null`; reseeds RNG when changed.
* **`globalModifiers`** — Must be an array of functions.
* **`temporaryModifiers`** — Must be an array of `{ fn: function, uses: positive integer }`.
* **`conditionalRules`** — Must be an array of functions.
* **`pitySystems`** — Must be a `Map<string, Pity>` with all numeric fields.
* **`exclusions`** — Must be a `Set<string>`.
* **`groups`** — Must be a `Map<string, Set<string>>` where all values are strings.
* **`rng`** — Must be a function returning a number in `[0, 1)`.
* **`items`** — Must be a `Map<string, ItemData>`; **clears old list before setting**.

---

### 🏗 Constructor

This section sets up all **core data structures** and provides strict **input validation** to keep the raffle system’s state consistent. 🎯

**Parameters**:

* `opts.rng` *(RngGenerator | null)* — Custom RNG function. Defaults to `Math.random` if no seed is provided.
* `opts.seed` *(number | null)* — RNG seed for reproducible results.
* `opts.normalization` *(Normalization)* — Probability scaling mode (`'relative'` by default).

---

## 🎯 Item Management & Rules

### 📦 Item Management

#### `hasItem(itemId)`

Check if an item exists in the system.

* **Parameters:**

  * `itemId` *(string)* — The ID of the item to check.
* **Returns:** `boolean` — `true` if the item exists, otherwise `false`.
* **Throws:** `TypeError` if `itemId` is not a string.

---

#### `addItem(id, opts = {})`

Add or update an item in the raffle.

* **Parameters:**

  * `id` *(string)* — Unique item identifier.
  * `opts` *(object, optional)* — Item configuration:

    * `weight` *(number, default=1)* — Base relative weight (≥ 0).
    * `label` *(string)* — Human-readable label.
    * `meta` *(object)* — Arbitrary metadata.
    * `groups` *(string\[] | Set<string>)* — Groups this item belongs to.
* **Returns:** `ItemData` — The created or updated item.
* **Throws:** `TypeError` for invalid types.

---

#### `removeItem(id)`

Remove an item from the system.

* **Parameters:**

  * `id` *(string)* — Item ID to remove.
* **Returns:** `boolean` — `true` if removed, `false` if it didn’t exist.
* **Throws:** `TypeError` if `id` is not a string.

---

#### `setBaseWeight(id, weight)`

Update the base weight of an existing item.

* **Parameters:**

  * `id` *(string)* — Item ID.
  * `weight` *(number)* — New base weight (≥ 0).
* **Throws:**

  * `Error` if the item is not found.
  * `TypeError` for invalid parameters.

---

#### `getItem(id)`

Retrieve an item by ID.

* **Parameters:**

  * `id` *(string)* — Item ID.
* **Returns:** `ItemData | null` — Item data or `null` if not found.
* **Throws:** `TypeError` if `id` is not a string.

---

#### `listItems()`

List all items in the system.

* **Returns:** `ItemData[]` — Array of cloned item objects.

---

#### `clearList()`

Remove all items, frequencies, and pity systems.

---

### 🛠 Modifiers & Rules

#### Global Modifiers

Modifiers applied **persistently** to all draws.

* **`hasGlobalModifier(fn)`** — Check if a global modifier exists.
* **`addGlobalModifier(fn)`** — Add a persistent modifier.
* **`removeGlobalModifier(fn)`** — Remove a specific global modifier.

---

#### Temporary Modifiers

Modifiers applied only for a **limited number of draws**.

* **`hasTemporaryModifier(fn)`** — Check if it exists.
* **`addTemporaryModifier(fn, uses = 1)`** — Add a modifier for `uses` draws.
* **`removeTemporaryModifier(fn)`** — Remove it.

---

#### Conditional Rules

Rules applied dynamically during each draw.

* **`hasConditionalRule(ruleFn)`** — Check if it exists.
* **`addConditionalRule(ruleFn)`** — Add a conditional rule.
* **`removeConditionalRule(ruleFn)`** — Remove a conditional rule.

---

### 🍀 Pity System

The **pity system** increases the chance of an item appearing if it hasn’t been drawn after a certain number of tries.

* **`hasPity(itemId)`** — Check if pity exists for an item.
* **`configurePity(itemId, cfg)`** — Configure pity with:

  * `threshold` *(number)* — Number of failed draws before increasing weight.
  * `increment` *(number)* — Weight added each draw after threshold.
  * `cap` *(number, default=Infinity)* — Max extra weight.
* **`resetPity(itemId)`** — Reset pity counters.
* **`clearPities()`** — Remove all pity configurations.

---

### 🚫 Exclusions & Groups

#### Exclusions

* **`hasExclusion(itemId)`** — Check if excluded.
* **`excludeItem(itemId)`** — Exclude from raffle.
* **`includeItem(itemId)`** — Re-include in raffle.

#### Groups

* **`_ensureGroup(name)`** *(private)* — Create or get a group.
* **`hasInGroup(itemId, groupName)`** — Check group membership.
* **`addToGroup(itemId, groupName)`** — Add item to a group.
* **`removeFromGroup(itemId, groupName)`** — Remove item from a group.

---

## 🎲 Draw Core

### 🔄 Frequency Management

#### `clearFreqs()`

Clear the draw frequency count for **all** items.
Effectively resets the internal frequency tracking map to an empty state.

---

#### `resetFreq(itemId)`

Reset the draw frequency for a **specific item**.

* **Parameters:**

  * `itemId` *(string)* — Unique identifier of the item.
* **Throws:**

  * `TypeError` if `itemId` is not a string.

---

### ⚖️ Weight Computation

#### `computeEffectiveWeights(context = {})`

Compute the **effective weights** of all items after applying:

1. Base weights
2. Global modifiers
3. Temporary modifiers
4. Conditional rules
5. Pity system adjustments
6. Exclusions
7. Removal of zero or negative weights

* **Parameters:**

  * `context` *(object, optional)* — Includes:

    * `previousDraws` *(array)* — List of past draws.
    * `metadata` *(object)* — Arbitrary metadata for rules.
* **Returns:** `Map<string, number>` — Map of item ID → effective weight.
* **Throws:**

  * `TypeError` for invalid `context` format or property types.

---

#### `_weightsToDistribution(weights)`

Convert a **weights map** into a normalized **probability distribution array**.

* **Parameters:**

  * `weights` *(Map\<string, number>)* — Item IDs and their weights.
* **Returns:**
  An array of objects:

  ```ts
  {
    id: string,          // item ID
    weight: number,      // weight value
    p: number,           // normalized probability
    cumulative: number   // cumulative probability for sampling
  }
  ```
* **Throws:**

  * `TypeError` if `weights` is not a Map.
  * `TypeError` for invalid key or value types.
* **Notes:**

  * Supports **`softmax`** or **relative normalization**.

---

### 🎯 Drawing Items

#### `drawOne(opts = {})`

Draw **one item** from the raffle considering all configurations, rules, and pity effects.

* **Parameters:**

  * `opts` *(object, optional)*:

    * `previousDraws` *(array)* — Draw history for context.
    * `metadata` *(object)* — Metadata for conditional rules.
* **Returns:**
  An object:

  ```ts
  {
    id: string,         // item ID
    label: string,      // display label
    meta: object,       // cloned metadata
    prob: number        // probability at time of draw
  }
  ```

  Or `null` if no items are available.
* **Throws:** `TypeError` for invalid option types.
* **Effects:**

  * Updates **pity counters**.
  * Consumes **temporary modifiers**.
  * Increments **frequency counts**.
  * Emits a **`draw`** event.

---

#### `_consumeTemporaryModifiers()` *(private)*

Decrements usage counts of **temporary modifiers** and removes them when their uses reach zero.

---

#### `drawMany(count = 1, opts = {})`

Draw multiple items in one operation.

* **Parameters:**

  * `count` *(integer > 0)* — Number of items to draw.
  * `opts` *(object, optional)*:

    * `metadata` *(object)* — Metadata for rules.
    * `withReplacement` *(boolean, default = true)* — Allow duplicates.
    * `ensureUnique` *(boolean, default = false)* — Attempt to ensure unique results.
    * `previousDraws` *(array)* — History for context.
* **Returns:** `DrawOne[]` — List of drawn items.
* **Throws:**

  * `TypeError` for invalid `count` or option types.
* **Behavior Notes:**

  * **`withReplacement = false` & `ensureUnique = true`** → Items are temporarily excluded during the draw session.
  * **`withReplacement = false`** (without `ensureUnique`) → Items are excluded only for the session, then re-included.

---

### 📦 Save & Load (JSON)

#### 📤 `exportToJson()`

Exports the current configuration into a **JSON-serializable object**, capturing:

* **Items** (ID, label, base weight, metadata, groups)
* **Pity systems**
* **Exclusions**
* **Normalization mode**
* **Seed value**

This method is ideal for saving and restoring the raffle configuration between sessions.

**Returns**

* `ExportedJson` — An object containing the complete configuration.

---

#### 📥 `loadFromJson(data)`

Loads configuration data previously generated by [`exportToJson()`](#-exporttojson).

**Behavior**

* Clears all existing items and state.
* Validates all input fields for type safety and constraints.
* Reconstructs items, pity systems, exclusions, and normalization settings.
* Restores the seed value if provided.

**Parameters**

* `data` (`ExportedJson`) — The configuration to load.

**Throws**

* `TypeError` if `data` is missing required properties or contains invalid values.

---

### 🪞 `clone()`

Creates a **deep clone** of the current raffle instance.

**Features**

* Fully duplicates all internal **Maps**, **Sets**, and **Arrays** to prevent shared references.
* Functions (e.g., callbacks) are **copied by reference** since they are immutable.
* The clone is entirely **independent** from the original instance.

**Returns**

* `TinyAdvancedRaffle` — A new cloned instance with identical state.

---

### 🎲 RNG: Seedable (mulberry32)

#### 🔢 `_makeSeededRng(seed)`

Creates a **deterministic pseudo-random number generator (PRNG)** using the **mulberry32** algorithm.

**Parameters**

* `seed` (`number`) — An integer used to seed the PRNG.

**Returns**

* `RngGenerator` — A function that returns a pseudo-random number in the range `[0, 1)`.

**Throws**

* `TypeError` if `seed` is not a finite number.

---

## 🗑️ `destroy()`

Completely **wipes** all internal data, breaks all references, and renders the raffle instance permanently unusable.
After calling this method, **any further calls** to its functions will throw an error.

**Use Cases**

* Freeing memory in long-running applications.
* Preventing accidental reuse after the raffle is no longer needed.
* Security-sensitive scenarios where sensitive item data must be fully erased.

**Example**

```js
const raffle = new TinyAdvancedRaffle();
raffle.destroy();
raffle.clone(); // ❌ Throws an error: instance has been destroyed
```