elo-mmr-kit 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# elo-mmr-kit
+
+[![npm version](https://img.shields.io/npm/v/elo-mmr-kit.svg?style=flat-square)](https://www.npmjs.com/package/elo-mmr-kit)
+[![CI](https://github.com/Koval09/elo-mmr-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Koval09/elo-mmr-kit/actions)
+
+A zero-dependency, fully configurable Elo/MMR rating and matchmaking toolkit for games.
+It contains no hardcoded values and is completely stateless — storage is entirely your responsibility.
+
+## Installation
+
+```bash
+npm install elo-mmr-kit
+```
+
+## Quick Start
+
+```typescript
+import { calculateElo } from "elo-mmr-kit";
+
+const result = calculateElo({
+  playerA: { rating: 1500, gamesPlayed: 5 },
+  playerB: { rating: 1400, gamesPlayed: 12 },
+  outcome: "A", // "A" | "B" | "draw"
+  config: { kFactor: 32 }
+});
+
+console.log(result.playerA.rating); // 1512 (gained +12 rating)
+console.log(result.playerA.delta);  // 12
+```
+
+## Configuration Reference
+
+### `EloConfig` Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `kFactor` | `number` \| `Array<[number, number]>` \| `(p: PlayerState) => number` | **Required** | The K-factor value, a list of `[minGames, k]` threshold pairs, or a custom resolver function. |
+| `divisor` | `number` | `400` | The scale divisor for probability curves (higher = slower difference scaling). |
+| `minRating` | `number` | `0` | The rating floor. Calculated ratings will never drop below this floor. |
+| `maxRating` | `number` | `undefined` | The optional rating ceiling. Calculated ratings will never exceed this ceiling. |
+| `roundTo` | `"integer"` \| `"none"` | `"integer"` | Rounding method applied to ratings. `"integer"` uses standard rounding; `"none"` keeps floating decimals. |
+
+### Helper Functions
+
+*   `resolveKFactor(player: PlayerState, kFactor: number | KFactorTable | KFactorFn): number` — Resolves the K-factor value for a player based on their current rating/gamesPlayed state and configuration.
+
+---
+
+## Example: Telegram PvP game
+
+Here is a realistic example demonstrating custom K-factor tiers, seasonal soft resets, and matchmaking pool expansion:
+
+```typescript
+import {
+  calculateElo,
+  createKFactorTable,
+  softReset,
+  MatchmakingPool,
+  MatchmakingEntry
+} from "elo-mmr-kit";
+
+interface TelegramPlayer extends MatchmakingEntry {
+  username: string;
+  gamesPlayed: number;
+}
+
+// 1. Dynamic K-factors: [minGamesPlayed, kFactor]
+const kFactorResolver = createKFactorTable([
+  [0, 50],   // Placements / new players
+  [10, 30],  // Casual players
+  [50, 20],  // Experienced players
+  [100, 10]  // Veterans
+]);
+
+// 2. Seasonal Soft Reset (floor: 1200, scale factor: 0.5)
+const oldRating = 1600;
+const resetRating = softReset(oldRating, { floor: 1200, factor: 0.5 });
+console.log(resetRating); // 1400
+
+// 3. Matchmaking Queue (initial window 50, expands by 25 every 5 seconds)
+const queue = new MatchmakingPool<TelegramPlayer>({
+  initialWindow: 50,
+  expandBy: 25,
+  expandEveryMs: 5000
+});
+
+// Add players who joined at t = 0ms
+queue.add({ id: "1", rating: 1500, gamesPlayed: 5, joinedAt: 0, username: "alex" });
+queue.add({ id: "2", rating: 1580, gamesPlayed: 12, joinedAt: 0, username: "boris" });
+
+// At t = 0s, window is 50. Difference is 80, so they don't match
+console.log(queue.findMatch("1", 0)); // null
+
+// At t = 10s (10000ms), window expands to 50 + 2 * 25 = 100. They match!
+const opponent = queue.findMatch("1", 10000);
+console.log(opponent?.username); // "boris"
+
+if (opponent) {
+  queue.remove("1");
+  queue.remove(opponent.id);
+
+  // Update ratings after "alex" wins
+  const result = calculateElo({
+    playerA: { rating: 1500, gamesPlayed: 5 },
+    playerB: { rating: opponent.rating, gamesPlayed: opponent.gamesPlayed },
+    outcome: "A",
+    config: { kFactor: kFactorResolver, minRating: 1000 }
+  });
+  
+  console.log(result.playerA.rating); // 1531 (gained +31 rating)
+}
+```
+
+> [!NOTE]
+> **Matchmaking Asymmetry:** Matchmaking searches are directed and asymmetric. A player who has been waiting in the queue longer has a wider search window and can match with a newer player, while that newer player might not match with the older player yet. Always remove both players from the pool once a match is found from either player's perspective.
+
+---
+
+## FAQ
+
+### Why zero dependencies?
+To keep the toolkit extremely lightweight, secure, and fast. It compiles to tiny ESM and CommonJS bundles, running anywhere without bloating your `node_modules` — from edge environments (like Cloudflare Workers) to browsers and backend servers.
+
+### Where do I store ratings?
+Since all functions are pure and the matchmaking pool is an in-memory data structure, the library has no database connection or I/O operations. Persisting player ratings and queue states is entirely up to you. You can use PostgreSQL, Redis, MongoDB, Firebase, DynamoDB, or any storage engine of your choice.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,255 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MatchmakingPool: () => MatchmakingPool,
+  calculateElo: () => calculateElo,
+  createKFactorTable: () => createKFactorTable,
+  resolveKFactor: () => resolveKFactor,
+  softReset: () => softReset
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/kfactor.ts
+function createKFactorTable(tiers) {
+  if (tiers.length === 0) {
+    throw new Error("K-factor table must have at least one tier");
+  }
+  const sortedTiers = [...tiers].sort((a, b) => b[0] - a[0]);
+  return (player) => {
+    if (player.gamesPlayed === void 0) {
+      throw new Error("gamesPlayed is required when using a dynamic K-factor table");
+    }
+    for (const [minGames, k] of sortedTiers) {
+      if (player.gamesPlayed >= minGames) {
+        return k;
+      }
+    }
+    return sortedTiers[sortedTiers.length - 1][1];
+  };
+}
+
+// src/rating.ts
+function resolveKFactor(player, kFactor) {
+  if (typeof kFactor === "number") {
+    return kFactor;
+  }
+  if (player.gamesPlayed === void 0) {
+    throw new Error("gamesPlayed is required when using a dynamic K-factor");
+  }
+  if (typeof kFactor === "function") {
+    return kFactor(player);
+  }
+  if (Array.isArray(kFactor)) {
+    return createKFactorTable(kFactor)(player);
+  }
+  throw new Error("Invalid kFactor configuration");
+}
+function calculateElo(input) {
+  const { playerA, playerB, outcome, config } = input;
+  const divisor = config.divisor ?? 400;
+  if (divisor <= 0) {
+    throw new Error(`divisor must be greater than 0, received ${divisor}`);
+  }
+  const minRating = config.minRating ?? 0;
+  const maxRating = config.maxRating;
+  if (maxRating !== void 0 && minRating > maxRating) {
+    throw new Error(`minRating (${minRating}) cannot be greater than maxRating (${maxRating})`);
+  }
+  const roundTo = config.roundTo ?? "integer";
+  const expectedScoreA = 1 / (1 + Math.pow(10, (playerB.rating - playerA.rating) / divisor));
+  const expectedScoreB = 1 - expectedScoreA;
+  let scoreA = 0.5;
+  let scoreB = 0.5;
+  if (outcome === "A") {
+    scoreA = 1;
+    scoreB = 0;
+  } else if (outcome === "B") {
+    scoreA = 0;
+    scoreB = 1;
+  }
+  const kA = resolveKFactor(playerA, config.kFactor);
+  const kB = resolveKFactor(playerB, config.kFactor);
+  let rawNewA = playerA.rating + kA * (scoreA - expectedScoreA);
+  let rawNewB = playerB.rating + kB * (scoreB - expectedScoreB);
+  if (roundTo === "integer") {
+    rawNewA = Math.round(rawNewA);
+    rawNewB = Math.round(rawNewB);
+  }
+  if (rawNewA < minRating) rawNewA = minRating;
+  if (rawNewB < minRating) rawNewB = minRating;
+  if (maxRating !== void 0) {
+    if (rawNewA > maxRating) rawNewA = maxRating;
+    if (rawNewB > maxRating) rawNewB = maxRating;
+  }
+  if (rawNewA === 0) rawNewA = 0;
+  if (rawNewB === 0) rawNewB = 0;
+  let deltaA = rawNewA - playerA.rating;
+  let deltaB = rawNewB - playerB.rating;
+  if (deltaA === 0) deltaA = 0;
+  if (deltaB === 0) deltaB = 0;
+  return {
+    playerA: {
+      rating: rawNewA,
+      delta: deltaA
+    },
+    playerB: {
+      rating: rawNewB,
+      delta: deltaB
+    },
+    expectedScoreA
+  };
+}
+
+// src/season.ts
+function softReset(rating, options) {
+  if (typeof options === "function") {
+    return options(rating);
+  }
+  const { floor, factor } = options;
+  if (factor < 0 || factor > 1) {
+    throw new Error(`factor must be between 0 and 1, received ${factor}`);
+  }
+  const resetRating = floor + (rating - floor) * factor;
+  return Math.max(floor, resetRating);
+}
+
+// src/matchmaking.ts
+var MatchmakingPool = class {
+  pool = /* @__PURE__ */ new Map();
+  initialWindow;
+  expandBy;
+  expandEveryMs;
+  maxWindow;
+  /**
+   * Constructs a new MatchmakingPool.
+   * 
+   * @param config Configuration for the matchmaking pool window.
+   */
+  constructor(config) {
+    this.initialWindow = config.initialWindow;
+    this.expandBy = config.expandBy;
+    this.expandEveryMs = config.expandEveryMs;
+    this.maxWindow = config.maxWindow;
+  }
+  /**
+   * Adds a player to the matchmaking pool.
+   * If joinedAt is not provided, it defaults to the current timestamp.
+   * 
+   * @param entry The matchmaking entry to add.
+   */
+  add(entry) {
+    const joinedAt = entry.joinedAt ?? Date.now();
+    this.pool.set(entry.id, {
+      entry,
+      joinedAt
+    });
+  }
+  /**
+   * Removes a player from the matchmaking pool.
+   * 
+   * @param id The ID of the player to remove.
+   * @returns true if the player was found and removed, false otherwise.
+   */
+  remove(id) {
+    return this.pool.delete(id);
+  }
+  /**
+   * Finds the best opponent for a player within their current rating window.
+   * 
+   * The rating window expands over time based on wait time.
+   * The "best" opponent is defined as:
+   * 1. The opponent with the smallest rating difference.
+   * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).
+   * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.
+   * 
+   * This query is deterministic given the same inputs and does not modify the pool.
+   * 
+   * @param id The ID of the player searching for a match.
+   * @param now The current timestamp. Defaults to Date.now().
+   * @returns The best opponent entry, or null if no opponent is within the window.
+   */
+  findMatch(id, now) {
+    const wrapper = this.pool.get(id);
+    if (!wrapper) {
+      return null;
+    }
+    const player = wrapper.entry;
+    const currentNow = now ?? Date.now();
+    const waitTime = Math.max(0, currentNow - wrapper.joinedAt);
+    let windowSize = this.initialWindow;
+    if (this.expandEveryMs > 0) {
+      windowSize += Math.floor(waitTime / this.expandEveryMs) * this.expandBy;
+    }
+    if (this.maxWindow != null && windowSize > this.maxWindow) {
+      windowSize = this.maxWindow;
+    }
+    let bestOpponentWrapper = null;
+    let minDiff = Infinity;
+    for (const candidateWrapper of this.pool.values()) {
+      const candidate = candidateWrapper.entry;
+      if (candidate.id === id) {
+        continue;
+      }
+      const diff = Math.abs(candidate.rating - player.rating);
+      if (diff <= windowSize) {
+        if (diff < minDiff) {
+          minDiff = diff;
+          bestOpponentWrapper = candidateWrapper;
+        } else if (diff === minDiff && bestOpponentWrapper) {
+          const candidateJoinedAt = candidateWrapper.joinedAt;
+          const bestJoinedAt = bestOpponentWrapper.joinedAt;
+          if (candidateJoinedAt < bestJoinedAt) {
+            bestOpponentWrapper = candidateWrapper;
+          } else if (candidateJoinedAt === bestJoinedAt) {
+            if (candidate.id < bestOpponentWrapper.entry.id) {
+              bestOpponentWrapper = candidateWrapper;
+            }
+          }
+        }
+      }
+    }
+    return bestOpponentWrapper ? bestOpponentWrapper.entry : null;
+  }
+  /**
+   * Returns the current size of the matchmaking pool.
+   * 
+   * @returns The number of players in the pool.
+   */
+  size() {
+    return this.pool.size;
+  }
+  /**
+   * Clears all players from the matchmaking pool.
+   */
+  clear() {
+    this.pool.clear();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MatchmakingPool,
+  calculateElo,
+  createKFactorTable,
+  resolveKFactor,
+  softReset
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/kfactor.ts","../src/rating.ts","../src/season.ts","../src/matchmaking.ts"],"sourcesContent":["/**\n * elo-mmr-kit: A zero-dependency, fully configurable Elo/MMR rating and matchmaking toolkit.\n */\n\nexport { calculateElo, resolveKFactor } from \"./rating.js\";\nexport { createKFactorTable } from \"./kfactor.js\";\nexport { softReset } from \"./season.js\";\nexport { MatchmakingPool } from \"./matchmaking.js\";\n\n// Export types\nexport * from \"./types.js\";\n","import { PlayerState, KFactorTable, KFactorFn } from \"./types.js\";\n\n/**\n * Creates a helper function that resolves a K-factor based on a lookup table\n * of [minGames, kFactor] thresholds.\n * \n * @param tiers An array of [minGames, kFactor] tuples.\n * @returns A function that accepts a PlayerState and returns the resolved K-factor.\n */\nexport function createKFactorTable(tiers: KFactorTable): KFactorFn {\n  if (tiers.length === 0) {\n    throw new Error(\"K-factor table must have at least one tier\");\n  }\n\n  // Sort tiers descending by minGames threshold\n  const sortedTiers = [...tiers].sort((a, b) => b[0] - a[0]);\n\n  return (player: PlayerState): number => {\n    if (player.gamesPlayed === undefined) {\n      throw new Error(\"gamesPlayed is required when using a dynamic K-factor table\");\n    }\n    for (const [minGames, k] of sortedTiers) {\n      if (player.gamesPlayed >= minGames) {\n        return k;\n      }\n    }\n    // Default to the tier with the lowest minGames threshold if none match\n    // (Usually this is the 0 threshold tier)\n    return sortedTiers[sortedTiers.length - 1][1];\n  };\n}\n","import { CalculateEloInput, CalculateEloResult, PlayerState, KFactorTable, KFactorFn } from \"./types.js\";\nimport { createKFactorTable } from \"./kfactor.js\";\n\n/**\n * Resolves the K-factor for a player based on the config.\n * \n * @param player The player state containing rating and gamesPlayed.\n * @param kFactor The K-factor configuration (number, lookup table, or custom function).\n * @returns The resolved K-factor as a number.\n */\nexport function resolveKFactor(\n  player: PlayerState,\n  kFactor: number | KFactorTable | KFactorFn\n): number {\n  if (typeof kFactor === \"number\") {\n    return kFactor;\n  }\n  if (player.gamesPlayed === undefined) {\n    throw new Error(\"gamesPlayed is required when using a dynamic K-factor\");\n  }\n  if (typeof kFactor === \"function\") {\n    return kFactor(player);\n  }\n  if (Array.isArray(kFactor)) {\n    return createKFactorTable(kFactor)(player);\n  }\n  throw new Error(\"Invalid kFactor configuration\");\n}\n\n/**\n * Calculates new Elo ratings for two players after a match outcome.\n * This function is pure and stateless.\n * \n * @param input The match outcome and configuration details.\n * @returns The new ratings, rating changes, and the expected score of player A.\n */\nexport function calculateElo(input: CalculateEloInput): CalculateEloResult {\n  const { playerA, playerB, outcome, config } = input;\n\n  const divisor = config.divisor ?? 400;\n  if (divisor <= 0) {\n    throw new Error(`divisor must be greater than 0, received ${divisor}`);\n  }\n\n  const minRating = config.minRating ?? 0;\n  const maxRating = config.maxRating;\n\n  if (maxRating !== undefined && minRating > maxRating) {\n    throw new Error(`minRating (${minRating}) cannot be greater than maxRating (${maxRating})`);\n  }\n\n  const roundTo = config.roundTo ?? \"integer\";\n\n  // Calculate expected scores\n  const expectedScoreA = 1 / (1 + Math.pow(10, (playerB.rating - playerA.rating) / divisor));\n  const expectedScoreB = 1 - expectedScoreA;\n\n  // Map outcome to actual scores\n  let scoreA = 0.5;\n  let scoreB = 0.5;\n  if (outcome === \"A\") {\n    scoreA = 1;\n    scoreB = 0;\n  } else if (outcome === \"B\") {\n    scoreA = 0;\n    scoreB = 1;\n  }\n\n  // Resolve K-factors\n  const kA = resolveKFactor(playerA, config.kFactor);\n  const kB = resolveKFactor(playerB, config.kFactor);\n\n  // Compute raw new ratings\n  let rawNewA = playerA.rating + kA * (scoreA - expectedScoreA);\n  let rawNewB = playerB.rating + kB * (scoreB - expectedScoreB);\n\n  // Apply rounding\n  if (roundTo === \"integer\") {\n    rawNewA = Math.round(rawNewA);\n    rawNewB = Math.round(rawNewB);\n  }\n\n  // Apply minRating floor\n  if (rawNewA < minRating) rawNewA = minRating;\n  if (rawNewB < minRating) rawNewB = minRating;\n\n  // Apply maxRating ceiling if configured\n  if (maxRating !== undefined) {\n    if (rawNewA > maxRating) rawNewA = maxRating;\n    if (rawNewB > maxRating) rawNewB = maxRating;\n  }\n\n  // Normalize -0 to +0\n  if (rawNewA === 0) rawNewA = 0;\n  if (rawNewB === 0) rawNewB = 0;\n\n  let deltaA = rawNewA - playerA.rating;\n  let deltaB = rawNewB - playerB.rating;\n\n  if (deltaA === 0) deltaA = 0;\n  if (deltaB === 0) deltaB = 0;\n\n  return {\n    playerA: {\n      rating: rawNewA,\n      delta: deltaA,\n    },\n    playerB: {\n      rating: rawNewB,\n      delta: deltaB,\n    },\n    expectedScoreA,\n  };\n}\n","import { SoftResetOptions, SoftResetFn } from \"./types.js\";\n\n/**\n * Performs a seasonal soft reset on a player's rating.\n * \n * If a config object is provided, computes: floor + (rating - floor) * factor.\n * The resulting rating will never go below the specified floor.\n * \n * Alternatively, a custom reset function can be passed.\n * \n * @param rating The current rating of the player.\n * @param options A SoftResetOptions object containing floor and factor, or a custom reset function.\n * @returns The reset rating.\n */\nexport function softReset(\n  rating: number,\n  options: SoftResetOptions | SoftResetFn\n): number {\n  if (typeof options === \"function\") {\n    return options(rating);\n  }\n\n  const { floor, factor } = options;\n  if (factor < 0 || factor > 1) {\n    throw new Error(`factor must be between 0 and 1, received ${factor}`);\n  }\n  const resetRating = floor + (rating - floor) * factor;\n  return Math.max(floor, resetRating);\n}\n","import { MatchmakingPoolConfig, MatchmakingEntry } from \"./types.js\";\n\n/**\n * An in-memory matchmaking pool that is generic over the user's player type.\n * It allows adding, removing, and finding matches for players based on their rating\n * and a waiting window that expands over time.\n */\nexport class MatchmakingPool<T extends MatchmakingEntry = MatchmakingEntry> {\n  private pool: Map<string, { entry: T; joinedAt: number }> = new Map();\n  private initialWindow: number;\n  private expandBy: number;\n  private expandEveryMs: number;\n  private maxWindow?: number;\n\n  /**\n   * Constructs a new MatchmakingPool.\n   * \n   * @param config Configuration for the matchmaking pool window.\n   */\n  constructor(config: MatchmakingPoolConfig) {\n    this.initialWindow = config.initialWindow;\n    this.expandBy = config.expandBy;\n    this.expandEveryMs = config.expandEveryMs;\n    this.maxWindow = config.maxWindow;\n  }\n\n  /**\n   * Adds a player to the matchmaking pool.\n   * If joinedAt is not provided, it defaults to the current timestamp.\n   * \n   * @param entry The matchmaking entry to add.\n   */\n  add(entry: T): void {\n    const joinedAt = entry.joinedAt ?? Date.now();\n    this.pool.set(entry.id, {\n      entry,\n      joinedAt,\n    });\n  }\n\n  /**\n   * Removes a player from the matchmaking pool.\n   * \n   * @param id The ID of the player to remove.\n   * @returns true if the player was found and removed, false otherwise.\n   */\n  remove(id: string): boolean {\n    return this.pool.delete(id);\n  }\n\n  /**\n   * Finds the best opponent for a player within their current rating window.\n   * \n   * The rating window expands over time based on wait time.\n   * The \"best\" opponent is defined as:\n   * 1. The opponent with the smallest rating difference.\n   * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).\n   * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.\n   * \n   * This query is deterministic given the same inputs and does not modify the pool.\n   * \n   * @param id The ID of the player searching for a match.\n   * @param now The current timestamp. Defaults to Date.now().\n   * @returns The best opponent entry, or null if no opponent is within the window.\n   */\n  findMatch(id: string, now?: number): T | null {\n    const wrapper = this.pool.get(id);\n    if (!wrapper) {\n      return null;\n    }\n    const player = wrapper.entry;\n\n    const currentNow = now ?? Date.now();\n    const waitTime = Math.max(0, currentNow - wrapper.joinedAt);\n\n    // Calculate expanding search window\n    let windowSize = this.initialWindow;\n    if (this.expandEveryMs > 0) {\n      windowSize += Math.floor(waitTime / this.expandEveryMs) * this.expandBy;\n    }\n    if (this.maxWindow != null && windowSize > this.maxWindow) {\n      windowSize = this.maxWindow;\n    }\n\n    let bestOpponentWrapper: { entry: T; joinedAt: number } | null = null;\n    let minDiff = Infinity;\n\n    for (const candidateWrapper of this.pool.values()) {\n      const candidate = candidateWrapper.entry;\n      if (candidate.id === id) {\n        continue;\n      }\n\n      const diff = Math.abs(candidate.rating - player.rating);\n      if (diff <= windowSize) {\n        if (diff < minDiff) {\n          minDiff = diff;\n          bestOpponentWrapper = candidateWrapper;\n        } else if (diff === minDiff && bestOpponentWrapper) {\n          // Tie-breaker 1: longest waiting time (earliest joinedAt)\n          const candidateJoinedAt = candidateWrapper.joinedAt;\n          const bestJoinedAt = bestOpponentWrapper.joinedAt;\n\n          if (candidateJoinedAt < bestJoinedAt) {\n            bestOpponentWrapper = candidateWrapper;\n          } else if (candidateJoinedAt === bestJoinedAt) {\n            // Tie-breaker 2: lexicographical order of id\n            if (candidate.id < bestOpponentWrapper.entry.id) {\n              bestOpponentWrapper = candidateWrapper;\n            }\n          }\n        }\n      }\n    }\n\n    return bestOpponentWrapper ? bestOpponentWrapper.entry : null;\n  }\n\n  /**\n   * Returns the current size of the matchmaking pool.\n   * \n   * @returns The number of players in the pool.\n   */\n  size(): number {\n    return this.pool.size;\n  }\n\n  /**\n   * Clears all players from the matchmaking pool.\n   */\n  clear(): void {\n    this.pool.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,145 @@
+interface PlayerState {
+    rating: number;
+    gamesPlayed?: number;
+}
+type KFactorFn = (player: PlayerState) => number;
+type KFactorTable = Array<[minGames: number, k: number]>;
+interface EloConfig {
+    kFactor: number | KFactorTable | KFactorFn;
+    divisor?: number;
+    minRating?: number;
+    maxRating?: number;
+    roundTo?: "integer" | "none";
+}
+interface CalculateEloInput {
+    playerA: PlayerState;
+    playerB: PlayerState;
+    outcome: "A" | "B" | "draw";
+    config: EloConfig;
+}
+interface PlayerResult {
+    rating: number;
+    delta: number;
+}
+interface CalculateEloResult {
+    playerA: PlayerResult;
+    playerB: PlayerResult;
+    expectedScoreA: number;
+}
+interface SoftResetOptions {
+    floor: number;
+    factor: number;
+}
+type SoftResetFn = (rating: number) => number;
+interface MatchmakingPoolConfig {
+    initialWindow: number;
+    expandBy: number;
+    expandEveryMs: number;
+    maxWindow?: number;
+}
+interface MatchmakingEntry {
+    id: string;
+    rating: number;
+    joinedAt?: number;
+}
+
+/**
+ * Resolves the K-factor for a player based on the config.
+ *
+ * @param player The player state containing rating and gamesPlayed.
+ * @param kFactor The K-factor configuration (number, lookup table, or custom function).
+ * @returns The resolved K-factor as a number.
+ */
+declare function resolveKFactor(player: PlayerState, kFactor: number | KFactorTable | KFactorFn): number;
+/**
+ * Calculates new Elo ratings for two players after a match outcome.
+ * This function is pure and stateless.
+ *
+ * @param input The match outcome and configuration details.
+ * @returns The new ratings, rating changes, and the expected score of player A.
+ */
+declare function calculateElo(input: CalculateEloInput): CalculateEloResult;
+
+/**
+ * Creates a helper function that resolves a K-factor based on a lookup table
+ * of [minGames, kFactor] thresholds.
+ *
+ * @param tiers An array of [minGames, kFactor] tuples.
+ * @returns A function that accepts a PlayerState and returns the resolved K-factor.
+ */
+declare function createKFactorTable(tiers: KFactorTable): KFactorFn;
+
+/**
+ * Performs a seasonal soft reset on a player's rating.
+ *
+ * If a config object is provided, computes: floor + (rating - floor) * factor.
+ * The resulting rating will never go below the specified floor.
+ *
+ * Alternatively, a custom reset function can be passed.
+ *
+ * @param rating The current rating of the player.
+ * @param options A SoftResetOptions object containing floor and factor, or a custom reset function.
+ * @returns The reset rating.
+ */
+declare function softReset(rating: number, options: SoftResetOptions | SoftResetFn): number;
+
+/**
+ * An in-memory matchmaking pool that is generic over the user's player type.
+ * It allows adding, removing, and finding matches for players based on their rating
+ * and a waiting window that expands over time.
+ */
+declare class MatchmakingPool<T extends MatchmakingEntry = MatchmakingEntry> {
+    private pool;
+    private initialWindow;
+    private expandBy;
+    private expandEveryMs;
+    private maxWindow?;
+    /**
+     * Constructs a new MatchmakingPool.
+     *
+     * @param config Configuration for the matchmaking pool window.
+     */
+    constructor(config: MatchmakingPoolConfig);
+    /**
+     * Adds a player to the matchmaking pool.
+     * If joinedAt is not provided, it defaults to the current timestamp.
+     *
+     * @param entry The matchmaking entry to add.
+     */
+    add(entry: T): void;
+    /**
+     * Removes a player from the matchmaking pool.
+     *
+     * @param id The ID of the player to remove.
+     * @returns true if the player was found and removed, false otherwise.
+     */
+    remove(id: string): boolean;
+    /**
+     * Finds the best opponent for a player within their current rating window.
+     *
+     * The rating window expands over time based on wait time.
+     * The "best" opponent is defined as:
+     * 1. The opponent with the smallest rating difference.
+     * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).
+     * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.
+     *
+     * This query is deterministic given the same inputs and does not modify the pool.
+     *
+     * @param id The ID of the player searching for a match.
+     * @param now The current timestamp. Defaults to Date.now().
+     * @returns The best opponent entry, or null if no opponent is within the window.
+     */
+    findMatch(id: string, now?: number): T | null;
+    /**
+     * Returns the current size of the matchmaking pool.
+     *
+     * @returns The number of players in the pool.
+     */
+    size(): number;
+    /**
+     * Clears all players from the matchmaking pool.
+     */
+    clear(): void;
+}
+
+export { type CalculateEloInput, type CalculateEloResult, type EloConfig, type KFactorFn, type KFactorTable, type MatchmakingEntry, MatchmakingPool, type MatchmakingPoolConfig, type PlayerResult, type PlayerState, type SoftResetFn, type SoftResetOptions, calculateElo, createKFactorTable, resolveKFactor, softReset };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+interface PlayerState {
+    rating: number;
+    gamesPlayed?: number;
+}
+type KFactorFn = (player: PlayerState) => number;
+type KFactorTable = Array<[minGames: number, k: number]>;
+interface EloConfig {
+    kFactor: number | KFactorTable | KFactorFn;
+    divisor?: number;
+    minRating?: number;
+    maxRating?: number;
+    roundTo?: "integer" | "none";
+}
+interface CalculateEloInput {
+    playerA: PlayerState;
+    playerB: PlayerState;
+    outcome: "A" | "B" | "draw";
+    config: EloConfig;
+}
+interface PlayerResult {
+    rating: number;
+    delta: number;
+}
+interface CalculateEloResult {
+    playerA: PlayerResult;
+    playerB: PlayerResult;
+    expectedScoreA: number;
+}
+interface SoftResetOptions {
+    floor: number;
+    factor: number;
+}
+type SoftResetFn = (rating: number) => number;
+interface MatchmakingPoolConfig {
+    initialWindow: number;
+    expandBy: number;
+    expandEveryMs: number;
+    maxWindow?: number;
+}
+interface MatchmakingEntry {
+    id: string;
+    rating: number;
+    joinedAt?: number;
+}
+
+/**
+ * Resolves the K-factor for a player based on the config.
+ *
+ * @param player The player state containing rating and gamesPlayed.
+ * @param kFactor The K-factor configuration (number, lookup table, or custom function).
+ * @returns The resolved K-factor as a number.
+ */
+declare function resolveKFactor(player: PlayerState, kFactor: number | KFactorTable | KFactorFn): number;
+/**
+ * Calculates new Elo ratings for two players after a match outcome.
+ * This function is pure and stateless.
+ *
+ * @param input The match outcome and configuration details.
+ * @returns The new ratings, rating changes, and the expected score of player A.
+ */
+declare function calculateElo(input: CalculateEloInput): CalculateEloResult;
+
+/**
+ * Creates a helper function that resolves a K-factor based on a lookup table
+ * of [minGames, kFactor] thresholds.
+ *
+ * @param tiers An array of [minGames, kFactor] tuples.
+ * @returns A function that accepts a PlayerState and returns the resolved K-factor.
+ */
+declare function createKFactorTable(tiers: KFactorTable): KFactorFn;
+
+/**
+ * Performs a seasonal soft reset on a player's rating.
+ *
+ * If a config object is provided, computes: floor + (rating - floor) * factor.
+ * The resulting rating will never go below the specified floor.
+ *
+ * Alternatively, a custom reset function can be passed.
+ *
+ * @param rating The current rating of the player.
+ * @param options A SoftResetOptions object containing floor and factor, or a custom reset function.
+ * @returns The reset rating.
+ */
+declare function softReset(rating: number, options: SoftResetOptions | SoftResetFn): number;
+
+/**
+ * An in-memory matchmaking pool that is generic over the user's player type.
+ * It allows adding, removing, and finding matches for players based on their rating
+ * and a waiting window that expands over time.
+ */
+declare class MatchmakingPool<T extends MatchmakingEntry = MatchmakingEntry> {
+    private pool;
+    private initialWindow;
+    private expandBy;
+    private expandEveryMs;
+    private maxWindow?;
+    /**
+     * Constructs a new MatchmakingPool.
+     *
+     * @param config Configuration for the matchmaking pool window.
+     */
+    constructor(config: MatchmakingPoolConfig);
+    /**
+     * Adds a player to the matchmaking pool.
+     * If joinedAt is not provided, it defaults to the current timestamp.
+     *
+     * @param entry The matchmaking entry to add.
+     */
+    add(entry: T): void;
+    /**
+     * Removes a player from the matchmaking pool.
+     *
+     * @param id The ID of the player to remove.
+     * @returns true if the player was found and removed, false otherwise.
+     */
+    remove(id: string): boolean;
+    /**
+     * Finds the best opponent for a player within their current rating window.
+     *
+     * The rating window expands over time based on wait time.
+     * The "best" opponent is defined as:
+     * 1. The opponent with the smallest rating difference.
+     * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).
+     * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.
+     *
+     * This query is deterministic given the same inputs and does not modify the pool.
+     *
+     * @param id The ID of the player searching for a match.
+     * @param now The current timestamp. Defaults to Date.now().
+     * @returns The best opponent entry, or null if no opponent is within the window.
+     */
+    findMatch(id: string, now?: number): T | null;
+    /**
+     * Returns the current size of the matchmaking pool.
+     *
+     * @returns The number of players in the pool.
+     */
+    size(): number;
+    /**
+     * Clears all players from the matchmaking pool.
+     */
+    clear(): void;
+}
+
+export { type CalculateEloInput, type CalculateEloResult, type EloConfig, type KFactorFn, type KFactorTable, type MatchmakingEntry, MatchmakingPool, type MatchmakingPoolConfig, type PlayerResult, type PlayerState, type SoftResetFn, type SoftResetOptions, calculateElo, createKFactorTable, resolveKFactor, softReset };

package/dist/index.js

@@ -0,0 +1,224 @@
+// src/kfactor.ts
+function createKFactorTable(tiers) {
+  if (tiers.length === 0) {
+    throw new Error("K-factor table must have at least one tier");
+  }
+  const sortedTiers = [...tiers].sort((a, b) => b[0] - a[0]);
+  return (player) => {
+    if (player.gamesPlayed === void 0) {
+      throw new Error("gamesPlayed is required when using a dynamic K-factor table");
+    }
+    for (const [minGames, k] of sortedTiers) {
+      if (player.gamesPlayed >= minGames) {
+        return k;
+      }
+    }
+    return sortedTiers[sortedTiers.length - 1][1];
+  };
+}
+
+// src/rating.ts
+function resolveKFactor(player, kFactor) {
+  if (typeof kFactor === "number") {
+    return kFactor;
+  }
+  if (player.gamesPlayed === void 0) {
+    throw new Error("gamesPlayed is required when using a dynamic K-factor");
+  }
+  if (typeof kFactor === "function") {
+    return kFactor(player);
+  }
+  if (Array.isArray(kFactor)) {
+    return createKFactorTable(kFactor)(player);
+  }
+  throw new Error("Invalid kFactor configuration");
+}
+function calculateElo(input) {
+  const { playerA, playerB, outcome, config } = input;
+  const divisor = config.divisor ?? 400;
+  if (divisor <= 0) {
+    throw new Error(`divisor must be greater than 0, received ${divisor}`);
+  }
+  const minRating = config.minRating ?? 0;
+  const maxRating = config.maxRating;
+  if (maxRating !== void 0 && minRating > maxRating) {
+    throw new Error(`minRating (${minRating}) cannot be greater than maxRating (${maxRating})`);
+  }
+  const roundTo = config.roundTo ?? "integer";
+  const expectedScoreA = 1 / (1 + Math.pow(10, (playerB.rating - playerA.rating) / divisor));
+  const expectedScoreB = 1 - expectedScoreA;
+  let scoreA = 0.5;
+  let scoreB = 0.5;
+  if (outcome === "A") {
+    scoreA = 1;
+    scoreB = 0;
+  } else if (outcome === "B") {
+    scoreA = 0;
+    scoreB = 1;
+  }
+  const kA = resolveKFactor(playerA, config.kFactor);
+  const kB = resolveKFactor(playerB, config.kFactor);
+  let rawNewA = playerA.rating + kA * (scoreA - expectedScoreA);
+  let rawNewB = playerB.rating + kB * (scoreB - expectedScoreB);
+  if (roundTo === "integer") {
+    rawNewA = Math.round(rawNewA);
+    rawNewB = Math.round(rawNewB);
+  }
+  if (rawNewA < minRating) rawNewA = minRating;
+  if (rawNewB < minRating) rawNewB = minRating;
+  if (maxRating !== void 0) {
+    if (rawNewA > maxRating) rawNewA = maxRating;
+    if (rawNewB > maxRating) rawNewB = maxRating;
+  }
+  if (rawNewA === 0) rawNewA = 0;
+  if (rawNewB === 0) rawNewB = 0;
+  let deltaA = rawNewA - playerA.rating;
+  let deltaB = rawNewB - playerB.rating;
+  if (deltaA === 0) deltaA = 0;
+  if (deltaB === 0) deltaB = 0;
+  return {
+    playerA: {
+      rating: rawNewA,
+      delta: deltaA
+    },
+    playerB: {
+      rating: rawNewB,
+      delta: deltaB
+    },
+    expectedScoreA
+  };
+}
+
+// src/season.ts
+function softReset(rating, options) {
+  if (typeof options === "function") {
+    return options(rating);
+  }
+  const { floor, factor } = options;
+  if (factor < 0 || factor > 1) {
+    throw new Error(`factor must be between 0 and 1, received ${factor}`);
+  }
+  const resetRating = floor + (rating - floor) * factor;
+  return Math.max(floor, resetRating);
+}
+
+// src/matchmaking.ts
+var MatchmakingPool = class {
+  pool = /* @__PURE__ */ new Map();
+  initialWindow;
+  expandBy;
+  expandEveryMs;
+  maxWindow;
+  /**
+   * Constructs a new MatchmakingPool.
+   * 
+   * @param config Configuration for the matchmaking pool window.
+   */
+  constructor(config) {
+    this.initialWindow = config.initialWindow;
+    this.expandBy = config.expandBy;
+    this.expandEveryMs = config.expandEveryMs;
+    this.maxWindow = config.maxWindow;
+  }
+  /**
+   * Adds a player to the matchmaking pool.
+   * If joinedAt is not provided, it defaults to the current timestamp.
+   * 
+   * @param entry The matchmaking entry to add.
+   */
+  add(entry) {
+    const joinedAt = entry.joinedAt ?? Date.now();
+    this.pool.set(entry.id, {
+      entry,
+      joinedAt
+    });
+  }
+  /**
+   * Removes a player from the matchmaking pool.
+   * 
+   * @param id The ID of the player to remove.
+   * @returns true if the player was found and removed, false otherwise.
+   */
+  remove(id) {
+    return this.pool.delete(id);
+  }
+  /**
+   * Finds the best opponent for a player within their current rating window.
+   * 
+   * The rating window expands over time based on wait time.
+   * The "best" opponent is defined as:
+   * 1. The opponent with the smallest rating difference.
+   * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).
+   * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.
+   * 
+   * This query is deterministic given the same inputs and does not modify the pool.
+   * 
+   * @param id The ID of the player searching for a match.
+   * @param now The current timestamp. Defaults to Date.now().
+   * @returns The best opponent entry, or null if no opponent is within the window.
+   */
+  findMatch(id, now) {
+    const wrapper = this.pool.get(id);
+    if (!wrapper) {
+      return null;
+    }
+    const player = wrapper.entry;
+    const currentNow = now ?? Date.now();
+    const waitTime = Math.max(0, currentNow - wrapper.joinedAt);
+    let windowSize = this.initialWindow;
+    if (this.expandEveryMs > 0) {
+      windowSize += Math.floor(waitTime / this.expandEveryMs) * this.expandBy;
+    }
+    if (this.maxWindow != null && windowSize > this.maxWindow) {
+      windowSize = this.maxWindow;
+    }
+    let bestOpponentWrapper = null;
+    let minDiff = Infinity;
+    for (const candidateWrapper of this.pool.values()) {
+      const candidate = candidateWrapper.entry;
+      if (candidate.id === id) {
+        continue;
+      }
+      const diff = Math.abs(candidate.rating - player.rating);
+      if (diff <= windowSize) {
+        if (diff < minDiff) {
+          minDiff = diff;
+          bestOpponentWrapper = candidateWrapper;
+        } else if (diff === minDiff && bestOpponentWrapper) {
+          const candidateJoinedAt = candidateWrapper.joinedAt;
+          const bestJoinedAt = bestOpponentWrapper.joinedAt;
+          if (candidateJoinedAt < bestJoinedAt) {
+            bestOpponentWrapper = candidateWrapper;
+          } else if (candidateJoinedAt === bestJoinedAt) {
+            if (candidate.id < bestOpponentWrapper.entry.id) {
+              bestOpponentWrapper = candidateWrapper;
+            }
+          }
+        }
+      }
+    }
+    return bestOpponentWrapper ? bestOpponentWrapper.entry : null;
+  }
+  /**
+   * Returns the current size of the matchmaking pool.
+   * 
+   * @returns The number of players in the pool.
+   */
+  size() {
+    return this.pool.size;
+  }
+  /**
+   * Clears all players from the matchmaking pool.
+   */
+  clear() {
+    this.pool.clear();
+  }
+};
+export {
+  MatchmakingPool,
+  calculateElo,
+  createKFactorTable,
+  resolveKFactor,
+  softReset
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kfactor.ts","../src/rating.ts","../src/season.ts","../src/matchmaking.ts"],"sourcesContent":["import { PlayerState, KFactorTable, KFactorFn } from \"./types.js\";\n\n/**\n * Creates a helper function that resolves a K-factor based on a lookup table\n * of [minGames, kFactor] thresholds.\n * \n * @param tiers An array of [minGames, kFactor] tuples.\n * @returns A function that accepts a PlayerState and returns the resolved K-factor.\n */\nexport function createKFactorTable(tiers: KFactorTable): KFactorFn {\n  if (tiers.length === 0) {\n    throw new Error(\"K-factor table must have at least one tier\");\n  }\n\n  // Sort tiers descending by minGames threshold\n  const sortedTiers = [...tiers].sort((a, b) => b[0] - a[0]);\n\n  return (player: PlayerState): number => {\n    if (player.gamesPlayed === undefined) {\n      throw new Error(\"gamesPlayed is required when using a dynamic K-factor table\");\n    }\n    for (const [minGames, k] of sortedTiers) {\n      if (player.gamesPlayed >= minGames) {\n        return k;\n      }\n    }\n    // Default to the tier with the lowest minGames threshold if none match\n    // (Usually this is the 0 threshold tier)\n    return sortedTiers[sortedTiers.length - 1][1];\n  };\n}\n","import { CalculateEloInput, CalculateEloResult, PlayerState, KFactorTable, KFactorFn } from \"./types.js\";\nimport { createKFactorTable } from \"./kfactor.js\";\n\n/**\n * Resolves the K-factor for a player based on the config.\n * \n * @param player The player state containing rating and gamesPlayed.\n * @param kFactor The K-factor configuration (number, lookup table, or custom function).\n * @returns The resolved K-factor as a number.\n */\nexport function resolveKFactor(\n  player: PlayerState,\n  kFactor: number | KFactorTable | KFactorFn\n): number {\n  if (typeof kFactor === \"number\") {\n    return kFactor;\n  }\n  if (player.gamesPlayed === undefined) {\n    throw new Error(\"gamesPlayed is required when using a dynamic K-factor\");\n  }\n  if (typeof kFactor === \"function\") {\n    return kFactor(player);\n  }\n  if (Array.isArray(kFactor)) {\n    return createKFactorTable(kFactor)(player);\n  }\n  throw new Error(\"Invalid kFactor configuration\");\n}\n\n/**\n * Calculates new Elo ratings for two players after a match outcome.\n * This function is pure and stateless.\n * \n * @param input The match outcome and configuration details.\n * @returns The new ratings, rating changes, and the expected score of player A.\n */\nexport function calculateElo(input: CalculateEloInput): CalculateEloResult {\n  const { playerA, playerB, outcome, config } = input;\n\n  const divisor = config.divisor ?? 400;\n  if (divisor <= 0) {\n    throw new Error(`divisor must be greater than 0, received ${divisor}`);\n  }\n\n  const minRating = config.minRating ?? 0;\n  const maxRating = config.maxRating;\n\n  if (maxRating !== undefined && minRating > maxRating) {\n    throw new Error(`minRating (${minRating}) cannot be greater than maxRating (${maxRating})`);\n  }\n\n  const roundTo = config.roundTo ?? \"integer\";\n\n  // Calculate expected scores\n  const expectedScoreA = 1 / (1 + Math.pow(10, (playerB.rating - playerA.rating) / divisor));\n  const expectedScoreB = 1 - expectedScoreA;\n\n  // Map outcome to actual scores\n  let scoreA = 0.5;\n  let scoreB = 0.5;\n  if (outcome === \"A\") {\n    scoreA = 1;\n    scoreB = 0;\n  } else if (outcome === \"B\") {\n    scoreA = 0;\n    scoreB = 1;\n  }\n\n  // Resolve K-factors\n  const kA = resolveKFactor(playerA, config.kFactor);\n  const kB = resolveKFactor(playerB, config.kFactor);\n\n  // Compute raw new ratings\n  let rawNewA = playerA.rating + kA * (scoreA - expectedScoreA);\n  let rawNewB = playerB.rating + kB * (scoreB - expectedScoreB);\n\n  // Apply rounding\n  if (roundTo === \"integer\") {\n    rawNewA = Math.round(rawNewA);\n    rawNewB = Math.round(rawNewB);\n  }\n\n  // Apply minRating floor\n  if (rawNewA < minRating) rawNewA = minRating;\n  if (rawNewB < minRating) rawNewB = minRating;\n\n  // Apply maxRating ceiling if configured\n  if (maxRating !== undefined) {\n    if (rawNewA > maxRating) rawNewA = maxRating;\n    if (rawNewB > maxRating) rawNewB = maxRating;\n  }\n\n  // Normalize -0 to +0\n  if (rawNewA === 0) rawNewA = 0;\n  if (rawNewB === 0) rawNewB = 0;\n\n  let deltaA = rawNewA - playerA.rating;\n  let deltaB = rawNewB - playerB.rating;\n\n  if (deltaA === 0) deltaA = 0;\n  if (deltaB === 0) deltaB = 0;\n\n  return {\n    playerA: {\n      rating: rawNewA,\n      delta: deltaA,\n    },\n    playerB: {\n      rating: rawNewB,\n      delta: deltaB,\n    },\n    expectedScoreA,\n  };\n}\n","import { SoftResetOptions, SoftResetFn } from \"./types.js\";\n\n/**\n * Performs a seasonal soft reset on a player's rating.\n * \n * If a config object is provided, computes: floor + (rating - floor) * factor.\n * The resulting rating will never go below the specified floor.\n * \n * Alternatively, a custom reset function can be passed.\n * \n * @param rating The current rating of the player.\n * @param options A SoftResetOptions object containing floor and factor, or a custom reset function.\n * @returns The reset rating.\n */\nexport function softReset(\n  rating: number,\n  options: SoftResetOptions | SoftResetFn\n): number {\n  if (typeof options === \"function\") {\n    return options(rating);\n  }\n\n  const { floor, factor } = options;\n  if (factor < 0 || factor > 1) {\n    throw new Error(`factor must be between 0 and 1, received ${factor}`);\n  }\n  const resetRating = floor + (rating - floor) * factor;\n  return Math.max(floor, resetRating);\n}\n","import { MatchmakingPoolConfig, MatchmakingEntry } from \"./types.js\";\n\n/**\n * An in-memory matchmaking pool that is generic over the user's player type.\n * It allows adding, removing, and finding matches for players based on their rating\n * and a waiting window that expands over time.\n */\nexport class MatchmakingPool<T extends MatchmakingEntry = MatchmakingEntry> {\n  private pool: Map<string, { entry: T; joinedAt: number }> = new Map();\n  private initialWindow: number;\n  private expandBy: number;\n  private expandEveryMs: number;\n  private maxWindow?: number;\n\n  /**\n   * Constructs a new MatchmakingPool.\n   * \n   * @param config Configuration for the matchmaking pool window.\n   */\n  constructor(config: MatchmakingPoolConfig) {\n    this.initialWindow = config.initialWindow;\n    this.expandBy = config.expandBy;\n    this.expandEveryMs = config.expandEveryMs;\n    this.maxWindow = config.maxWindow;\n  }\n\n  /**\n   * Adds a player to the matchmaking pool.\n   * If joinedAt is not provided, it defaults to the current timestamp.\n   * \n   * @param entry The matchmaking entry to add.\n   */\n  add(entry: T): void {\n    const joinedAt = entry.joinedAt ?? Date.now();\n    this.pool.set(entry.id, {\n      entry,\n      joinedAt,\n    });\n  }\n\n  /**\n   * Removes a player from the matchmaking pool.\n   * \n   * @param id The ID of the player to remove.\n   * @returns true if the player was found and removed, false otherwise.\n   */\n  remove(id: string): boolean {\n    return this.pool.delete(id);\n  }\n\n  /**\n   * Finds the best opponent for a player within their current rating window.\n   * \n   * The rating window expands over time based on wait time.\n   * The \"best\" opponent is defined as:\n   * 1. The opponent with the smallest rating difference.\n   * 2. (Tie-breaker) The opponent who has been waiting the longest (earliest joinedAt).\n   * 3. (Tie-breaker) The opponent with the lexicographically smaller ID.\n   * \n   * This query is deterministic given the same inputs and does not modify the pool.\n   * \n   * @param id The ID of the player searching for a match.\n   * @param now The current timestamp. Defaults to Date.now().\n   * @returns The best opponent entry, or null if no opponent is within the window.\n   */\n  findMatch(id: string, now?: number): T | null {\n    const wrapper = this.pool.get(id);\n    if (!wrapper) {\n      return null;\n    }\n    const player = wrapper.entry;\n\n    const currentNow = now ?? Date.now();\n    const waitTime = Math.max(0, currentNow - wrapper.joinedAt);\n\n    // Calculate expanding search window\n    let windowSize = this.initialWindow;\n    if (this.expandEveryMs > 0) {\n      windowSize += Math.floor(waitTime / this.expandEveryMs) * this.expandBy;\n    }\n    if (this.maxWindow != null && windowSize > this.maxWindow) {\n      windowSize = this.maxWindow;\n    }\n\n    let bestOpponentWrapper: { entry: T; joinedAt: number } | null = null;\n    let minDiff = Infinity;\n\n    for (const candidateWrapper of this.pool.values()) {\n      const candidate = candidateWrapper.entry;\n      if (candidate.id === id) {\n        continue;\n      }\n\n      const diff = Math.abs(candidate.rating - player.rating);\n      if (diff <= windowSize) {\n        if (diff < minDiff) {\n          minDiff = diff;\n          bestOpponentWrapper = candidateWrapper;\n        } else if (diff === minDiff && bestOpponentWrapper) {\n          // Tie-breaker 1: longest waiting time (earliest joinedAt)\n          const candidateJoinedAt = candidateWrapper.joinedAt;\n          const bestJoinedAt = bestOpponentWrapper.joinedAt;\n\n          if (candidateJoinedAt < bestJoinedAt) {\n            bestOpponentWrapper = candidateWrapper;\n          } else if (candidateJoinedAt === bestJoinedAt) {\n            // Tie-breaker 2: lexicographical order of id\n            if (candidate.id < bestOpponentWrapper.entry.id) {\n              bestOpponentWrapper = candidateWrapper;\n            }\n          }\n        }\n      }\n    }\n\n    return bestOpponentWrapper ? bestOpponentWrapper.entry : null;\n  }\n\n  /**\n   * Returns the current size of the matchmaking pool.\n   * \n   * @returns The number of players in the pool.\n   */\n  size(): number {\n    return this.pool.size;\n  }\n\n  /**\n   * Clears all players from the matchmaking pool.\n   */\n  clear(): void {\n    this.pool.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "elo-mmr-kit",
+  "version": "0.1.0",
+  "description": "Zero-dependency, fully configurable Elo/MMR rating and matchmaking toolkit for games",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+  },
+  "keywords": [
+    "elo",
+    "mmr",
+    "matchmaking",
+    "rating",
+    "ranking",
+    "game"
+  ],
+  "author": "",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.7.0",
+    "@types/node": "^20.11.0",
+    "eslint": "^9.7.0",
+    "fast-check": "^3.19.0",
+    "prettier": "^3.3.3",
+    "tsup": "^8.2.3",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.3"
+  }
+}