Add TypeWrapperFactoryExpression for Type-Safe Custom Number Mapping in Querydsl Aggregations (#1181)

* Introduce TypeWrapper to wrap Expression results into custom types

- Implement TypeWrapper<S, T> as a FactoryExpression
- Allows converting a source Expression (e.g. BigDecimal) to a domain type (e.g. Money)
- Prepares QueryDSL core to support custom aggregation projections without core API changes

* Add JPAQueryCustomTypeWrapperTest covering success and failure scenarios

- Verify IllegalArgumentException for unsupported custom types without wrapper
- Verify sum-and-wrap to Money via TypeWrapper in both direct and DTO projection use cases
- Ensure both positive and negative paths are exercised

Author: chadongmin

querydsl-libraries/querydsl-core/src/main/java/com/querydsl/core/types/dsl/TypeWrapper.java

@@ -0,0 +1,61 @@
+package com.querydsl.core.types.dsl;
+
+import com.querydsl.core.types.Expression;
+import com.querydsl.core.types.FactoryExpression;
+import com.querydsl.core.types.Visitor;
+import java.util.List;
+import java.util.function.Function;
+
+/**
+ * A {@link FactoryExpression} implementation that wraps a single source {@link Expression} and
+ * converts its result into a custom target type.
+ *
+ * <p>Typical usage: convert a {@link java.math.BigDecimal} sum result from a JPA query into a
+ * domain-specific value object such as {@code Money}.
+ *
+ * @param <S> the source expression type (e.g. {@link java.math.BigDecimal})
+ * @param <T> the target type to convert to (e.g. a custom {@code Money} class)
+ * @author chadongmin
+ * @see com.querydsl.core.types.FactoryExpression
+ * @since 6.11
+ */
+public class TypeWrapper<S, T> implements FactoryExpression<T> {
+  private final Class<T> valueClass;
+  private final Function<S, T> factory;
+  private final List<Expression<?>> args;
+
+  /**
+   * Create a new TypeWrapper.
+   *
+   * @param arg the source expression whose value will be converted
+   * @param valueClass the target type class
+   * @param factory a function that maps the source value to the target type
+   */
+  public TypeWrapper(Expression<S> arg, Class<T> valueClass, Function<S, T> factory) {
+    this.valueClass = valueClass;
+    this.factory = factory;
+    this.args = List.of(arg);
+  }
+
+  @Override
+  public <R, C> R accept(Visitor<R, C> v, C context) {
+    return v.visit(this, context);
+  }
+
+  @Override
+  public Class<? extends T> getType() {
+    return valueClass;
+  }
+
+  @Override
+  public List<Expression<?>> getArgs() {
+    return args;
+  }
+
+  @Override
+  public T newInstance(Object... args) {
+    @SuppressWarnings("unchecked")
+    S arg = (S) args[0];
+    return factory.apply(arg);
+  }
+}

querydsl-libraries/querydsl-jpa/src/test/java/com/querydsl/jpa/JPAQueryCustomTypeWrapperTest.java

@@ -0,0 +1,110 @@
+package com.querydsl.jpa;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.querydsl.core.types.dsl.NumberExpression;
+import com.querydsl.core.types.dsl.TypeWrapper;
+import com.querydsl.jpa.domain.*;
+import com.querydsl.jpa.impl.JPAQuery;
+import com.querydsl.jpa.testutil.JPATestRunner;
+import jakarta.persistence.EntityManager;
+import java.math.BigDecimal;
+import java.util.List;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+@RunWith(JPATestRunner.class)
+public class JPAQueryCustomTypeWrapperTest implements JPATest {
+
+  private EntityManager em;
+
+  @Override
+  public void setEntityManager(EntityManager em) {
+    this.em = em;
+  }
+
+  @Before
+  public void setupData() {
+    em.createQuery("delete from Invoice").executeUpdate();
+    em.persist(new Invoice("00000000-0000-0000-0000-000000000001", "A", new Money("111")));
+    em.persist(new Invoice("00000000-0000-0000-0000-000000000002", "A", new Money("222")));
+    em.persist(new Invoice("00000000-0000-0000-0000-000000000003", "B", new Money("333")));
+    em.flush();
+    em.clear();
+  }
+
+  @Test
+  public void sumWithoutWrapper_shouldThrowUnsupportedTargetTypeException() {
+    // Expect IllegalArgumentException due to unsupported target type Money
+    assertThatThrownBy(
+            () ->
+                new JPAQuery<>(em)
+                    .select(QInvoice.invoice.amount.sumAggregate())
+                    .from(QInvoice.invoice)
+                    .fetchOne())
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("Unsupported target type : Money");
+  }
+
+  @Test
+  public void projectionWithoutWrapper_shouldThrowException() {
+    // Expect IllegalArgumentException due to unsupported target type in projection
+    assertThatThrownBy(
+            () ->
+                new JPAQuery<>(em)
+                    .select(
+                        new QInvoiceSummary(
+                            QInvoice.invoice.category, QInvoice.invoice.amount.sumAggregate()))
+                    .from(QInvoice.invoice)
+                    .groupBy(QInvoice.invoice.category)
+                    .fetch())
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("Unsupported target type");
+  }
+
+  @Test
+  public void projectionWithTypeWrapper_shouldReturnInvoiceSummary() {
+    // When: Use TypeWrapper to convert BigDecimal to Money in projection
+    List<InvoiceSummary> results =
+        new JPAQuery<>(em)
+            .select(
+                new QInvoiceSummary(
+                    QInvoice.invoice.category,
+                    new TypeWrapper<>(
+                        QInvoice.invoice.amount.sumAggregate().castToNum(BigDecimal.class),
+                        Money.class,
+                        Money::new)))
+            .from(QInvoice.invoice)
+            .groupBy(QInvoice.invoice.category)
+            .fetch();
+
+    // Then: The results should match the expected InvoiceSummary values
+    assertThat(results)
+        .containsExactlyInAnyOrder(
+            new InvoiceSummary("A", new Money("333.00")), // 111 + 222
+            new InvoiceSummary("B", new Money("333.00")) // 333
+            );
+  }
+
+  @Test
+  public void sumWithTypeWrapper_shouldWrapToMoney() {
+    // Given: persist some Invoice instances ...
+
+    // Create a sum expression and cast to BigDecimal
+    NumberExpression<BigDecimal> sumExpr =
+        QInvoice.invoice.amount.sumAggregate().castToNum(BigDecimal.class);
+
+    // Use TypeWrapper to convert the sum result to Money
+    Money result =
+        new JPAQuery<>(em)
+            .select(new TypeWrapper<>(sumExpr, Money.class, Money::new))
+            .from(QInvoice.invoice)
+            .fetchOne();
+
+    assertThat(result).isEqualTo(new Money("666.00")); // 111 + 222 + 333 = 666
+
+    em.clear();
+  }
+}

querydsl-libraries/querydsl-jpa/src/test/java/com/querydsl/jpa/domain/Invoice.java

@@ -0,0 +1,66 @@
+package com.querydsl.jpa.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Convert;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import java.util.Comparator;
+import java.util.UUID;
+
+@Entity
+public class Invoice {
+
+  @Id private UUID id;
+
+  @Column(nullable = false)
+  private String category;
+
+  @Column(nullable = false, precision = 30, scale = 10)
+  @Convert(converter = MoneyConverter.class)
+  private Money amount;
+
+  public Invoice() {
+    // JPA 스펙용
+  }
+
+  public Invoice(String uuid, String category, Money amount) {
+    this.id = UUID.fromString(uuid);
+    this.category = category;
+    this.amount = amount;
+  }
+
+  public static Comparator<Invoice> comparator() {
+    return Comparator.comparing(Invoice::getId)
+        .thenComparing(Invoice::getCategory)
+        .thenComparing(Invoice::getAmount);
+  }
+
+  @Override
+  public String toString() {
+    return "Invoice{" + "id=" + id + ", category='" + category + '\'' + ", amount=" + amount + '}';
+  }
+
+  public UUID getId() {
+    return id;
+  }
+
+  public void setId(UUID id) {
+    this.id = id;
+  }
+
+  public String getCategory() {
+    return category;
+  }
+
+  public void setCategory(String category) {
+    this.category = category;
+  }
+
+  public Money getAmount() {
+    return amount;
+  }
+
+  public void setAmount(Money amount) {
+    this.amount = amount;
+  }
+}

querydsl-libraries/querydsl-jpa/src/test/java/com/querydsl/jpa/domain/InvoiceSummary.java

@@ -0,0 +1,48 @@
+package com.querydsl.jpa.domain;
+
+import com.querydsl.core.annotations.QueryProjection;
+import java.util.Objects;
+
+public class InvoiceSummary {
+
+  private final String category;
+  private final Money totalAmount;
+
+  @QueryProjection
+  public InvoiceSummary(String category, Money totalAmount) {
+    this.category = category;
+    this.totalAmount = totalAmount;
+  }
+
+  public String getCategory() {
+    return category;
+  }
+
+  public Money getTotalAmount() {
+    return totalAmount;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof InvoiceSummary)) return false;
+    InvoiceSummary that = (InvoiceSummary) o;
+    return Objects.equals(category, that.category) && Objects.equals(totalAmount, that.totalAmount);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(category, totalAmount);
+  }
+
+  @Override
+  public String toString() {
+    return "com.querydsl.jpa.domain.InvoiceSummary{"
+        + "category='"
+        + category
+        + '\''
+        + ", totalAmount="
+        + totalAmount
+        + '}';
+  }
+}

querydsl-libraries/querydsl-jpa/src/test/java/com/querydsl/jpa/domain/Money.java

@@ -0,0 +1,67 @@
+package com.querydsl.jpa.domain;
+
+import java.io.Serial;
+import java.math.BigDecimal;
+import java.util.Objects;
+
+public class Money extends Number implements Comparable<Money> {
+
+  @Serial private static final long serialVersionUID = 1L;
+
+  private final BigDecimal value;
+
+  public Money(BigDecimal value) {
+    this.value = value;
+  }
+
+  public Money(String value) {
+    this.value = new BigDecimal(value);
+  }
+
+  public BigDecimal getValue() {
+    return value;
+  }
+
+  @Override
+  public String toString() {
+    return value.toPlainString();
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof Money)) return false;
+    Money that = (Money) o;
+    return Objects.equals(value, that.value);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(value);
+  }
+
+  @Override
+  public long longValue() {
+    return value.longValue();
+  }
+
+  @Override
+  public int intValue() {
+    return value.intValue();
+  }
+
+  @Override
+  public float floatValue() {
+    return value.floatValue();
+  }
+
+  @Override
+  public double doubleValue() {
+    return value.doubleValue();
+  }
+
+  @Override
+  public int compareTo(Money o) {
+    return this.value.compareTo(o.value);
+  }
+}

querydsl-libraries/querydsl-jpa/src/test/java/com/querydsl/jpa/domain/MoneyConverter.java

@@ -0,0 +1,19 @@
+package com.querydsl.jpa.domain;
+
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+import java.math.BigDecimal;
+
+@Converter(autoApply = true)
+public class MoneyConverter implements AttributeConverter<Money, BigDecimal> {
+
+  @Override
+  public BigDecimal convertToDatabaseColumn(Money attribute) {
+    return attribute != null ? attribute.getValue() : null;
+  }
+
+  @Override
+  public Money convertToEntityAttribute(BigDecimal dbData) {
+    return dbData != null ? new Money(dbData) : null;
+  }
+}