Consider async API for large document processing

[vaceslav]

Description

Add async/await support for processing large documents to improve performance and prevent blocking in server applications.

Current Limitation

All APIs are synchronous, which can block threads when processing large documents (50+ pages, thousands of placeholders).

Proposed API Changes

New Async Methods

public async Task<ProcessingResult> ProcessTemplateAsync(
    Stream templateStream,
    Stream outputStream, 
    Dictionary<string, object> data,
    PlaceholderReplacementOptions? options = null,
    CancellationToken cancellationToken = default)
{
    // Async implementation
}

Visitor Pattern Updates

public interface ITemplateElementVisitorAsync
{
    Task VisitConditionalAsync(ConditionalBlock conditional, IEvaluationContext context);
    Task VisitLoopAsync(LoopBlock loop, IEvaluationContext context);
    Task VisitParagraphAsync(Paragraph paragraph, IEvaluationContext context);
}

Benefits

• Non-blocking I/O operations
• Better scalability in web applications
• Cancellation support
• Progress reporting capability
• Reduced memory pressure with streaming

Implementation Considerations

Breaking Change

This would be a v2.0 breaking change unless we:

1. Keep sync methods and add async overloads
2. Implement sync methods as wrappers
3. Maintain two parallel implementations

Performance Considerations

• Async overhead for small documents
• Consider threshold for sync vs async
• Benchmark performance impact

Use Cases

• Web API endpoints processing templates
• Batch processing applications
• Large document generation (reports, catalogs)
• Cloud functions/serverless scenarios

Alternative Approach

Instead of full async, consider:

• Streaming API for large documents
• Chunked processing
• Background task queue
• Worker service pattern

Acceptance Criteria

• Async API methods available
• Cancellation token support
• Progress reporting (IProgress)
• Maintains backwards compatibility
• Performance benchmarks
• Documentation for when to use async
• Examples for ASP.NET Core integration

Priority

Low - Consider for v2.0

Breaking Change Assessment

• Option 1: Add async methods alongside sync (no breaking change)
• Option 2: Replace sync with async (breaking change, v2.0)
• Option 3: Separate NuGet package for async API

References

• Async best practices
• Performance benchmarks showing need
• User feedback requesting async support