AnoiAsyncDebouncer 1.1.0

AnoiAsyncDebouncer

A lightweight, high-performance async debouncer for .NET with typed return values and cancellation token support.

Features

• Typed return values - Generic AsyncDebouncer<T> supports any return type
• Cancellation support - Proper cancellation token propagation
• Thread-safe - Safe for concurrent access
• Flush support - Execute pending operations immediately
• Max wait time - Optional cap on total debounce duration to prevent starvation under sustained input
• Memory efficient - Uses object pooling for CancellationTokenSource instances
• Zero dependencies - Only depends on .NET Standard 2.1
• Non-generic version - AsyncDebouncer for void operations

Installation

dotnet add package AnoiAsyncDebouncer

Or via Package Manager:

Install-Package AnoiAsyncDebouncer

Quick Start

Basic Usage (with return value)

using AnoiAsyncDebouncer;

// Create a debouncer for string results
var debouncer = new AsyncDebouncer<string>();

// Debounce an async operation with 300ms delay
var result = await debouncer.DebounceAsync(async cancellationToken =>
{
    return await SearchApiAsync(searchTerm, cancellationToken);
}, delayMilliseconds: 300);

Void Operations

// For operations without return values
var debouncer = new AsyncDebouncer();

await debouncer.DebounceAsync(async cancellationToken =>
{
    await SaveDataAsync(cancellationToken);
}, delayMilliseconds: 500);

Blazor Search Example

@inject HttpClient Http
@implements IDisposable

<input @oninput="OnSearchInput" placeholder="Search..." />

@code {
    private readonly AsyncDebouncer<List<string>> _searchDebouncer = new();
    private List<string> searchResults = new();

    private async Task OnSearchInput(ChangeEventArgs e)
    {
        var searchTerm = e.Value?.ToString() ?? "";
        
        searchResults = await _searchDebouncer.DebounceAsync(async ct =>
        {
            if (string.IsNullOrWhiteSpace(searchTerm))
                return new List<string>();
                
            return await Http.GetFromJsonAsync<List<string>>(
                $"api/search?q={searchTerm}", ct) ?? new List<string>();
        }, 300, defaultValue: new List<string>());
        
        StateHasChanged();
    }

    public void Dispose() => _searchDebouncer.Dispose();
}

API Reference

AsyncDebouncer<T>

AsyncDebouncer (non-generic)

Same API as above but for void operations. Does not throw on cancellation.

Advanced Usage

Cancellation Support

The cancellation token passed to your operation is automatically cancelled when:

• A new debounce call supersedes the current one
• Cancel() is called
• Dispose() is called

await debouncer.DebounceAsync(async ct =>
{
    // Check cancellation in long-running operations
    ct.ThrowIfCancellationRequested();
    
    // Or pass it to async methods
    await LongRunningOperationAsync(ct);
    
    return result;
}, 300);

Flush Pending Operations

// Execute any pending operation immediately (e.g., before form submit)
var result = await debouncer.FlushAsync();

Max Wait Time (Prevent Starvation)

When a debouncer is continuously called (e.g., a stream of rapid events), normal debouncing will keep resetting the timer and the operation may never execute. The optional maxWaitTime parameter sets an upper bound on how long debouncing can continue before the operation is forced to execute.

// Force execution if debouncing has lasted more than 2 seconds,
// even if new calls keep arriving
var result = await debouncer.DebounceAsync(async ct =>
{
    return await RefreshScreenAsync(ct);
}, delayMilliseconds: 300, maxWaitTime: TimeSpan.FromSeconds(2));

This is especially useful for UI scenarios such as screen redraws or live previews where you want to wait for a pause in activity, but also guarantee the user sees an update within a reasonable time.

// Non-generic version works the same way
var debouncer = new AsyncDebouncer();

await debouncer.DebounceAsync(async ct =>
{
    await RenderPreviewAsync(ct);
}, delayMilliseconds: 500, maxWaitTime: TimeSpan.FromSeconds(3));

If maxWaitTime is not specified (or null), the debouncer behaves exactly as before — it will keep resetting the timer on every call.

Default Values on Cancellation

// Returns empty list instead of throwing when cancelled
var results = await debouncer.DebounceAsync(
    async ct => await FetchDataAsync(ct),
    delayMilliseconds: 300,
    defaultValue: new List<Item>()
);

Best Practices

1. Always dispose - Implement IDisposable in your components and dispose the debouncer
2. Use cancellation tokens - Pass the token to your async operations for proper cancellation
3. Consider default values - Use the defaultValue overload in UI scenarios to avoid exception handling
4. One debouncer per operation type - Create separate debouncers for different operations

Requirements

• .NET Standard 2.1 or higher
• Compatible with: .NET Core 3.0+, .NET 5+, .NET 6+, .NET 7+, .NET 8+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel to submit a Pull Request.

Repository

https://github.com/eeaquino/AnoiAsyncDebouncer