[Ephem]

Description

👨:

I thought tokenCache was hard to read and realized it was mostly two things, naming and the fact we were storing the token multiple times. Renames here are subjective so do feel free to push back if it didn't help readability for you.

Note that there are a bunch of test changes that look like they are tweaking the tests, but they should actually be stricter now except for the unused feature explicitly dropped below.

🤖:

Stacked on #10429. Readability refactor of SessionTokenCache; no behaviour change.

• The cache no longer writes resolvedToken back onto the object passed to set(). Each entry stores its freshest known token and an isPending flag, and get() derives the served token from those. The token and its expiry now come from the same record, so they can't drift apart.
• get() returns { token?, tokenResolver } instead of the stored entry. Session.ts changes by one line.
• Renames:
  • TokenCacheEntry → TokenCacheSetParams (what callers pass to set())
  • TokenCacheValue → TokenCacheEntry (the stored record per key). Note that TokenCacheEntry now means something different from before.
  • TokenCacheGetResult → TokenCacheHit
  • CachedToken → TokenWithExpiry
  • freshest → freshestKnown
  • cachedAt → createdAt
• Removes the unused ability to pass a resolvedToken to set(). No production caller used it.

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 27, 2026 8:11pm UTC
swingset	Ready	Preview	Oct 27, 2026 8:11pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 8411927

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

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: clerk/javascript
• Branch: fredrik/tokens-refactor-2
• File: .coderabbit.yaml
• Commit: 8411927
• Layers: Repository YAML (base), Organization UI (inherited)
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: 964c315e-7eb3-4d08-86c1-4c21b16954c4

Commits

Reviewing files that changed from the base of the PR and between 4d8aeb3 and 8411927.

Files selected for processing: 1

• .changeset/dark-candles-fly.md

Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/clerk-android (auto-detected)
• clerk/cli (auto-detected)
• clerk/clerk-ios (auto-detected)

Included review availability: This review used your included allowance. 6 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

Walkthrough

TokenCache now returns an optional token and its resolver directly instead of exposing an internal entry. Internal entries track pending state and the freshest known token while managing expiration, refresh timers, and broadcasts. Session uses the updated result shape. Cache and Session tests assert against direct hit fields and cover concurrent mint resolution order.

Priority: Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• clerk/javascript#10401: Introduced the expiry model that this change refactors.
• clerk/javascript#10429: Changes the freshest-token handling in the same cache code paths.

Merge Risk: Minimal · up to 84119

The refactor preserves the inspected token-cache and Session behavior and is mergeable pending normal test and build checks.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly identifies the main change as a readability refactor of the Clerk.js token cache.
Description check		The description directly explains the token cache refactor, renamed types, behavior preservation, removed unused functionality, and testing status.
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within survi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 4 files. (1 skipped: 1 unsupported.)

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10468

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10468

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10468

@clerk/expo

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

@clerk/expo-biometrics

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10468

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10468

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10468

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 8411927

[github-actions]

API Changes Report

Generated by Break Check on 2026-10-27T20:17:24.689Z

Summary

Metric	Count
Packages analyzed	20
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 8411927.}

[wobsoriano]

this makes sense 👍🏼