refactor(js): extract a generic store from TokenCache

[jacekradko]

First slice of the TokenCache decoupling (SDK-117), in two no-behavior-change steps.

The first commit backfills characterization tests that pin down current cache behavior (cross-tab close() lifecycle, graceful degradation when BroadcastChannel is missing, audience key coalescing) to serve as the regression bar for the rest of the refactor. The second lifts the raw key/value storage out of MemoryTokenCache into a small generic createTokenStore<V> and rewires the cache onto it, so storage is testable on its own without timers or channel mocks.

The part worth a careful read is the cache.* -> store.* rewire in tokenCache.ts. The deleteKey identity check and the overwrite guard both rely on store.get(key) !== value preserving reference identity, which the Map-backed store does. The full src/core suite stays green (632 tests, with Session/Client as the real consumers).

Writing the backfill surfaced a pre-existing bug: a broadcast postMessage failure evicts a freshly cached token, because the throw lands in setInternal's .catch(deleteKey). I left it as an it.fails tripwire and filed it separately as SDK-119 (backport candidate) rather than fixing it in this refactor.

Empty changeset, since nothing here is user-facing.

[changeset-bot]

🦋 Changeset detected

Latest commit: 48ccda4

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 14, 2026 6:09pm
swingset	Ready	Preview, Comment	Jun 14, 2026 6:09pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 8cac00b4-5956-4bb5-8a32-08cbb72ca00e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8860

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8860

@clerk/upgrade

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

@clerk/vue

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

commit: 48ccda4