pkl-config-java: Refine nullness handling in Config and JavaType (#1544)

Motivation:
Config.as() causes nullness warnings when its result is intentionally assigned
to a non-null variable

Changes:

* Introduce Config.asNullable(Class<T>), asNullable(JavaType<T>), and
  asNullable(Type) to explicitly opt into nullable values
* Keep the signatures of Config.as(Class<T>) and Config.as(JavaType<T>)
  unchanged from 0.31 by adding @NullUnmarked
  * This gives users time to migrate from as() to asNullable() where appropriate
  * Avoids introducing new spurious warnings
* Change `<T> T Config.as(Type)` to `<T extends @nullable Object> T Config.as(Type)`
  * This overload is typically used by reflective code such as
    pkl-config-kotlin's Config.to() rather than directly by user code
* Clarify that JavaType<T> represents a non-null top-level type whose type arguments may be nullable
  * Restricting <T> to non-null keeps method signatures understandable for humans and tools
  * Enables full symmetry between Class<T> and JavaType<T> overloads in Config and JavaType
  * Enables future non-null runtime checks in both Config.as() overloads
* Simplify construction of `JavaType`s with nullable type arguments
  * Add ofNullable() variants for most factory methods, e.g., JavaType.listOfNullable()
* Overhaul Javadoc of Config and JavaType

Result:

* Clear separation between accessing nullable and non-null values
* Config.as() is used for the common non-null case
* Config.as() can perform non-null runtime checks in a future release (breaking change)
* More ergonomic construction of types with nullable type arguments
* More detailed and consistent documentation
This commit is contained in:
odenix authored and GitHub committed 2026-05-19 12:27:59 -07:00
1 parent e34c3e8c4f
commit dc9003d0f1
6 files changed
+622 -57

No files matched your search

@@ -17,6 +17,8 @@ package org.pkl.config.java;
import static org.assertj.core.api.Assertions.assertThat;
import java.lang.reflect.Type;
import org.jspecify.annotations.Nullable;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.Test;
import org.pkl.core.ModuleSource;
@@ -50,4 +52,31 @@ public final class ConfigEvaluatorTest extends AbstractConfigTest {
var address = addressConfig.as(Address.class);
assertThat(address.street).isEqualTo("Fuzzy St.");
}
@Test
public void asNullableWithClass() {
var mod = evaluator.evaluate(ModuleSource.text("nullValue = null; strValue = \"Bob\""));
@Nullable String nullValue = mod.get("nullValue").asNullable(String.class);
@Nullable String strValue = mod.get("strValue").asNullable(String.class);
assertThat(nullValue).isNull();
assertThat(strValue).isNotNull();
}
@Test
public void asNullableWithType() {
var mod = evaluator.evaluate(ModuleSource.text("nullValue = null; strValue = \"Bob\""));
@Nullable String nullValue = mod.get("nullValue").asNullable((Type) String.class);
@Nullable String strValue = mod.get("strValue").asNullable((Type) String.class);
assertThat(nullValue).isNull();
assertThat(strValue).isNotNull();
}
@Test
public void asNullableWithJavaType() {
var mod = evaluator.evaluate(ModuleSource.text("nullValue = null; strValue = \"Bob\""));
@Nullable String nullValue = mod.get("nullValue").asNullable(JavaType.of(String.class));
@Nullable String strValue = mod.get("strValue").asNullable(JavaType.of(String.class));
assertThat(nullValue).isNull();
assertThat(strValue).isNotNull();
}
}
@@ -17,15 +17,25 @@ package org.pkl.config.java;
import static org.assertj.core.api.Assertions.*;
import java.lang.reflect.Type;
import java.net.URI;
import java.net.URL;
import java.nio.file.Path;
import java.util.*;
import org.jspecify.annotations.Nullable;
import org.junit.jupiter.api.Test;
import org.pkl.config.java.mapper.Reflection;
import org.pkl.config.java.mapper.Types;
import org.pkl.core.Pair;
public final class JavaTypeTest {
@Test
public void constructSimpleType() {
assertThat(JavaType.of(String.class)).isEqualTo(new JavaType<String>() {});
//noinspection AssertBetweenInconvertibleTypes
assertThat(JavaType.of((Type) String.class)).isEqualTo(new JavaType<String>() {});
}
@Test
public void constructOptionalType() {
var type = JavaType.optionalOf(String.class);
@@ -34,6 +44,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Optional.class);
}
@Test
public void constructPairType() {
var type = JavaType.pairOf(String.class, Integer.class);
assertThat(type).isEqualTo(new JavaType<Pair<String, Integer>>() {});
assertThat(type)
.isEqualTo(JavaType.pairOf(JavaType.of(String.class), JavaType.of(Integer.class)));
}
@Test
public void constructArrayType() {
var type = JavaType.arrayOf(String.class);
@@ -42,6 +60,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType()).isArray()).isTrue();
}
@Test
public void constructArrayOfNullableType() {
var type = JavaType.arrayOfNullable(String.class);
assertThat(type).isEqualTo(new JavaType<@Nullable String[]>() {});
assertThat(type).isEqualTo(JavaType.arrayOfNullable(JavaType.of(String.class)));
assertThat(Reflection.toRawType(type.getType()).isArray()).isTrue();
}
@Test
public void constructIterableType() {
var type = JavaType.iterableOf(String.class);
@@ -50,6 +76,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Iterable.class);
}
@Test
public void constructIterableOfNullableType() {
var type = JavaType.iterableOfNullable(String.class);
assertThat(type).isEqualTo(new JavaType<Iterable<@Nullable String>>() {});
assertThat(type).isEqualTo(JavaType.iterableOfNullable(JavaType.of(String.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Iterable.class);
}
@Test
public void constructCollectionType() {
var type = JavaType.collectionOf(String.class);
@@ -58,6 +92,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Collection.class);
}
@Test
public void constructCollectionOfNullableType() {
var type = JavaType.collectionOfNullable(String.class);
assertThat(type).isEqualTo(new JavaType<Collection<@Nullable String>>() {});
assertThat(type).isEqualTo(JavaType.collectionOfNullable(JavaType.of(String.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Collection.class);
}
@Test
public void constructListType() {
var type = JavaType.listOf(String.class);
@@ -66,6 +108,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType())).isEqualTo(List.class);
}
@Test
public void constructListOfNullableType() {
var type = JavaType.listOfNullable(String.class);
assertThat(type).isEqualTo(new JavaType<List<@Nullable String>>() {});
assertThat(type).isEqualTo(JavaType.listOfNullable(JavaType.of(String.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(List.class);
}
@Test
public void constructSetType() {
var type = JavaType.setOf(String.class);
@@ -74,6 +124,14 @@ public final class JavaTypeTest {
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Set.class);
}
@Test
public void constructSetOfNullableType() {
var type = JavaType.setOfNullable(String.class);
assertThat(type).isEqualTo(new JavaType<Set<@Nullable String>>() {});
assertThat(type).isEqualTo(JavaType.setOfNullable(JavaType.of(String.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Set.class);
}
@Test
public void constructMapType() {
var type = JavaType.mapOf(String.class, URI.class);
@@ -83,7 +141,63 @@ public final class JavaTypeTest {
}
@Test
public void usageAsTypeToken() {
public void constructPairOfNullableFirstType() {
var type = JavaType.pairOfNullableFirst(String.class, Integer.class);
assertThat(type).isEqualTo(new JavaType<Pair<@Nullable String, Integer>>() {});
assertThat(type)
.isEqualTo(
JavaType.pairOfNullableFirst(JavaType.of(String.class), JavaType.of(Integer.class)));
}
@Test
public void constructPairOfNullableSecondType() {
var type = JavaType.pairOfNullableSecond(String.class, Integer.class);
assertThat(type).isEqualTo(new JavaType<Pair<String, @Nullable Integer>>() {});
assertThat(type)
.isEqualTo(
JavaType.pairOfNullableSecond(JavaType.of(String.class), JavaType.of(Integer.class)));
}
@Test
public void constructPairOfNullableFirstAndSecondType() {
var type = JavaType.pairOfNullableFirstAndSecond(String.class, Integer.class);
assertThat(type).isEqualTo(new JavaType<Pair<@Nullable String, @Nullable Integer>>() {});
assertThat(type)
.isEqualTo(
JavaType.pairOfNullableFirstAndSecond(
JavaType.of(String.class), JavaType.of(Integer.class)));
}
@Test
public void constructMapOfNullableKeysType() {
var type = JavaType.mapOfNullableKeys(String.class, URI.class);
assertThat(type).isEqualTo(new JavaType<Map<@Nullable String, URI>>() {});
assertThat(type)
.isEqualTo(JavaType.mapOfNullableKeys(JavaType.of(String.class), JavaType.of(URI.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Map.class);
}
@Test
public void constructMapOfNullableValuesType() {
var type = JavaType.mapOfNullableValues(String.class, URI.class);
assertThat(type).isEqualTo(new JavaType<Map<String, @Nullable URI>>() {});
assertThat(type)
.isEqualTo(JavaType.mapOfNullableValues(JavaType.of(String.class), JavaType.of(URI.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Map.class);
}
@Test
public void constructMapOfNullableKeysAndValuesType() {
var type = JavaType.mapOfNullableKeysAndValues(String.class, URI.class);
assertThat(type).isEqualTo(new JavaType<Map<@Nullable String, @Nullable URI>>() {});
assertThat(type)
.isEqualTo(
JavaType.mapOfNullableKeysAndValues(JavaType.of(String.class), JavaType.of(URI.class)));
assertThat(Reflection.toRawType(type.getType())).isEqualTo(Map.class);
}
@Test
public void constructTypeToken() {
var javaType = new JavaType<Map<String, List<URI>>>() {};
assertThat(javaType.getType()).isEqualTo(Types.mapOf(String.class, Types.listOf(URI.class)));
@@ -110,6 +224,7 @@ public final class JavaTypeTest {
var type2 = new JavaType<Map<String, List<URL>>>() {};
var type3 = JavaType.of(Types.mapOf(String.class, Types.listOf(Path.class)));
//noinspection AssertBetweenInconvertibleTypes
assertThat(type2).isNotEqualTo(type1);
assertThat(type3).isNotEqualTo(type1);
assertThat(type2).isNotEqualTo(type3);