@trieb.work/nextjs-turbo-redis-cache 1.17.0 → 1.18.0

package/test/nextjs-test-projects/next-app-16-2-6-cache-components/src/app/cache-lab/page.tsx

@@ -70,6 +70,28 @@ export default function CacheLabIndexPage() {
             it into a cached component to show correct boundaries.
           </p>
         </Link>
+
+        <Link
+          className="rounded-lg border p-5 hover:bg-slate-50"
+          href="/cache-lab/use-cache-remote"
+        >
+          <h2 className="text-lg font-medium">use cache: remote</h2>
+          <p className="mt-1 text-sm text-slate-600">
+            Exercises <code>cacheHandlers.remote</code> with Redis-backed
+            streams and <code>updateTag</code>.
+          </p>
+        </Link>
+
+        <Link
+          className="rounded-lg border p-5 hover:bg-slate-50"
+          href="/cache-lab/revalidate-durations"
+        >
+          <h2 className="text-lg font-medium">revalidateTag durations</h2>
+          <p className="mt-1 text-sm text-slate-600">
+            Deferred tag invalidation via{' '}
+            <code>revalidateTag(tag, {'{ expire }'})</code> and SWR behavior.
+          </p>
+        </Link>
       </section>
 
       <section className="mt-12 rounded-lg border bg-slate-50 p-5">

package/test/nextjs-test-projects/next-app-16-2-6-cache-components/src/app/cache-lab/revalidate-durations/page.tsx

@@ -0,0 +1,106 @@
+import Link from 'next/link';
+import { Suspense } from 'react';
+import { cacheLife, cacheTag, revalidateTag } from 'next/cache';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function getSlowTaggedValue() {
+  'use cache';
+
+  cacheLife({ stale: 60, revalidate: 120, expire: 300 });
+  cacheTag('cache-lab:durations');
+
+  await sleep(2500);
+
+  return {
+    computedAt: Date.now(),
+    value: Math.random(),
+  };
+}
+
+async function triggerDeferredRevalidateTag() {
+  'use server';
+  revalidateTag('cache-lab:durations', { expire: 2 });
+}
+
+async function CachedPanel() {
+  const data = await getSlowTaggedValue();
+
+  return (
+    <div className="rounded-lg border p-5">
+      <div className="text-sm text-slate-700">
+        <div>
+          <span className="font-medium">computedAt:</span>{' '}
+          <span data-testid="computedAt" className="font-mono">
+            {data.computedAt}
+          </span>
+        </div>
+        <div className="mt-1">
+          <span className="font-medium">value:</span>{' '}
+          <span data-testid="value" className="font-mono">
+            {data.value}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function RevalidateDurationsPage() {
+  return (
+    <main className="mx-auto max-w-3xl p-10">
+      <div className="mb-6">
+        <Link
+          className="text-sm text-blue-600 hover:underline"
+          href="/cache-lab"
+        >
+          ← Back to Cache Lab
+        </Link>
+      </div>
+
+      <header className="mb-6">
+        <h1 className="text-2xl font-semibold">
+          revalidateTag durations (SWR stale window)
+        </h1>
+        <p className="mt-2 text-sm text-slate-600">
+          Calls <code>revalidateTag(tag, {'{ expire: 2 }'})</code>. The handler
+          should mark the tag stale immediately while keeping the Redis entry so
+          the next request can serve stale content (SWR) during refresh.
+        </p>
+      </header>
+
+      <Suspense
+        fallback={
+          <div className="rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+            Loading cached content… (first load can take ~2.5s)
+          </div>
+        }
+      >
+        <CachedPanel />
+      </Suspense>
+
+      <form action={triggerDeferredRevalidateTag} className="mt-6">
+        <button
+          className="rounded-md border border-blue-600 bg-white px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-50"
+          type="submit"
+        >
+          revalidateTag(&apos;cache-lab:durations&apos;, {'{ expire: 2 }'})
+        </button>
+      </form>
+
+      <div className="mt-6 rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+        <p className="font-medium">How to observe SWR invalidation</p>
+        <ol className="mt-2 list-decimal space-y-1 pl-5">
+          <li>Load once (expect ~2.5s).</li>
+          <li>Click the button, then reload immediately.</li>
+          <li>
+            The reload should still show the old values (fast SWR). After
+            background refresh (~2.5s), values should change.
+          </li>
+        </ol>
+      </div>
+    </main>
+  );
+}

package/test/nextjs-test-projects/next-app-16-2-6-cache-components/src/app/cache-lab/use-cache-remote/page.tsx

@@ -0,0 +1,85 @@
+import Link from 'next/link';
+import { Suspense } from 'react';
+import { cacheTag, updateTag } from 'next/cache';
+
+async function getRemoteCachedValue() {
+  'use cache: remote';
+
+  cacheTag('cache-lab:remote');
+
+  return {
+    value: Math.random(),
+    computedAt: Date.now(),
+  };
+}
+
+async function triggerUpdateTag() {
+  'use server';
+  updateTag('cache-lab:remote');
+}
+
+async function RemotePanel() {
+  const data = await getRemoteCachedValue();
+
+  return (
+    <div className="rounded-lg border p-5">
+      <div className="text-sm text-slate-700">
+        <div>
+          <span className="font-medium">computedAt:</span>{' '}
+          <span data-testid="computedAt" className="font-mono">
+            {data.computedAt}
+          </span>
+        </div>
+        <div className="mt-1">
+          <span className="font-medium">value:</span>{' '}
+          <span data-testid="value" className="font-mono">
+            {data.value}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function UseCacheRemotePage() {
+  return (
+    <main className="mx-auto max-w-3xl p-10">
+      <div className="mb-6">
+        <Link
+          className="text-sm text-blue-600 hover:underline"
+          href="/cache-lab"
+        >
+          ← Back to Cache Lab
+        </Link>
+      </div>
+
+      <header className="mb-6">
+        <h1 className="text-2xl font-semibold">use cache: remote</h1>
+        <p className="mt-2 text-sm text-slate-600">
+          Exercises the <code>cacheHandlers.remote</code> handler backed by
+          Redis. Values should stay stable across reloads until{' '}
+          <code>updateTag</code> runs.
+        </p>
+      </header>
+
+      <Suspense
+        fallback={
+          <div className="rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+            Loading remote cached content…
+          </div>
+        }
+      >
+        <RemotePanel />
+      </Suspense>
+
+      <form action={triggerUpdateTag} className="mt-6">
+        <button
+          className="rounded-md border border-blue-600 bg-white px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-50"
+          type="submit"
+        >
+          updateTag(&apos;cache-lab:remote&apos;)
+        </button>
+      </form>
+    </main>
+  );
+}

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/next.config.ts

@@ -4,7 +4,9 @@ const nextConfig: NextConfig = {
   cacheComponents: true,
   cacheHandlers: {
     default: require.resolve('./cache-handler.js'),
+    remote: require.resolve('./cache-handler.js'),
   },
+  cacheMaxMemorySize: 0,
   turbopack: {
     root: __dirname,
   },

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/src/app/api/expire-matrix/revalidate/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server';
+import { revalidateTag } from 'next/cache';
+
+type Profile =
+  | 'max'
+  | 'default'
+  | 'seconds'
+  | 'minutes'
+  | 'hours'
+  | 'days'
+  | 'weeks'
+  | { expire: number };
+
+export async function POST(request: Request) {
+  const body = (await request.json()) as {
+    tag?: string;
+    profile?: Profile | null;
+  };
+  const tag = body.tag || 'expire-matrix-default';
+
+  if (body.profile === undefined || body.profile === null) {
+    // Deprecated single-arg form: Next.js calls updateTags(tags) with no durations.
+    (revalidateTag as (tag: string) => void)(tag);
+  } else {
+    revalidateTag(tag, body.profile);
+  }
+
+  return NextResponse.json({
+    revalidated: true,
+    tag,
+    profile: body.profile ?? null,
+    timestamp: Date.now(),
+  });
+}

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/src/app/api/expire-matrix/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+import { cacheLife, cacheTag } from 'next/cache';
+
+let counter = 0;
+
+export async function GET(request: Request) {
+  const id = new URL(request.url).searchParams.get('id') || 'default';
+  const data = await getExpireMatrixData(id);
+  return NextResponse.json({ ...data, id });
+}
+
+async function getExpireMatrixData(id: string) {
+  'use cache';
+  // Long time-based lifetime so only tag invalidation can change the value.
+  cacheLife({ stale: 300, revalidate: 3600, expire: 86_400 });
+  cacheTag(`expire-matrix-${id}`);
+
+  counter += 1;
+  return {
+    counter,
+    timestamp: Date.now(),
+  };
+}

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/src/app/cache-lab/page.tsx

@@ -70,6 +70,28 @@ export default function CacheLabIndexPage() {
             it into a cached component to show correct boundaries.
           </p>
         </Link>
+
+        <Link
+          className="rounded-lg border p-5 hover:bg-slate-50"
+          href="/cache-lab/use-cache-remote"
+        >
+          <h2 className="text-lg font-medium">use cache: remote</h2>
+          <p className="mt-1 text-sm text-slate-600">
+            Exercises <code>cacheHandlers.remote</code> with Redis-backed
+            streams and <code>updateTag</code>.
+          </p>
+        </Link>
+
+        <Link
+          className="rounded-lg border p-5 hover:bg-slate-50"
+          href="/cache-lab/revalidate-durations"
+        >
+          <h2 className="text-lg font-medium">revalidateTag durations</h2>
+          <p className="mt-1 text-sm text-slate-600">
+            Deferred tag invalidation via{' '}
+            <code>revalidateTag(tag, {'{ expire }'})</code> and SWR behavior.
+          </p>
+        </Link>
       </section>
 
       <section className="mt-12 rounded-lg border bg-slate-50 p-5">

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/src/app/cache-lab/revalidate-durations/page.tsx

@@ -0,0 +1,106 @@
+import Link from 'next/link';
+import { Suspense } from 'react';
+import { cacheLife, cacheTag, revalidateTag } from 'next/cache';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function getSlowTaggedValue() {
+  'use cache';
+
+  cacheLife({ stale: 60, revalidate: 120, expire: 300 });
+  cacheTag('cache-lab:durations');
+
+  await sleep(2500);
+
+  return {
+    computedAt: Date.now(),
+    value: Math.random(),
+  };
+}
+
+async function triggerDeferredRevalidateTag() {
+  'use server';
+  revalidateTag('cache-lab:durations', { expire: 2 });
+}
+
+async function CachedPanel() {
+  const data = await getSlowTaggedValue();
+
+  return (
+    <div className="rounded-lg border p-5">
+      <div className="text-sm text-slate-700">
+        <div>
+          <span className="font-medium">computedAt:</span>{' '}
+          <span data-testid="computedAt" className="font-mono">
+            {data.computedAt}
+          </span>
+        </div>
+        <div className="mt-1">
+          <span className="font-medium">value:</span>{' '}
+          <span data-testid="value" className="font-mono">
+            {data.value}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function RevalidateDurationsPage() {
+  return (
+    <main className="mx-auto max-w-3xl p-10">
+      <div className="mb-6">
+        <Link
+          className="text-sm text-blue-600 hover:underline"
+          href="/cache-lab"
+        >
+          ← Back to Cache Lab
+        </Link>
+      </div>
+
+      <header className="mb-6">
+        <h1 className="text-2xl font-semibold">
+          revalidateTag durations (SWR stale window)
+        </h1>
+        <p className="mt-2 text-sm text-slate-600">
+          Calls <code>revalidateTag(tag, {'{ expire: 2 }'})</code>. The handler
+          should mark the tag stale immediately while keeping the Redis entry so
+          the next request can serve stale content (SWR) during refresh.
+        </p>
+      </header>
+
+      <Suspense
+        fallback={
+          <div className="rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+            Loading cached content… (first load can take ~2.5s)
+          </div>
+        }
+      >
+        <CachedPanel />
+      </Suspense>
+
+      <form action={triggerDeferredRevalidateTag} className="mt-6">
+        <button
+          className="rounded-md border border-blue-600 bg-white px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-50"
+          type="submit"
+        >
+          revalidateTag(&apos;cache-lab:durations&apos;, {'{ expire: 2 }'})
+        </button>
+      </form>
+
+      <div className="mt-6 rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+        <p className="font-medium">How to observe SWR invalidation</p>
+        <ol className="mt-2 list-decimal space-y-1 pl-5">
+          <li>Load once (expect ~2.5s).</li>
+          <li>Click the button, then reload immediately.</li>
+          <li>
+            The reload should still show the old values (fast SWR). After
+            background refresh (~2.5s), values should change.
+          </li>
+        </ol>
+      </div>
+    </main>
+  );
+}

package/test/nextjs-test-projects/next-app-16-3-0-cache-components/src/app/cache-lab/use-cache-remote/page.tsx

@@ -0,0 +1,85 @@
+import Link from 'next/link';
+import { Suspense } from 'react';
+import { cacheTag, updateTag } from 'next/cache';
+
+async function getRemoteCachedValue() {
+  'use cache: remote';
+
+  cacheTag('cache-lab:remote');
+
+  return {
+    value: Math.random(),
+    computedAt: Date.now(),
+  };
+}
+
+async function triggerUpdateTag() {
+  'use server';
+  updateTag('cache-lab:remote');
+}
+
+async function RemotePanel() {
+  const data = await getRemoteCachedValue();
+
+  return (
+    <div className="rounded-lg border p-5">
+      <div className="text-sm text-slate-700">
+        <div>
+          <span className="font-medium">computedAt:</span>{' '}
+          <span data-testid="computedAt" className="font-mono">
+            {data.computedAt}
+          </span>
+        </div>
+        <div className="mt-1">
+          <span className="font-medium">value:</span>{' '}
+          <span data-testid="value" className="font-mono">
+            {data.value}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function UseCacheRemotePage() {
+  return (
+    <main className="mx-auto max-w-3xl p-10">
+      <div className="mb-6">
+        <Link
+          className="text-sm text-blue-600 hover:underline"
+          href="/cache-lab"
+        >
+          ← Back to Cache Lab
+        </Link>
+      </div>
+
+      <header className="mb-6">
+        <h1 className="text-2xl font-semibold">use cache: remote</h1>
+        <p className="mt-2 text-sm text-slate-600">
+          Exercises the <code>cacheHandlers.remote</code> handler backed by
+          Redis. Values should stay stable across reloads until{' '}
+          <code>updateTag</code> runs.
+        </p>
+      </header>
+
+      <Suspense
+        fallback={
+          <div className="rounded-lg border bg-slate-50 p-5 text-sm text-slate-700">
+            Loading remote cached content…
+          </div>
+        }
+      >
+        <RemotePanel />
+      </Suspense>
+
+      <form action={triggerUpdateTag} className="mt-6">
+        <button
+          className="rounded-md border border-blue-600 bg-white px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-50"
+          type="submit"
+        >
+          updateTag(&apos;cache-lab:remote&apos;)
+        </button>
+      </form>
+    </main>
+  );
+}

package/test/playwright/cache-lab.spec.ts

@@ -124,6 +124,81 @@ test.describe('Cache Lab (Cache Components)', () => {
     expect(payloadB).not.toBe(payloadA1);
   });
 
+  test('use cache: remote values are stable until updateTag', async ({
+    page,
+  }) => {
+    await page.goto('/cache-lab/use-cache-remote');
+
+    const computedAt = page.getByTestId('computedAt');
+    const value = page.getByTestId('value');
+
+    await expect(computedAt).toBeVisible();
+
+    const beforeComputedAt = await computedAt.textContent();
+    const beforeValue = await value.textContent();
+
+    await page.reload();
+    await expect(computedAt).toBeVisible();
+    expect(await computedAt.textContent()).toBe(beforeComputedAt);
+    expect(await value.textContent()).toBe(beforeValue);
+
+    await page
+      .getByRole('button', { name: "updateTag('cache-lab:remote')" })
+      .click();
+    await page.waitForLoadState('networkidle');
+
+    await expect(computedAt).toBeVisible();
+    expect(await computedAt.textContent()).not.toBe(beforeComputedAt);
+    expect(await value.textContent()).not.toBe(beforeValue);
+  });
+
+  test('revalidateTag with durations can serve stale values before refresh completes', async ({
+    page,
+  }) => {
+    await page.goto('/cache-lab/revalidate-durations');
+
+    const computedAt = page.getByTestId('computedAt');
+    const value = page.getByTestId('value');
+
+    await expect(computedAt).toBeVisible();
+
+    const beforeComputedAt = await computedAt.textContent();
+    const beforeValue = await value.textContent();
+
+    const actionResponse = page.waitForResponse(
+      (res) =>
+        res.request().method() === 'POST' &&
+        res.url().includes('/cache-lab/revalidate-durations'),
+    );
+    await page
+      .getByRole('button', {
+        name: "revalidateTag('cache-lab:durations', { expire: 2 })",
+      })
+      .click();
+    await actionResponse;
+
+    // Reload as soon as the Server Action has landed. Do not wait for
+    // networkidle — that can let the ~2.5s background refresh finish first.
+    await page.reload();
+    await expect(computedAt).toBeVisible();
+
+    const afterRevalidateComputedAt = await computedAt.textContent();
+    const afterRevalidateValue = await value.textContent();
+
+    // SWR: ideally the first reload still serves previous values. If background
+    // refresh already completed, skip the stale assertion and verify eventual refresh.
+    if (afterRevalidateComputedAt === beforeComputedAt) {
+      expect(afterRevalidateValue).toBe(beforeValue);
+    }
+
+    await page.waitForTimeout(5000);
+    await page.reload();
+    await expect(computedAt).toBeVisible();
+
+    expect(await computedAt.textContent()).not.toBe(beforeComputedAt);
+    expect(await value.textContent()).not.toBe(beforeValue);
+  });
+
   test('stale-while-revalidate demo eventually produces a new value after revalidateTag', async ({
     page,
   }) => {