keeperboard 2.0.0 → 2.0.1

package/dist/index.d.mts

@@ -306,6 +306,7 @@ declare class KeeperBoardSession {
     private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
+    private cachedLimit;
     private isSubmitting;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
@@ -328,7 +329,8 @@ declare class KeeperBoardSession {
      * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
      * plus the current player's rank if they're outside the top N.
      *
-     * Uses cache if enabled and fresh.
+     * Uses cache if enabled and fresh. If a larger limit is requested than
+     * what's cached, the cache is invalidated and fresh data is fetched.
      */
     getSnapshot(options?: {
         limit?: number;
@@ -427,11 +429,17 @@ declare function validateName(input: string, options?: NameValidationOptions): s
 
 /**
  * Generic TTL cache with in-flight deduplication and background refresh.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - In-flight request deduplication
+ * - Background refresh scheduling (handles concurrent refresh requests)
  */
 declare class Cache<T> {
     private data;
     private fetchedAt;
     private inflight;
+    private pendingRefresh;
     private readonly ttlMs;
     constructor(ttlMs: number);
     /**
@@ -441,9 +449,11 @@ declare class Cache<T> {
     getOrFetch(fetchFn: () => Promise<T>): Promise<T>;
     /**
      * Trigger a background refresh without awaiting the result.
-     * Returns immediately. If a fetch is already in flight, does nothing.
+     * Returns immediately. If a fetch is already in flight, schedules
+     * the refresh to run after the current one completes.
      */
     refreshInBackground(fetchFn: () => Promise<T>): void;
+    private startBackgroundFetch;
     /** Invalidate the cache, forcing the next getOrFetch to re-fetch. */
     invalidate(): void;
     /** Get the cached value without fetching. Returns undefined if empty or stale. */

package/dist/index.d.ts

@@ -306,6 +306,7 @@ declare class KeeperBoardSession {
     private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
+    private cachedLimit;
     private isSubmitting;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
@@ -328,7 +329,8 @@ declare class KeeperBoardSession {
      * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
      * plus the current player's rank if they're outside the top N.
      *
-     * Uses cache if enabled and fresh.
+     * Uses cache if enabled and fresh. If a larger limit is requested than
+     * what's cached, the cache is invalidated and fresh data is fetched.
      */
     getSnapshot(options?: {
         limit?: number;
@@ -427,11 +429,17 @@ declare function validateName(input: string, options?: NameValidationOptions): s
 
 /**
  * Generic TTL cache with in-flight deduplication and background refresh.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - In-flight request deduplication
+ * - Background refresh scheduling (handles concurrent refresh requests)
  */
 declare class Cache<T> {
     private data;
     private fetchedAt;
     private inflight;
+    private pendingRefresh;
     private readonly ttlMs;
     constructor(ttlMs: number);
     /**
@@ -441,9 +449,11 @@ declare class Cache<T> {
     getOrFetch(fetchFn: () => Promise<T>): Promise<T>;
     /**
      * Trigger a background refresh without awaiting the result.
-     * Returns immediately. If a fetch is already in flight, does nothing.
+     * Returns immediately. If a fetch is already in flight, schedules
+     * the refresh to run after the current one completes.
      */
     refreshInBackground(fetchFn: () => Promise<T>): void;
+    private startBackgroundFetch;
     /** Invalidate the cache, forcing the next getOrFetch to re-fetch. */
     invalidate(): void;
     /** Get the cached value without fetching. Returns undefined if empty or stale. */

package/dist/index.js

@@ -354,6 +354,7 @@ var Cache = class {
   constructor(ttlMs) {
     this.fetchedAt = 0;
     this.inflight = null;
+    this.pendingRefresh = null;
     this.ttlMs = ttlMs;
   }
   /**
@@ -380,17 +381,30 @@ var Cache = class {
   }
   /**
    * Trigger a background refresh without awaiting the result.
-   * Returns immediately. If a fetch is already in flight, does nothing.
+   * Returns immediately. If a fetch is already in flight, schedules
+   * the refresh to run after the current one completes.
    */
   refreshInBackground(fetchFn) {
-    if (this.inflight) return;
+    if (this.inflight) {
+      this.pendingRefresh = fetchFn;
+      return;
+    }
+    this.startBackgroundFetch(fetchFn);
+  }
+  startBackgroundFetch(fetchFn) {
     this.inflight = fetchFn().then((result) => {
       this.data = result;
       this.fetchedAt = Date.now();
       this.inflight = null;
+      if (this.pendingRefresh) {
+        const pending = this.pendingRefresh;
+        this.pendingRefresh = null;
+        this.startBackgroundFetch(pending);
+      }
       return result;
     }).catch((err) => {
       this.inflight = null;
+      this.pendingRefresh = null;
       throw err;
     });
     this.inflight.catch(() => {
@@ -473,7 +487,8 @@ function validateName(input, options) {
   if (opts.uppercase) {
     name = name.toUpperCase();
   }
-  name = name.replace(opts.allowedPattern, "");
+  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
     return null;
@@ -484,6 +499,8 @@ function validateName(input, options) {
 // src/KeeperBoardSession.ts
 var KeeperBoardSession = class {
   constructor(config) {
+    this.cachedLimit = 0;
+    // Track the limit used for cached data
     this.isSubmitting = false;
     this.client = new KeeperBoardClient({
       apiKey: config.apiKey,
@@ -543,6 +560,7 @@ var KeeperBoardSession = class {
       this.retryQueue?.clear();
       if (this.cache) {
         this.cache.invalidate();
+        this.cachedLimit = 0;
         this.cache.refreshInBackground(() => this.fetchSnapshot());
       }
       return {
@@ -564,12 +582,18 @@ var KeeperBoardSession = class {
    * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
    * plus the current player's rank if they're outside the top N.
    *
-   * Uses cache if enabled and fresh.
+   * Uses cache if enabled and fresh. If a larger limit is requested than
+   * what's cached, the cache is invalidated and fresh data is fetched.
    */
   async getSnapshot(options) {
     const limit = options?.limit ?? 10;
     if (this.cache) {
-      return this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      if (limit > this.cachedLimit) {
+        this.cache.invalidate();
+      }
+      const result = await this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      this.cachedLimit = limit;
+      return result;
     }
     return this.fetchSnapshot(limit);
   }
@@ -584,7 +608,10 @@ var KeeperBoardSession = class {
         newName
       });
       this.identity.setPlayerName(newName);
-      this.cache?.invalidate();
+      if (this.cache) {
+        this.cache.invalidate();
+        this.cachedLimit = 0;
+      }
       return true;
     } catch {
       return false;

package/dist/index.mjs

@@ -322,6 +322,7 @@ var Cache = class {
   constructor(ttlMs) {
     this.fetchedAt = 0;
     this.inflight = null;
+    this.pendingRefresh = null;
     this.ttlMs = ttlMs;
   }
   /**
@@ -348,17 +349,30 @@ var Cache = class {
   }
   /**
    * Trigger a background refresh without awaiting the result.
-   * Returns immediately. If a fetch is already in flight, does nothing.
+   * Returns immediately. If a fetch is already in flight, schedules
+   * the refresh to run after the current one completes.
    */
   refreshInBackground(fetchFn) {
-    if (this.inflight) return;
+    if (this.inflight) {
+      this.pendingRefresh = fetchFn;
+      return;
+    }
+    this.startBackgroundFetch(fetchFn);
+  }
+  startBackgroundFetch(fetchFn) {
     this.inflight = fetchFn().then((result) => {
       this.data = result;
       this.fetchedAt = Date.now();
       this.inflight = null;
+      if (this.pendingRefresh) {
+        const pending = this.pendingRefresh;
+        this.pendingRefresh = null;
+        this.startBackgroundFetch(pending);
+      }
       return result;
     }).catch((err) => {
       this.inflight = null;
+      this.pendingRefresh = null;
       throw err;
     });
     this.inflight.catch(() => {
@@ -441,7 +455,8 @@ function validateName(input, options) {
   if (opts.uppercase) {
     name = name.toUpperCase();
   }
-  name = name.replace(opts.allowedPattern, "");
+  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
     return null;
@@ -452,6 +467,8 @@ function validateName(input, options) {
 // src/KeeperBoardSession.ts
 var KeeperBoardSession = class {
   constructor(config) {
+    this.cachedLimit = 0;
+    // Track the limit used for cached data
     this.isSubmitting = false;
     this.client = new KeeperBoardClient({
       apiKey: config.apiKey,
@@ -511,6 +528,7 @@ var KeeperBoardSession = class {
       this.retryQueue?.clear();
       if (this.cache) {
         this.cache.invalidate();
+        this.cachedLimit = 0;
         this.cache.refreshInBackground(() => this.fetchSnapshot());
       }
       return {
@@ -532,12 +550,18 @@ var KeeperBoardSession = class {
    * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
    * plus the current player's rank if they're outside the top N.
    *
-   * Uses cache if enabled and fresh.
+   * Uses cache if enabled and fresh. If a larger limit is requested than
+   * what's cached, the cache is invalidated and fresh data is fetched.
    */
   async getSnapshot(options) {
     const limit = options?.limit ?? 10;
     if (this.cache) {
-      return this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      if (limit > this.cachedLimit) {
+        this.cache.invalidate();
+      }
+      const result = await this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      this.cachedLimit = limit;
+      return result;
     }
     return this.fetchSnapshot(limit);
   }
@@ -552,7 +576,10 @@ var KeeperBoardSession = class {
         newName
       });
       this.identity.setPlayerName(newName);
-      this.cache?.invalidate();
+      if (this.cache) {
+        this.cache.invalidate();
+        this.cachedLimit = 0;
+      }
       return true;
     } catch {
       return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keeperboard",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "TypeScript client SDK for KeeperBoard leaderboard-as-a-service",
   "main": "dist/index.js",
   "module": "dist/index.mjs",