add { signal } option

[juliangruber]

This allows iteration to be canceled cleanly.

Blocks filecoin-station/spark-api#304

[bajtos]

Great idea to add support for AbortSignal 👍🏻

I am unsure if (re)throwing the AbortError is the right way to handle the signal. I am concerned that this could cause unhandled rejections in the code consuming on-contract-event.

As a user of this library, I would expect the library to silently stop listening for new events when the abort signal is triggered. (I.e. treating "abort" as "stop listening").

Another aspect to consider: I think we should eventually implement a timeout for RPC API calls so that the HTTP request does not hang forever if the server is slow to respond. Such improvement is out of the scope of this pull request, though.

Anyhow, I am fine to land this PR as-is and iterate on improving the DX for consumers.

[juliangruber]

I am unsure if (re)throwing the AbortError is the right way to handle the signal. I am concerned that this could cause unhandled rejections in the code consuming on-contract-event.

As a user of this library, I would expect the library to silently stop listening for new events when the abort signal is triggered. (I.e. treating "abort" as "stop listening").

I have thought about this approach, but realized fetch() throws on abort, and to me this is the classic JS platform abortable function. I don't know whether it's necessarily the right approach for iteration too, but I have a feeling it's better because it lets the consumer choose whether to handle or ignore the event.

In spark-api we're handling it like this:

;(async () => {
  for await ...
})().catch(console.error)

Another aspect to consider: I think we should eventually implement a timeout for RPC API calls so that the HTTP request does not hang forever if the server is slow to respond. Such improvement is out of the scope of this pull request, though.

Good idea!

Anyhow, I am fine to land this PR as-is and iterate on improving the DX for consumers.

[juliangruber]

https://github.com/filecoin-station/on-contract-event/releases/tag/v1.1.0