feat: Add public GsonTypeMapper exposing gsonBuilder()

Author: thced

src/main/java/com/retailsvc/http/GsonTypeMapper.java

@@ -0,0 +1,70 @@
+package com.retailsvc.http;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.retailsvc.http.internal.gson.GsonJsonMapper;
+import java.util.Objects;
+
+/**
+ * {@link TypeMapper} for {@code application/json} backed by Gson. Mirrors the ergonomics of {@link
+ * Jackson2JsonTypeMapper} / {@link Jackson3JsonTypeMapper}: the caller supplies a fully configured
+ * {@link Gson}; this class never silently mutates it.
+ *
+ * <p>The no-argument constructor uses the library's default {@link Gson} — the same JSR-310-aware
+ * instance the built-in auto-registration produces — making this a drop-in replacement for the
+ * auto-registered mapper when callers want to wire it explicitly.
+ *
+ * <p>To extend the library default with extra type adapters or settings, use {@link
+ * #gsonBuilder()}:
+ *
+ * <pre>{@code
+ * Gson custom =
+ *     new GsonTypeMapper()
+ *         .gsonBuilder()
+ *         .registerTypeAdapter(MyType.class, new MyTypeAdapter())
+ *         .create();
+ * new GsonTypeMapper(custom);
+ * }</pre>
+ */
+public final class GsonTypeMapper implements TypedTypeMapper {
+
+  private final GsonJsonMapper delegate;
+
+  /** Creates a mapper backed by the library's default JSR-310-aware {@link Gson}. */
+  public GsonTypeMapper() {
+    this.delegate = new GsonJsonMapper();
+  }
+
+  /**
+   * Creates a mapper backed by the supplied {@link Gson}.
+   *
+   * @throws NullPointerException if {@code gson} is null
+   */
+  public GsonTypeMapper(Gson gson) {
+    this.delegate = new GsonJsonMapper(Objects.requireNonNull(gson, "gson must not be null"));
+  }
+
+  /**
+   * Returns a {@link GsonBuilder} pre-populated with the wrapped {@link Gson}'s configuration, so
+   * callers can derive a customized {@link Gson} from the library default (or from their own
+   * starting point).
+   */
+  public GsonBuilder gsonBuilder() {
+    return delegate.gson().newBuilder();
+  }
+
+  @Override
+  public Object readFrom(byte[] body, String contentTypeHeader) {
+    return delegate.readFrom(body, contentTypeHeader);
+  }
+
+  @Override
+  public <T> T readAs(byte[] body, String contentTypeHeader, Class<T> type) {
+    return delegate.readAs(body, contentTypeHeader, type);
+  }
+
+  @Override
+  public byte[] writeTo(Object value) {
+    return delegate.writeTo(value);
+  }
+}

src/test/java/com/retailsvc/http/GsonTypeMapperTest.java

@@ -0,0 +1,69 @@
+package com.retailsvc.http;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatNullPointerException;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.Collections;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class GsonTypeMapperTest {
+
+  @Test
+  void noArgConstructorRoundTripsInstantAsIso8601() {
+    GsonTypeMapper mapper = new GsonTypeMapper();
+
+    byte[] out = mapper.writeTo(Map.of("ts", Instant.parse("2026-05-13T10:00:00Z")));
+
+    assertThat(new String(out, StandardCharsets.UTF_8))
+        .isEqualTo("{\"ts\":\"2026-05-13T10:00:00Z\"}");
+  }
+
+  @Test
+  void readAsDelegatesToWrappedGson() {
+    GsonTypeMapper mapper = new GsonTypeMapper();
+
+    Item item =
+        mapper.readAs(
+            "{\"id\":\"x\",\"qty\":3}".getBytes(StandardCharsets.UTF_8),
+            "application/json",
+            Item.class);
+
+    assertThat(item.id).isEqualTo("x");
+    assertThat(item.qty).isEqualTo(3);
+  }
+
+  @Test
+  void customGsonIsUsed() {
+    Gson custom = new GsonBuilder().serializeNulls().create();
+    GsonTypeMapper mapper = new GsonTypeMapper(custom);
+
+    assertThat(
+            new String(mapper.writeTo(Collections.singletonMap("k", null)), StandardCharsets.UTF_8))
+        .isEqualTo("{\"k\":null}");
+  }
+
+  @Test
+  void nullGsonRejected() {
+    assertThatNullPointerException().isThrownBy(() -> new GsonTypeMapper(null));
+  }
+
+  @Test
+  void gsonBuilderReturnsBuilderForWrappedGson() {
+    Gson custom = new GsonBuilder().serializeNulls().create();
+    GsonTypeMapper mapper = new GsonTypeMapper(custom);
+
+    Gson derived = mapper.gsonBuilder().create();
+
+    assertThat(derived.toJson(Collections.singletonMap("k", null))).isEqualTo("{\"k\":null}");
+  }
+
+  static final class Item {
+    String id;
+    int qty;
+  }
+}