@juande_pl/rocketleague-stats-api-client 1.0.0 → 1.1.0

package/README.md

@@ -1,177 +1,204 @@
-# rocketleague-stats-api-client
-
-Fully typed WebSocket client for the official [Rocket League Stats API](https://www.rocketleague.com/developer/stats-api), with runtime type guards for every event and command.
-
-- Typed interfaces for all 22 events and 6 commands
-- Type guards that validate each message at runtime (enabled by default)
-- `RocketLeagueStatsClient`: connects automatically, reconnects with backoff, and gives you typed `on()` / `onAny()` / `send()`
-- No runtime dependencies. Works in Node.js >= 22 and in browsers. ESM and CommonJS builds.
-
-## Install
-
-```sh
-npm install @juande_pl/rocketleague-stats-api-client
-```
-
-## Enable the Stats API in Rocket League
-
-Edit `<Install Dir>\TAGame\Config\TAStatsAPI.ini` (or `DefaultStatsAPI.ini` if it doesn't exist) **before launching the game**:
-
-```ini
-[TAGame.MatchStatsExporter_TA]
-PacketSendRate=30
-WebPort=49124
-```
-
-| Setting          | Default | Description                                                         |
-| ---------------- | ------- | ------------------------------------------------------------------- |
-| `PacketSendRate` | `0`     | `UpdateState` packets per second (max 120). `0` disables the feature. |
-| `Port`           | `49123` | TCP port. `0` disables it.                                          |
-| `WebPort`        | `49124` | WebSocket port used by this library. `0` disables it.               |
-
-### Automatic setup (Node.js)
-
-On Node.js the client checks the `.ini` for you. It looks for `TAStatsAPI.ini` first, then `DefaultStatsAPI.ini`. On Windows it finds the Epic Games and Steam installs by itself. If `PacketSendRate` is `0` or less, missing, or above the maximum of `120`, it sets it to `30` and warns that **you must restart the game** for the Stats API to work. The game only reads this file at launch. In browsers the check is skipped and the Node-only code is never loaded.
-
-```ts
-import { RocketLeagueStatsClient } from '@juande_pl/rocketleague-stats-api-client';
-
-const client = new RocketLeagueStatsClient({
-  ensureStatsApi: true, // default. Or false, or { installDir, iniPath, packetSendRate, warn }
-});
-
-const config = await client.statsApiConfig;
-// { status: 'updated', iniPath, previous: 0, packetSendRate: 30, restartRequired: true }
-// or 'enabled' | 'not-found' | 'write-failed' (e.g. no permission under Program Files)
-```
-
-The helpers are exported from `@juande_pl/rocketleague-stats-api-client/node`. Run the check on its own with `ensureStatsApiEnabled(options)`, or use `editPacketSendRate(content)` to edit the `.ini` text without touching the disk.
-
-## Usage
-
-```ts
-import { RocketLeagueStatsClient } from "@juande_pl/rocketleague-stats-api-client";
-
-const client = new RocketLeagueStatsClient(); // ws://127.0.0.1:49124, connects automatically
-
-// A single event: `data` is typed as GoalScoredData
-client.on('GoalScored', (data) => {
-  console.log(`${data.Scorer.Name} scored at ${data.GoalSpeed} uu/s`);
-});
-
-// Every event, as a discriminated union
-client.onAny((event) => {
-  if (event.Event === 'StatfeedEvent') {
-    console.log(event.Data.MainTarget.Name, event.Data.EventName);
-  }
-});
-
-// Commands: checked at compile time and validated at runtime
-client.send('ChangePOV', { Focus: '1', Perspective: 'PlayerView' });
-client.send({ Command: 'SetHUDVisibility', Data: { bVisible: false } });
-```
-
-### Options
-
-```ts
-new RocketLeagueStatsClient({
-  host: '127.0.0.1',     // default
-  port: 49124,           // default (WebPort)
-  secure: false,         // use wss://
-  url: undefined,        // full URL, overrides host/port/secure
-  autoConnect: true,     // set to false and call client.connect() yourself
-  reconnect: true,       // or false, or { initialDelay, maxDelay, factor, maxAttempts }
-  validateEvents: true,  // run type guards on incoming events
-  WebSocket: undefined,  // custom implementation, defaults to globalThis.WebSocket
-  ensureStatsApi: true,  // Node.js only: enable PacketSendRate in the .ini (see above)
-});
-```
-
-With `autoConnect: true`, the connection opens on the next microtask, so listeners you add right after `new` still get the `connect` event. If the game isn't running yet, the client keeps retrying with exponential backoff (1 s, 2 s, 4 s … up to 30 s).
-
-On Node.js < 22, pass the `ws` package: `new RocketLeagueStatsClient({ WebSocket: (await import('ws')).default })`.
-
-### Listening
-
-| Method                          | Description                                                                 |
-| ------------------------------- | --------------------------------------------------------------------------- |
-| `on(name, listener)`            | Game event (`'GoalScored'`, …) or lifecycle event. Returns an unsubscribe function. |
-| `once(name, listener)`          | Same as `on`, but the listener runs only once.                              |
-| `off(name, listener)`           | Removes a listener.                                                         |
-| `onAny(listener)` / `offAny()`  | Every game event, as `StatsApiEvent` (narrow with `event.Event`).           |
-| `waitFor(name, { timeout })`    | Promise that resolves with the next payload of that event.                  |
-| `removeAllListeners(name?)`     | Removes every listener, or every listener for one name.                     |
-
-Game event listeners receive `(data, event)`: the typed payload and the full `{ Event, Data }` message.
-
-Lifecycle events:
-
-| Name             | Arguments                                   |
-| ---------------- | ------------------------------------------- |
-| `connect`        | none                                        |
-| `disconnect`     | `{ code, reason, willReconnect }`           |
-| `reconnecting`   | `{ attempt, delay }`                        |
-| `error`          | `Error` (`ConnectionError`, `ListenerError`) |
-| `invalidMessage` | `ParseFailure` (`reason`, `raw`, `event?`, `data?`) |
-
-Errors are only reported to `error` listeners. A throwing listener doesn't stop the other listeners from running.
-
-### Sending commands
-
-`send(command, data)` or `send({ Command, Data })`. It throws:
-
-- `CommandValidationError` if the command name or payload is invalid (for example, `ChangePOV` with neither `Focus` nor `Perspective`, or `SetGameSpeed` with a negative speed).
-- `NotConnectedError` if the socket is not open.
-
-| Command            | Payload                                                         |
-| ------------------ | --------------------------------------------------------------- |
-| `ChangePOV`        | `{ Focus?: 'Ball' \| '<shortcut>', Perspective?: Perspective }` (at least one) |
-| `LoadReplay`       | `{ FileName?: string, Path?: string }` (at least one)            |
-| `SeekReplay`       | `{ Frame?: number, TimeSeconds?: number }` (at least one)        |
-| `SetGameSpeed`     | `{ Speed: number }` (≥ 0)                                       |
-| `SetHUDVisibility` | `{ bVisible: boolean }`                                         |
-| `SetMatchPaused`   | `{ bPaused: boolean }`                                          |
-
-`Perspective` is one of `'Fly' | 'SoftAttach' | 'HardAttach' | 'PlayerView' | 'AutoCam' | 'Camera_Director'`.
-
-## Type guards
-
-Every guard is exported, so you can validate messages from any source (the TCP port, recordings, a relay server…):
-
-```ts
-import { isStatsApiEvent, isGoalScoredData, isEventData, isStatsApiCommand, parseEventMessage } from '@juande_pl/rocketleague-stats-api-client';
-
-isGoalScoredData(payload);                 // payload is GoalScoredData
-isEventData('BallHit', payload);           // payload is BallHitData
-isStatsApiEvent(message);                  // message is StatsApiEvent
-isStatsApiEvent(message, 'MatchEnded');    // message is StatsApiEventOf<'MatchEnded'>
-isStatsApiCommand(command, 'ChangePOV');   // command is StatsApiCommandOf<'ChangePOV'>
-
-// Decodes the wire format ({ Event, Data: "<json string>" }). Never throws.
-const result = parseEventMessage(rawText);
-if (result.ok) console.log(result.event.Event);
-else console.warn(result.reason); // 'invalid-json' | 'invalid-envelope' | 'invalid-data-json' | 'unknown-event' | 'invalid-data'
-```
-
-Guards accept extra, undocumented fields, so new fields added by a game update don't break validation. Fields the docs mark `SPECTATOR` or `CONDITIONAL` (and `MatchGuid`, which is only set online or on LAN) are optional.
-
-The building blocks (`shape`, `optional`, `arrayOf`, `oneOf`, `isString`, `isNumber`, …) are exported too.
-
-## Known quirks
-
-- `StatfeedEvent.Type` is a localized label. Use `EventName` in your logic.
-- `GoalScored.GoalTime` is the length of the previous round, not the match clock.
-- In offline exhibitions or with splitscreen players, `StatfeedEvent` can arrive more than once.
-
-## Development
-
-```sh
-npm install
-npm run typecheck
-npm test
-npm run build
-```
-
-## License
-
-MIT. This project is not affiliated with Psyonix or Epic Games.
+# rocketleague-stats-api-client
+
+Fully typed WebSocket client for the official [Rocket League Stats API](https://www.rocketleague.com/developer/stats-api), with runtime type guards for every event and command.
+
+- Typed interfaces for all 22 events and 6 commands
+- Type guards that validate each message at runtime (enabled by default)
+- `RocketLeagueStatsClient`: connects automatically, reconnects with backoff, and gives you typed `on()` / `onAny()` / `send()`
+- No runtime dependencies. Works in Node.js >= 22 and in browsers. ESM and CommonJS builds.
+
+## Install
+
+```sh
+npm install @juande_pl/rocketleague-stats-api-client
+```
+
+## Enable the Stats API in Rocket League
+
+Edit `<Install Dir>\TAGame\Config\TAStatsAPI.ini` (or `DefaultStatsAPI.ini` if it doesn't exist) **before launching the game**:
+
+```ini
+[TAGame.MatchStatsExporter_TA]
+PacketSendRate=30
+WebPort=49124
+```
+
+| Setting          | Default | Description                                                         |
+| ---------------- | ------- | ------------------------------------------------------------------- |
+| `PacketSendRate` | `0`     | `UpdateState` packets per second (max 120). `0` disables the feature. |
+| `Port`           | `49123` | TCP port. `0` disables it.                                          |
+| `WebPort`        | `49124` | WebSocket port used by this library. `0` disables it.               |
+
+### Automatic setup (Node.js)
+
+On Node.js the client checks the `.ini` for you. It looks for `TAStatsAPI.ini` first, then `DefaultStatsAPI.ini`. On Windows it finds the Epic Games and Steam installs by itself. If `PacketSendRate` is `0` or less, missing, or above the maximum of `120`, it sets it to `30` and warns that **you must restart the game** for the Stats API to work. The game only reads this file at launch. In browsers the check is skipped and the Node-only code is never loaded.
+
+```ts
+import { RocketLeagueStatsClient } from '@juande_pl/rocketleague-stats-api-client';
+
+const client = new RocketLeagueStatsClient({
+  ensureStatsApi: true, // default. Or false, or { installDir, iniPath, packetSendRate, warn }
+});
+
+const config = await client.statsApiConfig;
+// { status: 'updated', iniPath, previous: 0, packetSendRate: 30, restartRequired: true }
+// or 'enabled' | 'not-found' | 'write-failed' (e.g. no permission under Program Files)
+```
+
+The helpers are exported from `@juande_pl/rocketleague-stats-api-client/node`. Run the check on its own with `ensureStatsApiEnabled(options)`, or use `editPacketSendRate(content)` to edit the `.ini` text without touching the disk.
+
+## Usage
+
+```ts
+import { RocketLeagueStatsClient } from "@juande_pl/rocketleague-stats-api-client";
+
+const client = new RocketLeagueStatsClient(); // ws://127.0.0.1:49124, connects automatically
+
+// A single event: `data` is typed as GoalScoredData
+client.on('GoalScored', (data) => {
+  console.log(`${data.Scorer.Name} scored at ${data.GoalSpeed} uu/s`);
+});
+
+// Every event, as a discriminated union
+client.onAny((event) => {
+  if (event.Event === 'StatfeedEvent') {
+    console.log(event.Data.MainTarget.Name, event.Data.EventName);
+  }
+});
+
+// Commands: checked at compile time and validated at runtime
+client.send('ChangePOV', { Focus: '1', Perspective: 'PlayerView' });
+client.send({ Command: 'SetHUDVisibility', Data: { bVisible: false } });
+```
+
+### Options
+
+```ts
+new RocketLeagueStatsClient({
+  host: '127.0.0.1',     // default
+  port: 49124,           // default (WebPort)
+  secure: false,         // use wss://
+  url: undefined,        // full URL, overrides host/port/secure
+  autoConnect: true,     // set to false and call client.connect() yourself
+  reconnect: true,       // or false, or { initialDelay, maxDelay, factor, maxAttempts }
+  validateEvents: true,  // run type guards on incoming events
+  ignoreReplayEndGoal: true, // drop the fake GoalScored sent when a replay ends
+  sortPlayers: undefined, // sort UpdateState.Players (see below). Default: the game's order
+  WebSocket: undefined,  // custom implementation, defaults to globalThis.WebSocket
+  ensureStatsApi: true,  // Node.js only: enable PacketSendRate in the .ini (see above)
+});
+```
+
+With `autoConnect: true`, the connection opens on the next microtask, so listeners you add right after `new` still get the `connect` event. If the game isn't running yet, the client keeps retrying with exponential backoff (1 s, 2 s, 4 s … up to 30 s).
+
+On Node.js < 22, pass the `ws` package: `new RocketLeagueStatsClient({ WebSocket: (await import('ws')).default })`.
+
+### Listening
+
+| Method                          | Description                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `on(name, listener)`            | Game event (`'GoalScored'`, …) or lifecycle event. Returns an unsubscribe function. |
+| `once(name, listener)`          | Same as `on`, but the listener runs only once.                              |
+| `off(name, listener)`           | Removes a listener.                                                         |
+| `onAny(listener)` / `offAny()`  | Every game event, as `StatsApiEvent` (narrow with `event.Event`).           |
+| `waitFor(name, { timeout })`    | Promise that resolves with the next payload of that event.                  |
+| `removeAllListeners(name?)`     | Removes every listener, or every listener for one name.                     |
+
+Game event listeners receive `(data, event)`: the typed payload and the full `{ Event, Data }` message.
+
+Lifecycle events:
+
+| Name             | Arguments                                   |
+| ---------------- | ------------------------------------------- |
+| `connect`        | none                                        |
+| `disconnect`     | `{ code, reason, willReconnect }`           |
+| `reconnecting`   | `{ attempt, delay }`                        |
+| `error`          | `Error` (`ConnectionError`, `ListenerError`) |
+| `invalidMessage` | `ParseFailure` (`reason`, `raw`, `event?`, `data?`) |
+
+Errors are only reported to `error` listeners. A throwing listener doesn't stop the other listeners from running.
+
+### Sending commands
+
+`send(command, data)` or `send({ Command, Data })`. It throws:
+
+- `CommandValidationError` if the command name or payload is invalid (for example, `ChangePOV` with neither `Focus` nor `Perspective`, or `SetGameSpeed` with a negative speed).
+- `NotConnectedError` if the socket is not open.
+
+| Command            | Payload                                                         |
+| ------------------ | --------------------------------------------------------------- |
+| `ChangePOV`        | `{ Focus?: 'Ball' \| '<shortcut>', Perspective?: Perspective }` (at least one) |
+| `LoadReplay`       | `{ FileName?: string, Path?: string }` (at least one)            |
+| `SeekReplay`       | `{ Frame?: number, TimeSeconds?: number }` (at least one)        |
+| `SetGameSpeed`     | `{ Speed: number }` (≥ 0)                                       |
+| `SetHUDVisibility` | `{ bVisible: boolean }`                                         |
+| `SetMatchPaused`   | `{ bPaused: boolean }`                                          |
+
+`Perspective` is one of `'Fly' | 'SoftAttach' | 'HardAttach' | 'PlayerView' | 'AutoCam' | 'Camera_Director'`.
+
+## Sorting players
+
+By default `UpdateState.Players` arrives in the order the game sends it. To change that, pass `sortPlayers` to the client, or call `sortPlayers()` yourself on any player list:
+
+```ts
+import { RocketLeagueStatsClient, sortPlayers, byTeam, byStat, byName, byShortcut } from '@juande_pl/rocketleague-stats-api-client';
+
+// Every UpdateState: Blue then Orange, best score first within each team
+const client = new RocketLeagueStatsClient({ sortPlayers: [byTeam(), byStat('Score')] });
+
+// Or on demand. Returns a new array and doesn't change the original.
+const byBoost = sortPlayers(data.Players, byStat('Boost'));
+const custom = sortPlayers(data.Players, (a, b) => a.Demos - b.Demos);
+```
+
+| Comparator                    | Order                                                              |
+| ----------------------------- | ------------------------------------------------------------------ |
+| `byTeam(order = 'asc')`       | Blue (0) first. `'desc'` puts Orange first.                        |
+| `byShortcut(order = 'asc')`   | Spectator shortcut.                                                |
+| `byName(order = 'asc')`       | Name, case-insensitive.                                            |
+| `byStat(stat, order = 'desc')`| Any numeric field (`Score`, `Goals`, `Boost`…). Missing values go last. |
+
+The first comparator decides and the next ones break ties. The sort is stable, so players that compare equal keep the game's order.
+
+## Type guards
+
+Every guard is exported, so you can validate messages from any source (the TCP port, recordings, a relay server…):
+
+```ts
+import { isStatsApiEvent, isGoalScoredData, isEventData, isStatsApiCommand, parseEventMessage } from '@juande_pl/rocketleague-stats-api-client';
+
+isGoalScoredData(payload);                 // payload is GoalScoredData
+isEventData('BallHit', payload);           // payload is BallHitData
+isStatsApiEvent(message);                  // message is StatsApiEvent
+isStatsApiEvent(message, 'MatchEnded');    // message is StatsApiEventOf<'MatchEnded'>
+isStatsApiCommand(command, 'ChangePOV');   // command is StatsApiCommandOf<'ChangePOV'>
+
+// Decodes the wire format ({ Event, Data: "<json string>" }). Never throws.
+const result = parseEventMessage(rawText);
+if (result.ok) console.log(result.event.Event);
+else console.warn(result.reason); // 'invalid-json' | 'invalid-envelope' | 'invalid-data-json' | 'unknown-event' | 'invalid-data'
+```
+
+Guards accept extra, undocumented fields, so new fields added by a game update don't break validation. Fields the docs mark `SPECTATOR` or `CONDITIONAL` (and `MatchGuid`, which is only set online or on LAN) are optional.
+
+The building blocks (`shape`, `optional`, `arrayOf`, `oneOf`, `isString`, `isNumber`, …) are exported too.
+
+## Known quirks
+
+- `StatfeedEvent.Type` is a localized label. Use `EventName` in your logic.
+- `GoalScored.GoalTime` is the length of the previous round, not the match clock.
+- In offline exhibitions or with splitscreen players, `StatfeedEvent` can arrive more than once.
+- When a replay ends, the game sends a fake `GoalScored` event whose `Scorer` is `{ "Name": "", "Shortcut": 0, "TeamNum": 0 }`. The client drops it by default. Pass `ignoreReplayEndGoal: false` to receive it, and use `isReplayEndGoal(event)` to detect it yourself.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT. This project is not affiliated with Psyonix or Epic Games.

package/dist/{chunk-IVUQE3LJ.js → chunk-5ZC7WJPK.js}

@@ -333,6 +333,37 @@ function parseEventMessage(raw, options = {}) {
   return { ok: true, event: { Event: event, Data: data } };
 }
 
+// src/sort.ts
+var direction = (order) => order === "asc" ? 1 : -1;
+function byTeam(order = "asc") {
+  return (a, b) => (a.TeamNum - b.TeamNum) * direction(order);
+}
+function byShortcut(order = "asc") {
+  return (a, b) => (a.Shortcut - b.Shortcut) * direction(order);
+}
+function byName(order = "asc") {
+  return (a, b) => a.Name.localeCompare(b.Name, void 0, { sensitivity: "base" }) * direction(order);
+}
+function byStat(stat, order = "desc") {
+  return (a, b) => {
+    const x = a[stat];
+    const y = b[stat];
+    if (x === void 0 || y === void 0) return x === y ? 0 : x === void 0 ? 1 : -1;
+    return (x - y) * direction(order);
+  };
+}
+function sortPlayers(players, ...comparators) {
+  const copy = [...players];
+  if (comparators.length === 0) return copy;
+  return copy.sort((a, b) => {
+    for (const compare of comparators) {
+      const result = compare(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  });
+}
+
 // src/errors.ts
 var StatsApiError = class extends Error {
   name = "StatsApiError";
@@ -367,6 +398,11 @@ var ListenerError = class extends StatsApiError {
 
 // src/client.ts
 var WS_OPEN = 1;
+function isReplayEndGoal(event) {
+  if (event.Event !== "GoalScored") return false;
+  const { Name, Shortcut, TeamNum } = event.Data.Scorer;
+  return Name === "" && Shortcut === 0 && TeamNum === 0;
+}
 function isNodeRuntime() {
   const proc = globalThis.process;
   return typeof proc?.versions?.node === "string";
@@ -382,6 +418,8 @@ var RocketLeagueStatsClient = class {
   #autoConnect;
   #reconnect;
   #validateEvents;
+  #ignoreReplayEndGoal;
+  #playerComparators;
   #WebSocket;
   #socket = null;
   #state = "idle";
@@ -395,6 +433,8 @@ var RocketLeagueStatsClient = class {
     this.url = options.url ?? `${protocol}://${options.host ?? "127.0.0.1"}:${options.port ?? 49124}`;
     this.#autoConnect = options.autoConnect ?? true;
     this.#validateEvents = options.validateEvents ?? true;
+    this.#ignoreReplayEndGoal = options.ignoreReplayEndGoal ?? true;
+    this.#playerComparators = options.sortPlayers === void 0 ? [] : [options.sortPlayers].flat();
     this.#WebSocket = options.WebSocket ?? globalThis.WebSocket;
     const reconnect = options.reconnect ?? true;
     this.#reconnect = reconnect === false ? null : {
@@ -533,6 +573,10 @@ var RocketLeagueStatsClient = class {
       return;
     }
     const { event } = result;
+    if (this.#ignoreReplayEndGoal && isReplayEndGoal(event)) return;
+    if (this.#playerComparators.length > 0 && event.Event === "UpdateState" && Array.isArray(event.Data.Players)) {
+      event.Data.Players = sortPlayers(event.Data.Players, ...this.#playerComparators);
+    }
     this.#dispatch(event.Event, [event.Data, event]);
     for (const listener of [...this.#anyListeners]) {
       this.#invoke("*", listener, [event]);
@@ -716,11 +760,17 @@ export {
   isCommandData,
   isStatsApiCommand,
   parseEventMessage,
+  byTeam,
+  byShortcut,
+  byName,
+  byStat,
+  sortPlayers,
   StatsApiError,
   NotConnectedError,
   CommandValidationError,
   ConnectionError,
   ListenerError,
+  isReplayEndGoal,
   RocketLeagueStatsClient
 };
-//# sourceMappingURL=chunk-IVUQE3LJ.js.map
+//# sourceMappingURL=chunk-5ZC7WJPK.js.map