Skip to content

feat(async/unstable): move Channel to options-bag constructor and split per-operation options#7106

Merged
bartlomieju merged 2 commits into
denoland:mainfrom
tomas-zijdemans:async-channel-prep-stabilize
Apr 27, 2026
Merged

feat(async/unstable): move Channel to options-bag constructor and split per-operation options#7106
bartlomieju merged 2 commits into
denoland:mainfrom
tomas-zijdemans:async-channel-prep-stabilize

Conversation

@tomas-zijdemans
Copy link
Copy Markdown
Contributor

@tomas-zijdemans tomas-zijdemans commented Apr 24, 2026

  • Constructor → options bag. new Channel<T>(capacity?: number) becomes new Channel<T>(options?: ChannelOptions) where ChannelOptions = { capacity?: number }. Matches the pattern already used in std, and leaves room for future construction-time options (drop policies, debug labels, etc.) without a second breaking change once stable. Per the style guide, single positional optionals are only fine when "inconceivable more will be added later". For a channel, more certainly will be.
  • Split operation options. The old combined ChannelOptions (for send/receive) is split into ChannelSendOptions and ChannelReceiveOptions. Frees the ChannelOptions name for the constructor and lets each direction evolve independently.
  • Class-level JSDoc summary. Documents FIFO order for both queues, the intentional close() / close(reason) asymmetry (senders always reject with ChannelClosedError so they can recover the unsent value, receivers reject with reason), undefined as a valid value, and multi-consumer fan-out.
  • Pin + document multi-consumer toReadableStream(). Adds a JSDoc note that each call returns an independent consumer and values are distributed FIFO across all consumers, plus a test that asserts this.
  • Minor: inline single-use #nextReceiver() helper into #deliverToReceiver.

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 24, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.61%. Comparing base (f318978) to head (03146fb).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #7106      +/-   ##
==========================================
+ Coverage   94.59%   94.61%   +0.01%     
==========================================
  Files         632      633       +1     
  Lines       51780    51775       -5     
  Branches     9324     9324              
==========================================
+ Hits        48981    48985       +4     
+ Misses       2225     2216       -9     
  Partials      574      574              

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Takes `Channel` through the remaining API-shape decisions before it moves
out of `unstable_*`:

- Replace the bare `new Channel<T>(capacity?)` positional with an options
  bag: `new Channel<T>(options?: ChannelOptions)` where
  `ChannelOptions = { capacity?: number }`. Follows the `CircuitBreakerOptions`
  / `TtlCacheOptions` pattern already used in std and leaves room for
  future construction-time options (drop policies, debug labels, etc.)
  without breaking callers post-stabilization.
- Split the old combined send/receive `ChannelOptions` into
  `ChannelSendOptions` and `ChannelReceiveOptions`. Frees the
  `ChannelOptions` name for the constructor and lets each direction
  evolve independently.
- Add a "Semantics" summary to the class JSDoc documenting FIFO order,
  the intentional close() vs close(reason) asymmetry, `undefined` as a
  valid value, and multi-consumer fan-out of `toReadableStream()`.
- Document and pin multi-consumer `toReadableStream()` behavior: each
  call returns an independent consumer; values are distributed FIFO and
  delivered to exactly one consumer.
- Inline single-use `#nextReceiver()` helper.

No behavioral changes to send/receive/close/iteration/stream semantics.

Made-with: Cursor
@tomas-zijdemans tomas-zijdemans force-pushed the async-channel-prep-stabilize branch from 31819bd to 03146fb Compare April 24, 2026 08:36
@tomas-zijdemans tomas-zijdemans changed the title BREAKING(async/unstable): prepare Channel for stabilization BREAKING(async/unstable): move Channel to options-bag constructor and split per-operation options Apr 24, 2026
@bartlomieju bartlomieju changed the title BREAKING(async/unstable): move Channel to options-bag constructor and split per-operation options feat(async/unstable): move Channel to options-bag constructor and split per-operation options Apr 27, 2026
@bartlomieju
Copy link
Copy Markdown
Member

Dropping BREAKING because it's already an unstable API

@bartlomieju bartlomieju merged commit 3b57683 into denoland:main Apr 27, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants