feat(shared): Add in-memory telemetry throttling for non-browsers #6842

mwickett · 2025-09-23T14:27:16Z

Description

Problem
React Native SDKs were bypassing client-side throttling because localStorage doesn't exist, causing massive event volumes (335K+ METHOD_CALLED events per instance per day vs 5-25 for web).

Solution
Added in-memory fallback throttling for non-browser environments:

TelemetryEventThrottler: Added #memoryCache Map as fallback when window is undefined
Memory safety: 10,000 entry limit with automatic cache clearing to prevent memory issues
Same behavior: Identical 24-hour TTL and throttling logic as localStorage version
Zero impact: Browser behavior completely unchanged

Testing

Added comprehensive test suite for React Native throttling scenarios
Verified TTL expiration works correctly in memory
Confirmed memory safety with cache size limits
All existing tests pass

Expected Impact
Reduces React Native telemetry events by 99%+ during app sessions, bringing them in line with web SDK volumes while maintaining dev-only telemetry
functionality.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- In-memory telemetry throttling for non-browser environments (e.g., React Native) to maintain consistent rate-limiting when persistent storage isn’t available.
- Cache-size safeguard to prevent unbounded memory growth by clearing the cache if it becomes very large.
Tests
- Added tests covering in-memory throttling: first-pass vs repeat events, TTL expiry, distinct event handling, and cache-size limits.

changeset-bot · 2025-09-23T14:27:20Z

🦋 Changeset detected

Latest commit: 6f585b6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@clerk/shared	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2025-09-23T14:27:24Z

Walkthrough

Adds an in-memory throttling path to TelemetryEventThrottler for environments without localStorage (e.g., React Native) and expands tests to cover in-memory behavior: duplicate suppression, TTL expiry, and cache-size eviction. No public API changes; browser/localStorage logic remains unchanged.

Changes

Cohort / File(s)	Summary
Throttling logic (non-browser fallback) `packages/shared/src/telemetry/throttler.ts`	Adds private `#memoryCache` and `#isEventThrottledInMemory(...)`; `isEventThrottled` delegates to memory when `localStorage` is unavailable. Implements TTL checks and a cache-size guard (~10,000 entries). No public signature changes.
Tests: in-memory throttling (React Native-like) `packages/shared/src/__tests__/telemetry.test.ts`	Adds tests exercising the in-memory path: first event allowed, identical events throttled, different events allowed, TTL expiry via fake timers, and cache eviction when size limit exceeded. Duplicate suite appears to reinforce coverage.
Release metadata `.changeset/wet-mails-yawn.md`	Adds a patch changeset for @clerk/shared describing the native-environment throttling update.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client
  participant T as TelemetryEventThrottler
  participant LS as localStorage (browser)
  participant MC as In-Memory Cache (non-browser)

  Client->>T: isEventThrottled(payload)
  alt Browser (localStorage available)
    T->>LS: get(key)
    LS-->>T: timestamp or null
    T->>T: compare timestamp to TTL
    T-->>Client: true / false
    note right of LS #eef2ff: Browser/localStorage path unchanged
  else Non-browser (no localStorage)
    T->>MC: get(key)
    MC-->>T: timestamp or null
    T->>T: compare timestamp to TTL
    T->>MC: evict if size > 10000
    T-->>Client: true / false
    note right of MC #eef9ee: New in-memory throttling path
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

I thump my paws in tidy glee,
When browsers sleep, my cache runs free.
I hush repeats with TTL light,
Evict old crumbs to keep things tight.
Small hops, then signals take to flight. 🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly conveys the primary change, namely adding an in-memory telemetry throttling mechanism for non-browser environments, and uses a clear conventional commit format without extraneous details.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch mwickett/grow-774-fix-telemetry-throttling-for-mobile-sdks

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2025-09-23T14:32:05Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6842

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6842

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6842

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6842

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6842

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6842

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6842

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6842

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6842

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6842

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6842

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6842

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6842

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6842

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6842

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6842

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6842

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6842

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6842

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6842

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6842

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6842

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6842

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6842

commit: 6f585b6

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (4)

packages/shared/src/telemetry/throttler.ts (2)
15-15: Initialize memory cache eagerly and make it readonly.

Removes null checks and prevents accidental reassignment.

Apply this diff:
-  #memoryCache: Map<string, TtlInMilliseconds> | null = null;
+  readonly #memoryCache: Map<string, TtlInMilliseconds> = new Map();
And remove the lazy init in the in‑memory method (see below).

47-72: Unify TTL semantics and extract a named limit; tighten max-size check.

Align TTL behavior with the localStorage path (or update the localStorage path to match this one). Currently, in-memory allows immediately after TTL; localStorage deletes then returns throttled for that call. Prefer consistent “allow and refresh” on expiry.

Replace the magic number 10000 with a named constant.

Use a “>=” check so the cache never grows beyond the limit, and clear before inserting.

Remove lazy init if adopting the readonly initialization.

Apply this diff to the in‑memory method:
-  #isEventThrottledInMemory(payload: TelemetryEvent): boolean {
-    if (!this.#memoryCache) {
-      this.#memoryCache = new Map();
-    }
-
-    const now = Date.now();
-    const key = this.#generateKey(payload);
-
-    // Defensive: clear cache if it gets too large to prevent memory issues
-    if (this.#memoryCache.size > 10000) {
-      this.#memoryCache.clear();
-    }
-
-    const lastSeen = this.#memoryCache.get(key);
-    if (!lastSeen || now - lastSeen > this.#cacheTtl) {
-      this.#memoryCache.set(key, now);
-      return false; // Not throttled - allow the event
-    }
-
-    return true; // Event is throttled
-  }
+  #isEventThrottledInMemory(payload: TelemetryEvent): boolean {
+    const now = Date.now();
+    const key = this.#generateKey(payload);
+
+    // Defensive: clear cache if it reaches the max size to prevent memory issues
+    if (this.#memoryCache.size >= MEMORY_CACHE_MAX_SIZE) {
+      this.#memoryCache.clear();
+    }
+
+    const lastSeen = this.#memoryCache.get(key);
+    if (!lastSeen || now - lastSeen > this.#cacheTtl) {
+      this.#memoryCache.set(key, now);
+      return false; // Not throttled - allow the event
+    }
+
+    return true; // Event is throttled
+  }
Add the named constant near the TTL:
// just below DEFAULT_CACHE_TTL_MS
const MEMORY_CACHE_MAX_SIZE = 10_000;
For consistency, consider updating the localStorage path to “allow and refresh” on expiry:
// Replace the invalidate+return branch in isEventThrottled() with:
const isExpired = typeof entry === 'number' && now - entry > this.#cacheTtl;
if (isExpired) {
  const updatedCache = {
    ...this.#cache,
    [key]: now,
  };
  localStorage.setItem(this.#storageKey, JSON.stringify(updatedCache));
  return false; // allow after TTL and refresh timestamp
}
packages/shared/src/__tests__/telemetry.test.ts (2)
396-401: Strengthen environment mocking for non‑browser.

Spying on window’s getter often works in jsdom, but it’s brittle. Prefer explicitly unsetting globalThis.window within the test scope (and restoring it) to avoid false positives in env detection.

Example:
const realWindow = globalThis.window;
Object.defineProperty(globalThis, 'window', { value: undefined, configurable: true });
try {
  // run test
} finally {
  Object.defineProperty(globalThis, 'window', { value: realWindow, configurable: true });
}
Also consider asserting that Storage methods aren’t touched (e.g., spy on Storage.prototype.getItem).

457-475: Make the cache‑limit test more deterministic.

Set maxBufferSize: 1 to avoid depending on timers for flush.

Assert that a sentinel event after exceeding the limit is delivered (e.g., inspect the last fetch payload) to prove the clear‑then‑allow behavior, instead of a generic “toHaveBeenCalled”.

Example pattern:
const collector = new TelemetryCollector({ publishableKey: TEST_PK, maxBufferSize: 1 });
// ... fill > 10_000 unique keys ...
collector.record({ event: 'TEST_EVENT', payload: { id: 'SENTINEL' } });
jest.runAllTimers();
const lastCall = fetchSpy.mock.calls.at(-1);
expect(JSON.parse(lastCall[1].body).events).toEqual(
  expect.arrayContaining([expect.objectContaining({ payload: { id: 'SENTINEL' } })]),
);

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 98fe792 and 90e1043.

📒 Files selected for processing (2)

packages/shared/src/__tests__/telemetry.test.ts (1 hunks)
packages/shared/src/telemetry/throttler.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (8)

**/*.{js,jsx,ts,tsx}