Proposal: Use async primitives instead of timeout durations

[simolus3]

We currently expose timeouts and debounce operations built-in to sqlite_async by passing durations:

• onChange and watch have a Duration throttle parameter indicating a minimum delay between durations.
• readTransaction and writeTransaction have a Duration lockTimeout parameter indicating the maximum time to wait for a free connection.

Having these APIs available is nice, but they don't provide all the flexibility a user might need:

• What if two competing long-running transactions should only be started while the user is on a specific screen in the app? Having a timeout doesn't help here.
• What if I need a watch query with a flexible throttle depending on the app's state?

Both of these cases aren't exactly common, but it doesn't cost us much to support them:

• We should just remove the throttle parameter on streams, and rely on backpressure instead:
  • For onChange, if the subscription is paused we'd buffer into a set of updated tables and emit once the subscription is resumed.
  • For watch, we'd start fetching when the subscription is resumed and just keep a "dirty" flag we'd set when an upstream update comes in while the subscription is paused.
• To express timeouts on transactions and read/write locks, we can use Future<void> as a generalization. If users want timeouts, they can pass a Future.delayed. Internally, we'd use .whenComplete() as an abort signal. This is also how abort signals are expressed in the http package and it seems to work.

[rkistner]

I like these ideas.

Should we keep the existing timeouts to cover backwards-compatibility, and keep plain timeout & throttling cases simple?

[simolus3]

I've thought about that, but since we likely have to do a major version bump for the other planned changes anyway, I'm not sure. Keeping existing parameters gets weird when both a timeout and an abort future are passed, preventing that at a type-level may be worth it. We could mark the existing parameters as @Deprecated since that at least gives users a warning. If we want to keep plain timeout parameters as a dedicated API for those simple use-cases, it might be worth introducing throttledOnChange and throttledWatch methods that specifically don't take a Future<void> abortSignal.