Fix stale cache-hit lifecycle claims in middleware doc comments by sorenbs · Pull Request #915 · prisma/prisma-next

sorenbs · 2026-07-04T00:08:22Z

Linked issue

Refs prisma/web#8008 (Prisma Next docs validation, which surfaced these stale comments). Stacked on #912 (examples/extensions-middleware-docs) — the corrected comments reference its slowQueryWarning example, so that PR must merge first. Sibling fix from the same validation pass: #913.

At a glance

// examples/prisma-next-demo/src/prisma/db.ts
middleware: [
  // Cache first: interceptors are consulted in registration order and
  // the first non-`undefined` result wins, so the cache gets first
  // claim. A hit skips only the driver call and per-row `onRow` hooks:
  // every middleware's `beforeExecute` (`lints`, `budgets`) has already
  // run before any `intercept` is consulted, and `afterExecute` still
  // fires for all of them with `source: 'middleware'`. The cache stores
  // raw rows; the runtime still runs `decodeRow` on the hit path, so
  // consumers see decoded values in both cases.
  createCacheMiddleware({ maxEntries: 1_000 }),
  lints(),
  budgets({
    maxRows: 10_000,
    defaultTableRows: 10_000,
    tableRows: { user: 10_000, post: 10_000 },
    maxLatencyMs: 1_000,
  }),
  slowQueryWarning({ thresholdMs: 250 }),
],

Before, this comment claimed a cache hit "short-circuits before any downstream middleware (lints, budgets) fires" — behavior the framework does not have.

Decision

Comment-only PR (no runtime change): correct three doc comments that describe middleware-lifecycle behavior the framework does not have.

db.ts middleware-order comment — reworded to state what cache-first ordering actually buys (intercept precedence) and what a hit actually skips (the driver call and onRow, nothing else).
find-user-by-id-cached.ts observability note — dropped the claim that "telemetry is wired in front of the cache in db.ts"; no telemetry middleware exists anywhere in the repo. The note now states the real mechanism (afterExecute fires for every middleware on a hit, tagged source: 'middleware') and points at slowQueryWarning, the actual observer registered in db.ts.
middleware-cache package doc — the package's own hook documentation carried the same error ("the runtime skips beforeExecute, runDriver, and onRow") and is the likely origin of the stale example wording. Fixed the beforeExecute claim.

Reviewer notes

The third file (packages/3-extensions/middleware-cache/src/cache-middleware.ts) is outside the examples scope the validation flagged, but it carries the identical false claim and likely seeded it. One-sentence doc fix; happy to split it out if you prefer this PR examples-only.
This PR targets the Add slow-query warning custom middleware example to prisma-next-demo #912 branch, so the diff shown is exactly the three-file comment fix. When Add slow-query warning custom middleware example to prisma-next-demo #912 merges, GitHub retargets this to main automatically (or I can rebase).
I audited the other "short-circuit" mentions across examples/ and the cache package: they all use the term in the accurate sense (the driver is skipped) and stand unchanged.
No Linear ticket exists for this fix (it comes from the docs-validation GitHub issue), so the title follows the plain style of Add slow-query warning custom middleware example to prisma-next-demo #912/docs: update Supabase runtime README #913 rather than the TML-NNNN: convention; left unchecked in the checklist below.
The pre-commit lint-deps hook could not run locally (dependency-cruiser requires Node ≥ 24; the local shell had 23.7), so the commit bypassed it. The diff is comment-only with imports untouched; CI runs the authoritative check.

How the lifecycle actually works

The corrected wording follows the execution order that run-with-middleware.ts documents as canonical:

beforeExecute runs first, for every middleware. Family runtimes call runBeforeExecuteChain between AST → plan lowering and parameter encoding (sql-runtime.ts, before-execute-chain.ts), so lints and budgets vet every execution before any cache lookup happens.
intercept is consulted afterwards, in registration order; the first non-undefined result wins. That precedence is the actual reason to register the cache first.
A hit skips the driver call and per-row onRow hooks — nothing else. afterExecute still fires for every middleware with source: 'middleware', which is how observers such as slow-query-warning.ts see cached reads.

What changed & evidence

examples/prisma-next-demo/src/prisma/db.ts — middleware-order comment now describes intercept precedence and what a hit skips. The hit path is pinned by repositories.integration.test.ts (second cached call never reaches driver.execute).
examples/prisma-next-demo/src/orm-client/find-user-by-id-cached.ts — observability bullet now references slowQueryWarning instead of a nonexistent telemetry middleware. The afterExecute-fires-on-hit behavior is pinned by cache-middleware.test.ts.
packages/3-extensions/middleware-cache/src/cache-middleware.ts — hook doc no longer claims beforeExecute is skipped on a hit.

Testing performed

pnpm --filter prisma-next-demo --filter @prisma-next/middleware-cache typecheck — passes. Comment-only change with no behavioural delta, so no test updates.

Skill update

n/a — doc comments only; no user-facing surface (CLI, public API, config, error codes) changed.

Alternatives considered

Make the code match the comment instead (have a cache hit actually suppress lints/budgets): rejected — running beforeExecute before parameter encoding is deliberate, so middleware that mutates ParamRef values (e.g. bulk-encrypt) stays visible to encode; run-with-middleware.ts documents this lifecycle as canonical.
Drop the telemetry sentence entirely rather than rewording: rejected — the underlying fact (afterExecute still fires on hits, tagged source: 'middleware') is the useful teaching point, and Add slow-query warning custom middleware example to prisma-next-demo #912's slowQueryWarning finally gives it a real referent.
Restrict the PR to examples/ and leave the package doc stale: rejected — it is the same false claim and the likely origin; fixing it here keeps one logical concern in one review.

Checklist

All commits are signed off (git commit -s) per the DCO.
I read CONTRIBUTING.md and the change is scoped to one logical concern.
Tests are updated — n/a: doc-comment-only, no behavioural delta.
PR title in TML-NNNN: form — no Linear ticket exists for this fix; plain title per the precedent of Add slow-query warning custom middleware example to prisma-next-demo #912/docs: update Supabase runtime README #913 (see reviewer notes).
The Skill update section above is filled in (n/a — doc comments only).

The prisma-next-demo db.ts comment claimed that registering the cache first makes a hit short-circuit downstream middleware (lints, budgets), and find-user-by-id-cached.ts referenced a telemetry middleware that does not exist. Per run-with-middleware.ts, beforeExecute runs for every middleware before any intercept is consulted; a hit skips only the driver call and onRow hooks, and afterExecute still fires for all middleware with source: middleware. Reword both example comments accordingly, point the observability note at the real slowQueryWarning middleware, and fix the same beforeExecute-is-skipped claim in the middleware-cache package doc, which likely seeded the example wording. Found while validating the Prisma Next docs (prisma/web#8008). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Søren Bramer Schmidt <sorenbs@gmail.com>

coderabbitai · 2026-07-04T00:08:29Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 852c7aa3-6748-4dfb-8beb-10a4b7fb95c6

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch examples/middleware-lifecycle-doc-fixes

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

github-actions · 2026-07-04T00:11:29Z

size-limit report 📦

Path	Size
postgres / no-emit	160.74 KB (0%)
postgres / emit	147.87 KB (0%)
mongo / no-emit	98.2 KB (0%)
mongo / emit	89.39 KB (0%)
cf-worker / no-emit	188.88 KB (0%)
cf-worker / emit	174.17 KB (0%)

pkg-pr-new · 2026-07-04T00:11:39Z

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@915

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@915

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@915

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@915

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@915

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@915

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@915

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@915

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@915

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@915

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@915

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@915

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@915

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@915

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@915

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@915

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@915

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@915

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@915

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@915

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@915

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@915

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@915

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@915

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@915

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@915

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@915

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@915

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@915

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@915

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@915

@prisma-next/config-loader

npm i https://pkg.pr.new/@prisma-next/config-loader@915

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@915

@prisma-next/language-server

npm i https://pkg.pr.new/@prisma-next/language-server@915

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@915

prisma-next

npm i https://pkg.pr.new/prisma-next@915

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@915

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@915

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@915

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@915

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@915

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@915

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@915

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@915

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@915

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@915

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@915

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@915

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@915

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@915

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@915

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@915

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@915

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@915

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@915

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@915

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@915

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@915

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@915

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@915

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@915

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@915

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@915

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@915

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@915

commit: 9045a56

sorenbs requested a review from a team as a code owner July 4, 2026 00:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix stale cache-hit lifecycle claims in middleware doc comments#915

Fix stale cache-hit lifecycle claims in middleware doc comments#915
sorenbs wants to merge 1 commit into
examples/extensions-middleware-docsfrom
examples/middleware-lifecycle-doc-fixes

sorenbs commented Jul 4, 2026

Uh oh!

coderabbitai Bot commented Jul 4, 2026

Review skipped

Uh oh!

github-actions Bot commented Jul 4, 2026

Uh oh!

pkg-pr-new Bot commented Jul 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

sorenbs commented Jul 4, 2026

Linked issue

At a glance

Decision

Reviewer notes

How the lifecycle actually works

What changed & evidence

Testing performed

Skill update

Alternatives considered

Checklist

Uh oh!

coderabbitai Bot commented Jul 4, 2026

Review skipped

Uh oh!

github-actions Bot commented Jul 4, 2026

size-limit report 📦

Uh oh!

pkg-pr-new Bot commented Jul 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant