[API Proposal]: Add JsonSerializer.SerializeAsync returning string

[Dreamescaper]

Background and motivation

JsonSerializer requires async execution for some types, like IAsyncEnumerable. I would be nice to have a method SerializeAsync, which returns serialized string instead of writing to stream.

API Proposal

Add the following methods:

public static Task<string> SerializeAsync<TValue>(TValue value, JsonSerializerOptions? options = null);
public static Task<string> SerializeAsync<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo);
public static Task<string> SerializeAsync(object? value, Type inputType, JsonSerializerContext context);
public static Task<string> SerializeAsync(object? value, Type inputType, JsonSerializerOptions? options = null);
public static Task<string> SerializeAsync(object? value, JsonTypeInfo jsonTypeInfo);
public static Task<byte[]> SerializeToUtf8BytesAsync<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo);
public static Task<byte[]> SerializeToUtf8BytesAsync<TValue>(TValue value, JsonSerializerOptions? options = null);
public static Task<byte[]> SerializeToUtf8BytesAsync(object? value, Type inputType, JsonSerializerContext context);
public static Task<byte[]> SerializeToUtf8BytesAsync(object? value, Type inputType, JsonSerializerOptions? options = null);
public static Task<byte[]> SerializeToUtf8BytesAsync(object? value, JsonTypeInfo jsonTypeInfo);
public static Task<JsonNode?> SerializeToNodeAsync<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo);
public static Task<JsonNode?> SerializeToNodeAsync<TValue>(TValue value, JsonSerializerOptions? options = null);
public static Task<JsonNode?> SerializeToNodeAsync(object? value, Type inputType, JsonSerializerContext context);
public static Task<JsonNode?> SerializeToNodeAsync(object? value, Type inputType, JsonSerializerOptions? options = null);
public static Task<JsonNode?> SerializeToNodeAsync(object? value, JsonTypeInfo jsonTypeInfo);
public static Task<JsonElement> SerializeToElementAsync<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo);
public static Task<JsonElement> SerializeToElementAsync<TValue>(TValue value, JsonSerializerOptions? options = null);
public static Task<JsonElement> SerializeToElementAsync(object? value, Type inputType, JsonSerializerContext context);
public static Task<JsonElement> SerializeToElementAsync(object? value, Type inputType, JsonSerializerOptions? options = null);
public static Task<JsonElement> SerializeToElementAsync(object? value, JsonTypeInfo jsonTypeInfo);
public static Task<JsonDocument> SerializeToDocumentAsync<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo);
public static Task<JsonDocument> SerializeToDocumentAsync<TValue>(TValue value, JsonSerializerOptions? options = null);
public static Task<JsonDocument> SerializeToDocumentAsync(object? value, Type inputType, JsonSerializerContext context);
public static Task<JsonDocument> SerializeToDocumentAsync(object? value, Type inputType, JsonSerializerOptions? options = null);
public static Task<JsonDocument> SerializeToDocumentAsync(object? value, JsonTypeInfo jsonTypeInfo);

API Usage

IAsyncEnumerable<MyType> asyncEnumerable = GetAsyncEnumerable();
var json = await JsonSerializer.SerializeAsync(asyncEnumerable);

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

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

[eiriktsarpalis]

Seems reasonable given that async serialization is a prerequisite for IAsyncEnumerable support. For completeness we should also consider accelerators for all the other supported encoding mediums such as SerializeToNodeAsync, SerializeToUtf8Async and SerializeToElementAsync, SerializeToDocumentAsync, etc.

[Dreamescaper]

@eiriktsarpalis
Would it be fine for me to contribute it?

[eiriktsarpalis]

The API proposal needs a bit of work before we can consider it for API review. Bare minimum it should scope out all the relevant overloads that need to be included as part of this change. It's not something our team can prioritize right now, but if you want to expedite the process you can try by updating the OP to something that can be easily reviewed. You can take a look at previously approved proposals for examples of what this should look like.

[Dreamescaper]

@eiriktsarpalis
Would you prefer for me to add SerializeToNodeAsync, SerializeToUtf8Async and SerializeToElementAsync, SerializeToDocumentAsync, etc. to the proposal?

Or focus on SerializeAsync, and tackle others separately?

[eiriktsarpalis]

I think they should be addressed in tandem. They logically belong to the same set of APIs but they use different names out of disambiguation concerns.

[Dreamescaper]

@eiriktsarpalis
I have updated the proposal.
Currently there are 5 overloads for each of Serialize* methods. I have included Async counterparts for all of them (although I am not sure whether all of them are needed here).