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

package/src/utils/cacheTtl.ts

@@ -0,0 +1,71 @@
+export type ResolveCacheEntryTtlContext = {
+  revalidate?: number | false;
+  cacheControl?: { revalidate?: number | false; expire?: number | undefined };
+};
+
+export type ResolveCacheEntryTtlData = {
+  kind?: string;
+  revalidate?: number | false;
+} | null;
+
+export type ResolveCacheEntryTtlOptions = {
+  estimateExpireAge: (staleAge: number) => number;
+  defaultStaleAge: number;
+};
+
+/**
+ * Resolves the Redis TTL (seconds) for an ISR / incremental-cache entry.
+ *
+ * Official Next.js semantics (cache-handler-redis example + self-hosting docs):
+ * - Key TTL on `cacheControl.expire`, never on `revalidate` alone.
+ * - Past `revalidate` an entry is only stale (SWR); evicting at that boundary
+ *   would defeat background refresh.
+ * - When no finite `expire` is provided, fall back to `estimateExpireAge(revalidate)`
+ *   for legacy Pages Router / pre-cacheLife callers that only pass `revalidate`.
+ * - When neither `expire` nor `revalidate` is available, return `undefined` (no TTL;
+ *   rely on tag-based invalidation). This is intentional — not a missing
+ *   `defaultStaleAge` fallback. `revalidate: false` is a separate branch above
+ *   and is covered by unit + Pages Router integration tests (`/static-forever`).
+ */
+export function resolveCacheEntryTtlSeconds(
+  ctx: ResolveCacheEntryTtlContext,
+  data: ResolveCacheEntryTtlData,
+  options: ResolveCacheEntryTtlOptions,
+): number | undefined {
+  const expire = ctx.cacheControl?.expire;
+
+  if (Number.isFinite(expire) && expire! > 0) {
+    return Math.max(1, Math.ceil(expire!));
+  }
+
+  const revalidate = resolveRevalidateValue(ctx, data);
+
+  if (revalidate === false) {
+    return options.estimateExpireAge(options.defaultStaleAge);
+  }
+
+  if (revalidate && Number.isSafeInteger(revalidate) && revalidate > 0) {
+    return options.estimateExpireAge(revalidate);
+  }
+
+  return undefined;
+}
+
+function resolveRevalidateValue(
+  ctx: ResolveCacheEntryTtlContext,
+  data: ResolveCacheEntryTtlData,
+): number | false | undefined {
+  if (data?.kind === 'FETCH' && data.revalidate !== undefined) {
+    return data.revalidate;
+  }
+  if (ctx.revalidate !== undefined) {
+    return ctx.revalidate;
+  }
+  if (ctx.cacheControl?.revalidate !== undefined) {
+    return ctx.cacheControl.revalidate;
+  }
+  if (data?.revalidate !== undefined) {
+    return data.revalidate;
+  }
+  return undefined;
+}

package/src/utils/compareAndUnlink.ts

@@ -0,0 +1,29 @@
+/**
+ * Atomically delete `key` only if its current value still equals `expected`.
+ * GET then UNLINK would race: another instance can SET a replacement in between.
+ */
+const COMPARE_AND_UNLINK = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('UNLINK', KEYS[1])
+end
+return 0
+`;
+
+type EvalClient = {
+  eval(
+    script: string,
+    options: { keys: string[]; arguments: string[] },
+  ): Promise<unknown>;
+};
+
+export async function compareAndUnlink(
+  client: EvalClient,
+  key: string,
+  expected: string,
+): Promise<boolean> {
+  const deleted = await client.eval(COMPARE_AND_UNLINK, {
+    keys: [key],
+    arguments: [expected],
+  });
+  return deleted === 1 || deleted === 1n;
+}

package/src/utils/redisConnection.ts

@@ -0,0 +1,17 @@
+/**
+ * Matches `PHASE_PRODUCTION_BUILD` from `next/constants`.
+ *
+ * Hardcoded so ESM builds (tsup `shims: false`) never call `require()`.
+ * A dynamic `require('next/constants')` throws in ESM, and catching that used
+ * to cache `undefined` for the process lifetime — disabling the build-phase
+ * Redis skip entirely.
+ */
+export const PHASE_PRODUCTION_BUILD = 'phase-production-build';
+
+/**
+ * Returns true during `next build` so handlers can skip opening Redis
+ * connections. Matches the official Next.js cache-handler-redis example.
+ */
+export function shouldDeferRedisConnection(): boolean {
+  return process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD;
+}

package/src/utils/tagRevalidation.ts

@@ -0,0 +1,162 @@
+/**
+ * Tag manifest matching Next.js 16.0–16.3
+ * `next/dist/server/lib/cache-handlers/default.js` `updateTags`
+ * and `next/dist/server/lib/incremental-cache/tags-manifest.external.js`.
+ *
+ * `revalidateTag(tag, profile)` resolves `cacheLife[profile].expire` (seconds)
+ * and calls `updateTags(tags, { expire })`. `updateTag` / no profile calls
+ * `updateTags(tags)` with no durations (immediate hard expire).
+ */
+export type TagManifestEntry = {
+  stale?: number;
+  expired?: number;
+};
+
+/**
+ * Read a tag-manifest field from Redis.
+ *
+ * Next.js 16.0–16.3 never persists plain numbers here — `updateTags` always
+ * writes `{ stale, expired }` via `applyTagUpdate()`. A plain number can only
+ * appear from older releases of this package that stored `Date.now()` directly
+ * (before the `{ stale, expired }` manifest). ISR uses a separate Redis hash
+ * (`__revalidated_tags__`) and is unaffected.
+ *
+ * A future-looking plain number is not produced by Next.js and is not the same
+ * as intentional SWR (`{ stale: now, expired: now + N }`). It can only happen
+ * when another instance wrote the timestamp with a faster clock (NTP skew).
+ * Clamp to `now` on read so the revalidation is not delayed on slower instances.
+ */
+export function normalizeTagManifest(
+  stored: unknown,
+  now: number = Date.now(),
+): TagManifestEntry {
+  if (typeof stored === 'number' && Number.isFinite(stored)) {
+    return { expired: Math.min(stored, now) };
+  }
+
+  if (stored && typeof stored === 'object') {
+    const rec = stored as {
+      stale?: unknown;
+      expired?: unknown;
+      last?: unknown;
+      pending?: unknown;
+    };
+    const stale =
+      typeof rec.stale === 'number' && Number.isFinite(rec.stale)
+        ? rec.stale
+        : typeof rec.last === 'number' && Number.isFinite(rec.last)
+          ? rec.last
+          : undefined;
+    const expired =
+      typeof rec.expired === 'number' && Number.isFinite(rec.expired)
+        ? rec.expired
+        : typeof rec.pending === 'number' && Number.isFinite(rec.pending)
+          ? rec.pending
+          : undefined;
+    return {
+      ...(stale !== undefined ? { stale } : {}),
+      ...(expired !== undefined ? { expired } : {}),
+    };
+  }
+
+  return {};
+}
+
+/**
+ * Mirrors Next.js DefaultCacheHandler.updateTags().
+ */
+export function applyTagUpdate(
+  existing: TagManifestEntry,
+  durations: { expire?: number } | undefined,
+  now: number,
+): TagManifestEntry {
+  if (durations) {
+    const updates = { ...existing };
+    updates.stale = now;
+    if (durations.expire !== undefined) {
+      updates.expired = now + durations.expire * 1000;
+    }
+    return updates;
+  }
+
+  return {
+    ...existing,
+    expired: now,
+  };
+}
+
+/**
+ * Immediate hard-expires (`expired <= now`) are stored as a plain number so
+ * older package versions that JSON.parse + numeric-compare the hash field still
+ * see the invalidation during a rolling deploy. SWR windows stay objects.
+ */
+export function persistableTagManifest(
+  entry: TagManifestEntry,
+  now: number,
+): TagManifestEntry | number {
+  if (
+    typeof entry.expired === 'number' &&
+    entry.expired <= now &&
+    (entry.stale === undefined || entry.stale <= entry.expired)
+  ) {
+    return entry.expired;
+  }
+  return entry;
+}
+
+/**
+ * Mirrors Next.js `areTagsExpired`: hard miss once `expired` has elapsed
+ * and is newer than the entry timestamp.
+ */
+export function areTagsExpired(
+  tags: string[],
+  entryTimestamp: number,
+  now: number,
+  getEntry: (tag: string) => TagManifestEntry | undefined,
+): boolean {
+  for (const tag of tags) {
+    const expiredAt = getEntry(tag)?.expired;
+    if (
+      typeof expiredAt === 'number' &&
+      expiredAt <= now &&
+      expiredAt > entryTimestamp
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Mirrors Next.js `areTagsStale`: SWR when `stale` is newer than the entry.
+ */
+export function areTagsStale(
+  tags: string[],
+  entryTimestamp: number,
+  getEntry: (tag: string) => TagManifestEntry | undefined,
+): boolean {
+  for (const tag of tags) {
+    const staleAt = getEntry(tag)?.stale ?? 0;
+    if (typeof staleAt === 'number' && staleAt > entryTimestamp) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Mirrors Next.js DefaultCacheHandler.getExpiration(): max `expired` or 0.
+ */
+export function maxExpiredTimestamp(
+  tags: string[],
+  getEntry: (tag: string) => TagManifestEntry | undefined,
+): number {
+  let max = 0;
+  for (const tag of tags) {
+    const expired = getEntry(tag)?.expired || 0;
+    if (expired > max) {
+      max = expired;
+    }
+  }
+  return max;
+}

package/test/README.md

@@ -83,12 +83,12 @@ pnpm test:integration:build-id-prefix
 
 Integration tests specific to Next.js 16 Cache Components (`use cache`). CI runs them against the 16.0, 16.2, and 16.3 Cache Components test apps.
 
-| File                                   | What it tests                                                                                          |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `cache-components.integration.test.ts` | `use cache` lifecycle: store, retrieve, tag invalidation, `cacheLife` expiry                           |
-| `redis-kill-reconnect.test.ts`         | Graceful recovery when Redis drops and reconnects (main client ping only)                              |
-| `redis-subscriber-outage.test.ts`      | Issue #86: subscriber PubSub does not recover after Redis outage (expected to fail until bug is fixed) |
-| `redis-quit-vs-disconnect.test.ts`     | `quit()` does not reliably close a subscriber during an outage; `disconnect()` does                    |
+| File                                   | What it tests                                                                                                                                                                                                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cache-components.integration.test.ts` | `use cache` lifecycle: store, retrieve, tag invalidation, `cacheLife` expiry, and every `revalidateTag` expire setting (`max`/`default`/`seconds`/`minutes`/`hours`/`days`/`weeks`, `{ expire: N }`, `{ expire: 0 }`, omitted profile) against `next start` + Redis |
+| `redis-kill-reconnect.test.ts`         | Graceful recovery when Redis drops and reconnects (main client ping only)                                                                                                                                                                                           |
+| `redis-subscriber-outage.test.ts`      | Issue #86: subscriber PubSub does not recover after Redis outage (expected to fail until bug is fixed)                                                                                                                                                              |
+| `redis-quit-vs-disconnect.test.ts`     | `quit()` does not reliably close a subscriber during an outage; `disconnect()` does                                                                                                                                                                                 |
 
 `redis-kill-reconnect.test.ts` uses a container runtime and auto-detects `podman` first, then `docker`. You can force runtime selection with `CONTAINER_RUNTIME=podman` or `CONTAINER_RUNTIME=docker`.
 
@@ -121,10 +121,10 @@ Browser-based tests that validate Cache Components behavior from the user's pers
 
 The Vitest cache-components integration tests verify the server-side plumbing (Redis state, HTTP responses). Playwright closes the gap by testing the full user-facing flow.
 
-| File                 | What it tests                                                                                                        |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `cache-lab.spec.ts`  | `use cache` stability, tag invalidation (`updateTag`/`revalidateTag`), runtime cookie-based cache keys, SWR behavior |
-| `update-tag.spec.ts` | `updateTag` via Server Actions (button click → action → UI update)                                                   |
+| File                 | What it tests                                                                                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cache-lab.spec.ts`  | `use cache` / `use cache: remote` stability, tag invalidation (`updateTag`/`revalidateTag`), `revalidateTag` durations (SWR stale window), runtime cookie-based cache keys, SWR behavior |
+| `update-tag.spec.ts` | `updateTag` via Server Actions (button click → action → UI update)                                                                                                                       |
 
 ```bash
 pnpm test:e2e

package/test/nextjs-test-projects/next-app-16-0-11-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-0-11-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-0-11-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-0-11-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-0-11-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-0-11-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-2-6-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-2-6-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-2-6-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(),
+  };
+}