Debouncer.Sharp 1.1.6

Debouncer.Sharp

Thread-safe debounce primitives for delayed, coalesced async work.

Three tiers, pick the one that matches your use case:

Install

<PackageReference Include="Debouncer.Sharp" Version="1.0.*" />

Or via CLI:

dotnet add package Debouncer.Sharp

Versioning follows Semantic Versioning. Releases are cut by pushing a vX.Y.Z git tag; see CHANGELOG.md for release history.

Releasing

The Publish NuGet workflow only runs on vX.Y.Z tag pushes, and will fail unless the .csproj version and CHANGELOG.md are both updated first. To cut a release:

1. Bump <Version> in Debouncer.Sharp.csproj.
2. Move the relevant [Unreleased] entries in CHANGELOG.md into a new ## [X.Y.Z] - YYYY-MM-DD section.
3. Commit both changes.
4. Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z — this triggers the publish workflow.

Basic debouncer

using Debouncer.Sharp;

using var debouncer = new Debouncer(TimeSpan.FromMilliseconds(250));

await debouncer.HitAsync(async ct =>
{
    await PersistAsync(ct);
});

Each hit cancels any pending action. Only the latest action runs after the delay window.

Async fetch + apply

using Debouncer.Sharp;

var operation = new DebouncedAsync<string, SearchResult>(
    TimeSpan.FromMilliseconds(300),
    fetchAsync: SearchAsync,
    apply: (_, result) => ViewModel.Apply(result),
    shouldApply: (query, _) => query == ViewModel.CurrentQuery,
    cache: null,
    cacheTtl: TimeSpan.FromSeconds(30),
    dispatcher: null);

If you need UI-thread marshalling, pass a GuiDispatcher.Sharp IGuiDispatcher to DebouncedAsync or DebounceFactory — e.g. AvaloniaGuiDispatcher from GuiDispatcher.Sharp.Avalonia, or ImmediateGuiDispatcher for headless/test hosts.

Latest value (coalesce to newest)

using Debouncer.Sharp;

using var settingsSave = factory.CreateLatest<Settings>(
    TimeSpan.FromMilliseconds(750),
    applyAsync: async (settings, ct) => await SaveToDiskAsync(settings, ct));

settingsSave.Hit(currentSettings); // rapid calls coalesce to the last value

Important: Dispose() only cancels the pending timer — it does not flush. If you need a guaranteed write before shutdown, await FlushAsync() explicitly before disposing:

await settingsSave.FlushAsync();
settingsSave.Dispose();

This avoids a sync-over-async deadlock risk when IGuiDispatcher marshals onto a UI thread that a blocking flush-on-dispose could otherwise block against.

Batch (collect then flush, with caps)

using Debouncer.Sharp;

using var telemetry = factory.CreateBatch<TelemetryEvent>(
    TimeSpan.FromSeconds(1),
    flushAsync: async (events, ct) => await SendBatchAsync(events, ct),
    options: new DebouncedBatchOptions
    {
        MaxBatchSize = 1000,       // flush as soon as the buffer reaches this many items
        MaxWait = TimeSpan.FromSeconds(5), // flush even if items keep arriving without a quiet period
    });

telemetry.Add(evt);

A pure debounce would postpone the flush forever under continuous load, since the quiet period never elapses. MaxBatchSize and MaxWait are hard caps that force a flush regardless of ongoing activity — MaxWait should typically be >= delay. Same Dispose()-does-not-flush caveat as IDebouncedLatest<T> applies here.

File system sinks (Debouncer.Sharp.FileSystem)

Ready-made sinks for the most common debounce use case — coalescing writes to a file:

using Debouncer.Sharp.FileSystem;
using System.Text.Json.Serialization;

[JsonSerializable(typeof(Settings))]
internal partial class AppJsonContext : JsonSerializerContext { }

// Atomic JSON snapshot: writes to a temp sibling, then moves it into place.
using var settingsSave = factory.CreateJsonSnapshot(
    "settings.json",
    TimeSpan.FromMilliseconds(750),
    AppJsonContext.Default.Settings,
    onError: ex => log.Warning(ex, "Failed to save settings"));

settingsSave.Hit(currentSettings);

// JSON Lines batch: plain .jsonl append, or additive bursts inside a .jsonl.zip archive.
using var telemetry = factory.CreateJsonLinesBatch(
    "telemetry.jsonl",
    TimeSpan.FromSeconds(1),
    AppJsonContext.Default.TelemetryEvent,
    options: new DebouncedBatchOptions { MaxBatchSize = 1000 },
    zip: true, // omit or set false for a plain, human-readable .jsonl file
    onError: ex => log.Warning(ex, "Failed to write telemetry batch"));

telemetry.Add(evt);

// Reading back a zip-mode batch:
var events = JsonlZipReader.ReadAllRecords("telemetry.jsonl.zip", AppJsonContext.Default.TelemetryEvent);

Both sinks take an optional onError callback invoked instead of throwing when the write fails (a transient disk error shouldn't crash the debouncer); without it, failures propagate through FlushAsync()/the discarded background task, same as the raw tiers. The zip sink also accepts an optional onDiagnostic callback for informational messages (e.g. burst-sequence recovery on restart). There's no logging-framework dependency — these are plain Action delegates, by design.

Deterministic testing

Debounce timers use the standard .NET TimeProvider abstraction. Pass a FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) to make quiet-period behaviour deterministic in tests:

using Microsoft.Extensions.Time.Testing;

var time = new FakeTimeProvider();
using var latest = new DebouncedLatest<int>(
    TimeSpan.FromMilliseconds(250),
    applyAsync: async (value, ct) => { /* ... */ },
    timeProvider: time);

latest.Hit(1);
latest.Hit(2);
time.Advance(TimeSpan.FromMilliseconds(250));
await Task.Yield();

// apply ran for value 2 — no real-time sleep required

The same optional timeProvider is available on Debouncer, DebouncedAsync<TIn,TOut>, DebouncedBatch<T>, and DebounceFactory. Omit it in production code.

Dependency injection

using Debouncer.Sharp;
using GuiDispatcher.Sharp;
using Microsoft.Extensions.DependencyInjection;

services.AddDebouncing();

// Optional: register a dispatcher for UI-thread apply
services.AddSingleton<IGuiDispatcher, MyUiDispatcher>();

var factory = serviceProvider.GetRequiredService<IDebounceFactory>();
var cache = serviceProvider.CreateDebounceCache<string, SearchResult>("search");

// The same factory also exposes the Latest and Batch tiers:
var settingsSave = factory.CreateLatest<Settings>(TimeSpan.FromMilliseconds(750), SaveAsync);
var telemetry = factory.CreateBatch<TelemetryEvent>(TimeSpan.FromSeconds(1), SendBatchAsync);

API overview