@wvdsh/sdk-js 1.3.5 → 1.3.7

package/dist/index.d.ts

@@ -82,6 +82,7 @@ type LeaderboardEntries = FunctionReturnType<typeof api.sdk.leaderboards.listEnt
 type UpsertedLeaderboardEntry = FunctionReturnType<typeof api.sdk.leaderboards.upsertLeaderboardEntry>["entry"] & {
     userId: GenericId<"users">;
     username: string;
+    userAvatarUrl?: string;
 };
 type WavedashEvent = (typeof WavedashEvents)[keyof typeof WavedashEvents];
 interface WavedashConfig {
@@ -278,6 +279,8 @@ declare class LobbyManager extends WavedashManager {
     private recentMessageIds;
     private maybeBeingDeletedLobbyIds;
     private resetMaybeBeingDeletedLobbyIdTimeouts;
+    private static readonly METADATA_UPDATE_THROTTLE_MS;
+    private inFlightMetadataUpdate;
     private cachedLobbies;
     private unsubscribeLobbyInvites;
     private seenInviteIds;
@@ -295,7 +298,6 @@ declare class LobbyManager extends WavedashManager {
     getHostId(lobbyId: GenericId<"lobbies">): GenericId<"users"> | null;
     getLobbyData(lobbyId: GenericId<"lobbies">, key: string): string | number | null;
     deleteLobbyData(lobbyId: GenericId<"lobbies">, key: string): boolean;
-    private debouncedMetadataUpdate;
     setLobbyData(lobbyId: GenericId<"lobbies">, key: string, value: string | number | null): boolean;
     getLobbyMaxPlayers(lobbyId: GenericId<"lobbies">): number;
     getNumLobbyUsers(lobbyId: GenericId<"lobbies">): number;
@@ -333,7 +335,8 @@ declare class LobbyManager extends WavedashManager {
      * Called during session end to ensure no lingering listeners.
      */
     destroy(): void;
-    private processPendingLobbyDataUpdates;
+    private throttledSetMetadata;
+    private setMetadata;
     /**
      * Process user updates and emit individual user events
      * @param newUsers - The updated list of lobby users
@@ -556,10 +559,6 @@ declare class P2PManager extends WavedashManager {
     private decodeBinaryMessage;
 }
 
-type StatEntry = {
-    identifier: string;
-    value: number;
-};
 declare class StatsManager extends WavedashManager {
     private stats;
     private unlockedAchievements;
@@ -569,24 +568,23 @@ declare class StatsManager extends WavedashManager {
     private knownAchievementIds;
     private loaded;
     private subscriptions;
-    private periodicPersistInterval;
+    private inFlightPersist;
+    private flushRequested;
     constructor(sdk: WavedashSDK);
     destroy(): void;
     private isReady;
     private subscribe;
     requestStats(): Promise<boolean>;
-    private debouncedPersist;
+    private throttledPersist;
     storeStats(): boolean;
+    private requestPersistFlush;
     private persist;
     getStat(identifier: string): number;
     setStat(identifier: string, value: number, storeNow?: boolean): boolean;
     getAchievement(identifier: string): boolean;
     setAchievement(identifier: string, storeNow?: boolean): boolean;
     /** @destructive - Returns the pending stats and achievements and resets the dirty collections */
-    getPendingData(): {
-        stats: StatEntry[];
-        achievements: string[];
-    } | null;
+    private getPendingData;
 }
 
 /**

package/dist/index.js

@@ -2,7 +2,7 @@
 import { ConvexClient } from "convex/browser";
 
 // src/services/lobby.ts
-import debounce from "lodash.debounce";
+import throttle from "lodash.throttle";
 
 // src/constants.ts
 import {
@@ -94,7 +94,7 @@ var WavedashManager = class {
 };
 
 // src/services/lobby.ts
-var LobbyManager = class extends WavedashManager {
+var _LobbyManager = class _LobbyManager extends WavedashManager {
   constructor(sdk) {
     super(sdk);
     // Track current lobby state
@@ -109,6 +109,7 @@ var LobbyManager = class extends WavedashManager {
     this.recentMessageIds = [];
     this.maybeBeingDeletedLobbyIds = /* @__PURE__ */ new Set();
     this.resetMaybeBeingDeletedLobbyIdTimeouts = /* @__PURE__ */ new Map();
+    this.inFlightMetadataUpdate = null;
     // Cache results of queries for a list of lobbies
     // We'll cache metadata and num users for each lobby and return that info synchronously when requested by the game
     this.cachedLobbies = {};
@@ -117,9 +118,13 @@ var LobbyManager = class extends WavedashManager {
     this.seenInviteIds = /* @__PURE__ */ new Set();
     // Queue for serializing P2P connection updates to prevent race conditions
     this.p2pUpdateQueue = Promise.resolve();
-    this.debouncedMetadataUpdate = debounce(
-      () => this.processPendingLobbyDataUpdates(),
-      50
+    // leading: false so the first call doesn't fire synchronously inside setLobbyData
+    // (which is called from a tight loop); trailing: true to flush coalesced updates
+    // at the end of the window.
+    this.throttledSetMetadata = throttle(
+      () => this.setMetadata(),
+      _LobbyManager.METADATA_UPDATE_THROTTLE_MS,
+      { leading: false, trailing: true }
     );
     /**
      * Process user updates and emit individual user events
@@ -266,7 +271,7 @@ var LobbyManager = class extends WavedashManager {
       this.lobbyMetadata[key] = value;
     }
     this.pendingMetadataUpdates[key] = value;
-    this.debouncedMetadataUpdate();
+    this.throttledSetMetadata();
     return true;
   }
   getLobbyMaxPlayers(lobbyId) {
@@ -443,7 +448,7 @@ var LobbyManager = class extends WavedashManager {
   cleanupLobbyState() {
     const currentLobbyId = this.lobbyId;
     this.lobbyId = null;
-    this.debouncedMetadataUpdate.cancel();
+    this.throttledSetMetadata.cancel();
     this.pendingMetadataUpdates = {};
     if (this.unsubscribeLobbyMessages) {
       this.unsubscribeLobbyMessages();
@@ -501,14 +506,22 @@ var LobbyManager = class extends WavedashManager {
     this.seenInviteIds.clear();
     this.cachedLobbies = {};
   }
-  processPendingLobbyDataUpdates() {
+  setMetadata() {
+    if (this.inFlightMetadataUpdate !== null) return;
+    if (this.lobbyId === null) return;
+    if (Object.keys(this.pendingMetadataUpdates).length === 0) return;
     const updates = this.pendingMetadataUpdates;
     this.pendingMetadataUpdates = {};
-    this.sdk.convexClient.mutation(api.sdk.gameLobby.setLobbyMetadata, {
+    this.inFlightMetadataUpdate = this.sdk.convexClient.mutation(api.sdk.gameLobby.setLobbyMetadata, {
       lobbyId: this.lobbyId,
       updates
     }).catch((error) => {
       this.sdk.logger.error("Error updating lobby metadata:", error);
+    }).finally(() => {
+      this.inFlightMetadataUpdate = null;
+      if (Object.keys(this.pendingMetadataUpdates).length > 0) {
+        this.throttledSetMetadata();
+      }
     });
   }
   // ================
@@ -547,6 +560,10 @@ var LobbyManager = class extends WavedashManager {
     }
   }
 };
+// Throttle (not debounce) batches rapid setLobbyData calls; the in-flight
+// gate in setMetadata prevents OCC self-conflicts.
+_LobbyManager.METADATA_UPDATE_THROTTLE_MS = 150;
+var LobbyManager = _LobbyManager;
 
 // src/utils/indexedDB.ts
 var LOCAL_STORAGE_DB_NAME = "/userfs";
@@ -1081,7 +1098,8 @@ var LeaderboardManager = class extends WavedashManager {
     return {
       ...result.entry,
       userId: this.sdk.wavedashUser.id,
-      username: this.sdk.wavedashUser.username
+      username: this.sdk.wavedashUser.username,
+      userAvatarUrl: this.sdk.wavedashUser.avatarUrl
     };
   }
   // ================
@@ -2424,9 +2442,8 @@ var P2PManager = _P2PManager;
 
 // src/services/stats.ts
 import { api as api6 } from "@wvdsh/api";
-import debounce2 from "lodash.debounce";
-var STORE_DEBOUNCE_MS = 1e3;
-var PERIODIC_PERSIST_MS = 1e4;
+import throttle2 from "lodash.throttle";
+var STORE_THROTTLE_MS = 1e3;
 var StatsManager = class extends WavedashManager {
   constructor(sdk) {
     super(sdk);
@@ -2444,32 +2461,33 @@ var StatsManager = class extends WavedashManager {
     this.loaded = { stats: false, achievements: false };
     // Subscription cleanup
     this.subscriptions = [];
-    // Background flush timer — see PERIODIC_PERSIST_MS
-    this.periodicPersistInterval = null;
+    // Single in-flight persist mutation; prevents OCC self-conflicts.
+    this.inFlightPersist = null;
+    // Set when a storeNow flush hits the in-flight gate; persist's .finally()
+    // checks this and fires immediately on the next cycle instead of waiting
+    // out the throttle window. (lodash treats the gated flush as a successful
+    // invocation, so without this flag a contended storeNow waits ~THROTTLE_MS.)
+    this.flushRequested = false;
     // ================
     // Store / Persist
     // ================
-    // Debounced persist — used by storeNow in setters to batch rapid calls.
-    // Leading+trailing: first call fires immediately, subsequent calls within
-    // the window are batched into one trailing call.
-    this.debouncedPersist = debounce2(() => this.persist(), STORE_DEBOUNCE_MS, {
-      leading: true,
-      trailing: true
-    });
+    // leading: false so a single setStat doesn't fire synchronously inside the
+    // setter; trailing: true to flush coalesced edits at the end of the window.
+    // storeNow=true (and storeStats()) call .flush() to fire the pending invocation
+    // immediately. The in-flight gate in persist() covers mutations that outlast
+    // the throttle window, which would otherwise overlap and cause OCC conflicts.
+    this.throttledPersist = throttle2(
+      () => this.persist(),
+      STORE_THROTTLE_MS,
+      { leading: false, trailing: true }
+    );
     this.subscribe();
     this.requestStats().catch((error) => {
       this.sdk.logger.error("Initial stats fetch failed:", error);
     });
-    this.periodicPersistInterval = setInterval(() => {
-      void this.persist();
-    }, PERIODIC_PERSIST_MS);
   }
   destroy() {
-    this.debouncedPersist.cancel();
-    if (this.periodicPersistInterval !== null) {
-      clearInterval(this.periodicPersistInterval);
-      this.periodicPersistInterval = null;
-    }
+    this.throttledPersist.cancel();
     for (const unsub of this.subscriptions) unsub();
     this.subscriptions = [];
   }
@@ -2534,35 +2552,51 @@ var StatsManager = class extends WavedashManager {
   }
   storeStats() {
     if (!this.isReady()) return false;
-    this.debouncedPersist.cancel();
-    this.persist();
+    this.throttledPersist();
+    this.requestPersistFlush();
     return true;
   }
-  async persist() {
+  // Force-fire the throttled persist now. If a mutation is already in flight,
+  // the gate will swallow the flush(), so we also flag flushRequested so the
+  // next .finally() flushes again instead of waiting a full throttle window.
+  requestPersistFlush() {
+    if (this.inFlightPersist !== null) this.flushRequested = true;
+    this.throttledPersist.flush();
+  }
+  persist() {
+    if (this.inFlightPersist !== null) return;
+    if (this.dirtyStats.size === 0 && this.dirtyAchievements.size === 0) return;
     const pending = this.getPendingData();
     if (!pending) return;
-    try {
-      await Promise.all([
-        pending.stats.length > 0 ? this.sdk.convexClient.mutation(
-          api6.sdk.gameAchievements.setUserGameStats,
-          { stats: pending.stats }
-        ) : Promise.resolve(),
-        pending.achievements.length > 0 ? this.sdk.convexClient.mutation(
-          api6.sdk.gameAchievements.setUserGameAchievements,
-          { achievements: pending.achievements }
-        ) : Promise.resolve()
-      ]);
+    this.inFlightPersist = Promise.all([
+      pending.stats.length > 0 ? this.sdk.convexClient.mutation(
+        api6.sdk.gameAchievements.setUserGameStats,
+        { stats: pending.stats }
+      ) : Promise.resolve(),
+      pending.achievements.length > 0 ? this.sdk.convexClient.mutation(
+        api6.sdk.gameAchievements.setUserGameAchievements,
+        { achievements: pending.achievements }
+      ) : Promise.resolve()
+    ]).then(() => {
       this.sdk.gameEventManager.notifyGame(WavedashEvents.STATS_STORED, {
         success: true
       });
-    } catch (error) {
+    }).catch((error) => {
       const message = error instanceof Error ? error.message : `Error storing stats: ${error}`;
       this.sdk.logger.error(message);
       this.sdk.gameEventManager.notifyGame(WavedashEvents.STATS_STORED, {
         success: false,
         message
       });
-    }
+    }).finally(() => {
+      this.inFlightPersist = null;
+      const shouldFlushNow = this.flushRequested;
+      this.flushRequested = false;
+      if (this.dirtyStats.size > 0 || this.dirtyAchievements.size > 0) {
+        this.throttledPersist();
+        if (shouldFlushNow) this.throttledPersist.flush();
+      }
+    });
   }
   // ================
   // Stats
@@ -2576,8 +2610,9 @@ var StatsManager = class extends WavedashManager {
     if (this.stats.get(identifier) !== value) {
       this.stats.set(identifier, value);
       this.dirtyStats.add(identifier);
+      this.throttledPersist();
     }
-    if (storeNow) this.debouncedPersist();
+    if (storeNow) this.requestPersistFlush();
     return true;
   }
   // ================
@@ -2594,13 +2629,11 @@ var StatsManager = class extends WavedashManager {
     if (!this.unlockedAchievements.has(identifier)) {
       this.unlockedAchievements.add(identifier);
       this.dirtyAchievements.add(identifier);
+      this.throttledPersist();
     }
-    if (storeNow) this.debouncedPersist();
+    if (storeNow) this.requestPersistFlush();
     return true;
   }
-  // ================
-  // Session End
-  // ================
   /** @destructive - Returns the pending stats and achievements and resets the dirty collections */
   getPendingData() {
     if (this.dirtyStats.size === 0 && this.dirtyAchievements.size === 0) {
@@ -2705,8 +2738,10 @@ var HeartbeatManager = class extends WavedashManager {
     if (!reestablish && this.heartbeatInFlight) return;
     this.heartbeatInFlight = true;
     this.sdk.convexClient.mutation(api7.sdk.presence.heartbeat, {
-      ...reestablish ? { data: { forceUpdate: true } } : {},
-      deviceFingerprint: this.deviceFingerprint
+      ...reestablish ? {
+        data: { forceUpdate: true },
+        deviceFingerprint: this.deviceFingerprint
+      } : {}
     }).then((accepted) => {
       if (accepted) {
         this.lastHeartbeatTime = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wvdsh/sdk-js",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "type": "module",
   "description": "Wavedash JavaScript SDK",
   "main": "./dist/client.js",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/lodash.debounce": "^4.0.9",
+    "@types/lodash.throttle": "^4.1.9",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.7.4",
@@ -49,8 +49,8 @@
     "typescript-eslint": "^8.52.0"
   },
   "dependencies": {
-    "@wvdsh/api": "^0.1.14",
+    "@wvdsh/api": "^0.1.16",
     "convex": "^1.34.0",
-    "lodash.debounce": "^4.0.8"
+    "lodash.throttle": "^4.1.1"
   }
 }