qguard

library0.3.1jsnpmunverified

qguard (v0.3.1) detects N+1 queries at the database driver level by monkey-patching pg and mysql2. Zero configuration, works with any ORM (Prisma 7, Drizzle, TypeORM, Knex, Sequelize, Kysely, raw drivers). Ships TypeScript types, zero runtime dependencies under 40 KB. Released weekly on npm. Key differentiator: operates below ORMs so it catches N+1 from any abstraction layer, unlike ORM-specific lint rules. Test framework integrations for Vitest and Jest available as subpath exports ('qguard/vitest', 'qguard/jest'). Requires Node >=20. Note: Prisma 6 not supported (it bypasses pg/mysql2).

testing

npm install qguard

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QGUARD

qguard

testingjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

assertNoNPlusOne

✓ import { assertNoNPlusOne } from 'qguard/vitest'

✗ import { assertNoNPlusOne } from 'qguard'

Must import from 'qguard/vitest' or 'qguard/jest' subpath; no default export from main entry.

queryBudget

✓ import { queryBudget } from 'qguard/vitest'

✗ const { queryBudget } = require('qguard/vitest')

ESM-only; require() will fail because package type is module.

assertScaling

✓ import { assertScaling } from 'qguard/vitest'

Available only in Vitest/Jest subpath; not exported from main entry.

Shows how to wrap a test function with assertNoNPlusOne to detect N+1 queries; uses Vitest and an async handler.

import { assertNoNPlusOne } from 'qguard/vitest' import { test } from 'vitest' // Example handler that might cause N+1 export async function handler(req, res) { const users = await db.query('SELECT * FROM users').rows for (const user of users) { await db.query('SELECT * FROM profiles WHERE user_id = $1', [user.id]) } res.json(users) } test('listing users does not N+1', async () => { await assertNoNPlusOne(() => handler({}, { json: () => {} }), { threshold: 2, ignore: [/pg_catalog/], }) })

Debug

Known issues

gotchaPrisma 6 is not supported; qguard only works with Prisma 7 (which uses @prisma/adapter-pg) because Prisma 6's Rust query engine bypasses the pg driver.

fix

Upgrade to Prisma 7 and use @prisma/adapter-pg, or use raw pg/mysql2.

affects: >=0.0.0

gotchaqguard patches pg and mysql2 at import time; if you import qguard before those drivers, the patch may not apply correctly.

fix

Ensure pg/mysql2 are imported before qguard, or import qguard first (the library handles order internally, but avoid dynamic requires).

affects: >=0.0.0

gotchaassertNoNPlusOne only detects N+1 patterns outside transactions by default; enable detectInsideTransactions option if needed.

fix

Pass { detectInsideTransactions: true } to the options object.

affects: >=0.0.0

gotchaThe package uses ESM-only (type: module). require() will fail with ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import() in CommonJS projects.

affects: >=0.0.0

gotchaassertScaling requires the setup function to clean up state between cardinalities; leftover data can cause false positives.

fix

Ensure setup deletes/recreates all relevant records.

affects: >=0.0.0

gotchaThe threshold option defaults to 2; a query appearing more than 2 times is flagged. For low-data tests, this may produce false positives.

fix

Adjust threshold higher (e.g., 5) if your test naturally fires many similar queries.

affects: >=0.0.0

gotchaqguard relies on AsyncLocalStorage; Node 20 is required. Older Node versions are not supported.

fix

Use Node >=20.

affects: >=0.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require('qguard/vitest') in a CommonJS context.

fix

Change to import { assertNoNPlusOne } from 'qguard/vitest' or use dynamic import().

Cannot find module 'qguard/vitest'

Subpath export not resolved; possibly due to bundler misconfiguration or old Node version.

fix

Update Node to >=20 and ensure your bundler supports package.json exports field (or use full path 'node_modules/qguard/dist/vitest.js').

qguard: no queries detected. Did you patch the correct driver?

The database driver (pg/mysql2) is not installed or qguard imported before the driver.

fix

Install the matching driver (pg or mysql2) and ensure it is imported before the test runs.

AssertionError: Expected no N+1 queries, but found 3 patterns

assertNoNPlusOne detected query fingerprints repeated beyond threshold.

fix

Check your code for N+1 patterns, adjust threshold, or use ignore option to filter known non-N+1 queries.

TypeError: qguard_default is not a function

Using default import 'import qguard from 'qguard'' which does not exist.

fix

Use named imports like 'import { assertNoNPlusOne } from 'qguard/vitest''.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

pgoptionalPatched at runtime to detect N+1 queries; must be installed in the project.

mysql2optionalPatched at runtime to detect N+1 queries; must be installed in the project.

@jest/globalsoptionalRequired for Jest integration (via 'qguard/jest').

expressoptionalOptional: used in example integrations but not required.

fastifyoptionalOptional: used in example integrations but not required.

honooptionalOptional: used in example integrations but not required.

vitestoptionalRequired for Vitest integration (via 'qguard/vitest').

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/oniani1/queryguard ↗

packageqguard ↗

homepagehttps://oniani1.github.io/queryguard ↗