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

package/dist/index.d.ts

@@ -596,6 +596,33 @@ interface ParseOptions {
  */
 declare function parseEventMessage(raw: unknown, options?: ParseOptions): ParseResult;
 
+/** Compares two players like an `Array.prototype.sort` callback. */
+type PlayerComparator<T extends PlayerRef = Player> = (a: T, b: T) => number;
+/** Sort direction. */
+type SortOrder = 'asc' | 'desc';
+/** Numeric `Player` fields that can be used with {@link byStat}. */
+type PlayerStat = {
+    [K in keyof Player]-?: NonNullable<Player[K]> extends number ? K : never;
+}[keyof Player];
+/** Orders by team: Blue (0) first, or Orange (1) first with `'desc'`. */
+declare function byTeam<T extends PlayerRef>(order?: SortOrder): PlayerComparator<T>;
+/** Orders by spectator shortcut. */
+declare function byShortcut<T extends PlayerRef>(order?: SortOrder): PlayerComparator<T>;
+/** Orders by display name (case-insensitive, locale-aware). */
+declare function byName<T extends PlayerRef>(order?: SortOrder): PlayerComparator<T>;
+/** Orders by a numeric stat (`Score`, `Goals`, `Boost`…). Highest first by default. Missing values go last. */
+declare function byStat(stat: PlayerStat, order?: SortOrder): PlayerComparator;
+/**
+ * Returns a new array sorted by the given comparators: the first one decides, the next ones break ties.
+ * The sort is stable, so players that compare equal keep their original order. The input is not modified.
+ *
+ * ```ts
+ * sortPlayers(data.Players, byTeam(), byStat('Score'));        // Blue then Orange, best score first
+ * sortPlayers(data.Players, (a, b) => a.Demos - b.Demos);       // any custom comparator
+ * ```
+ */
+declare function sortPlayers<T extends PlayerRef>(players: readonly T[], ...comparators: PlayerComparator<T>[]): T[];
+
 /** Base class for every error thrown or emitted by this library. */
 declare class StatsApiError extends Error {
     name: string;
@@ -773,6 +800,17 @@ interface StatsApiClientOptions {
      * @default true
      */
     validateEvents?: boolean;
+    /**
+     * Drop the fake `GoalScored` event the game sends when a replay ends
+     * (its `Scorer` is `{ Name: '', Shortcut: 0, TeamNum: 0 }`). See {@link isReplayEndGoal}.
+     * @default true
+     */
+    ignoreReplayEndGoal?: boolean;
+    /**
+     * Sort `UpdateState.Players` before listeners receive it. Pass one comparator, or several to break ties
+     * (e.g. `[byTeam(), byStat('Score')]`). When omitted, players keep the order sent by the game.
+     */
+    sortPlayers?: PlayerComparator | PlayerComparator[];
     /**
      * WebSocket implementation. Defaults to `globalThis.WebSocket`
      * (browsers, Node.js >= 22). Pass `WebSocket` from the `ws` package for older runtimes.
@@ -786,6 +824,11 @@ interface StatsApiClientOptions {
      */
     ensureStatsApi?: boolean | EnsureStatsApiOptions;
 }
+/**
+ * `true` for the fake `GoalScored` event the game sends when a replay ends:
+ * its `Scorer` is `{ Name: '', Shortcut: 0, TeamNum: 0 }`.
+ */
+declare function isReplayEndGoal(event: StatsApiEvent): boolean;
 /** Connection state of the client. */
 type ConnectionState = 'idle' | 'connecting' | 'open' | 'closed';
 interface DisconnectInfo {
@@ -914,5 +957,5 @@ declare class RocketLeagueStatsClient {
     send(command: StatsApiCommand): void;
 }
 
-export { BALL_UNTOUCHED_TEAM_NUM, COMMAND_NAMES, CommandValidationError, ConnectionError, DEFAULT_PACKET_SEND_RATE as D, EVENT_NAMES, ListenerError, MAX_PACKET_SEND_RATE as M, NotConnectedError, PERSPECTIVES, RocketLeagueStatsClient, STATS_API_INI_FILES as S, StatsApiError, Team, STATS_API_SECTION as a, allOf, arrayOf, ensureStatsApiEnabled as b, findStatsApiIni as c, commandDataGuards, RocketLeagueStatsClient as default, editPacketSendRate as e, eventDataGuards, findRocketLeagueInstallDirs as f, isBallHitData, isBallLastTouch, isBoolean, isBoostPickupData, isChangePOVData, isClockUpdatedSecondsData, isCommandData, isCommandName, isCountdownBeginData, isCrossbarHitData, isEventData, isEventName, isFocus, isGame, isGameBall, isGameTeam, isGoalReplayEndData, isGoalReplayStartData, isGoalReplayWillEndData, isGoalScoredData, isInteger, isLoadReplayData, isMatchCreatedData, isMatchDestroyedData, isMatchEndedData, isMatchInitializedData, isMatchPausedData, isMatchUnpausedData, isNumber, isPerspective, isPlayer, isPlayerJoinedData, isPlayerLeftData, isPlayerRef, isPodiumStartData, isRawEventEnvelope, isRecord, isReplayCreatedData, isRoundStartedData, isSeekReplayData, isSetGameSpeedData, isSetHUDVisibilityData, isSetMatchPausedData, isStatfeedEventData, isStatsApiCommand, isStatsApiEvent, isString, isUpdateStateData, isVector, oneOf, optional, parseEventMessage, statsApiIniPaths as s, shape };
-export type { AnyEventListener, BallHitData, BallLastTouch, BaseEventData, BoostPickupData, BoostType, ChangePOVData, ClientEventName, ClientListenerMap, ClockUpdatedSecondsData, CommandDataMap, CommandName, ConnectionState, CountdownBeginData, CrossbarHitData, DisconnectInfo, EnsureStatsApiOptions, EnsureStatsApiResult, EventDataMap, EventName, Focus, Game, GameBall, GameEventListener, GameTeam, GoalReplayEndData, GoalReplayStartData, GoalReplayWillEndData, GoalScoredData, Guard, GuardedType, LifecycleListenerMap, LoadReplayData, MatchCreatedData, MatchDestroyedData, MatchEndedData, MatchInitializedData, MatchPausedData, MatchUnpausedData, PacketSendRateEdit as P, ParseFailure, ParseFailureReason, ParseOptions, ParseResult, ParseSuccess, Perspective, Player, PlayerJoinedData, PlayerLeftData, PlayerRef, PodiumStartData, PrimaryId, RawEventEnvelope, ReconnectInfo, ReconnectOptions, ReplayCreatedData, RoundStartedData, SeekReplayData, SetGameSpeedData, SetHUDVisibilityData, SetMatchPausedData, ShapeSpec, StatEventName, StatfeedEventData, StatsApiClientOptions, StatsApiCommand, StatsApiCommandOf, StatsApiEvent, StatsApiEventOf, TeamNum, Unsubscribe, UpdateStateData, Vector, WebSocketConstructor, WebSocketLike };
+export { BALL_UNTOUCHED_TEAM_NUM, COMMAND_NAMES, CommandValidationError, ConnectionError, DEFAULT_PACKET_SEND_RATE as D, EVENT_NAMES, ListenerError, MAX_PACKET_SEND_RATE as M, NotConnectedError, PERSPECTIVES, RocketLeagueStatsClient, STATS_API_INI_FILES as S, StatsApiError, Team, STATS_API_SECTION as a, allOf, arrayOf, ensureStatsApiEnabled as b, byName, byShortcut, byStat, byTeam, findStatsApiIni as c, commandDataGuards, RocketLeagueStatsClient as default, editPacketSendRate as e, eventDataGuards, findRocketLeagueInstallDirs as f, isBallHitData, isBallLastTouch, isBoolean, isBoostPickupData, isChangePOVData, isClockUpdatedSecondsData, isCommandData, isCommandName, isCountdownBeginData, isCrossbarHitData, isEventData, isEventName, isFocus, isGame, isGameBall, isGameTeam, isGoalReplayEndData, isGoalReplayStartData, isGoalReplayWillEndData, isGoalScoredData, isInteger, isLoadReplayData, isMatchCreatedData, isMatchDestroyedData, isMatchEndedData, isMatchInitializedData, isMatchPausedData, isMatchUnpausedData, isNumber, isPerspective, isPlayer, isPlayerJoinedData, isPlayerLeftData, isPlayerRef, isPodiumStartData, isRawEventEnvelope, isRecord, isReplayCreatedData, isReplayEndGoal, isRoundStartedData, isSeekReplayData, isSetGameSpeedData, isSetHUDVisibilityData, isSetMatchPausedData, isStatfeedEventData, isStatsApiCommand, isStatsApiEvent, isString, isUpdateStateData, isVector, oneOf, optional, parseEventMessage, statsApiIniPaths as s, shape, sortPlayers };
+export type { AnyEventListener, BallHitData, BallLastTouch, BaseEventData, BoostPickupData, BoostType, ChangePOVData, ClientEventName, ClientListenerMap, ClockUpdatedSecondsData, CommandDataMap, CommandName, ConnectionState, CountdownBeginData, CrossbarHitData, DisconnectInfo, EnsureStatsApiOptions, EnsureStatsApiResult, EventDataMap, EventName, Focus, Game, GameBall, GameEventListener, GameTeam, GoalReplayEndData, GoalReplayStartData, GoalReplayWillEndData, GoalScoredData, Guard, GuardedType, LifecycleListenerMap, LoadReplayData, MatchCreatedData, MatchDestroyedData, MatchEndedData, MatchInitializedData, MatchPausedData, MatchUnpausedData, PacketSendRateEdit as P, ParseFailure, ParseFailureReason, ParseOptions, ParseResult, ParseSuccess, Perspective, Player, PlayerComparator, PlayerJoinedData, PlayerLeftData, PlayerRef, PlayerStat, PodiumStartData, PrimaryId, RawEventEnvelope, ReconnectInfo, ReconnectOptions, ReplayCreatedData, RoundStartedData, SeekReplayData, SetGameSpeedData, SetHUDVisibilityData, SetMatchPausedData, ShapeSpec, SortOrder, StatEventName, StatfeedEventData, StatsApiClientOptions, StatsApiCommand, StatsApiCommandOf, StatsApiEvent, StatsApiEventOf, TeamNum, Unsubscribe, UpdateStateData, Vector, WebSocketConstructor, WebSocketLike };

package/dist/index.js

@@ -12,6 +12,10 @@ import {
   Team,
   allOf,
   arrayOf,
+  byName,
+  byShortcut,
+  byStat,
+  byTeam,
   commandDataGuards,
   eventDataGuards,
   isBallHitData,
@@ -52,6 +56,7 @@ import {
   isRawEventEnvelope,
   isRecord,
   isReplayCreatedData,
+  isReplayEndGoal,
   isRoundStartedData,
   isSeekReplayData,
   isSetGameSpeedData,
@@ -66,8 +71,9 @@ import {
   oneOf,
   optional,
   parseEventMessage,
-  shape
-} from "./chunk-IVUQE3LJ.js";
+  shape,
+  sortPlayers
+} from "./chunk-5ZC7WJPK.js";
 export {
   BALL_UNTOUCHED_TEAM_NUM,
   COMMAND_NAMES,
@@ -82,6 +88,10 @@ export {
   Team,
   allOf,
   arrayOf,
+  byName,
+  byShortcut,
+  byStat,
+  byTeam,
   commandDataGuards,
   RocketLeagueStatsClient as default,
   eventDataGuards,
@@ -123,6 +133,7 @@ export {
   isRawEventEnvelope,
   isRecord,
   isReplayCreatedData,
+  isReplayEndGoal,
   isRoundStartedData,
   isSeekReplayData,
   isSetGameSpeedData,
@@ -137,6 +148,7 @@ export {
   oneOf,
   optional,
   parseEventMessage,
-  shape
+  shape,
+  sortPlayers
 };
 //# sourceMappingURL=index.js.map

package/dist/node.cjs

@@ -243,6 +243,10 @@ __export(node_exports, {
   Team: () => Team,
   allOf: () => allOf,
   arrayOf: () => arrayOf,
+  byName: () => byName,
+  byShortcut: () => byShortcut,
+  byStat: () => byStat,
+  byTeam: () => byTeam,
   commandDataGuards: () => commandDataGuards,
   default: () => RocketLeagueStatsClient,
   editPacketSendRate: () => editPacketSendRate,
@@ -288,6 +292,7 @@ __export(node_exports, {
   isRawEventEnvelope: () => isRawEventEnvelope,
   isRecord: () => isRecord,
   isReplayCreatedData: () => isReplayCreatedData,
+  isReplayEndGoal: () => isReplayEndGoal,
   isRoundStartedData: () => isRoundStartedData,
   isSeekReplayData: () => isSeekReplayData,
   isSetGameSpeedData: () => isSetGameSpeedData,
@@ -303,6 +308,7 @@ __export(node_exports, {
   optional: () => optional,
   parseEventMessage: () => parseEventMessage,
   shape: () => shape,
+  sortPlayers: () => sortPlayers,
   statsApiIniPaths: () => statsApiIniPaths
 });
 module.exports = __toCommonJS(node_exports);
@@ -642,6 +648,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";
@@ -676,6 +713,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";
@@ -691,6 +733,8 @@ var RocketLeagueStatsClient = class {
   #autoConnect;
   #reconnect;
   #validateEvents;
+  #ignoreReplayEndGoal;
+  #playerComparators;
   #WebSocket;
   #socket = null;
   #state = "idle";
@@ -704,6 +748,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 : {
@@ -842,6 +888,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]);
@@ -983,6 +1033,10 @@ init_config();
   Team,
   allOf,
   arrayOf,
+  byName,
+  byShortcut,
+  byStat,
+  byTeam,
   commandDataGuards,
   editPacketSendRate,
   ensureStatsApiEnabled,
@@ -1027,6 +1081,7 @@ init_config();
   isRawEventEnvelope,
   isRecord,
   isReplayCreatedData,
+  isReplayEndGoal,
   isRoundStartedData,
   isSeekReplayData,
   isSetGameSpeedData,
@@ -1042,6 +1097,7 @@ init_config();
   optional,
   parseEventMessage,
   shape,
+  sortPlayers,
   statsApiIniPaths
 });
 //# sourceMappingURL=node.cjs.map