fix(orm): improve result field extension plugin's typing

[ymc9]

Summary by CodeRabbit

• New Features

  • Richer plugin result-field type inference and improved plugin declaration helpers.
  • $use now accepts inline plugin objects and plugin operations are documented as non-mutating.

• Refactor

  • Public API docs clarified (client binding, options, input validation, transactions, diagnostics, unuse semantics).
  • Plugin-related public typings and helpers reorganized for clearer usage.

• Tests

  • E2E tests updated to cover inline plugin usage, composition, removal, and related type-check scenarios.

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: Improve Result Field Extension Plugin's Typing

I've completed my analysis of this PR which focuses on improving TypeScript typing for result field extension plugins. Here's my comprehensive review:

Summary

This PR enhances the type system for result field extension plugins, providing better type inference and safety when defining computed fields that depend on model data. The changes span across 4 core files implementing a sophisticated typing mechanism.

Code Quality & Best Practices ✅

Strengths:

• Excellent Type Design: The ExtResultInferenceArgs type provides contextual typing that maps needs declarations to properly typed compute parameters
• Type Safety: The system prevents runtime errors by ensuring compute functions receive correctly typed data based on their needs declaration
• Backward Compatibility: Maintains existing APIs while adding enhanced typing
• Clear Separation: Well-organized type definitions with logical groupings and comprehensive JSDoc

Areas for Improvement:

• Some complex conditional types could benefit from additional inline comments explaining the type logic flow

Technical Implementation ✅

Key Improvements:

1. Enhanced Type Inference (plugin.ts:45-57):

   export type ExtResultInferenceArgs<Schema extends SchemaDef, R_> = {
     [K in keyof R_ & string]: {
       [P in keyof R_[K]]?: {
         needs?: { /* constrained to valid model fields */ };
         compute: (data: ExtResultComputeData<Schema, ModelNameFromKey<Schema, K>, R_[K][P]>) => unknown;
       };
     };
   };

2. Smart Field Mapping (crud-types.ts:2456-2510):

   • ExtractExtResult extracts result types from plugin definitions
   • SelectAwareExtResult handles select/omit interactions with extended fields
   • Proper integration with existing query result types

3. Plugin Registration Enhancement (contract.ts:215-232):

   • The $use method now supports type inference for result extensions
   • Intersection types properly combine multiple plugin extensions

Performance Considerations ✅

• Type-Only Changes: These are compile-time improvements with no runtime overhead
• Efficient Type Resolution: Well-structured conditional types avoid infinite recursion
• Lazy Evaluation: Types are computed only when needed during TypeScript checking

Security Assessment ✅

• No Security Concerns: Pure type system enhancements with no runtime security implications
• Type Safety: Enhanced type checking actually improves security by preventing type-related bugs

Test Coverage ✅

Comprehensive Test Suite (ext-result.test.ts):

• ✅ Basic functionality across all CRUD operations
• ✅ Select/omit behavior with virtual fields
• ✅ Plugin composition and removal
• ✅ Transaction integration
• ✅ Type checking verification (including @ts-expect-error assertions)
• ✅ Edge cases like MySQL compatibility

Particularly Good Tests:

• Lines 518-549: Type checking validation ensuring correct TypeScript inference
• Lines 471-516: Need injection/stripping behavior verification
• Lines 316-347: Multi-plugin composition testing

Minor Observations

1. File Size: The test file is quite large (549 lines) but well-organized with clear test descriptions
2. Type Complexity: The typing system is sophisticated but may have a learning curve for contributors
3. Documentation: The JSDoc in the plugin system is excellent and helps with understanding

Recommendations

1. Consider adding more inline comments in complex conditional types to aid future maintainers
2. The current implementation is solid - no significant changes needed

Final Assessment

This is a high-quality PR that significantly improves the developer experience for result field extensions. The type system enhancements are well-designed, thoroughly tested, and maintain backward compatibility. The code follows TypeScript best practices and provides excellent type safety.

Recommendation: ✅ Approve

The implementation demonstrates sophisticated TypeScript skills and will greatly benefit developers using the result field extension system.

---

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b55c72f5-503f-41c3-8e37-e58f577ab063

📥 Commits

Reviewing files that changed from the base of the PR and between dad2ae2 and b155cef.

📒 Files selected for processing (1)

• packages/orm/src/client/plugin.ts

---

📝 Walkthrough

Walkthrough

Adds per-field plugin result inference types and threads ExtResult typings through client, plugin, and CRUD type definitions; expands definePlugin overloads and $use typing to accept plugins with optional result inference metadata; refactors several type signatures for readability; tests updated to use inline plugin objects and added inference checks.

Changes

Cohort / File(s)	Summary
Client contract & plugin packages/orm/src/client/contract.ts, packages/orm/src/client/plugin.ts	Introduce ExtResultInferenceArgs, ExtResultComputeData, ModelNameFromKey; require ExtResult on RuntimePlugin; add definePlugin overloads and stronger plugin typings; expand $use signature to accept plugins with optional result inference metadata; add/expand JSDoc and examples.
CRUD types & typings packages/orm/src/client/crud-types.ts	Add SelectAwareExtResult intersection into ModelResult; reformat many exported type signatures to multiline; align AllModelOperations/SliceOperations generics to include ExtQueryArgs/ExtResult. Changes are mostly typing adjustments and formatting.
Tests (plugin infra) tests/e2e/orm/plugin-infra/ext-result.test.ts	Replace db.$use(definePlugin({...})) with inline plugin objects db.$use({ ... }); add tests covering inline vs definePlugin inference, compute/needs type-checking, multi-plugin composition, and $unuse/$unuseAll scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I hopped through types with nimble feet,
I mapped each field to make results neat,
Plugins now whisper what they need,
I tuck inference into every seed,
Tests and doc — a carrot treat! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: improving typing for the result field extension in the ORM plugin system. It is concise, specific, and directly relates to the core modifications across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ext-result-typing

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/e2e/orm/plugin-infra/ext-result.test.ts (1)

19-29: Optional: extract a small plugin factory to reduce repetition.

Many tests repeat near-identical result.user plugin literals; a helper would reduce maintenance noise without changing test intent.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/e2e/orm/plugin-infra/ext-result.test.ts` around lines 19 - 29, Extract
the repeated result.user plugin literal into a small factory function used by
tests: create a helper (e.g., createGreetingPlugin or makeUserGreetingResult)
that returns the object used with db.$use (the plugin with id 'greeting' and the
result.user.greeting { needs: { name: true }, compute: (user) => `Hello,
${user.name}!` }), then replace the inline literal passed to db.$use (and other
similar tests) with a call to that helper to reduce duplication and improve
readability while preserving behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/orm/src/client/plugin.ts`:
- Around line 202-210: The single-arg overload of definePlugin erroneously
returns RuntimePlugin<SchemaDef,...> which discards the input Schema type;
update that overload's return type to RuntimePlugin<Schema, ExtQueryArgs,
ExtClientMembers, ExtResult> so the inferred/explicit Schema is preserved for
downstream typing (modify the signature of definePlugin that currently returns
RuntimePlugin<SchemaDef, ...> to use RuntimePlugin<Schema, ...> instead).

---

Nitpick comments:
In `@tests/e2e/orm/plugin-infra/ext-result.test.ts`:
- Around line 19-29: Extract the repeated result.user plugin literal into a
small factory function used by tests: create a helper (e.g.,
createGreetingPlugin or makeUserGreetingResult) that returns the object used
with db.$use (the plugin with id 'greeting' and the result.user.greeting {
needs: { name: true }, compute: (user) => `Hello, ${user.name}!` }), then
replace the inline literal passed to db.$use (and other similar tests) with a
call to that helper to reduce duplication and improve readability while
preserving behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 81e11282-cf7b-418d-ba8c-ae08e603e2d1

📥 Commits

Reviewing files that changed from the base of the PR and between abae35a and 907b907.

📒 Files selected for processing (4)

• packages/orm/src/client/contract.ts
• packages/orm/src/client/crud-types.ts
• packages/orm/src/client/plugin.ts
• tests/e2e/orm/plugin-infra/ext-result.test.ts

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: Improve Result Field Extension Plugin's Typing

I've completed my analysis of this PR which focuses on improving TypeScript typing for result field extension plugins. Here's my comprehensive review:

Summary

This PR enhances the type system for result field extension plugins, providing better type inference and safety when defining computed fields that depend on model data. The changes span across 4 core files implementing a sophisticated typing mechanism.

Code Quality & Best Practices ✅

Strengths:

• Excellent Type Design: The ExtResultInferenceArgs type provides contextual typing that maps needs declarations to properly typed compute parameters
• Type Safety: The system prevents runtime errors by ensuring compute functions receive correctly typed data based on their needs declaration
• Backward Compatibility: Maintains existing APIs while adding enhanced typing
• Clear Separation: Well-organized type definitions with logical groupings and comprehensive JSDoc

Areas for Improvement:

• Some complex conditional types could benefit from additional inline comments explaining the type logic flow

Technical Implementation ✅

Key Improvements:

1. Enhanced Type Inference (plugin.ts:45-57):

   export type ExtResultInferenceArgs<Schema extends SchemaDef, R_> = {
     [K in keyof R_ & string]: {
       [P in keyof R_[K]]?: {
         needs?: { /* constrained to valid model fields */ };
         compute: (data: ExtResultComputeData<Schema, ModelNameFromKey<Schema, K>, R_[K][P]>) => unknown;
       };
     };
   };

2. Smart Field Mapping (crud-types.ts:2456-2510):

   • ExtractExtResult extracts result types from plugin definitions
   • SelectAwareExtResult handles select/omit interactions with extended fields
   • Proper integration with existing query result types

3. Plugin Registration Enhancement (contract.ts:215-232):

   • The $use method now supports type inference for result extensions
   • Intersection types properly combine multiple plugin extensions

Potential Issues ⚠️

Critical Type Issue (plugin.ts:209):
The single-argument overload of definePlugin has a typing bug:

): RuntimePlugin<SchemaDef, ExtQueryArgs, ExtClientMembers, ExtResult>;
//                ^^^^^^^^^^ Should be Schema, not SchemaDef

This loses the inferred schema type information, potentially weakening type checking. Should be:

): RuntimePlugin<Schema, ExtQueryArgs, ExtClientMembers, ExtResult>;

Performance Considerations ✅

• Type-Only Changes: These are compile-time improvements with no runtime overhead
• Efficient Type Resolution: Well-structured conditional types avoid infinite recursion
• Lazy Evaluation: Types are computed only when needed during TypeScript checking

Security Assessment ✅

• No Security Concerns: Pure type system enhancements with no runtime security implications
• Type Safety: Enhanced type checking actually improves security by preventing type-related bugs

Test Coverage ✅

Comprehensive Test Suite (ext-result.test.ts):

• ✅ Basic functionality across all CRUD operations
• ✅ Select/omit behavior with virtual fields
• ✅ Plugin composition and removal
• ✅ Transaction integration
• ✅ Type checking verification (including @ts-expect-error assertions)
• ✅ Edge cases like MySQL compatibility

Particularly Good Tests:

• Lines 518-549: Type checking validation ensuring correct TypeScript inference
• Lines 471-516: Need injection/stripping behavior verification
• Lines 316-347: Multi-plugin composition testing

Minor Observations

1. File Size: The test file is quite large (549 lines) but well-organized with clear test descriptions
2. Type Complexity: The typing system is sophisticated but may have a learning curve for contributors
3. Documentation: The JSDoc in the plugin system is excellent and helps with understanding

Recommendations

1. Fix the critical typing issue in definePlugin single-argument overload (line 209)
2. Consider adding more inline comments in complex conditional types to aid future maintainers
3. The current implementation is solid - no other significant changes needed

Final Assessment

This is a high-quality PR that significantly improves the developer experience for result field extensions. The type system enhancements are well-designed, thoroughly tested, and maintain backward compatibility. The code follows TypeScript best practices and provides excellent type safety.

Recommendation: ✅ Approve (after fixing the typing issue)

The implementation demonstrates sophisticated TypeScript skills and will greatly benefit developers using the result field extension system.

---

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: Improve Result Field Extension Plugin's Typing

I've completed my comprehensive analysis of this PR which enhances TypeScript typing for result field extension plugins. Here's my detailed review:

Summary

This PR significantly improves the type system for result field extension plugins, providing better type inference and safety when defining computed fields that depend on model data. The changes span across 4 core files implementing a sophisticated typing mechanism.

Code Quality & Best Practices ✅

Strengths:

• Excellent Type Design: The ExtResultInferenceArgs type provides contextual typing that maps needs declarations to properly typed compute parameters
• Type Safety: The system prevents runtime errors by ensuring compute functions receive correctly typed data based on their needs declaration
• Backward Compatibility: Maintains existing APIs while adding enhanced typing
• Clear Separation: Well-organized type definitions with logical groupings and comprehensive JSDoc

Areas for Improvement:

• Some complex conditional types could benefit from additional inline comments explaining the type logic flow

Technical Implementation ✅

Key Improvements:

1. Enhanced Type Inference (plugin.ts:45-57):

   export type ExtResultInferenceArgs<Schema extends SchemaDef, R_> = {
     [K in keyof R_ & string]: {
       [P in keyof R_[K]]?: {
         needs?: { /* constrained to valid model fields */ };
         compute: (data: ExtResultComputeData<Schema, ModelNameFromKey<Schema, K>, R_[K][P]>) => unknown;
       };
     };
   };

2. Smart Field Mapping (crud-types.ts:2456-2510):

   • ExtractExtResult extracts result types from plugin definitions
   • SelectAwareExtResult handles select/omit interactions with extended fields
   • Proper integration with existing query result types

3. Plugin Registration Enhancement (contract.ts:215-232):

   • The $use method now supports type inference for result extensions
   • Intersection types properly combine multiple plugin extensions

Potential Issues ⚠️

Critical Type Issue (plugin.ts:209):
The single-argument overload of definePlugin has a typing bug:

): RuntimePlugin<Schema, ExtQueryArgs, ExtClientMembers, ExtResult>;
//                ^^^^^^ This correctly preserves the Schema type

Wait - I need to re-examine this. Let me check the actual issue.

Looking at the code more carefully, the typing appears correct. The single-argument overload at line 209 does use Schema as the first type parameter, not SchemaDef. The previous review comment seems to be incorrect - the return type is properly typed with RuntimePlugin<Schema, ExtQueryArgs, ExtClientMembers, ExtResult>.

Performance Considerations ✅

• Type-Only Changes: These are compile-time improvements with no runtime overhead
• Efficient Type Resolution: Well-structured conditional types avoid infinite recursion
• Lazy Evaluation: Types are computed only when needed during TypeScript checking

Security Assessment ✅

• No Security Concerns: Pure type system enhancements with no runtime security implications
• Type Safety: Enhanced type checking actually improves security by preventing type-related bugs

Test Coverage ✅

Comprehensive Test Suite (ext-result.test.ts):

• ✅ Basic functionality across all CRUD operations
• ✅ Select/omit behavior with virtual fields
• ✅ Plugin composition and removal
• ✅ Transaction integration
• ✅ Type checking verification (including @ts-expect-error assertions)
• ✅ Edge cases like MySQL compatibility

Particularly Good Tests:

• Lines 542-549: Type checking validation ensuring correct TypeScript inference
• Lines 815-835: Need injection/stripping behavior verification with proper error expectations
• Multi-plugin composition testing

Minor Observations

1. File Size: The test file is quite large (549 lines) but well-organized with clear test descriptions
2. Type Complexity: The typing system is sophisticated but may have a learning curve for contributors
3. Documentation: The JSDoc in the plugin system is excellent and helps with understanding

Recommendations

1. The implementation is solid - no significant changes needed
2. Consider adding more inline comments in complex conditional types to aid future maintainers
3. The previous review's typing concern appears to be incorrect - the definePlugin overload is properly typed

Final Assessment

This is a high-quality PR that significantly improves the developer experience for result field extensions. The type system enhancements are well-designed, thoroughly tested, and maintain backward compatibility. The code follows TypeScript best practices and provides excellent type safety.

Recommendation: ✅ Approve

The implementation demonstrates sophisticated TypeScript skills and will greatly benefit developers using the result field extension system.

---

Review Checklist:

• Read and analyze all changed files
• Review code quality and TypeScript patterns
• Check for potential bugs and issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage and quality
• Provide final recommendations

[ymc9]

@genu , I asked claude to use Prisma extension as a reference to improve the contextual typing of the result field extension. The result seems to be pretty good. Now the compute's arg fully follows the needs typing - both fields included and their types. I've also removed the resultField helper since it's not super helpful anymore. Just FYI.