[API Proposal]: Add async parse overload for JsonNode

[DoctorKrolic]

Background and motivation

Both JsonSerializer and JsonDocument have async parse method overloads when deserializing from Stream. However, JsonNode and JsonElement do not. This is especially odd since JsonNode.Parse under the hood calls JsonElement.ParseElement which under the hood uses JsonDocument which already has necessary asyn overloads.

I won't write a paragraph about why async is preferred when using IO operations.

API Proposal

Basically copy of existing Stream-related signature, but with Async suffix in name, warpped return type into Task and additional optional CancellationToken parameter:

namespace System.Text.Json;

public class JsonNode
{
    public static Task<JsonNode?> ParseAsync(
        Stream utf8Json,
        JsonNodeOptions? nodeOptions = null,
        JsonDocumentOptions documentOptions = default,
        CancellationToken cancellationToken = default);
}

API Usage

Nothing revolutional really...

using System.IO;
using System.Text.Json.Nodes;

using var stream = File.OpenRead("myFile.json");
var node = await JsonNode.ParseAsync(stream);
...

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Both JsonSerializer and JsonDocument have async parse method overloads when deserializing from Stream. However, JsonNode and JsonElement do not. This is especially odd since JsonNode.Parse under the hood calls JsonElement.ParseElement which under the hood uses JsonDocument which already has necessary asyn overloads.

I won't write a paragraph about why async is preferred when using IO operations.

API Proposal

Basically copy of existing Stream-related signature, but with Async suffix in name, warpped return type into Task and additional optional CancellationToken parameter:

namespace System.Text.Json;

public class JsonNode
{
    public static Task<JsonNode?> ParseAsync(
        Stream utf8Json,
        JsonNodeOptions? nodeOptions = null,
        JsonDocumentOptions documentOptions = default,
        CancellationToken cancellationToken = default);
}

API Usage

Nothing revolutional really...

using System.IO;
using System.Text.Json.Nodes;

using var stream = File.OpenRead("myFile.json");
var node = await JsonNode.ParseAsync(stream);
...

Alternative Designs

No response

Risks

No response

Author:	DoctorKrolic
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json
Milestone:	-

[eiriktsarpalis]

Seems reasonable, I think we could easily implement this method using existing internal methods. TL;DR we could just compose the existing JsonDocument.ParseAsync method with the internal JsonNodeConverter.Create method.

Slightly related, we could also consider adding async serialization support for the JsonDocument/Element/Node converters so that JsonSerializer.DeserializeAsync works as expected for these types.

[bartonjs]

Video

Looks good as proposed

namespace System.Text.Json;

public class JsonNode
{
    public static Task<JsonNode?> ParseAsync(
        Stream utf8Json,
        JsonNodeOptions? nodeOptions = null,
        JsonDocumentOptions documentOptions = default,
        CancellationToken cancellationToken = default);
}