Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

cache.ts

138 lines3.9 KB

1/**
2 * Server-side stale-while-revalidate cache (PLAN.md task 3.1) — the
3 * "server-side react query". Values live in KV; freshness metadata lives in
4 * the `cache_meta` D1 table. Reads always serve immediately; stale reads
5 * kick a background revalidation through `waitUntil`, deduped across
6 * isolates by the `cache_meta.refreshing` flag.
7 */
8import { eq } from 'drizzle-orm'
9​
10import type { Db } from '#/db/index.ts'
11import { cacheMeta } from '#/db/schema.ts'
12import { getJson, putJson } from '#/server/kv.ts'
13​
14export interface SwrDeps {
15 db: Db
16 kv: KVNamespace
17 /** `ctx.waitUntil` — keeps background revalidation alive past the response. */
18 waitUntil: (promise: Promise<unknown>) => void
19 /** Injectable clock (unix epoch seconds) for deterministic tests. */
20 now?: () => number
22​
23export interface SwrOptions {
24 /** Seconds a cached value is considered fresh. */
25 staleTime: number
26 /** Optional KV expirationTtl (seconds) — the hard eviction backstop. */
27 hardTtl?: number
29​
30export interface SwrResult<T> {
31 value: T
32 fetchedAt: number
33 staleAt: number
34 /** True when this read kicked off a background revalidation. */
35 revalidating: boolean
37​
38const KV_PREFIX = 'swr:'
39​
40async function persist<T>(
41 deps: SwrDeps,
42 key: string,
43 value: T,
44 staleTime: number,
45 hardTtl: number | undefined,
46 fetchedAt: number,
47): Promise<void> {
48 await putJson(
49 deps.kv,
50 KV_PREFIX + key,
51 value,
52 hardTtl !== undefined ? { expirationTtl: hardTtl } : undefined,
53 )
54 await deps.db
55 .insert(cacheMeta)
56 .values({ key, fetchedAt, staleTime, refreshing: false, lastError: null })
57 .onConflictDoUpdate({
58 target: cacheMeta.key,
59 set: { fetchedAt, staleTime, refreshing: false, lastError: null },
60 })
62​
63async function revalidate<T>(
64 deps: SwrDeps,
65 key: string,
66 fetcher: () => Promise<T>,
67 options: SwrOptions,
68 now: number,
69): Promise<void> {
70 try {
71 const value = await fetcher()
72 await persist(deps, key, value, options.staleTime, options.hardTtl, now)
73 } catch (error) {
74 await deps.db
75 .update(cacheMeta)
76 .set({
77 refreshing: false,
78 lastError: error instanceof Error ? error.message : String(error),
79 })
80 .where(eq(cacheMeta.key, key))
81 }
83​
84/**
85 * KV hit + fresh → return. KV hit + stale → return immediately AND
86 * revalidate in the background (guarded by the `refreshing` flag; a stuck
87 * flag older than 2× staleTime is ignored). Miss → fetch inline + persist.
88 */
89export async function swr<T>(
90 deps: SwrDeps,
91 key: string,
92 fetcher: () => Promise<T>,
93 options: SwrOptions,
94): Promise<SwrResult<T>> {
95 const now = deps.now?.() ?? Math.floor(Date.now() / 1000)
96​
97 const [cached, meta] = await Promise.all([
98 getJson<T>(deps.kv, KV_PREFIX + key),
99 deps.db.query.cacheMeta.findFirst({ where: eq(cacheMeta.key, key) }),
100 ])
101​
102 if (cached !== null && meta) {
103 const staleAt = meta.fetchedAt + meta.staleTime
104 if (now < staleAt) {
105 return {
106 value: cached,
107 fetchedAt: meta.fetchedAt,
108 staleAt,
109 revalidating: false,
110 }
111 }
112​
113 // Stale: serve immediately, revalidate in the background unless another
114 // isolate already is. A flag that has been set for over 2× staleTime is
115 // treated as stuck (crashed revalidation) and ignored.
116 const stuck = now > meta.fetchedAt + 2 * meta.staleTime
117 let revalidating = false
118 if (!meta.refreshing || stuck) {
119 await deps.db
120 .update(cacheMeta)
121 .set({ refreshing: true })
122 .where(eq(cacheMeta.key, key))
123 deps.waitUntil(revalidate(deps, key, fetcher, options, now))
124 revalidating = true
125 }
126 return { value: cached, fetchedAt: meta.fetchedAt, staleAt, revalidating }
127 }
128​
129 // Miss (no blob or no metadata): fetch inline.
130 const value = await fetcher()
131 await persist(deps, key, value, options.staleTime, options.hardTtl, now)
132 return {
133 value,
134 fetchedAt: now,
135 staleAt: now + options.staleTime,
136 revalidating: false,
137 }