feat: add async APIs for ToonEncoder and ToonDecoder (#19)

Author: parsapanahpoor

src/ToonFormat/ToonDecoder.cs

@@ -4,6 +4,8 @@
 using System.Text;
 using System.Text.Json;
 using System.Text.Json.Nodes;
+using System.Threading;
+using System.Threading.Tasks;
 using ToonFormat;
 using ToonFormat.Internal.Decode;
 
@@ -194,4 +196,124 @@ public static class ToonDecoder
         var text = reader.ReadToEnd();
         return Decode<T>(text, options ?? new ToonDecodeOptions());
     }
+
+    #region Async Methods
+
+    /// <summary>
+    /// Asynchronously decodes a TOON-formatted string into a JsonNode with default options.
+    /// </summary>
+    /// <param name="toonString">The TOON-formatted string to decode.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the decoded JsonNode.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when toonString is null.</exception>
+    /// <exception cref="ToonFormatException">Thrown when the TOON format is invalid.</exception>
+    public static Task<JsonNode?> DecodeAsync(string toonString, CancellationToken cancellationToken = default)
+    {
+        return DecodeAsync(toonString, new ToonDecodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes a TOON-formatted string into a JsonNode with custom options.
+    /// </summary>
+    /// <param name="toonString">The TOON-formatted string to decode.</param>
+    /// <param name="options">Decoding options to customize parsing behavior.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the decoded JsonNode.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when toonString or options is null.</exception>
+    /// <exception cref="ToonFormatException">Thrown when the TOON format is invalid.</exception>
+    public static Task<JsonNode?> DecodeAsync(string toonString, ToonDecodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var result = Decode(toonString, options);
+        return Task.FromResult(result);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes a TOON-formatted string into the specified type with default options.
+    /// </summary>
+    /// <typeparam name="T">Target type to deserialize into.</typeparam>
+    /// <param name="toonString">The TOON-formatted string to decode.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized value.</returns>
+    public static Task<T?> DecodeAsync<T>(string toonString, CancellationToken cancellationToken = default)
+    {
+        return DecodeAsync<T>(toonString, new ToonDecodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes a TOON-formatted string into the specified type with custom options.
+    /// </summary>
+    /// <typeparam name="T">Target type to deserialize into.</typeparam>
+    /// <param name="toonString">The TOON-formatted string to decode.</param>
+    /// <param name="options">Decoding options to customize parsing behavior.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized value.</returns>
+    public static Task<T?> DecodeAsync<T>(string toonString, ToonDecodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var result = Decode<T>(toonString, options);
+        return Task.FromResult(result);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes TOON data from a stream (UTF-8) into a JsonNode with default options.
+    /// </summary>
+    /// <param name="stream">The input stream to read from.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the decoded JsonNode.</returns>
+    public static Task<JsonNode?> DecodeAsync(Stream stream, CancellationToken cancellationToken = default)
+    {
+        return DecodeAsync(stream, new ToonDecodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes TOON data from a stream (UTF-8) into a JsonNode with custom options.
+    /// </summary>
+    /// <param name="stream">The input stream to read from.</param>
+    /// <param name="options">Decoding options to customize parsing behavior.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the decoded JsonNode.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when stream is null.</exception>
+    public static async Task<JsonNode?> DecodeAsync(Stream stream, ToonDecodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        if (stream == null)
+            throw new ArgumentNullException(nameof(stream));
+
+        using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true, leaveOpen: true);
+        var text = await reader.ReadToEndAsync(cancellationToken).ConfigureAwait(false);
+        return Decode(text, options ?? new ToonDecodeOptions());
+    }
+
+    /// <summary>
+    /// Asynchronously decodes TOON data from a stream (UTF-8) into the specified type with default options.
+    /// </summary>
+    /// <typeparam name="T">Target type to deserialize into.</typeparam>
+    /// <param name="stream">The input stream to read from.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized value.</returns>
+    public static Task<T?> DecodeAsync<T>(Stream stream, CancellationToken cancellationToken = default)
+    {
+        return DecodeAsync<T>(stream, new ToonDecodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously decodes TOON data from a stream (UTF-8) into the specified type with custom options.
+    /// </summary>
+    /// <typeparam name="T">Target type to deserialize into.</typeparam>
+    /// <param name="stream">The input stream to read from.</param>
+    /// <param name="options">Decoding options to customize parsing behavior.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized value.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when stream is null.</exception>
+    public static async Task<T?> DecodeAsync<T>(Stream stream, ToonDecodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        if (stream == null)
+            throw new ArgumentNullException(nameof(stream));
+
+        using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true, leaveOpen: true);
+        var text = await reader.ReadToEndAsync(cancellationToken).ConfigureAwait(false);
+        return Decode<T>(text, options ?? new ToonDecodeOptions());
+    }
+
+    #endregion
 }

src/ToonFormat/ToonEncoder.cs

@@ -3,6 +3,8 @@
 using System.ComponentModel;
 using System.IO;
 using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
 using ToonFormat;
 using ToonFormat.Internal.Encode;
 
@@ -192,4 +194,97 @@ public static void EncodeToStream<T>(T data, Stream destination, ToonEncodeOptio
         var bytes = EncodeToBytes(data, options);
         destination.Write(bytes, 0, bytes.Length);
     }
+
+    #region Async Methods
+
+    /// <summary>
+    /// Asynchronously encodes the specified value into TOON format with default options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the TOON-formatted string.</returns>
+    public static Task<string> EncodeAsync<T>(T data, CancellationToken cancellationToken = default)
+    {
+        return EncodeAsync(data, new ToonEncodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously encodes the specified value into TOON format with custom options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="options">Encoding options to customize the output format.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the TOON-formatted string.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when options is null.</exception>
+    public static Task<string> EncodeAsync<T>(T data, ToonEncodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var result = Encode(data, options);
+        return Task.FromResult(result);
+    }
+
+    /// <summary>
+    /// Asynchronously encodes the specified value into UTF-8 bytes with default options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the UTF-8 encoded TOON bytes.</returns>
+    public static Task<byte[]> EncodeToBytesAsync<T>(T data, CancellationToken cancellationToken = default)
+    {
+        return EncodeToBytesAsync(data, new ToonEncodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously encodes the specified value into UTF-8 bytes with custom options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="options">Encoding options to customize the output format.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the UTF-8 encoded TOON bytes.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when options is null.</exception>
+    public static Task<byte[]> EncodeToBytesAsync<T>(T data, ToonEncodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        var result = EncodeToBytes(data, options);
+        return Task.FromResult(result);
+    }
+
+    /// <summary>
+    /// Asynchronously encodes the specified value and writes UTF-8 bytes to the destination stream using default options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="destination">The destination stream to write to. The stream is not disposed.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous write operation.</returns>
+    public static Task EncodeToStreamAsync<T>(T data, Stream destination, CancellationToken cancellationToken = default)
+    {
+        return EncodeToStreamAsync(data, destination, new ToonEncodeOptions(), cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously encodes the specified value and writes UTF-8 bytes to the destination stream using custom options.
+    /// </summary>
+    /// <typeparam name="T">Type of the value to encode.</typeparam>
+    /// <param name="data">The value to encode.</param>
+    /// <param name="destination">The destination stream to write to. The stream is not disposed.</param>
+    /// <param name="options">Encoding options to customize the output format.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task that represents the asynchronous write operation.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when destination or options is null.</exception>
+    public static async Task EncodeToStreamAsync<T>(T data, Stream destination, ToonEncodeOptions? options, CancellationToken cancellationToken = default)
+    {
+        if (destination == null)
+            throw new ArgumentNullException(nameof(destination));
+
+        cancellationToken.ThrowIfCancellationRequested();
+        var bytes = EncodeToBytes(data, options);
+        await destination.WriteAsync(bytes, 0, bytes.Length, cancellationToken).ConfigureAwait(false);
+    }
+
+    #endregion
 }