BREAKING(async): make abortablePromise() and abortableAsyncIterable() private

[iuioiua]

What's changed

abortablePromise() and abortableAsyncIterable() have been made private functions (no longer exported) in favor of abortable().

Why this change was made

Under the hood, abortable() uses abortablePromise() if the first argument, p, is a promise, or abortableAsyncIterable() if p is an async iterable. This change was made to avoid confusion for users regarding which function to use; now, use abortable().

Migration guide

To migrate, use abortable() instead of abortablePromise() or abortableAsyncIterable() in the same way.

For promises:

- import { abortablePromise } from "@std/async/abortable";
+ import { abortable } from "@std/async/abortable";

  const request = fetch("https://example.com");

  const c = new AbortController();
  setTimeout(() => c.abort(), 100);

- const p = abortablePromise(request, c.signal);
+ const p = abortable(request, c.signal);

  // The below throws if the request didn't resolve in 100ms
  await p;

For async iterables:

- import { abortableAsyncIterable, delay } from "@std/async";
+ import { abortable, delay } from "@std/async";

  const p = async function* () {
    yield "Hello";
    await delay(1000);
    yield "World";
  };
  const c = new AbortController();
  setTimeout(() => c.abort(), 100);

  // Below throws `DOMException` after 100 ms
  // and items become `["Hello"]`
  const items: string[] = [];
- for await (const item of abortableAsyncIterable(p(), c.signal)) {
+ for await (const item of abortable(p(), c.signal)) {
    items.push(item);
  }

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.17%. Comparing base (d35f8a3) to head (7b949e2).
Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5056      +/-   ##
==========================================
- Coverage   92.17%   92.17%   -0.01%     
==========================================
  Files         487      487              
  Lines       38800    38796       -4     
  Branches     5435     5435              
==========================================
- Hits        35764    35760       -4     
  Misses       2981     2981              
  Partials       55       55              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

Note: It was originally designed this way, but the exports were added later by the request from the community. ref: #2031

@harrysolovay Do you still find abortablePromise useful/more appropriate to your use case?

[iuioiua]

I think we should either:

1. Only export abortable()
2. Or, remove abortable() and export abortablePromise() and abortableAsyncIterable()

[kt3k]

I think we should either:

1. Only export abortable()
2. Or, remove abortable() and export abortablePromise() and abortableAsyncIterable()

I'm in favor of 1 because it's the original design and also #2031 doesn't seem discussed well (In addition, the requested point ('would prefer to not include the code of abortableAsyncIterable') has not been achieved because all APIs sit in the same file)

but if anyone has any opinion on this, please comment

[iuioiua]

For more context, rough Github search results:

• abortable()
• abortablePromise()
• abortableAsyncIterable()

While these searches aren't perfect, it seems that abortablePromise() and abortableAsyncIterable() aren't used much compared to abortable().

[kt3k]

@kyoh86 is probably the only active user of abortableAsyncIterable.

@kyoh86 Hey, do you prefer to keep using abortableAsyncIterable or are you fine to change it to abortable?

[kyoh86]

@kt3k Yes, I can replace abortableAsyncIterable with abortable.

[kt3k]

LGTM