Prisma Nested Middleware

Common errors

• Prisma middleware not being called for nested writes

  cause 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.
  fix Wrap 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

  cause Older versions of `prisma-nested-middleware` had a bug in parsing malformed logical `where` conditions (e.g., `AND`, `OR`, `NOT`).
  fix Upgrade `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

  cause A bug in older versions of `prisma-nested-middleware` affected queries involving Prisma's JSON `NullTypes`.
  fix Upgrade `prisma-nested-middleware` to version `3.0.1` or higher. This version contains a fix for handling JSON `NullTypes` correctly.

Warnings

• breaking Version 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.
  Fix: Re-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.
• breaking In 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.
  Fix: Update 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`.
• breaking Version 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.
  Fix: Update middleware for nested 'create' operations to access the data via `params.args.data`. Example: `params.args.data.title` instead of `params.args.title`.
• gotcha The `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.
  Fix: Always 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.
• gotcha Prisma'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.
  Fix: If 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`.

Install

• npm install prisma-nested-middleware npm
• yarn add prisma-nested-middleware yarn
• pnpm add prisma-nested-middleware pnpm

Imports

• createNestedMiddleware
  wrong:

  const createNestedMiddleware = require('prisma-nested-middleware')

  correct:

  import { createNestedMiddleware } from '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.

Quickstart

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());