Add documentation and tests for typed/untyped conversion utilities (#2)

* Document type conversion utilities (fromUntyped/toUntyped)

Added comprehensive documentation for the Json.fromUntyped() and Json.toUntyped()
methods that provide bidirectional conversion between JsonValue objects and
standard Java collections/types. Includes usage examples and type mappings.

* Add comprehensive tests for typed/untyped conversion utilities

- Created JsonTypedUntypedTests with full coverage of Json.fromUntyped() and Json.toUntyped()
- Tests simple types, collections, nested structures, edge cases, and round-trip conversion
- Added .mvn directory to fix mvnd warning about root directory

* Fix JsonTypedUntypedTests compilation and test failures

- Fixed generic type issues with List<?> by using @SuppressWarnings and proper casting
- Corrected numeric type expectations (Integer boxed to Long in JsonNumber)
- All 14 tests now pass successfully

* Update GitHub Actions to trigger on PR events

- Added explicit PR event types: opened, synchronize, reopened
- Ensures checks run when PRs are created or updated

Author: Simon Massey

README.md

@@ -43,4 +43,40 @@ The API provides immutable JSON value types:
 Parsing is done via the `Json` class:
 ```java
 JsonValue value = Json.parse(jsonString);
-```
+```
+
+## Type Conversion Utilities
+
+The `Json` class provides bidirectional conversion between `JsonValue` objects and standard Java types:
+
+### Converting from Java Objects to JSON (`fromUntyped`)
+```java
+// Convert standard Java collections to JsonValue
+Map<String, Object> data = Map.of(
+    "name", "John",
+    "age", 30,
+    "scores", List.of(85, 92, 78)
+);
+JsonValue json = Json.fromUntyped(data);
+```
+
+### Converting from JSON to Java Objects (`toUntyped`)
+```java
+// Convert JsonValue back to standard Java types
+JsonValue parsed = Json.parse("{\"name\":\"John\",\"age\":30}");
+Object data = Json.toUntyped(parsed);
+// Returns a Map<String, Object> with standard Java types
+```
+
+The conversion mappings are:
+- `JsonObject` ↔ `Map<String, Object>`
+- `JsonArray` ↔ `List<Object>`
+- `JsonString` ↔ `String`
+- `JsonNumber` ↔ `Number` (Long, Double, BigInteger, or BigDecimal)
+- `JsonBoolean` ↔ `Boolean`
+- `JsonNull` ↔ `null`
+
+This is useful for:
+- Integrating with existing code that uses standard collections
+- Serializing/deserializing to formats that expect Java types
+- Working with frameworks that use reflection on standard types

src/main/java/jdk/sandbox/demo/JsonDemo.java

@@ -14,8 +14,8 @@ public static void main(String[] args) {
             "age", JsonNumber.of(30)
         ));
 
-        System.out.println(jsonObject.toString());
-        
+        System.out.println(jsonObject);
+
         // Parse JSON string
         String jsonStr = "{\"name\":\"Jane\",\"age\":25}";
         var parsed = Json.parse(jsonStr);

src/main/java/jdk/sandbox/internal/util/json/JsonNumberImpl.java

@@ -40,9 +40,9 @@ public final class JsonNumberImpl implements JsonNumber {
     private final int startOffset;
     private final int endOffset;
     private final boolean isFp;
-    private final jdk.sandbox.StableValue<Number> theNumber = jdk.sandbox.StableValue.of();
-    private final jdk.sandbox.StableValue<String> numString = jdk.sandbox.StableValue.of();
-    private final jdk.sandbox.StableValue<BigDecimal> cachedBD = jdk.sandbox.StableValue.of();
+    private final StableValue<Number> theNumber = StableValue.of();
+    private final StableValue<String> numString = StableValue.of();
+    private final StableValue<BigDecimal> cachedBD = StableValue.of();
 
     public JsonNumberImpl(Number num) {
         // Called by factories. Input is Double, Long, BI, or BD.

src/main/java/jdk/sandbox/internal/util/json/JsonParser.java

@@ -48,7 +48,7 @@ public final class JsonParser {
     // Access to the underlying JSON contents
     private final char[] doc;
     // Lazily initialized for member names with escape sequences
-    private final Supplier<StringBuilder> sb = jdk.sandbox.StableValue.supplier(this::initSb);
+    private final Supplier<StringBuilder> sb = StableValue.supplier(this::initSb);
     // Current offset during parsing
     private int offset;
     // For exception message on failure

src/main/java/jdk/sandbox/internal/util/json/JsonStringImpl.java

@@ -42,12 +42,12 @@ public final class JsonStringImpl implements JsonString {
     // It always conforms to JSON syntax. If created by parsing a JSON document,
     // it matches the original text exactly. If created via the factory method,
     // non-conformant characters are properly escaped.
-    private final jdk.sandbox.StableValue<String> jsonStr = jdk.sandbox.StableValue.of();
+    private final StableValue<String> jsonStr = StableValue.of();
 
     // The String instance returned by `value()`.
     // If created by parsing a JSON document, escaped characters are unescaped.
     // If created via the factory method, the input String is used as-is.
-    private final jdk.sandbox.StableValue<String> value = jdk.sandbox.StableValue.of();
+    private final StableValue<String> value = StableValue.of();
 
     // Called by JsonString.of() factory. The passed String represents the
     // unescaped value.

…c/main/java/jdk/sandbox/StableValue.java …dbox/internal/util/json/StableValue.javasrc/main/java/jdk/sandbox/StableValue.java renamed to src/main/java/jdk/sandbox/internal/util/json/StableValue.java src/main/java/jdk/sandbox/StableValue.java renamed to src/main/java/jdk/sandbox/internal/util/json/StableValue.java

@@ -1,40 +1,26 @@
-package jdk.sandbox;
+package jdk.sandbox.internal.util.json;
 
 import java.util.function.Supplier;
 
 /**
  * Mimics JDK's StableValue using double-checked locking pattern
  * for thread-safe lazy initialization.
  */
-public class StableValue<T> {
+class StableValue<T> {
     private volatile T value;
     private final Object lock = new Object();
-    
+
     private StableValue() {}
-    
+
     public static <T> StableValue<T> of() {
         return new StableValue<>();
     }
-    
-    public T get() {
-        return value;
-    }
-    
-    public void set(T value) {
-        if (this.value == null) {
-            synchronized (lock) {
-                if (this.value == null) {
-                    this.value = value;
-                }
-            }
-        }
-    }
-    
-    public T orElse(T defaultValue) {
+
+  public T orElse(T defaultValue) {
         T result = value;
         return result != null ? result : defaultValue;
     }
-    
+
     public T orElseSet(Supplier<T> supplier) {
         T result = value;
         if (result == null) {
@@ -47,7 +33,7 @@ public T orElseSet(Supplier<T> supplier) {
         }
         return result;
     }
-    
+
     public void setOrThrow(T newValue) {
         if (value != null) {
             throw new IllegalStateException("Value already set");
@@ -59,25 +45,25 @@ public void setOrThrow(T newValue) {
             value = newValue;
         }
     }
-    
+
     public static <T> Supplier<T> supplier(Supplier<T> supplier) {
-        return new Supplier<T>() {
-            private volatile T cached;
-            private final Object supplierLock = new Object();
-            
-            @Override
-            public T get() {
-                T result = cached;
+        return new Supplier<>() {
+          private volatile T cached;
+          private final Object supplierLock = new Object();
+
+          @Override
+          public T get() {
+            T result = cached;
+            if (result == null) {
+              synchronized (supplierLock) {
+                result = cached;
                 if (result == null) {
-                    synchronized (supplierLock) {
-                        result = cached;
-                        if (result == null) {
-                            cached = result = supplier.get();
-                        }
-                    }
+                  cached = result = supplier.get();
                 }
-                return result;
+              }
             }
+            return result;
+          }
         };
     }
 }

src/main/java/jdk/sandbox/java/util/json/Json.java

@@ -48,8 +48,8 @@
  * <p>
  * {@link #fromUntyped(Object)} and {@link #toUntyped(JsonValue)} provide a conversion
  * between {@code JsonValue} and an untyped object.
- *
- * @spec https://datatracker.ietf.org/doc/html/rfc8259 RFC 8259: The JavaScript
+ * <p>
+ * {@code @spec} <a href="https://datatracker.ietf.org/doc/html/rfc8259">...</a> RFC 8259: The JavaScript
  *      Object Notation (JSON) Data Interchange Format
  * @since 99
  */