feat!: return IAsyncEnumerable from Watch and OnChange

[LucDeCaf]

Status

TODOS

• Implementation
• Use within codebase / demos
• Replace Listen with ListenAsync for most/all uses
• Better tests / testing practices

Description

Most SDKs have moved away from the callback-based APIs and towards async iterators/enumerators. This comes with a few ergonomic benefits and a few practical ones, including the ability to subscribe to changes lazily. Using an async iterator means users can decide when they want to process the next item in the stream, whereas with callbacks, changes are pushed eagerly and are processed when we are ready instead of when the caller is ready.

I want to avoid maintaining two APIs for this, as doing so could lead to a situation like the one in the Javascript SDK, where both approaches need to be maintained in order to maintain API stability guarantees. This makes the implementation code for watched queries in JS quite difficult to follow. Plus, the eager-fetching behaviour from the old callback style can still be achieved via a background task, so the callback syntax is somewhat obsoleted by the async iterator syntax.

This PR replaces the callback-based maintenance nightmare that was the old Watch and OnChange implementations and return types with methods that return IAsyncEnumerable's, using the Kotlin SDK as a reference. IMO, this makes Watch both more flexible and easier to maintain.

Example

Old syntax

// Optional cancellation token
var cts = new CancellationTokenSource();

// Register listener synchronously on main thread (callbacks run on separate thread)
var dispose = db.Watch<Todo>(
    "SELECT * FROM todos",
    [],
    new WatchHandler()
    {
        OnResult = (result) =>
        {
            Console.WriteLine($"Number of todos: {result.Length}");
        },
        OnError = (ex) => { throw ex; }
    },
    new SQLWatchOptions { Signal = cts.Token }
);

// Stop watching via IDisposable callback or by cancelling token
dispose.Dispose();
// OR:
// cts.Cancel();

New syntax

// Register listener synchronously on main thread
var listener = db.Watch<Todo>(
    "SELECT * FROM todos",
    [],
    new SQLWatchOptions { Signal = cts.Token }
);

// ...then listen to changes on another thread
_ = Task.Run(async () =>
{
    await foreach (var result in listener)
    {
        Console.WriteLine($"Number of todos: {result.Length}");
    }
}, cts.Token);

// Stop watching by cancelling token
cts.Cancel();

[Chriztiaan]

Happy with the changes from my side.

[Chriztiaan]

Changelog entry