Add public JsonElement.ParseValue() and TryParseValue()

src/libraries/System.Text.Json/ref/System.Text.Json.cs

@@ -70,6 +70,7 @@ public readonly partial struct JsonElement
         [System.CLSCompliantAttribute(false)]
         public ulong GetUInt64() { throw null; }
         public override string? ToString() { throw null; }
+        public static System.Text.Json.JsonElement ParseValue(ref System.Text.Json.Utf8JsonReader reader) { throw null; }
         public bool TryGetByte(out byte value) { throw null; }
         public bool TryGetBytesFromBase64([System.Diagnostics.CodeAnalysis.NotNullWhenAttribute(true)] out byte[]? value) { throw null; }
         public bool TryGetDateTime(out System.DateTime value) { throw null; }
@@ -92,6 +93,7 @@ public readonly partial struct JsonElement
         public bool TryGetUInt32(out uint value) { throw null; }
         [System.CLSCompliantAttribute(false)]
         public bool TryGetUInt64(out ulong value) { throw null; }
+        public static bool TryParseValue(ref System.Text.Json.Utf8JsonReader reader, [System.Diagnostics.CodeAnalysis.NotNullWhenAttribute(true)] out System.Text.Json.JsonElement? element) { throw null; }
         public bool ValueEquals(System.ReadOnlySpan<byte> utf8Text) { throw null; }
         public bool ValueEquals(System.ReadOnlySpan<char> text) { throw null; }
         public bool ValueEquals(string? text) { throw null; }

src/libraries/System.Text.Json/src/System.Text.Json.csproj

@@ -33,6 +33,7 @@
     <Compile Include="System\Text\Json\Document\JsonElement.ArrayEnumerator.cs" />
     <Compile Include="System\Text\Json\Document\JsonElement.cs" />
     <Compile Include="System\Text\Json\Document\JsonElement.ObjectEnumerator.cs" />
+    <Compile Include="System\Text\Json\Document\JsonElement.Parse.cs" />
     <Compile Include="System\Text\Json\Document\JsonProperty.cs" />
     <Compile Include="System\Text\Json\Document\JsonValueKind.cs" />
     <Compile Include="System\Text\Json\JsonCommentHandling.cs" />

src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs

@@ -337,7 +337,8 @@ public static JsonDocument ParseValue(ref Utf8JsonReader reader)
             bool ret = TryParseValue(ref reader, out JsonDocument? document, shouldThrow: true, useArrayPools: true);
 
             Debug.Assert(ret, "TryParseValue returned false with shouldThrow: true.");
-            return document!;
+            Debug.Assert(document != null, "null document returned with shouldThrow: true.");
+            return document;
         }
 
         internal static bool TryParseValue(

src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.Parse.cs

@@ -0,0 +1,100 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace System.Text.Json
+{
+    public readonly partial struct JsonElement
+    {
+        /// <summary>
+        ///   Parses one JSON value (including objects or arrays) from the provided reader.
+        /// </summary>
+        /// <param name="reader">The reader to read.</param>
+        /// <returns>
+        ///   A JsonElement representing the value (and nested values) read from the reader.
+        /// </returns>
+        /// <remarks>
+        ///   <para>
+        ///     If the <see cref="Utf8JsonReader.TokenType"/> property of <paramref name="reader"/>
+        ///     is <see cref="JsonTokenType.PropertyName"/> or <see cref="JsonTokenType.None"/>, the
+        ///     reader will be advanced by one call to <see cref="Utf8JsonReader.Read"/> to determine
+        ///     the start of the value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     Upon completion of this method <paramref name="reader"/> will be positioned at the
+        ///     final token in the JSON value.  If an exception is thrown the reader is reset to
+        ///     the state it was in when the method was called.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     This method makes a copy of the data the reader acted on, so there is no caller
+        ///     requirement to maintain data integrity beyond the return of this method.
+        ///   </para>
+        /// </remarks>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="reader"/> is using unsupported options.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   The current <paramref name="reader"/> token does not start or represent a value.
+        /// </exception>
+        /// <exception cref="JsonException">
+        ///   A value could not be read from the reader.
+        /// </exception>
+        public static JsonElement ParseValue(ref Utf8JsonReader reader)
+        {
+            bool ret = JsonDocument.TryParseValue(ref reader, out JsonDocument? document, shouldThrow: true, useArrayPools: false);
+
+            Debug.Assert(ret, "TryParseValue returned false with shouldThrow: true.");
+            Debug.Assert(document != null, "null document returned with shouldThrow: true.");
+            return document.RootElement;
+        }
+
+        /// <summary>
+        ///   Attempts to parse one JSON value (including objects or arrays) from the provided reader.
+        /// </summary>
+        /// <param name="reader">The reader to read.</param>
+        /// <param name="element">Receives the parsed element.</param>
+        /// <returns>
+        ///   <see langword="true"/> if a value was read and parsed into a JsonElement,
+        ///   <see langword="false"/> if the reader ran out of data while parsing.
+        ///   All other situations result in an exception being thrown.
+        /// </returns>
+        /// <remarks>
+        ///   <para>
+        ///     If the <see cref="Utf8JsonReader.TokenType"/> property of <paramref name="reader"/>
+        ///     is <see cref="JsonTokenType.PropertyName"/> or <see cref="JsonTokenType.None"/>, the
+        ///     reader will be advanced by one call to <see cref="Utf8JsonReader.Read"/> to determine
+        ///     the start of the value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     Upon completion of this method <paramref name="reader"/> will be positioned at the
+        ///     final token in the JSON value.  If an exception is thrown, or <see langword="false"/>
+        ///     is returned, the reader is reset to the state it was in when the method was called.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     This method makes a copy of the data the reader acted on, so there is no caller
+        ///     requirement to maintain data integrity beyond the return of this method.
+        ///   </para>
+        /// </remarks>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="reader"/> is using unsupported options.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   The current <paramref name="reader"/> token does not start or represent a value.
+        /// </exception>
+        /// <exception cref="JsonException">
+        ///   A value could not be read from the reader.
+        /// </exception>
+        public static bool TryParseValue(ref Utf8JsonReader reader, [NotNullWhen(true)] out JsonElement? element)
+        {
+            bool ret = JsonDocument.TryParseValue(ref reader, out JsonDocument? document, shouldThrow: false, useArrayPools: false);
+            element = document?.RootElement;
+            return ret;
+        }
+    }
+}

src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs

@@ -27,17 +27,6 @@ internal JsonElement(JsonDocument parent, int idx)
             _idx = idx;
         }
 
-        // Currently used only as an optimization by the serializer, which does not want to
-        // return elements that are based on the <see cref="JsonDocument.Dispose"/> pattern.
-        internal static JsonElement ParseValue(ref Utf8JsonReader reader)
-        {
-            bool ret = JsonDocument.TryParseValue(ref reader, out JsonDocument? document, shouldThrow: true, useArrayPools: false);
-
-            Debug.Assert(ret != false, "Parse returned false with shouldThrow: true.");
-            Debug.Assert(document != null, "null document returned with shouldThrow: true.");
-            return document.RootElement;
-        }
-
         [DebuggerBrowsable(DebuggerBrowsableState.Never)]
         private JsonTokenType TokenType
         {

src/libraries/System.Text.Json/tests/JsonElementParseTests.cs

@@ -0,0 +1,142 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Xunit;
+using System.Collections.Generic;
+
+namespace System.Text.Json.Tests
+{
+    public static class JsonElementParseTests
+    {
+        public static IEnumerable<object[]> ElementParseCases
+        {
+            get
+            {
+                yield return new object[] { "null", JsonValueKind.Null };
+                yield return new object[] { "true", JsonValueKind.True };
+                yield return new object[] { "false", JsonValueKind.False };
+                yield return new object[] { "\"MyString\"", JsonValueKind.String };
+                yield return new object[] { "{}", JsonValueKind.Object };
+                yield return new object[] { "[]", JsonValueKind.Array };
+            }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParseCases))]
+        public static void ParseValue(string json, JsonValueKind kind)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            JsonElement? element = JsonElement.ParseValue(ref reader);
+            Assert.Equal(kind, element!.Value.ValueKind);
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParseCases))]
+        public static void TryParseValue(string json, JsonValueKind kind)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            bool success = JsonElement.TryParseValue(ref reader, out JsonElement? element);
+            Assert.True(success);
+            Assert.Equal(kind, element!.Value.ValueKind);
+        }
+
+        public static IEnumerable<object[]> ElementParsePartialDataCases
+        {
+            get
+            {
+                yield return new object[] { "\"MyString"};
+                yield return new object[] { "{" };
+                yield return new object[] { "[" };
+            }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParsePartialDataCases))]
+        public static void ParseValuePartialDataFail(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            try
+            {
+                JsonElement.ParseValue(ref reader);
+                Assert.True(false, "Expected exception.");
+            }
+            catch (JsonException) { }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParsePartialDataCases))]
+        public static void TryParseValuePartialDataFail(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            try
+            {
+                JsonElement.TryParseValue(ref reader, out JsonElement? element);
+                Assert.True(false, "Expected exception.");
+            }
+            catch (JsonException) { }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParsePartialDataCases))]
+        public static void ParseValueOutOfData(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json), isFinalBlock: false, new JsonReaderState());
+
+            try
+            {
+                JsonElement.ParseValue(ref reader);
+                Assert.True(false, "Expected exception.");
+            }
+            catch (JsonException) { }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParsePartialDataCases))]
+        public static void TryParseValueOutOfData(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json), isFinalBlock: false, new JsonReaderState());
+            Assert.False(JsonElement.TryParseValue(ref reader, out JsonElement? element));
+        }
+
+        public static IEnumerable<object[]> ElementParseInvalidDataCases
+        {
+            get
+            {
+                yield return new object[] { "nul" };
+                yield return new object[] { "{]" };
+            }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParseInvalidDataCases))]
+        public static void ParseValueInvalidDataFail(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            try
+            {
+                JsonElement.ParseValue(ref reader);
+                Assert.True(false, "Expected exception.");
+            }
+            catch (JsonException) { }
+        }
+
+        [Theory]
+        [MemberData(nameof(ElementParseInvalidDataCases))]
+        public static void TryParseValueInvalidDataFail(string json)
+        {
+            var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
+
+            try
+            {
+                JsonElement.TryParseValue(ref reader, out JsonElement? element);
+                Assert.True(false, "Expected exception.");
+            }
+            catch (JsonException) { }
+        }
+    }
+}

src/libraries/System.Text.Json/tests/System.Text.Json.Tests.csproj

@@ -21,6 +21,7 @@
     <Compile Include="JsonDateTimeTestData.cs" />
     <Compile Include="JsonDocumentTests.cs" />
     <Compile Include="JsonElementCloneTests.cs" />
+    <Compile Include="JsonElementParseTests.cs" />
     <Compile Include="JsonElementWriteTests.cs" />
     <Compile Include="JsonEncodedTextTests.cs" />
     <Compile Include="JsonGuidTestData.cs" />