fix(fastify): per-query file tag, withRequestContext signature, and a first-party Fastify plugin

[veksen]

Addresses the three issues reported in the Fastify + drizzle-orm/postgres-js dogfooding feedback (Site#3434). The investigation showed two of them are shared with the mikroorm/typeorm packages, so those are fixed too.

1. file tag clobbered / dropped under concurrency (drizzle) — bug

The build-time caller was stored in a WeakMap keyed by the drizzle session, which a drizzle() instance shares across every query. Two queries built before either executed collided on that one entry: the first to reach prepareQuery emitted both call sites joined (fileA;fileB) and deleted the entry; the second emitted no file tag. This breaks under any real concurrency (two in-flight HTTP requests, Promise.all).

Fix: then → execute → _prepare → session.prepareQuery runs synchronously, so each built query object is tagged with its own caller, published into a module variable only for that synchronous window. Concurrent queries can't interleave inside it, and it's robust to building/awaiting in different orders (an ordered queue would not be).

2. withRequestContext's signature rejected Fastify's done — DX

next: () => Promise<unknown> failed tsc (TS2345) when passed Fastify's done: (err?: Error) => void (and Express's next). Widened to () => unknown (next is only handed to als.run, return ignored). Also corrected the JSDoc wording.

3. Fastify integration docs + first-party plugin — DX

Two silent pitfalls when wiring by hand: a plain register() encapsulates the onRequest hook (applies to nothing, no error), and wrapping the handler misses queries in earlier onRequest/preHandler hooks.

• New @query-doctor/sqlcommenter-<driver>/fastify → sqlcommenterFastify: a global onRequest hook (via the skip-override symbol — no extra dependency) using request.routeOptions.url + request.method, with an optional context callback. fastify added as an optional peer dependency.
• Fastify README section rewritten: recommends the plugin; for the manual path documents the fastify-plugin + onRequest + ordering requirements and routerPath → routeOptions.url (Fastify v5).

Verification

• Reproduced the concurrency bug, then confirmed the fix across select / insert / update / delete / findMany / findFirst / execute, sequential + Promise.all + out-of-order build/await. New regression tests fail on the old code, pass on the new.
• Signature: tsc confirms the new form compiles and the old one fails with the exact reported TS2345.
• Plugin verified against a real Fastify v5 app — auth-phase (onRequest/preHandler) and handler queries all get route/method/file; a plain encapsulated register is silently untagged (negative control). The manual fastify-plugin path was also validated end-to-end.
• All packages build (dual ESM/CJS) and pass: drizzle 19, mikroorm 30, typeorm 22.

Notes

• No version bumps included — drizzle/mikroorm/typeorm would each warrant a minor (new /fastify entry; drizzle also the bug fix). Happy to add.
• package-lock.json changes are only the fastify devDep tree (no fastify-plugin — that's user-installed, referenced only in the manual README example).

🤖 Generated with Claude Code