pkl-config-java: Replace Config.fromPklBinary() with ConfigDecoder

pkl-config-java/src/main/java/org/pkl/config/java/Config.java

@@ -15,22 +15,19 @@
  */
 package org.pkl.config.java;
 
-import static org.pkl.config.java.ConfigUtils.makeConfig;
-
 import java.io.InputStream;
 import java.lang.reflect.Type;
 import org.jspecify.annotations.Nullable;
 import org.pkl.config.java.mapper.ConversionException;
 import org.pkl.config.java.mapper.ValueMapper;
 import org.pkl.core.Evaluator;
-import org.pkl.core.PklBinaryDecoder;
 
 /**
  * A root, intermediate, or leaf node in a configuration tree. Child nodes can be obtained by name
  * using {@link #get(String)}. To consume the node's composite or scalar value, convert the value to
  * the desired Java type, using one of the provided {@link #as} methods.
  */
-@SuppressWarnings("unused")
+@SuppressWarnings({"DeprecatedIsStillUsed"})
 public interface Config {
   /**
    * The dot-separated name of this node. For example, the node reached using {@code
@@ -76,39 +73,50 @@ public interface Config {
   <T extends @Nullable Object> T as(JavaType<T> type);
 
   /**
-   * Decode a config from the supplied byte array.
+   * Decodes a config from the supplied byte array.
    *
-   * @return the encoded config
+   * @return the decoded config
+   * @deprecated Use {@code ConfigDecoderBuilder...build().decode(bytes)} instead. For a direct
+   *     equivalent, use {@code ConfigDecoder.preconfigured().setValueMapper(mapper).decode(bytes)}.
    */
+  @Deprecated(forRemoval = true)
   static Config fromPklBinary(byte[] bytes, ValueMapper mapper) {
-    return makeConfig(PklBinaryDecoder.decode(bytes), mapper);
+    return ConfigDecoder.preconfigured().setValueMapper(mapper).decode(bytes);
   }
 
   /**
-   * Decode a config from the supplied byte array using a preconfigured {@link ValueMapper}.
+   * Decodes a config from the supplied byte array using a preconfigured {@link ValueMapper}.
    *
-   * @return the encoded config
+   * @return the decoded config
+   * @deprecated Use {@code ConfigDecoder.preconfigured().decode(bytes)} instead.
    */
+  @Deprecated(forRemoval = true)
   static Config fromPklBinary(byte[] bytes) {
-    return fromPklBinary(bytes, ValueMapper.preconfigured());
+    return ConfigDecoder.preconfigured().decode(bytes);
   }
 
   /**
-   * Decode a config from the supplied {@link InputStream} using a preconfigured {@link
+   * Decodes a config from the supplied {@link InputStream} using a preconfigured {@link
    * ValueMapper}.
    *
-   * @return the encoded config
+   * @return the decoded config
+   * @deprecated Use {@code ConfigDecoderBuilder...build().decode(inputStream)} instead. For a
+   *     direct equivalent, use {@code
+   *     ConfigDecoder.preconfigured().setValueMapper(mapper).decode(inputStream)}.
    */
+  @Deprecated(forRemoval = true)
   static Config fromPklBinary(InputStream inputStream, ValueMapper mapper) {
-    return makeConfig(PklBinaryDecoder.decode(inputStream), mapper);
+    return ConfigDecoder.preconfigured().setValueMapper(mapper).decode(inputStream);
   }
 
   /**
-   * Decode a config from the supplied {@link InputStream}.
+   * Decodes a config from the supplied {@link InputStream}.
    *
-   * @return the encoded config
+   * @return the decoded config
+   * @deprecated Use {@code ConfigDecoder.preconfigured().decode(inputStream)} instead.
    */
+  @Deprecated(forRemoval = true)
   static Config fromPklBinary(InputStream inputStream) {
-    return fromPklBinary(inputStream, ValueMapper.preconfigured());
+    return ConfigDecoder.preconfigured().decode(inputStream);
   }
 }

pkl-config-java/src/main/java/org/pkl/config/java/ConfigDecoder.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.config.java;
+
+import java.io.InputStream;
+import org.pkl.config.java.mapper.ValueMapper;
+
+/** Decodes Pkl binary data into {@link Config} objects. */
+public interface ConfigDecoder {
+
+  /**
+   * Returns a preconfigured decoder that uses {@link ValueMapper#preconfigured()}.
+   *
+   * <p>For more control over configuration, use {@link ConfigDecoderBuilder}.
+   *
+   * @return a preconfigured decoder
+   */
+  static ConfigDecoder preconfigured() {
+    return ConfigDecoderBuilder.preconfigured().build();
+  }
+
+  ValueMapper getValueMapper();
+
+  /**
+   * Returns a copy of this decoder with the supplied value mapper.
+   *
+   * @param mapper the value mapper to use
+   * @return a decoder with the supplied value mapper
+   */
+  ConfigDecoder setValueMapper(ValueMapper mapper);
+
+  /**
+   * Decodes configuration from the supplied byte array.
+   *
+   * @param bytes the data to decode
+   * @return the decoded configuration
+   */
+  Config decode(byte[] bytes);
+
+  /**
+   * Decodes configuration from the supplied input stream.
+   *
+   * <p>This method does not close the stream; the caller is responsible for closing it.
+   *
+   * @param inputStream the data to decode
+   * @return the decoded configuration
+   */
+  Config decode(InputStream inputStream);
+}

pkl-config-java/src/main/java/org/pkl/config/java/ConfigDecoderBuilder.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.config.java;
+
+import org.pkl.config.java.mapper.ValueMapperBuilder;
+
+/**
+ * Builder for {@link ConfigDecoder} instances.
+ *
+ * <p>Use {@link #preconfigured()} to obtain a preconfigured builder, or {@link #unconfigured()} for
+ * full control over its configuration.
+ */
+public final class ConfigDecoderBuilder {
+  private ValueMapperBuilder mapperBuilder;
+
+  private ConfigDecoderBuilder(ValueMapperBuilder mapperBuilder) {
+    this.mapperBuilder = mapperBuilder;
+  }
+
+  /**
+   * Returns a preconfigured builder that uses {@link ValueMapperBuilder#preconfigured()}.
+   *
+   * @return a preconfigured builder
+   */
+  public static ConfigDecoderBuilder preconfigured() {
+    return new ConfigDecoderBuilder(ValueMapperBuilder.preconfigured());
+  }
+
+  /**
+   * Returns an unconfigured builder that uses {@link ValueMapperBuilder#unconfigured()}.
+   *
+   * @return an unconfigured builder
+   */
+  public static ConfigDecoderBuilder unconfigured() {
+    return new ConfigDecoderBuilder(ValueMapperBuilder.unconfigured());
+  }
+
+  /**
+   * Returns the value mapper builder used by this decoder builder.
+   *
+   * @return the value mapper builder
+   */
+  public ValueMapperBuilder getValueMapperBuilder() {
+    return mapperBuilder;
+  }
+
+  /**
+   * Sets the value mapper builder used by this decoder builder.
+   *
+   * @param mapperBuilder the value mapper builder to use
+   * @return this builder
+   */
+  public ConfigDecoderBuilder setValueMapperBuilder(ValueMapperBuilder mapperBuilder) {
+    this.mapperBuilder = mapperBuilder;
+    return this;
+  }
+
+  /**
+   * Builds a {@link ConfigDecoder} using the current configuration.
+   *
+   * @return the configured decoder
+   */
+  public ConfigDecoder build() {
+    return new ConfigDecoderImpl(mapperBuilder.build());
+  }
+}

pkl-config-java/src/main/java/org/pkl/config/java/ConfigDecoderImpl.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.config.java;
+
+import java.io.InputStream;
+import org.pkl.config.java.mapper.ValueMapper;
+import org.pkl.core.PklBinaryDecoder;
+
+final class ConfigDecoderImpl implements ConfigDecoder {
+  private final ValueMapper mapper;
+
+  ConfigDecoderImpl(ValueMapper mapper) {
+    this.mapper = mapper;
+  }
+
+  @Override
+  public ValueMapper getValueMapper() {
+    return mapper;
+  }
+
+  @Override
+  public ConfigDecoder setValueMapper(ValueMapper mapper) {
+    return new ConfigDecoderImpl(mapper);
+  }
+
+  @Override
+  public Config decode(byte[] bytes) {
+    return ConfigUtils.createConfig(PklBinaryDecoder.decode(bytes), mapper);
+  }
+
+  @Override
+  public Config decode(InputStream inputStream) {
+    return ConfigUtils.createConfig(PklBinaryDecoder.decode(inputStream), mapper);
+  }
+}

pkl-config-java/src/main/java/org/pkl/config/java/ConfigEvaluatorImpl.java

@@ -15,7 +15,7 @@
  */
 package org.pkl.config.java;
 
-import static org.pkl.config.java.ConfigUtils.makeConfig;
+import static org.pkl.config.java.ConfigUtils.createConfig;
 
 import org.pkl.config.java.mapper.ValueMapper;
 import org.pkl.core.Evaluator;
@@ -39,13 +39,13 @@ public Config evaluate(ModuleSource moduleSource) {
   @Override
   public Config evaluateOutputValue(ModuleSource moduleSource) {
     var value = evaluator.evaluateOutputValue(moduleSource);
-    return makeConfig(value, mapper);
+    return createConfig(value, mapper);
   }
 
   @Override
   public Config evaluateExpression(ModuleSource moduleSource, String expression) {
     var value = evaluator.evaluateExpression(moduleSource, expression);
-    return makeConfig(value, mapper);
+    return createConfig(value, mapper);
   }
 
   @Override

pkl-config-java/src/main/java/org/pkl/config/java/ConfigUtils.java

@@ -19,16 +19,16 @@
 import org.pkl.config.java.mapper.ValueMapper;
 import org.pkl.core.Composite;
 
-class ConfigUtils {
+final class ConfigUtils {
   private ConfigUtils() {}
 
-  static Config makeConfig(Object decoded, ValueMapper mapper) {
-    if (decoded instanceof Composite composite) {
+  static Config createConfig(Object value, ValueMapper mapper) {
+    if (value instanceof Composite composite) {
       return new CompositeConfig("", mapper, composite);
     }
-    if (decoded instanceof Map<?, ?> map) {
+    if (value instanceof Map<?, ?> map) {
       return new MapConfig("", mapper, map);
     }
-    return new LeafConfig("", mapper, decoded);
+    return new LeafConfig("", mapper, value);
   }
 }