Registry /
database / prisma-nested-middleware
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createNestedMiddleware
✓ import { createNestedMiddleware } from 'prisma-nested-middleware'
✗ const createNestedMiddleware = require('prisma-nested-middleware')
This is the primary function to wrap your custom middleware. The package primarily uses ESM, though CommonJS `require` might work with transpilation or specific Node.js configurations.
NestedParams
✓ import type { NestedParams } from 'prisma-nested-middleware'
This TypeScript type extends `Prisma.MiddlewareParams` with additional fields like `scope`, `modifier`, `logicalOperators`, and `relations` for handling nested contexts.
PrismaClient
✓ import { PrismaClient } from '@prisma/client'
While not from this package, `PrismaClient` is essential for setting up the middleware with `$use` and is often mistakenly imported from `prisma-nested-middleware` by new users.
This quickstart demonstrates how to apply `prisma-nested-middleware` to your Prisma client and shows an example of intercepting and modifying nested 'create' operations on 'Post' models, logging parameters and results. It also includes handling for varying `params.args` structures across major versions for nested 'create' actions.
import { PrismaClient } from '@prisma/client';
import { createNestedMiddleware, NestedParams } from 'prisma-nested-middleware';
const prisma = new PrismaClient();
prisma.$use(createNestedMiddleware(async (params: NestedParams, next) => {
console.log(`[${params.model}] Action: ${params.action}`);
if (params.scope) {
console.log(' Scope:', params.scope.parentParams?.model, '->', params.scope.relation?.to);
}
// Example: Modify 'create' args for a nested operation
if (params.action === 'create' && params.model === 'Post' && params.scope) {
console.log(' Intercepted nested Post create:', params.args);
// Ensure params.args structure for nested creates, which can vary by version
if ('data' in params.args && typeof params.args.data === 'object') {
// For v2.x to <v3.0.0, data was inside params.args.data
params.args.data.title = `[Nested] ${params.args.data.title}`;
} else if (typeof params.args === 'object') {
// For v3.x onwards, data is directly in params.args
params.args.title = `[Nested] ${params.args.title}`;
}
}
const result = await next(params);
if (result) {
console.log(`[${params.model}] Result for ${params.action}:`, result);
}
return result;
}));
async function main() {
await prisma.user.deleteMany({});
await prisma.post.deleteMany({});
const user = await prisma.user.create({
data: {
email: 'test@example.com',
name: 'Test User',
posts: {
create: [
{ title: 'First Post', content: 'Content 1' },
{ title: 'Second Post', content: 'Content 2' }
],
},
},
include: { posts: true },
});
console.log('\nCreated user with nested posts:', JSON.stringify(user, null, 2));
}
main().catch(console.error).finally(() => prisma.$disconnect());
Debug
Known issues
breakingVersion 4.0.0 removed the ability for middleware to be called with the 'select' action for 'select' objects found within an 'include' statement. Middleware that relied on this specific call pattern will no longer function as expected for such scenarios.fixRe-evaluate middleware logic for handling 'select' objects inside 'include' operations. You may need to manually traverse the `include` structure or adapt to alternative ways of modifying these specific nested selections, if applicable within your use case.
affects: >=4.0.0
breakingIn version 3.0.0, the structure for nested 'create' actions was reverted: `params.args` no longer moves its content into a `data` field. This directly reverses the breaking change introduced in v2.0.0. If you upgraded from v2.x, your middleware might be broken.fixUpdate middleware for nested 'create' operations to access `params.args` directly for the data, removing any `.data` access that was added for v2.x compatibility. Example: `params.args.title` instead of `params.args.data.title`.
affects: >=3.0.0 <4.0.0
breakingVersion 2.0.0 introduced a breaking change where for nested 'create' actions, `params.args` would contain its content within a `data` field (e.g., `params.args.data`). Middleware written for prior versions would break, as they would expect `params.args` to directly hold the data.fixUpdate middleware for nested 'create' operations to access the data via `params.args.data`. Example: `params.args.data.title` instead of `params.args.title`.
affects: >=2.0.0 <3.0.0
gotchaThe `NestedParams` object provided by this library extends `Prisma.MiddlewareParams` with additional fields like `scope`, `modifier`, `logicalOperators`, and `relations`. Not accounting for these enriched fields can lead to incomplete middleware logic or runtime errors when attempting to access them.fixAlways import and type-check against `NestedParams` to ensure full access to the nested context. Refer to the library's documentation for the structure and purpose of `scope` and its sub-fields to correctly implement conditional logic for nested operations.
affects: >=1.0.0
gotchaPrisma's built-in `$use` middleware is deprecated in Prisma ORM v4.16.0 and removed in v6.14.0. Users of `prisma-nested-middleware` should be aware that the underlying mechanism it leverages is being phased out by Prisma.fixIf upgrading to Prisma ORM versions that deprecate or remove `$use` middleware, consider migrating to `prisma-extension-nested-operations`, which leverages Prisma Client Extensions for a more future-proof approach. The maintainer of `prisma-nested-middleware` also maintains `prisma-extension-nested-operations`.
affects: >=4.16.0 of @prisma/client
Errors
Common errors & fixes
Prisma middleware not being called for nested writes
Prisma's native middleware (`prisma.$use`) is designed for top-level queries only and does not inherently intercept operations within nested `create`, `update`, or `connect` clauses.
fixWrap your middleware function with `createNestedMiddleware` from this library and apply it to your `PrismaClient` using `$use`. This library specifically enables middleware execution for nested operations.
Error parsing invalid logical where arrays
Older versions of `prisma-nested-middleware` had a bug in parsing malformed logical `where` conditions (e.g., `AND`, `OR`, `NOT`).
fixUpgrade `prisma-nested-middleware` to version `3.0.2` or higher, which includes a fix for this issue. Additionally, ensure your `where` arrays adhere to Prisma's expected structure for logical operators.
Queries that use Json NullTypes are not working correctly
A bug in older versions of `prisma-nested-middleware` affected queries involving Prisma's JSON `NullTypes`.
fixUpgrade `prisma-nested-middleware` to version `3.0.1` or higher. This version contains a fix for handling JSON `NullTypes` correctly.
Audit
Dependencies
@prisma/clientrequiredRequired peer dependency for Prisma ORM functionality.