feat(orm)!: Add typed typed mutation hooks #2365

[genu]

fixes: #2365

Summary by CodeRabbit

• New Features

  • Added support for model-specific entity mutation hooks, with strongly typed loaded entities.
  • Model-specific hooks can run alongside catch-all hooks and receive the correct entity snapshots.
  • Per-model configuration for whether after-mutation hooks run inside or outside transactions.

• Bug Fixes

  • Fixed mutation hook handling so model-specific hooks execute even when only per-model hooks are provided.
  • Improved scheduling so after-mutation hooks correctly follow in-transaction vs out-of-transaction behavior.

• Breaking Changes

  • Catch-all entity mutation hooks must now be registered under onEntityMutation.$all.

• Tests

  • Expanded E2E coverage for per-model mutation hooks and updated related regression tests.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Entity mutation hooks

Layer / File(s)	Summary
Model-scoped hook contracts packages/orm/src/client/plugin.ts	Adds typed per-model before/after mutation hook arguments and extends EntityMutationHooksDef with model-specific hook definitions.
Hook detection and dispatch packages/orm/src/client/executor/zenstack-query-executor.ts	Executes catch-all and model-specific hooks independently, including per-model transaction-scope resolution.
Hook registration updates BREAKINGCHANGES.md, tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts, tests/regression/test/issue-586.test.ts	Moves catch-all hook registrations under onEntityMutation.$all.
Per-model hook behavior tests tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts	Covers model targeting, hook composition, before-entity propagation, and typed loaded entities.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title matches the main change: adding typed mutation hooks for ORM, and it is concise and specific.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts (1)

806-831: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Test can silently pass without executing any assertion.

All expect calls are inside afterEntityMutation; there's no outer check confirming the hook actually ran. If per-model after-hook dispatch regresses, this test would still pass with zero assertions executed.

✅ Proposed fix

     it('per-model hooks infer correct entity types', async () => {
+        expect.assertions(2);
         const client = _client.$use({

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts` around lines 806 -
831, Add an outer execution flag to the “per-model hooks infer correct entity
types” test, set it inside User.afterEntityMutation after the hook runs, and
assert it after client.user.create completes. Keep the existing entity type and
email assertions unchanged.

packages/orm/src/client/executor/zenstack-query-executor.ts (1)

376-386: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Optional: extract shared per-model hook lookup.

The (onEntityMutation as Record<string, any>)[mutationInfo.model] lookup pattern is duplicated between callBeforeMutationHooks and callAfterMutationHooks. A small private helper (e.g. getModelHooks(onEntityMutation, model)) would remove the duplication, though the current repetition is small and low-risk.

Also applies to: 417-429

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/orm/src/client/executor/zenstack-query-executor.ts` around lines 376
- 386, Extract the duplicated per-model hook lookup into a private helper, such
as getModelHooks, and use it in both callBeforeMutationHooks and
callAfterMutationHooks. Keep the helper’s behavior equivalent to the existing
onEntityMutation Record lookup for mutationInfo.model.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/orm/src/client/executor/zenstack-query-executor.ts`:
- Around line 125-132: Update the hasEntityMutationPluginsWithAfterMutationHooks
getter to accept the mutationModel and check only that model’s per-model
afterEntityMutation hook, while preserving catch-all hook detection. Update the
needLoadAfterMutationEntities call site to pass the existing mutationModel,
preventing hooks registered for other models from triggering entity loading.

---

Nitpick comments:
In `@packages/orm/src/client/executor/zenstack-query-executor.ts`:
- Around line 376-386: Extract the duplicated per-model hook lookup into a
private helper, such as getModelHooks, and use it in both
callBeforeMutationHooks and callAfterMutationHooks. Keep the helper’s behavior
equivalent to the existing onEntityMutation Record lookup for
mutationInfo.model.

In `@tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts`:
- Around line 806-831: Add an outer execution flag to the “per-model hooks infer
correct entity types” test, set it inside User.afterEntityMutation after the
hook runs, and assert it after client.user.create completes. Keep the existing
entity type and email assertions unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c7f981f2-b6a7-49fb-a7d5-79f609339101

📥 Commits

Reviewing files that changed from the base of the PR and between b83efad and ce01ceb.

📒 Files selected for processing (3)

• packages/orm/src/client/executor/zenstack-query-executor.ts
• packages/orm/src/client/plugin.ts
• tests/e2e/orm/plugin-infra/entity-mutation-hooks.test.ts