Add TypeWrapperFactoryExpression for Type-Safe Custom Number Mapping in Querydsl Aggregations

[chadongmin]

Background & Problem

Querydsl’s aggregation functions (e.g., sum(), sumAggregate()) return raw numeric types like BigDecimal or Double. However, when attempting to map these directly to custom Number subtypes (e.g., Money, MyCustomNumber), Querydsl throws:

IllegalArgumentException: Unsupported target type : MyCustomNumber

This limitation forces developers to write manual conversion logic, increasing boilerplate and risking errors in complex queries. The issue was originally reported in Issue #3550 and persists in the latest Querydsl release (6.11). A reproducible example is provided here:
https://github.com/chadongmin/querydsl-jpa-customnumber-aggregate-conversion-bug

---

Discussion

The problem stems from Querydsl’s internal casting mechanism (MathUtils#cast), which lacks support for custom Number subclasses. Community feedback highlighted two viable strategies:

1. Extend MathUtils#cast
   Modify the core cast method to automatically handle custom Number subclasses.

2. Introduce TypeWrapper Abstraction
   Create a TypeWrapper mechanism to carry target-type metadata for specific expressions, enabling type-safe mapping only when explicitly applied.

---

Deliberation

Extending MathUtils#cast would have required invasive changes to a core utility used by every numeric operation, risking regressions and complicating future QueryDSL upgrades. By contrast, TypeWrapper lets me opt in only where needed, avoids touching existing casting logic, and cleanly isolates the custom-type support in one place—greatly simplifying maintenance and preserving backward compatibility.

Chosen Solution

I’ve implemented the TypeWrapper extension for FactoryExpression contexts. Now, any expression—be it sum(), avg(), or a factory-based projection—wrapped with TypeWrapper.wrap(expr, MyCustomNumber.class) is correctly serialized and mapped back to the custom type, while all unwrapped code paths remain unchanged.

• Added TypeWrapper<S,T> to querydsl-core as a FactoryExpression implementation.
• Added JPAQueryCustomTypeWrapperTest in querydsl-jpa covering:
  • failure without wrapper
  • success with direct wrapper
  • success in @QueryProjection DTO.

Next Steps
If there’s a better approach or any improvements you’d suggest, please let me know—I’ll be happy to incorporate your feedback into this PR.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 71.04%. Comparing base (4980432) to head (3de6536).
Report is 33 commits behind head on master.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1181      +/-   ##
============================================
+ Coverage     61.19%   71.04%   +9.85%     
  Complexity       84       84              
============================================
  Files           831      858      +27     
  Lines         32015    32359     +344     
  Branches       3590     3600      +10     
============================================
+ Hits          19590    22988    +3398     
+ Misses        11179     8148    -3031     
+ Partials       1246     1223      -23     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.